Erste Schritte
Um die Ricloud-API verwenden zu können, müssen Sie sich zuerst mit uns in Verbindung setzen, um Ihre Organisation einzurichten. Sobald dies abgeschlossen ist, sollten Sie über Ihr anfängliches key_token dem Sie Zugriff auf die API erhalten.
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:
-
permissionsZeigt die Basisberechtigungen für Ihre Organisation an. -
storage_configsundstorage_config_defaultsind leer, da noch keine eingerichtet werden müssen. -
webhook_configsdem gleichen Grund sind auchwebhook_configsundwebhook_config_defaultleer. -
stateist nichtunconfiguredwas 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
Eine Sitzung repräsentiert den Zugriff auf eine Quelle. In diesem Fall ist unsere Quelle ein iCloud-Konto, und beim Erstellen einer Sitzung wird das Konto effektiv "angemeldet". Die Sitzung kümmert sich dann darum, die Verbindung zwischen der API und dem iCloud-System für zukünftige Anforderungen zu verfolgen.
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>" } }'
Die Antwort enthält eine Sitzungsressource, die sich zunächst im Status " pending während die API den Prozess zum Einrichten der Kommunikation mit dem Dienst eines Drittanbieters durchläuft.
{ "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>'
Wenn der Status failed , ist während des Initialisierungsprozesses ein Fehler aufgetreten. Überprüfen Sie den Wert des error auf weitere Details. Wenn 2FA in Ihrem Konto aktiviert ist und Sie Ihr Passwort korrekt eingegeben haben, ist der aufgetretene Fehler wahrscheinlich für den code-required . Auf einem Ihrer mit dem Konto verbundenen iOS-Geräte wurde ein 2FA-Code angezeigt. Rufen Sie einfach erneut ab Schritt (1) auf, diesmal jedoch mit dem 2FA-Code in der Nutzlast.
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>" } }'
Wenn ein anderer Fehler aufgetreten ist, lesen Sie bitte den Abschnitt Fehler, um weitere Informationen zu erhalten.
Sobald der Status active die Sitzung Daten und Dateien aus der Quelle abrufen.
Wie wir bereits gesehen haben, ist Ihre Organisation noch nicht für den Empfang dieser Daten konfiguriert.
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.
Sobald Sie eine Speicherkonfiguration haben, können Sie erneut versuchen, Ihre Organisation abzurufen. Der state sollte jetzt active und nicht mehr unconfigured .
Erstellen Sie eine Umfrage für Daten
Um eine Umfrage zu erstellen, müssen wir lediglich die ID einer aktiven Sitzung und einige Details zu den Daten oder Dateien angeben, die abgerufen werden sollen.
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"], } }'
Beachten Sie, dass wir im icpl.photos Aufruf den Datentyp icpl.photos . Möglicherweise möchten Sie einen anderen Datentyp abrufen, oder Sie haben insbesondere keine Berechtigungen für diesen Datentyp. Ersetzen Sie diesen Wert nach Bedarf.
Dadurch wird eine Abfrageressource zurückgegeben, deren state pending oder processing . Im Hintergrund hat die API auch eine Aufgabe erstellt, die die eigentliche Arbeit erledigt, die zum Abrufen dieser Informationen erforderlich ist (eine Aufgabe wurde auch erstellt, um unsere Sitzung früher einzurichten).
{ "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 }
Beachten Sie das results , das zu diesem Zeitpunkt leer ist. Hier werden Referenzen für alle Daten oder Dateien angezeigt, die aus dieser Umfrage veröffentlicht wurden. Die Ergebnisse werden veröffentlicht, sobald sie verfügbar sind, sodass sie abgerufen werden können, bevor die gesamte Umfrage abgeschlossen ist.
Sobald alle angeforderten Daten und Dateien in Ihrem Speicher veröffentlicht wurden, ändert sich der Status der Umfrage in " completed .
Ergebnisinformationen abrufen
Dies erfolgt anhand des results der Umfrage.
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
Bestimmte API-Funktionen werden automatisch ausgelöst, entweder aufgrund externer Auslöser wie einer Reincubate Relay-App, die neue Daten findet, oder aufgrund eines Abonnements. In diesen Fällen muss die API Ihrem System mitteilen, dass Änderungen vorgenommen wurden oder dass neue Daten veröffentlicht wurden, die Sie kennen sollten.
Zu diesem Zweck verwendet die API Webhook-Benachrichtigungen. Bevor die API diese senden kann und bevor Sie den Reincubate Relay-Dienst oder Abonnements verwenden können, muss Ihre Organisation mit einer gültigen Webhook-Konfiguration konfiguriert werden. Weitere Informationen finden Sie in der Anleitung zur Webhook-Konfiguration .
