Apple iCloud-Dienst (v2)

Aktualisierte

Der icloud -Dienst der ricloud- API bietet Funktionen für den Zugriff auf auf der iCloud gespeicherte Informationen, und zwar sowohl in Batch-Form aus iOS-Gerätesicherungen als auch in Echtzeit und icloud aus anderen Quellen. Die API unterstützt seit ihrer ursprünglichen Version den Zugriff auf die iCloud.

Es gibt vier Hauptvorgänge, die ein Client möglicherweise für den iCloud-Dienst ausführen muss.

  • Authentifizierung: log-in , perform-2fa-challenge , submit-2fa-challenge
  • Gerätezählung: list-devices
  • Feeds anfordern: fetch-data abrufen
  • Rohdateien anfordern: download-file

Arbeiten mit Scheindaten aus der API

Um die Entwicklung von Integrationen mit der API zu unterstützen, wird ein Scheinkonto mit umfangreichen Daten zur Verfügung gestellt. Auf diese Weise können Clients viele Funktionen der ricloud- API testen, ohne mit echten Benutzerdaten arbeiten zu müssen.

Das Mock-Konto heißt Jonny Appleseed und ist über die iCloud-Konto-ID john.appleseed@reincubate.com und das Kennwort joshua .

Authentifizierung

Anmeldung bei: log-in

Der erste Schritt zur Interaktion mit dem icloud Dienst ist die Anmeldung.

Für die Anfrage müssen wir angeben:

  • Der service , mit dem interagiert werden soll: icloud
  • Die auszuführende action : log-in
  • Der Parameter account , der die ID des iCloud-Kontos darstellt, z. B. john.appleseed@reincubate.com
  • Die Aktionsparameter, die von der Aktion benötigt werden, in diesem Fall nur ein password
  • Wir können auch optionale Aktionsparameter angeben, die vom /account/ endpoint aufgelistet werden
$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=log-in" \
    -d "account=<ACCOUNT>" \
    -d "password=<PASSWORD>" \
    <TASK_SUBMISSION_ENDPOINT>

Der asapi- Endpunkt antwortet im JSON-Format:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_1>"
}

Wenn Sie mit dem richtigen stream_endpoint auf dem aschannel- Endpoint verbunden sind, wird ein Ergebnis angezeigt , das mit der <TASK_ID_1> übereinstimmt, die Sie vom asapi- Endpoint erhalten haben.

{ "message": "Log-in successful",
  "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG",
  "success": true
}

Die Ergebnisse enthalten einen success , der bei erfolgreicher Anmeldung wahr ist, sowie eine Meldung und ein Apple-Authentifizierungstoken zur Verwendung mit anderen Serviceaktionen.

Fehlerbehebung bei der Anmeldung

Weitere Informationen zu Fehlerdefinitionen und Lösungen finden Sie im Abschnitt zu Anmeldefehlerantworten .

2FA und 2SV

Nach dem Versuch, sich bei einem iCloud-Konto anzumelden, das mit 2SV oder 2FA eingerichtet wurde, schlägt die normale Anmeldung fehl und es wird eine Fehlermeldung ähnlich der folgenden zurückgegeben.

{ "message": "This account has Two Step Verification enabled, please select a device to challenge.",
  "data": {
    "trustedDevices": ["********12", "Renate's iPhone - iPhone 6s"],
  },
  "error": "2fa-required"
}

Die data Wörterbuch enthält eine Liste Geräte, verkeilt durch device_id . Dies sind die Geräte, denen das iCloud-Konto vertraut, um den nächsten Authentifizierungsschritt durchzuführen.

Für die Bestätigung in zwei Schritten (2SV)

Im Fall von 2SV enthält die Liste der trustedDevices Geräte ein oder mehrere Geräte. Kunden müssen ein aufgelistetes Gerät auswählen, um es herauszufordern.

Dies geschieht durch Ausführen einer perform-2fa-challenge wobei challenge trustedDevices von trustedDevices den Schlüssel des ausgewählten Geräts trustedDevices .

Für Zwei-Faktor-Authentifizierung (2FA)

