Erste Schritte

Aktualisierte

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.

Die API-Aufrufe in diesem Abschnitt werden mit cURL ausgeführt. Diese können jedoch problemlos durch entsprechende Aufrufe von ricloud-py ersetzt werden .

Anzeigen Ihrer Organisation

Zunächst werfen wir einen kurzen Blick auf Ihre Organisation.

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

Sie sollten eine ähnliche Antwort wie unten sehen. Wenn Sie eine HTTP 401-Antwort erhalten, überprüfen Sie den key_token Ihnen im Authorization Header angegebenen key_token Wert.

{
    "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 sehen Sie einige Informationen zu Ihrer Organisation:

  • permissions Zeigt die Basisberechtigungen für Ihre Organisation an.
  • storage_configs und storage_config_default sind leer, da noch keine eingerichtet werden müssen.
  • webhook_configs dem gleichen Grund sind auch webhook_configs und webhook_config_default leer.
  • state ist nicht unconfigured was das Fehlen gültiger Speicherkonfigurationen widerspiegelt.

Wir werden später auf die Konfigurationsschritte zurückkommen, da dies Sie nicht daran hindert, über die API auf Dienste zuzugreifen.

Nachdem wir bestätigt haben, dass Ihre Organisation funktioniert, versuchen wir, auf ein iCloud-Konto zuzugreifen.

Eine Sitzung einrichten

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.

Erstellen Sie einen Benutzer

Bevor eine Sitzung eingerichtet werden kann, muss ein Benutzer erstellt werden, um zu definieren, welcher Endbenutzer auf die Quelle zugreifen möchte. Dies hilft bei der Sitzungsverwaltung und Datensicherheit auf der 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>"
}'

Die Antwort enthält die Benutzer-ID, die beim nächsten Aufruf benötigt wird.

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

Erstellen Sie eine Sitzung

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
}

Sie können den Sitzungsstatus über den Abruf überprüfen.

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.

Daten und Dateien abrufen

Bevor die API mit dem Abrufen von Daten aus einer Quelle beginnen kann, muss bekannt sein, wo die Daten veröffentlicht werden sollen. Die API unterstützt derzeit das Veröffentlichen in Google Cloud Storage- und Amazon S3- Speicher-Buckets (AWS) , die über eine Speicherkonfiguration Ihres Unternehmens konfiguriert werden müssen. Befolgen Sie die Schritte in den Einrichtungsdokumenten für die Speicherkonfiguration , um einen eigenen Bucket für die Verwendung mit der API bereitzustellen.

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

Erstellen Sie eine Umfrage für Daten

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.

Ergebnisinformationen abrufen

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>'

Die Antwort enthält die benötigten Informationen.

{
  "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"
}

Das url Attribut des Ergebnisses url auf die in Ihrem Bucket gespeicherte Datei.

Empfangen von Webhook-Ereignissen

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.

Wie können wir helfen?

Unser Support-Team hilft Ihnen gerne weiter!

Unsere Bürozeiten sind Montag bis Freitag von 9 bis 17 Uhr GMT. Die Zeit ist aktuell 12:56 nachm. GMT.

Wir bemühen uns, auf alle Mitteilungen innerhalb eines Arbeitstages zu antworten.

Zum Support-Bereich gehen › Wenden Sie sich an das Unternehmensteam ›
Unser großartiges Supportteam

Können wir diesen Artikel verbessern?

Wir hören gerne von Nutzern: Warum schicken Sie uns nicht eine E-Mail, schreiben Sie einen Kommentar oder tweeten Sie @reincubate?

© 2008 - 2020 Reincubate Ltd. Alle Rechte vorbehalten. Registriert in England und Wales #5189175, VAT GB151788978. Reincubate® ist eine eingetragene Marke. Datenschutz-Bestimmungen & Begriffe. Wir empfehlen die Multi-Faktor-Authentifizierung. Mit Liebe in London gebaut.