Apple iCloud-Dienst

Aktualisierte Mai 15^th, 2020

The API supports retrieval of a variety of data and files from Apple's iCloud services.

Sitzungen

Das Einrichten einer Sitzung für die iCloud-Dienste auf der API ist so einfach wie das Anmelden bei einem iCloud-Konto. Der Vorgang kann mehrere Versuche zum Erstellen der Sitzung erfordern, wenn das Konto die Multifaktorauthentifizierung wie 2FA oder 2SV aktiviert hat.

Creating a session for an account without 2FA/2SV

The session payload to create a session for an account without 2FA/2SV enabled contains the following parameters.

name	type	description
`password`	string	The iCloud account password.

CURL verwenden

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

Response

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "succeeded",
  "error": null,
  ...
}

Creating a session for an account with 2FA

Creating a session for a 2FA enabled account is a two step process:

Attempt to create a session using just the iCloud account password. This will trigger the 2FA process, which sends an authentication code to iOS and macOS devices associated with the account. The session creation attempt will fail with error="code-required".
Use the iCloud account password and the authentication code received in (1) to create a session. If the code is accepted, the session will be successfully created.

Step 1: create session

name	type	description
`password`	string	The iCloud account password.

CURL verwenden

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

Response

If the 2FA process is triggered as expected, the session should fail to be created with the error: code-required.

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "failed",
  "error": "code-required",
  ...
}

Step 2: create session with code

name	type	description
`password`	string	The iCloud account password.
`code`	string	The authentication code.

CURL verwenden

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": "<authentication code>"
  }
}'

Response

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "succeeded",
  "error": null,
  ...
}

Creating a session for an account with 2SV

The process to create a session for a 2SV enabled account has three steps:

Attempt to create a session using the iCloud account password. As 2SV is required, this will fail with error="choice-required" and error_info={"choices": [<2SV enabled devices>]}.
Attempt to create a session again using the iCloud account password and a choice from the error_info["choices"] list. This time, the attempt will trigger the 2SV process which sends an authentication code to the chosen device. The attempt will fail with error="code-required".
Use the iCloud account password and the authentication code received in (2) to create a session. If the code is accepted, the session will be successfully created.

This will trigger the 2SV process, which sends an authentication code to iOS and macOS devices associated with the account. The session creation attempt will fail with error="code-required".

Step 1: create session

name	type	description
`password`	string	The iCloud account password.

CURL verwenden

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

Response

If 2SV is enabled on the account, the session creation attempt will fail with error choice-required.

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "failed",
  "error": "choice-required",
  "error_info": {
    "choices": [
      "********02 - SMS to Phone Number"
    ]
  }
  ...
}

Step 2: create session with choice

name	type	description
`password`	string	The iCloud account password.
`choice`	string	The chosen device to send an authentication code to.

CURL verwenden

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>",
    "choice": "********02 - SMS to Phone Number"
  }
}'

Response

If the 2FA process is triggered as expected, the session should fail to be created with the error: code-required.

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "failed",
  "error": "code-required",
  ...
}

Step 3: create session with code

name	type	description
`password`	string	The iCloud account password.
`code`	string	The authentication code.

CURL verwenden

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": "<authentication code>"
  }
}'

Response

{
  "id": "<session ID>",
  "resource": "session",
  ...
  "state": "succeeded",
  "error": null,
  ...
}

Quelltypen

identifier	description
`icloud.account`	primary source Corresponds to an iCloud account.

Umfragen

Der iCloud-Dienst unterstützt alle Attribute des Poll-Payload-Schemas.

Quelleninformationen werden abgerufen

Dieser Abfragetyp ruft Informationen zur Zielquelle ab. Die Ergebnisse werden im JSON-Format veröffentlicht.

CURL verwenden

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "session": "<session ID>",
  "payload": {
    "info_types": ["*"]
  }
}'

Verwendung von * ricloud-py *

import ricloud

# The ID of a session we made earlier.
session_id = "<session ID>"

poll = ricloud.Poll.create(
  session=session_id,
  payload={
    "info_types": ["*"]
  }
)

Daten abrufen

Dieser Abfragetyp ruft Daten aus der Zielsitzung ab und verarbeitet sie. Die Ergebnisse werden im JSON-Format veröffentlicht.

Weitere Informationen zu bestimmten Datentypen finden Sie in der Liste der verfügbaren Datentypen .

CURL verwenden

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

Verwendung von * ricloud-py *

import ricloud

# The ID of a session we made earlier.
session_id = "<session ID>"

poll_payload = {
    "data_types": ["icpl.photos"]
}