Im Fall von trustedDevices wird die Liste der trustedDevices ["Challenge all 2FA devices"] auf ["Challenge all 2FA devices"] herausfordern ["Challenge all 2FA devices"] , um trustedDevices , dass eine Herausforderung an alle iOS-Geräte gesendet werden muss, die mit diesem Konto verbunden sind. Dies erfolgt durch Ausführen von perform-2fa-challenge wobei challenge auf den Wert ["Challenge all 2FA devices"] challenge ["Challenge all 2FA devices"] .

Verwenden Sie perform-2fa-challenge

Diese Methode sendet in Echtzeit eine Anfrage an alle Geräte auf dem Konto im Fall von 2FA oder das ausgewählte Gerät im Fall von 2SV.

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=perform-2fa-challenge" \
    -d "challenge=<TRUSTED_DEVICE>" \
    <TASK_SUBMISSION_ENDPOINT>

<TRUSTED_DEVICE> must be set to a device_id, or to "Challenge all 2FA devices"

asapi antwortet wie gewohnt:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_X>"
}

Der Abrufendpunkt antwortet mit:

{ "message": "Challenge has been submitted.",
  "success": true
}

Sobald die submit-2fa-challenge an das Gerät des Benutzers gesendet wurde, muss der Zwei-Faktor-Code mit submit-2fa-challenge an die API zurückgesendet werden. In der folgenden Anforderung ist <CODE> der vom Endbenutzer bereitgestellte numerische Code, der die für die 2FA / 2SV-Anmeldung an das Gerät übertragenen Codes darstellt.

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=submit-2fa-challenge" \
    -d "code=<CODE>" \
    <TASK_SUBMISSION_ENDPOINT>

asapi antwortet wie gewohnt:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_X>"
}

Der Abrufendpunkt antwortet mit einer normalen Anmeldemeldung:

{ "message": "Log-in successful",
  "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG",
  "success": true
}

Aktualisieren einer Kontoanmeldung mithilfe von Authentifizierungstoken

ricloud bietet Authentifizierungstoken zur Aktualisierung von Anmeldungen, ohne dass vollständige iCloud-Anmeldeinformationen erforderlich sind. Benutzer des Tokenisierungsmechanismus müssen keine Benutzeranmeldeinformationen beibehalten.

Dazu müssen Clients das Feld auth_token verwenden, das während der Anmeldung abgerufen wurde. Dies muss an den Aktionsendpunkt des refresh-session gesendet werden.

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=refresh-session" \
    -d "auth_token=<ICLOUD_AUTH_TOKEN>" \
    <TASK_SUBMISSION_ENDPOINT>

Wenn dies erledigt ist, kann jede Serviceaktion gegen den Service ausgeführt werden.

Gerätezählung

Aufzählung der Geräte: list-devices

Wenn Sie bei einem Konto angemeldet sind, können Clients Geräte und Gerätesicherungen auflisten, die dem iCloud-Konto zugeordnet sind. Dies erfolgt durch Ausführen der Aktion list-devices für den iCloud-Dienst.

Dies erfolgt auf die gleiche Weise wie bei jeder anderen Serviceaktion. Hier ist ein Beispiel für eine curl Anforderung für diese Aktion. Der folgende Parameter <ACCOUNT> kann mit einer Konto-ID wie z. B. john.appleseed@reincubate.com .

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=list-devices" \
    -d "account=<ACCOUNT>" \
    <TASK_SUBMISSION_ENDPOINT>

Der asapi- Endpunkt antwortet im JSON-Format:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_2>"
}

Ihr Ergebnis wird in Kürze auf dem Abrufendpunkt angezeigt. Nachfolgend finden Sie eine Beispielantwort:

{ "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG",
  "devices": {
    "<DEVICE_ID_1>": {
      "ios_version": "10.0",
      "colour": "1",
      "device_name": "Johnny's iP7 iOS10 Black",
      "latest-backup": "2016-09-16 14:08:13.000000",
      "model": "D101AP",
      "serial": "ABC123AAAAAA",
      "name": "iPhone 7"
    },
    "<DEVICE_ID_2>": {
      "ios_version": "9.1",
      "colour": "#e1e4e3",
      "device_name": "Johnny's iPad",
      "latest-backup": "2016-11-16 16:36:33.000000",
      "model": "J98aAP",
      "serial": "ABC123BBBBBB",
      "name": "iPad Pro"
    },
    "<DEVICE_ID_3>": {
      "ios_version": "9.2.1",
      "colour": "#3b3b3c",
      "device_name": "Johnny's other iPhone",
      "latest-backup": "2016-06-16 16:00:49.000000",
      "model": "N49AP",
      "serial": "DFVDASDDSVAS",
      "name": "iPhone 5c"
    },
    "<DEVICE_ID_4>": {
      "ios_version": "9.0.2",
      "colour": "#e1e4e3",
      "device_name": "Johnny's white iPhone",
      "latest-backup": "2016-02-25 15:37:38.000000",
      "model": "N61AP",
      "serial": "HYTWGFHGHDSF",
      "name": "iPhone 6"
    }
  }
}

