Ermee beginnen

bijgewerkt

To start using the ricloud API, you first need to get in touch to setup your organisation. Once this is completed, you should have your initial key_token which will grant you access to the API.

De API-oproepen in deze sectie worden uitgevoerd met behulp van cURL, maar deze kunnen eenvoudig worden vervangen door equivalente oproepen van ricloud-py .

Uw organisatie bekijken

Eerst zullen we snel naar uw organisatie kijken.

curl 'https://ricloud-api.reincubate.com/organisation' \
  -H 'Authorization: Token <your key_token>'

Je zou een reactie moeten zien die lijkt op die hieronder. Als u een HTTP 401-antwoord key_token controleert u de key_token waarde die u hebt key_token in de Authorization .

{
    "id": 1,
    "resource": "organisation",
    "name": "Getting started",
    "slug": "getting-started",
    "permissions": {
        "id": 1,
        "resource": "organisation_permissions",
        "identifier": "default",
        "scopes": {
            "source_type:icloud.*": [],
            "task_type:*": [],
            "data_type:icloud.account.info": [],
        },
        "date_created": "2018-11-22T12:59:57.168354Z"
    },
    "storage_configs": {
      "data": [],
      "has_more": false,
      "total_count": 0,
      "url": "/configs/storage"
    },
    "storage_config_default": null,
    "webhook_configs": {
      "data": [],
      "has_more": false,
      "total_count": 0,
      "url": "/configs/webhook"
    },
    "webhook_config_default": null,
    "state": "unconfigured",
    "date_created": "2018-11-22T12:59:57.016467Z"
}

Hier kunt u informatie over uw organisatie bekijken:

  • permissions geeft de basisrechten voor uw organisatie weer.
  • storage_configs en storage_config_default zijn leeg omdat we nog geen instellingen moeten instellen.
  • webhook_configs en webhook_config_default zijn ook om dezelfde reden leeg.
  • state is niet unconfigured wat het gebrek aan geldige opslagconfiguren weerspiegelt.

We komen later terug naar configuratiestappen, omdat dit u er niet van weerhoudt toegang te krijgen tot services via de API.

Nu we hebben bevestigd dat uw organisatie actief is, laten we proberen toegang tot een iCloud-account te krijgen.

Een sessie opzetten

A session represents access to a source. In this case, our source will be an iCloud account and creating a session will effectively "login" to the account. The session will then take care of keeping track of the connection between the API and iCloud's system for future requests.

Maak een gebruiker aan

Voordat een sessie kan worden opgezet, moet een gebruiker worden gemaakt om te definiëren welke eindgebruiker toegang tot de bron wil hebben. Dit helpt bij sessiebeheer en gegevensbeveiliging op de API.

curl 'https://ricloud-api.reincubate.com/users' \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "identifier": "<some identifier for the user your system will recognise>"
}'

Het antwoord bevat het gebruikers-ID dat nodig is in de volgende oproep.

{
  "id": "1",
  "resource": "user",
  "organisation": "1",
  "key": "1",
  "identifier": "<your user identifier>",
  "state": "active",
  "date_created": "2018-11-22T13:49:37.215516Z"
}

Maak een sessie

curl 'https://ricloud-api.reincubate.com/sessions' \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "source": {
    "user": "<user ID from previous request>",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
  }
}'

The response will contain a session resource, which will initially be in the pending state while the API goes through the process of setting up communications with the third-party service.

{
  "id": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "resource": "session",
  "organisation": "1",
  "user": "1",
  "source": "1",
  "state": "pending",
  "error": null,
  "date_created": "2018-11-22T13:50:12.628776Z",
  "date_expired": null
}

U kunt de status van de sessie controleren via de ophaaloproep.

curl 'https://ricloud-api.reincubate.com/sessions/ed855b07-f72b-4983-ac1d-980fafee8a0b' \
  -H 'Authorization: Token <your key_token>'

If the state becomes failed, something went wrong during the initialisation process. Check the value of the error attribute for more details. If 2FA is enabled on your account -- and you got your password correct -- the error encountered is likely to be code-required. You will have been prompted with a 2FA code on one of your iOS devices connected to the account. Simply make the call from step (1) again, but this time including the 2FA code in the payload.

curl 'https://ricloud-api.reincubate.com/sessions' \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "source": {
    "user": "<user ID from previous request>",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>",
    "code": "<2FA code>"
  }
}'

If another error occurred, please check the errors section for more information.

Once the state becomes active the session is ready for use to retrieve data and files from the source.

However, as we saw earlier, your organisation is not yet configured to receive any of this data.

Ophalen van gegevens en bestanden