poll = ricloud.Poll.create(
  session=session_id,
  payload=poll_payload,
)

Dateien werden abgerufen

The files poll payload attribute is used to request the retrieval of binary files from the targeted source.

The IDs will typically be retrieved from a previous poll for data types that include direct file references, like iCloud Photo Library, or that include attachments, like message data types.

CURL verwenden

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "session": "<session ID>",
    "payload": {
        "files": [
            "icpl://ATnrIxddlwbCEjN33NBq8zXQwYgE",
            "icpl://AbfMRXQ55H4WfS5YguuUWxir4hq6"
        ]
    }
}'

Verwendung von * ricloud-py *

import ricloud

# The ID of a session we made earlier.
session_id = "<session ID>"

poll_payload = {
    'files': [
        'icpl://ATnrIxddlwbCEjN33NBq8zXQwYgE',
        'icpl://AbfMRXQ55H4WfS5YguuUWxir4hq6',
    ]
}

poll = ricloud.Poll.create(
    session=session_id,
    payload=poll_payload,
)

Datentypen

iCloud-Datentypen

Kennung	Beschreibung
`icpl.photos`	Retrieves iCloud Photo Library assets.
`mme_contacts.contacts`	Retrieves iCloud stored iOS Contacts data.
`mme_calendar.events`	Retrieves iCloud stored iOS Calendar data.
`mme_notes.notes`	Ruft in iCloud gespeicherte iOS Notes-Daten ab.
`callkit.calls`	Ruft mit CallKit synchronisierte iOS-Telefondaten ab.
`cloudkit_safari.history`	Rufen Sie in iCloud gespeicherte Safari-Browserverlaufsdaten ab.
`fmip.devices`	Abrufen von Find My iPhone-Geräte- und Standortdaten.

iCloud Photo Library

Photos, videos and other media

Retrieves information on photos, videos and other media stored in iCloud Photo Library (ICPL).

This module requires that iCloud Photo Library is enabled on the user's iCloud account.


Data type ID	`icpl.photos`
Associated setting	`Settings` > `[username]` > `iCloud` > `Photos` > `iCloud Photo Library`

Data attributes

Name	Art	Beschreibung
`id`	string	An identifier for the data item. Useful for deduplicating data across multiple polls.
`filename`	string	The name of the file as it is stored in ICPL.
`files`	list of `image`, `video`, `audio` items	Files associated with this ICPL asset. The original file, Live Photos, thumbnails will be included in this list.
`date_created`	datetime	When the file was originally created. In the case of photos or videos taken on an iOS device, this will be the date when they were taken. In the case of existing assets imported to ICPL, this will be the original import date.
`date_uploaded`	datetime	When the file was last uploaded to ICPL. This will correspond to when the file was first retrievable via the ricloud API.

Data filters

name	type	description
`since`	datetime	Only includes items with a `date_uploaded` later than the provided value.
`until`	datetime	Only includes items with a `date_uploaded` earlier than the provided value.

Sample data

[
  {
    "id": "4d475a7bba2c604",
    "data_type": "icpl.asset",
    "filename": "IMG_0123.PNG",
    "files": [
      {
        "id": "icpl://ATnrIxddlwbCEjN33NBq8zXQwYgE",
        "data_type": "image",
        "extension": "png",
        "size": 119842,
        "width": 750,
        "height": 1334
      },
      {
        "id": "icpl://AcXwu8/wH8s6lfiGBDEZah6KzQjC",
        "data_type": "image",
        "extension": "jpg",
        "size": 210680,
        "width": 750,
        "height": 1334
      },
      {
        "id": "icpl://AbfMRXQ55H4WfS5YguuUWxir4hq6",
        "data_type": "image",
        "extension": "jpg",
        "size": 71032,
        "width": 310,
        "height": 554
      }
    ],
    "date_created": "2020-01-01T00:00:00.000000Z",
    "date_uploaded": "2020-01-01T00:00:00.000000Z"
  }
]

MobileMe Contacts

Contacts

Retrieves iOS Contacts data stored in iCloud.


Data type ID	`mme_contacts.contacts`
Associated setting	`Settings` > `[username]` > `iCloud` > `Contacts`

Data attributes

The mme_contacts.contact data type inherits most attributes from the base contact data type. The table below outlines additional or differing attributes.

Name	Art	Beschreibung
`id`	string	An identifier for the data item. Useful for deduplicating data across multiple polls.
`data_type`	string, always `mme_contacts.contact`	The data type of the item.
`uid`	string	A unique identifier that can be used to deduplicate across different sources of iOS Contacts data.
`image`	nested `image` item, optional	Profile image for the contact.