Diese Antwort enthält das auth_token für die iCloud-Sitzung des angegebenen Kontos sowie eine Liste der diesem Konto zugeordneten devices Abschnitt devices . Jeder Geräteeintrag enthält folgende Schlüssel:

  • ios_version : Die iOS-Version des Geräts
  • colour : Die colour des Geräts als Hex-Code
  • device_name : Der vom Benutzer festgelegte Gerätename
  • latest-backup : Das Datum, an dem das Gerät zuletzt in der iCloud gesichert wurde
  • model : Die model des Geräts
  • serial : Die serial des Geräts
  • name : Der von Apple beworbene Produktname des Geräts

Feeds anfordern

Abruf von Feed-Daten: fetch-data

Die Aktion fetch-data wird verwendet, um über die API auf Feeds mit JSON-Daten zuzugreifen. Es erfordert die folgenden Parameter:

  • device : Das Gerät, von dem oder über das Daten abgerufen werden sollen
  • data : Eine CSV der angeforderten Feed-Module

Optionale Parameter sind:

  • since : Der Zeitraum, ab dem die Ergebnisse übereinstimmen sollen

Unten sehen Sie ein Beispiel für eine Aktion zum fetch-data .

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=icloud" \
    -d "action=fetch-data" \
    -d "account=<ACCOUNT>" \
    -d "device=<DEVICE_ID>" \
    -d "data=<FEED_MODULES>" \
    <TASK_SUBMISSION_ENDPOINT>

<FEED_MODULES> can be any of the feed modules listed in feed modules.

Mit dem Wert sms in <FEED_MODULES> im obigen Befehl kann beispielsweise auf SMS, MMS und iMessages in einer Sicherung <FEED_MODULES> . Mit dem Wert sms,whatsapp_messages,snapchat_messages in <FEED_MODULES> im Befehl können wir auf SMS-, MMS- und iMessages-, WhatsApp- und Snapchat-Nachrichten zugreifen, die alle dasselbe JSON-Ergebnis haben.

Der Asapi wird antworten mit:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_3>"
}

Kurz darauf werden die Ergebnisse auf dem Ergebnisendpunkt mit derselben task_id :

{ "sms": [
    { "group_handles": [
        "+441234567890",
        "renate@reincubate.com"
      ],
      "attachments": [],
      "deleted": false,
      "text": "Welcome to Vodafone!",
      "conversation_id": "vodafone",
      "from_me": false,
      "date": "2015-10-28 09:18:17.000000",
      "handle": "vodafone",
      "type": "SMS",
      "id": 6
    }
  ]
}

Andere Feed-Module stellen Informationen bereit, mit denen auf andere Arten von Inhalten zugegriffen werden kann. Eine Aktion zum fetch-data bei der "Fotos" als <FEED_MODULES> für ein bestimmtes Gerät verwendet werden, sieht beispielsweise folgendermaßen aus:

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=icloud" \
    -d "action=fetch-data" \
    -d "account=<ACCOUNT>" \
    -d "device=<DEVICE_ID>" \
    -d "data=photos" \
    <TASK_SUBMISSION_ENDPOINT>

Wird veranlassen, dass asapi antwortet mit:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_4>"
}

Das folgende Ergebnis wird auf dem entsprechenden Endpunkt angezeigt:

{ "photos": [{
    "file_path": "Media/DCIM/100APPLE/IMG_0001.PNG",
    "last_modified": "2016-10-05 10:24:03.000000",
    "file_id": "c8ada38b9acf7368c6347be1c353dc68ed2c7741",
    "filename": "IMG_0001.PNG"
  }, {
    "file_path": "Media/DCIM/100APPLE/IMG_0002.MOV",
    "last_modified": "2016-10-11 09:39:25.000000",
    "file_id": "5c3e35cc01689340a34d13d34a0591e2ed450e63",
    "filename": "IMG_0002.MOV"
  }]
}

JSON-Feed-Formate

Die JSON- Feeds sollen so einfach wie möglich zu analysieren sein. Der Feed gibt alle angeforderten Datentypen in einer einzigen Antwort zurück.

Jedes im Modul-Flag angegebene Feed-Modul verfügt über einen eigenen Schlüssel im zurückgegebenen JSON-Wörterbuch der obersten Ebene.

{
    "first_module_name": "Module's data",
    "second_module_name": "Module's data",
    "etc.": "etc."
}

Rohdateien anfordern

Abruf von Rohdateien: download-file

Mit download-file Aktion " download-file herunterladen" können Sie Dateien oder Nachrichtenanhänge direkt von der iCloud herunterladen. Die benötigten Parameter sind das Ziel <DEVICE_ID> und eine <FILE_ID> .

Einige der Feed-Module, einschließlich der Module file_list und photo, enthalten Verweise auf Dateien oder Anhänge, die zum Herunterladen verfügbar sind. Diese enthalten eine <FILE_ID> , mit der die Datei identifiziert und heruntergeladen wird, und häufig einige zusätzliche Metadaten wie filename , file_path , size und type . Weitere Informationen finden Sie unter Informationsextraktoren .

Der Befehl

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=icloud" \
    -d "action=download-file" \
    -d "account=<ACCOUNT>" \
    -d "device=<DEVICE_ID>" \
    -d "file=<FILE_ID>" \
    <TASK_SUBMISSION_ENDPOINT>

asapi wird antworten mit:

{ "retrieval_protocol": "aschannel",
  "stream": "<STREAM>",
  "success": true,
  "task_id": "<TASK_ID_5>"
}

Kurz darauf werden die Ergebnisse auf dem Endpunkt mit derselben task_id .

Fehlerbehebung bei Fehlerreaktionen

Allgemeine Fehlerreaktionen

Die folgende Tabelle zeigt die Fehlercodes, die jede Aktion auslösen kann.

Antwort Zusammenfassung
task-failed Unbekannter Fehler
deactivated-account Konto deaktiviert
deactivated-device Gerät deaktiviert
client-account-disabled API-Token deaktiviert
account-locked Konto gesperrt
account-credentials-blocked Konto gesperrt und geschützt
push-api-timeout Internes Timeout
icloud-unauthorised Zeitlimit für Apple-Sitzung
service-inactive-error Apple-Dienst nicht initialisiert

Unbekannter Fehler

Die Anmeldeaufgabe ist fehlgeschlagen und der Grund war unbekannt. Bei einem Fehlschlagen der Aufgabe mit diesem Code sollten sich die Kunden an das Support-Team wenden .

Konto deaktiviert

Dies bedeutet, dass das Konto mit dem Verwaltungsbefehl zur Deaktivierung des Kontos deaktiviert wurde. Der Zugriff ist nur möglich, wenn ein manueller Aktivierungsbefehl gesendet wird.

Gerät deaktiviert

Dies bedeutet, dass das Gerät mit dem Befehl zur Verwaltung der Gerätedeaktivierung deaktiviert wurde. Der Zugriff ist nur möglich, wenn ein manueller Aktivierungsbefehl gesendet wird.

API-Token deaktiviert

Das für den Zugriff auf die API verwendete Token wurde deaktiviert. Wenden Sie sich an das Support-Team.

Internes Timeout

Wenn die API-Sitzung während der Ausführung anderer Serviceaktionen abläuft, erhalten Clients den Fehlercode: push-api-timeout und müssen sich erneut anmelden.

{ "message": "Unable to recover the session. Please re-login and try again",
  "error": "push-api-timeout"
}

iCloud nicht autorisiert