Voordat de API kan starten met het ophalen van gegevens uit een bron, moet deze weten waar de gegevens moeten worden gepubliceerd. De API ondersteunt momenteel publiceren naar opslagruimten voor Google Cloud Storage en Amazon S3 (AWS) , die moeten worden geconfigureerd via een opslagconfiguratie van uw organisatie. Volg de stappen in de documentatie voor configuratie van de opslagconfiguratie om zelf een emmer klaar te maken voor gebruik met de API.

Once you have a storage config, you can try retrieving your organisation again. The state should now be active, rather than unconfigured.

Maak een peiling voor gegevens

To create a poll, all we need to provide is the ID of an active session and some details on the data or files we want retrieved.

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "payload": {
    "data_types": ["icpl.photos"],
  }
}'

Note that in the call above we request the icpl.photos data type. You might be interested in retrieving a different type of data, or might not have permissions for this data type in particular. Substitute this value as necessary.

This will return a poll resource, with state in pending or processing. In the background, the API has also created a task which will do the actual work required to retrieve this information (a task was also created to set up our session earlier).

{
  "id": "f1447e76-59f1-486b-942f-6b90e3570c63",
  "resource": "poll",
  "organisation": "1",
  "key": "1",
  "user": "1",
  "source": "1",
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "tasks_pending": [],
  "tasks_processing": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "tasks_completed": [],
  "results": {
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results"
  },
  "errors": {
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors"
  },
  "state": "processing",
  "date_created": "2018-11-22T14:20:52.211618Z",
  "date_started": "2018-11-22T14:20:52.731838Z",
  "date_completed": null
}

Note the results attribute, which is empty at this point. This is where we will see references appear for any data or files published from this poll. Results are published as they become available, so they can be retrieved before the whole poll has completed.

Once all requested data and files have been published to your storage, the poll's state will change to completed.

Ophalen van resultaatinformatie

This is done by looking at the results attribute of the poll.

curl 'https://ricloud-api.reincubate.com/polls/f1447e76-59f1-486b-942f-6b90e3570c63' \
  -H 'Authorization: Token <your key_token>'

Het antwoord zal de informatie bevatten die we nodig hebben.

{
  "id": "f1447e76-59f1-486b-942f-6b90e3570c63",
  "resource": "poll",
  "organisation": "1",
  "key": "1",
  "user": "1",
  "source": "1",
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "tasks_pending": [],
  "tasks_processing": [],
  "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "results": {
    "data": [
      {
        "id": "754cfef0-7576-44c0-acfe-8b0d8d0dd32f",
        "resource": "result",
        "task": "6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb",
        "identifier": "data:info.account",
        "url": "<your storage config url>",
        "checksum": "2668324d21a20301ce71c28bc5e621d4",
        "size": 12345,
        "state": "available",
        "date_created": "2018-11-22T14:20:53.506542Z",
        "date_consumed": null,
        "date_deleted": null
      }
    ],
    "has_more": false,
    "total_count": 0,
    "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results"
  },
  "errors": {
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors"
  },
  "state": "completed",
  "date_created": "2018-11-22T14:20:52.211618Z",
  "date_started": "2018-11-22T14:20:52.731838Z",
  "date_completed": "2018-11-22T14:20:53.548372Z"
}

Het url kenmerk van het resultaat url naar het bestand dat in uw bucket is opgeslagen.

Webhook-evenementen ontvangen

Certain API functionality is triggered automatically, either as a result of external triggers such as a Reincubate Relay app finding new data or due to a subscription. In these cases, the API needs a way to tell your system that changes have happened or that new data has been published which you should be aware of.

To do this, the API makes use of webhook notifications. Before the API can start sending these, and before you can start using the Reincubate Relay service or subscriptions, your organisation needs to be configured with a valid webhook config. Follow the guide on webhook configuration for more details.

Hoe kunnen we helpen?

Ons ondersteuningsteam is er om u te helpen!

Onze kantooruren zijn van maandag tot vrijdag van 09.00 tot 17.00 uur GMT. De tijd is momenteel 10:45 AM GMT.

We streven ernaar om alle berichten binnen één werkdag te beantwoorden.

Ga naar het ondersteuningsgedeelte › Neem contact op met het Enterprise-team ›
Ons geweldige ondersteuningsteam

Kunnen we dit artikel verbeteren?

We horen graag van gebruikers: Stuur ons een e-mail, laat een reactie achter of stuur een tweet @reincubate?

© 2008 - 2020 Reincubate Ltd. Alle rechten voorbehouden. Geregistreerd in Engeland en Wales #5189175, VAT GB151788978. Reincubate® is een geregistreerd handelsmerk. Privacybeleid & termen. Wij bevelen 2FA aan. Gebouwd met in Londen.