Sample data

[
  {
    "id": "2cf6a837304d6614",
    "data_type": "mme_contacts.contact",
    "uid": "NzNlNjkxYjctOTBmYi00MTYxLWI5YzYtZTk0ZDlhZjljMmE5",
    "first_name": "John",
    "middle_name": "'Gala'",
    "last_name": "Appleseed",
    "prefix": "Mr.",
    "suffix": "Jr.",
    "nickname": "John'o",
    "records": [
      {
        "type": "Phone",
        "name": "MAIN",
        "value": "1-800-MY-APPLE"
      },
      {
        "type": "Phone",
        "name": "UK",
        "value": "0800 039 1010"
      },
      {
        "type": "URL",
        "name": "HOMEPAGE",
        "value": "http://www.apple.com"
      },
      {
        "type": "URL",
        "name": "HOMEPAGE",
        "value": "http://www.apple.com/uk/"
      },
      {
        "City": "Cupertino",
        "State": "CA",
        "ZIP": "95014",
        "name": "WORK",
        "CountryCode": "US",
        "Country": "United States",
        "Street": "1 Infinite Loop",
        "type": "Address",
        "SubLocality": null,
        "Municipality": null
      }
    ],
    "organisation": "Apple Inc.",
    "department": "Marketing",
    "jobtitle": "VP Coring",
    "birthday": "1976-04-01",
    "image": {
      "id": "mme_contact_image://2cf6a837304d6614",
      "data_type": "image",
      "extension": "jpg"
    }
  }
]

MobileMe Calendar events `mme_calendar.events`

Ruft in iCloud gespeicherte iOS-Kalenderdaten ab.

MobileMe Notes notes `mme_notes.notes`

Ruft in iCloud gespeicherte iOS Notes-Daten ab.

CallKit

Anrufe von CallKit callkit.calls

Ruft mit dem CallKit-Dienst synchronisierte Anrufprotokolle ab.

Fehler

callkit-uninitialised

Zeigt an, dass der CallKit-Dienst nicht für dieses Konto eingerichtet wurde. Der iCloud-Kontoinhaber kann diesen Fehler mithilfe eines iOS-Geräts beheben, das dem iCloud-Konto zugeordnet ist. Führen Sie dazu die folgenden Schritte aus: - Stellen Sie sicher, dass das Gerät mit Wi-Fi verbunden ist. - Navigieren Sie zu Settings > [username] > iCloud . - Schalten Sie iCloud Drive aus und warten Sie 30 bis 60 Sekunden, bis die Änderung wirksam wird. - Schalten Sie iCloud Drive ein, sobald die vorherige Änderung abgeschlossen ist. Dies sollte die Initialisierung auslösen.

Wenn der Fehler nach dem Ausführen dieses Vorgangs weiterhin besteht, wenden Sie sich an den Support.

callkit-sync-disabled

In diesem Fall wurde der CallKit-Dienst initialisiert, aber die Voraussetzungen, unter denen Geräte die Synchronisierung des Anrufprotokolls mit der iCloud starten können, wurden nicht erfüllt. Die API löst dies remote über die iCloud auf, aber das mit dem iCloud-Konto verknüpfte Gerät kann den Synchronisierungsstatus möglicherweise nicht neu bewerten, da dieser zwischengespeichert wird.

Der iCloud-Kontoinhaber kann ein Gerät auslösen, um die Synchronisierungsbedingungen für das Anrufprotokoll anhand der folgenden Schritte erneut zu überprüfen:

Navigieren Sie zu Settings > [username] > iCloud .
Schalten Sie iCloud Drive aus und warten Sie 30 bis 60 Sekunden, bis die Änderung wirksam wird.
Schalten Sie iCloud Drive ein, sobald die vorherige Änderung abgeschlossen ist. Dies sollte die Initialisierung auslösen.

Fehlerbehebung

Der Verlauf der letzten Anrufe wird in den Umfrageergebnissen nicht zurückgegeben.

Dies wird normalerweise dadurch verursacht, dass das Gerät seine letzten Anruflisteneinträge nicht mit der iCloud synchronisiert hat. Der CallKit-Dienst ist ein interner iOS-Dienst und kann in den Einstellungen nicht aktiviert oder deaktiviert oder manuell synchronisiert werden. Dies kann das Debuggen fehlender Daten erschweren, da unklar ist, welches Gerät mit der iCloud synchronisiert wurde oder nicht.