Wenn die Sitzung mit Apple vor einer Aktion abgelaufen ist oder während einer Aktion ungültig wird, muss die Aktion abgebrochen und die Sitzung durch erneute Authentifizierung über eine neue log-in wiederhergestellt werden. Die Verwendung der refresh-session funktioniert in diesem Fall nicht, da das für diesen Anruf verwendete Token an die Sitzung mit Apple gebunden ist, die jetzt abgelaufen ist.

In bestimmten Fällen kann eine Sitzung teilweise abgelaufen sein. Zum Beispiel gibt list-devices immer noch eine gültige, aktuelle Geräteliste zurück, aber das fetch-data schlägt mit icloud-unauthorised fehl. In diesem Fall kann die Sitzung weiterhin für zugreifbare Daten verwendet werden, muss jedoch mithilfe einer log-in vollständig aktualisiert werden, um weitere Daten abzurufen.

Inaktiver Fehler des Dienstes

Diese Antwort wird zurückgegeben, wenn die API versucht hat, einen Dienst zu initialisieren, aber von Apple eine Antwort erhalten hat, die angibt, dass er im Benutzerkonto nicht inaktiviert wurde. Bitte überprüfen Sie die entsprechende Einstellung für den abgefragten Datentyp und stellen Sie sicher, dass dieser aktiviert und initialisiert ist.

Anmeldefehlerantworten

Die folgende Tabelle zeigt die Fehlercodes zeigt , dass die log-in und submit-2fa-challenge Aktionen zusätzlich zu den allgemeinen Codes oben anheben können.

Antwort Zusammenfassung
unable-to-login Anmeldeinformationen sind falsch
2fa-required 2FA erforderlich
invalid-2fa-code Ungültiger 2FA-Code
too-many-2fa-requests 2FA rate-limited
account-locked Konto gesperrt
account-credentials-blocked Konto gesperrt und geschützt
terms-of-service-update-client Nutzungsbedingungen werden nicht akzeptiert
session-creation-error Behebbarer Fehler während der Sitzungsinitialisierung
session-corrupt-error Nicht behebbarer Fehler während der Sitzungsinitialisierung

Anmeldeinformationen sind falsch

Die für das Konto angegebenen Anmeldeinformationen waren falsch und eine Authentifizierung ist nicht möglich.

2FA erforderlich

Für die Anmeldung bei Konten, die die Zwei-Faktor-Authentifizierung (2FA) oder die Bestätigung in zwei Schritten (2SV) verwenden, sind einige zusätzliche Schritte erforderlich. Siehe die folgenden Abschnitte "2FA und 2SV".

Ungültiger 2FA-Code

Als Antwort auf die 2FA-Abfrage wurde ein ungültiger oder anderweitig falscher 2FA-Code gesendet.

2FA rate-limited

Vor kurzem wurden zu viele 2FA-Anfragen für das Konto gesendet: Es wurde eine Preisbeschränkung eingeführt. Versuchen Sie es nach 30 Minuten erneut.

Konto gesperrt

Das iCloud-Konto wurde von Apple gesperrt. Wenn in kurzer Zeit erneut versucht wird, auf das Konto zuzugreifen, wird stattdessen ein Fehler zurückgegeben, der die account-credentials-blocked Kontoanmeldeinformationen bewirkt.

Konto gesperrt und geschützt

Das iCloud - Konto wurde von Apple gesperrt und ricloud hat bereits den Client mit informiert account-locked . Diese Nachricht wird ersetzt, um anzuzeigen, dass der Dienst die Anforderung nicht an Apple weiterleitet.

Nutzungsbedingungen werden nicht akzeptiert

Das iCloud-Konto wird deaktiviert, bis die neuesten Geschäftsbedingungen von iCloud akzeptiert werden. Der Benutzer kann diese auf seinem Gerät akzeptieren oder sich bei icloud.com anmelden.

Sitzungserstellungsfehler

Das iCloud-Backend hat während der Sitzungsinitialisierung mit einem Fehler geantwortet, aber ein erneuter Versuch wird das Problem wahrscheinlich lösen und erfolgreich sein.

Sitzungsfehler

Das iCloud-Backend hat während der Sitzungsinitialisierung mit einem Fehler geantwortet. Ein erneuter Versuch führt nicht zu einem anderen Ergebnis. Wenden Sie sich an den Support (vorzugsweise mit Kontoausweisen), damit dieser Randfall untersucht werden kann.

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 7:54 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

© 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.