Service Apple iCloud

L'API prend en charge la récupération d'une variété de données et de fichiers à partir des services iCloud d'Apple.

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.

Création d'une session pour un compte sans 2FA / 2SV

La charge utile de session pour créer une session pour un compte sans 2FA / 2SV activé contient les paramètres suivants.

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

Réponse

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

Création d'une session pour un compte avec 2FA

La création d'une session pour un compte compatible 2FA est un processus en deux étapes:

1. Essayez de créer une session en utilisant uniquement le mot de passe du compte iCloud. Cela déclenchera le processus 2FA, qui envoie un code d'authentification aux appareils iOS et macOS associés au compte. La tentative de création de session échouera avec error="code-required" .
2. Utilisez le mot de passe du compte iCloud et le code d'authentification reçu en (1) pour créer une session. Si le code est accepté, la session sera créée avec succès.

Étape 1: créer une session

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

Réponse

Si le processus 2FA est déclenché comme prévu, la session ne doit pas être créée avec l'erreur: code-required .

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

Étape 2: créer une session avec du 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>"
  }
}'

Réponse

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

Création d'une session pour un compte avec 2SV

Le processus de création d'une session pour un compte compatible 2SV comprend trois étapes:

1. Essayez de créer une session à l'aide du mot de passe du compte iCloud. Comme 2SV est requis, cela échouera avec error="choice-required" et error_info={"choices": [<2SV enabled devices>]} .
2. Essayez de recréer une session à l'aide du mot de passe du compte iCloud et d'un choix dans la liste error_info["choices"] . Cette fois, la tentative déclenchera le processus 2SV qui envoie un code d'authentification à l'appareil choisi. La tentative échouera avec error="code-required" .
3. Utilisez le mot de passe du compte iCloud et le code d'authentification reçu en (2) pour créer une session. Si le code est accepté, la session sera créée avec succès.

Cela déclenchera le processus 2SV, qui envoie un code d'authentification aux appareils iOS et macOS associés au compte. La tentative de création de session échouera avec error="code-required" .

Étape 1: créer une session

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

Réponse

Si 2SV est activé sur le compte, la tentative de création de session échouera avec un choice-required erreur choice-required .

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

Étape 2: créer une session avec choix

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

Réponse

Si le processus 2FA est déclenché comme prévu, la session ne doit pas être créée avec l'erreur: code-required .

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

Étape 3: créer une session avec du 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>"
  }
}'

Réponse

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

Types de source

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

L'attribut de charge utile d'interrogation des files est utilisé pour demander la récupération des fichiers binaires de la source ciblée.

Les ID seront généralement récupérés à partir d'un sondage précédent pour les types de données qui incluent des références de fichier directes, comme la bibliothèque de photos iCloud, ou qui incluent des pièces jointes, comme les types de données de message.

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

Photothèque iCloud

Photos, vidéos et autres médias

Récupère des informations sur les photos, vidéos et autres supports stockés dans la bibliothèque de photos iCloud (ICPL).

Ce module nécessite que la bibliothèque de photos iCloud soit activée sur le compte iCloud de l'utilisateur.

Attributs de données

Filtres de données

Exemples de données

[
  {
    "id": "7f1384f5038255f5",
    "data_type": "icpl.asset",
    "filename": "IMG_0002.HEIC",
    "files": [
      {
        "id": "icpl://AWo/lDeN8fEExAUJajRHzVx2j605",
        "data_type": "image",
        "extension": "heic",
        "size": 905818,
        "width": 4032,
        "height": 3024
      },
      {
        "id": "icpl://ASDPdJ/LvFWjsBy4YOOp7B5c+XOi",
        "data_type": "video",
        "extension": "mov",
        "size": 2456163,
        "width": 980,
        "height": 1308
      },
      {
        "id": "icpl://ASAwWOvwrvAUuO71uXcU6mm+nMU4",
        "data_type": "image",
        "extension": "jpg",
        "size": 595624,
        "width": 1536,
        "height": 2048
      },
      {
        "id": "icpl://ATy/qmemCas1jzYWuhR4mQywhpzz",
        "data_type": "image",
        "extension": "jpg",
        "size": 65407,
        "width": 360,
        "height": 480
      }
    ],
    "date_created": "2020-09-18T12:32:17Z",
    "date_uploaded": "2020-09-18T12:41:19Z",
    "local_date_created": "2020-09-18T13:32:17+01:00"
  }
]

Contacts MobileMe

Contacts

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

Attributs de données

Le type de données mme_contacts.contact hérite de la plupart des attributs du type de données de contact base. Le tableau ci-dessous présente les attributs supplémentaires ou différents.

Exemples de données

[
  {
    "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"
    }
  }
]

Événements du calendrier MobileMe mme_calendar.events

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

Notes MobileMe 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 et Find My iPhone

Emplacements des appareils

Récupérez les données de localisation de mon appareil et de localisation.

Notez que ce type de données peut nécessiter plusieurs sondages, le second venant ~ 10-30 secondes après le premier, afin de renvoyer des données complètes. Cela est dû au fonctionnement de Find My: le premier sondage déclenchera Find My pour demander de nouvelles données aux appareils accessibles, mais les données ne seront pas disponibles avant 10 à 30 secondes.

Attributs de données

Exemples de données

[
  {
    "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