Dieses Problem tritt häufiger bei Konten auf, bei denen nicht viele Daten synchronisiert werden müssen (weniger als ~ 3 Anrufe), was beim Testen von Konten häufig der Fall ist.

Empfehlungen:

Vergewissern Sie sich, dass auf dem Gerät mehr als eine Handvoll Anruflistenaufzeichnungen synchronisiert werden müssen. Unsere Tests haben gezeigt, dass ein Gerät mit nur wenigen Anruflisteneinträgen den iCloud-Synchronisierungsprozess nicht auslöst.
Warten Sie, bis das Gerät eine regelmäßige Synchronisierung durchgeführt hat. Dies kann bis zu 12 Stunden dauern, je nachdem, wie das Gerät verwendet wird, in welchem Konnektivitäts- und Ladezustand es sich befindet.
Stecken Sie das Gerät in die Steckdose. In diesem Zustand löst das Gerät eher eine Synchronisierung aus.
Das alte Anrufprotokoll wird in den Umfrageergebnissen nicht zurückgegeben.

Der CallKit-Dienst dient zum Synchronisieren von Anruflisteneinträgen zwischen Geräten und nicht zum unbegrenzten Speichern dieser Einträge. In der Regel können Anrufverlaufsdatensätze für ca. 3 Monate aus CallKit abgerufen werden. Dies kann jedoch je nach internen Bereinigungsprozessen in der iCloud zwischen den Konten variieren.

CloudKit

Browserverlauf aus iCloud cloudkit_safari.history

Rufen Sie im iCloud-Synchronisierungsdienst gespeicherte Safari-Browserverlaufsdaten ab.

Find My and Find My iPhone

Device locations

Retrieve Find My device and location data.

Note that this data type may require multiple polls, with the second coming ~10-30 seconds after the first, in order to return complete data. This is due to how Find My operates: the first poll will trigger Find My to request new data from reachable devices but the data will not be available for another 10-30 seconds.


Data type ID	`fmip.devices`
Associated setting	`Settings` > `[username]` > `Find My`

Data attributes

Name	Art	Beschreibung
`id`	string	An identifier for the data item. Useful for deduplicating data across multiple polls.
`data_type`	string, always `fmip.devices`	The data type of the item.
`name`	string	The user set name for the device.
`model_name`	string	Apple's marketing name for the device model.
`model_identifier`	string	Apple's identifier for the device model.
`product_type`	string	The product category of the device.
`location`	optional nested `location`	The last reported location for the device, if one is available.
`battery_status`	string	The current battery status of the device.
`battery_level`	float	If known, the percentage battery charge remaining.

Sample data

[
  {
    "id": "e7694d7a0d2ab6cf",
    "data_type": "fmip.device",
    "name": "John's iMac",
    "model_name": "iMac with Retina 5K display",
    "model_identifier": "iMac15,1",
    "product_type": "iMac",
    "location": null,
    "battery_status": "Unknown",
    "battery_level": 0.0
  },
  {
    "id": "4d86a6181808d152",
    "data_type": "fmip.device",
    "name": "John's iPhone 11",
    "model_name": "iPhone 11",
    "model_identifier": "iPhone6,2",
    "product_type": "iPhone",
    "location": {
      "data_type": "location",
      "latitude": 51.507452392689146,
      "longitude": -0.07398372304584414,
      "altitude": 0.0,
      "horizontal_accuracy": 65.0,
      "vertical_accuracy": 0.0,
      "positioning_type": "Wifi",
      "date_created": "2020-01-01T00:00:00.000000Z"
    },
    "battery_status": "Unknown",
    "battery_level": 0.0
  }
]

Datentypen

identifier	description
`icpl`	A file from iCloud Photo Library.
`mme_contact_image`	An `mme_contacts.contacts` contact profile image.

Sitzungen

Creating a session for an account without 2FA/2SV

Creating a session for an account with 2FA

Step 1: create session

Step 2: create session with code

Creating a session for an account with 2SV

Step 1: create session

Step 2: create session with choice

Step 3: create session with code

Quelltypen

Umfragen

Quelleninformationen werden abgerufen

Daten abrufen

Dateien werden abgerufen

Datentypen

iCloud Photo Library

Photos, videos and other media

MobileMe Contacts

Contacts

MobileMe Calendar events mme_calendar.events

MobileMe Notes notes mme_notes.notes

CallKit

CloudKit

Find My and Find My iPhone

Device locations

Datentypen

Wie können wir helfen?

MobileMe Calendar events `mme_calendar.events`

MobileMe Notes notes `mme_notes.notes`