Erste Schritte

Aktualisierte

So starten Sie den ricloud v3 API verwenden, müssen Sie zuerst in Verbindung zu Setup Ihre Organisation. Sobald dies abgeschlossen ist, sollten Sie Ihr erstes key_token das Ihnen Zugriff auf die API gewährt.

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": [],
    "storage_config_default": null,
    "webhook_configs": [],
    "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

Eine Sitzung repräsentiert den Zugriff auf eine Quelle. Im Fall einer iCloud-Kontoquelle muss sich die API beim Konto anmelden, um die Sitzung zwischen sich und dem iCloud-Dienst von Apple zu erstellen.

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": "1",
    "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 die Kommunikation mit dem Drittanbieter-Service einrichtet. In diesem Fall erhalten wir Zugriff auf die iCloud.

{
  "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 , um weitere Informationen zu den error .

In dem Fall, dass 2FA in Ihrem Konto aktiviert ist, ist der aufgetretene Fehler höchstwahrscheinlich code-required und Sie wurden mit dem 2FA-Prozess auf einem Ihrer Geräte aufgefordert. 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": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
    "code": "<2FA code>"
  }
}'

Wenn ein anderer Fehler aufgetreten ist, überprüfen Sie den Abschnitt " Fehler " auf weitere Details.

Sobald der Status active die Sitzung zum Abrufen von Daten und Dateien von der Quelle verwendet werden. Wie wir bereits gesehen haben, ist Ihre Organisation noch nicht für den Empfang dieser Daten konfiguriert, sodass wir mit dem nächsten Schritt fortfahren können.

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.

Erstellen Sie eine Umfrage für Daten

Der einfachste Datensatz, der von der iCloud abgerufen werden kann, sind einige grundlegende Kontoinformationen. Sie benötigen lediglich die ID einer aktiven Sitzung und einige Angaben zu den Daten, die Sie wiederherstellen möchten.

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",
  "type": "data",
  "payload": {
    "data_types": ["callkit.calls"],
  }
}'

Beachten Sie, dass wir im callkit.calls Aufruf den Datentyp callkit.calls angegeben callkit.calls , Ihr Schlüssel jedoch möglicherweise Berechtigungen für verschiedene Datentypen hat oder Sie möglicherweise daran interessiert sind, eine andere Art von Daten abzurufen. Ersetzen Sie sie einfach nach Bedarf.

Dies gibt eine Umfrageressource zurück. Im Hintergrund hat die API auch eine Aufgabe erstellt, die die eigentliche Arbeit erledigt, um diese Informationen abzurufen (eine Aufgabe wurde auch erstellt, um unsere Sitzung früher einzurichten). Die ID der Aufgabe kann unter dem Attribut " tasks eingesehen werden.

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

Beachten Sie auch das results , das an dieser Stelle leer ist. Hier werden die IDs der von der Task veröffentlichten Daten angezeigt.

Jetzt möchten wir warten, bis die Verarbeitung abgeschlossen ist und der Status der Umfrage als succeeded .

Ergebnisinformationen abrufen

Dies ist einfach durch Betrachten des results der Umfrage möglich.

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",
  "type": "data",
  "tasks_pending": [],
  "tasks_processing": [],
  "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "results": [
    {
      "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
    }
  ],
  "state": "processing",
  "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 als Folge externer Auslöser wie einer Relaisinstanz , die neue Daten findet, oder aufgrund einer geplanten Abfrage. In diesen Fällen muss die API Ihrem System mitteilen, dass Änderungen stattgefunden haben 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 Relay- Dienst oder geplante Abfragen verwenden können, muss Ihre Organisation mit einer gültigen Webhook-Konfiguration konfiguriert werden. Weitere Informationen finden Sie in der Anleitung zur Webhook-Konfiguration .

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 4:34 vorm. 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 - 2019 Reincubate Ltd. Alle Rechte vorbehalten. Registriert in England und Wales #5189175, VAT GB151788978. Reincubate® ist eine eingetragene Marke. Datenschutz. Wir empfehlen die Multi-Faktor-Authentifizierung. Mit Liebe in London gebaut.