Service Apple iCloud

Mis à jour

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

Sessions

La configuration d'une session pour les services iCloud sur l'API est aussi simple que la connexion à un compte iCloud. Le processus peut nécessiter plusieurs tentatives de création de session si le compte a activé l'authentification multi-facteurs, telle que 2FA ou 2SV.

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.

Utiliser cURL

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:

  1. 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".
  2. 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.

Utiliser cURL

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.

Utiliser cURL

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:

  1. 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>]}.
  2. 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".
  3. 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.

Utiliser cURL

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.

Utiliser cURL

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.

Utiliser cURL

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,
  ...
}

Types de source

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

Les sondages

Le service iCloud prend en charge tous les attributs du schéma de charge utile d'interrogation.

Récupération des informations sur la source

Ce type d'interrogation récupère des informations sur la source ciblée. Les résultats sont publiés au format JSON.

Utiliser cURL

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": ["*"]
  }
}'

Utiliser * 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": ["*"]
  }
)

Récupération des données

Ce type d'interrogation récupère et traite les données de la session ciblée. Les résultats sont publiés au format JSON.

Consultez la liste des types de données disponibles pour plus d'informations sur des types de données spécifiques.

Utiliser cURL

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

Utiliser * 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,
)

Récupérer des fichiers

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.

Utiliser cURL

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

Utiliser * 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,
)

Types de données

Types de données iCloud

identifiant la description
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 Récupère les données iOS Notes stockées dans iCloud.
callkit.calls Récupère les données du téléphone iOS synchronisées par CallKit.
cloudkit_safari.history Récupérez les données d'historique du navigateur Safari stockées dans iCloud.
fmip.devices Récupérez les données de localisation de mon appareil iPhone.

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

prénom type la description
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.

prénom type la description
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

Récupère les données de calendrier iOS stockées dans iCloud.

MobileMe Notes notes mme_notes.notes

Récupère les données iOS Notes stockées dans iCloud.

CallKit

Appels de CallKit callkit.calls

Récupère les journaux d'appels synchronisés avec le service CallKit.

les erreurs

callkit-uninitialised

Indique que le service CallKit n'a pas été configuré pour ce compte. Le propriétaire du compte iCloud peut résoudre cette erreur à l'aide d'un périphérique iOS associé au compte iCloud en procédant comme suit: - Assurez-vous que le périphérique est connecté au Wi-Fi. - Accédez à Settings > [username] > iCloud . - Mettez iCloud Drive hors tension en attendant 30 à 60 secondes pour que le changement prenne effet. - Allumez iCloud Drive une fois la modification précédente terminée. Cela devrait déclencher l'initialisation.

Si l'erreur persiste après l'exécution de ce processus, veuillez contacter le support.

callkit-sync-disabled

Dans ce cas, le service CallKit a été initialisé, mais les conditions nécessaires pour que les appareils commencent à synchroniser l'historique des appels sur iCloud ne sont pas remplies. L'API résoudra ce problème à distance via iCloud, mais le périphérique associé au compte iCloud peut ne pas réévaluer son état de synchronisation car celui-ci est mis en cache.

Le propriétaire du compte iCloud peut demander à un appareil de revérifier les conditions de synchronisation de l'historique des appels en procédant comme suit:

  • Accédez à Settings > [username] > iCloud .
  • Mettez iCloud Drive hors tension en attendant 30 à 60 secondes pour que la modification soit prise en compte.
  • Allumez iCloud Drive une fois la dernière modification effectuée. Cela devrait déclencher l'initialisation.

Dépannage

  • L'historique des appels récents n'est pas renvoyé dans les résultats du sondage.

Cela est généralement dû au fait que l'appareil n'a pas synchronisé ses derniers enregistrements d'historique d'appels avec iCloud. Le service CallKit est un service iOS interne et ne peut pas être activé ou désactivé dans les paramètres ni déclencher la synchronisation manuelle. Cela peut rendre difficile le débogage des données manquantes car il est difficile de savoir ce que le périphérique a synchronisé ou non avec iCloud.

Ce problème est plus courant pour les comptes qui n'ont pas beaucoup de données à synchroniser (moins de ~ 3 appels), ce qui peut souvent être le cas pour les comptes de test.

Recommandations:

  • Assurez-vous que l'appareil dispose de plus d'une poignée d'enregistrements d'historique d'appels à synchroniser. Nos tests ont montré qu'un appareil avec seulement quelques enregistrements d'historique d'appels ne déclenchera pas le processus de synchronisation iCloud.
  • Attendez que le périphérique effectue une synchronisation périodique. Cela peut prendre jusqu'à 12 heures en fonction de l'utilisation du périphérique, de son état de connectivité et de son état de charge.
  • Branchez l'appareil au pouvoir. Le périphérique est plus susceptible de déclencher une synchronisation dans cet état.

  • L’ancien historique des appels n’est pas renvoyé dans les résultats du sondage.

Le service CallKit est conçu pour synchroniser les enregistrements de l'historique des appels entre les périphériques et non pour stocker ces enregistrements indéfiniment. En règle générale, les enregistrements de l'historique des appels peuvent être récupérés depuis CallKit pendant environ 3 mois, mais cela peut varier d'un compte à l'autre en fonction des processus de nettoyage internes dans iCloud.

CloudKit

Historique du navigateur de iCloud cloudkit_safari.history

Récupérez les données d'historique du navigateur Safari stockées dans le service de synchronisation iCloud.

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

prénom type la description
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
  }
]

Types de fichier

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

Comment pouvons nous aider?

Notre équipe de support est là pour vous aider!

Nos bureaux sont ouverts du lundi au vendredi, de 9 h à 17 h GMT. L’heure est actuellement 6:54 Après-midi GMT.

Notre objectif est de répondre à tous les messages en un jour ouvrable.

Aller à la section support › Contacter l'équipe de l'entreprise ›
Notre superbe équipe de support

© 2008 - 2020 Reincubate Ltd. Tous droits réservés. Enregistré en Angleterre et au Pays de Galles #5189175, VAT GB151788978. Reincubate® est une marque déposée. Politique de confidentialité & termes. Nous recommandons l'authentification multi-facteurs. Construit avec à Londres.