Service Apple iCloud (v2)

Mis à jour

Le service icloud l'API ricloud fournit une fonctionnalité permettant d'accéder aux informations stockées sur iCloud, à la fois sous forme de lot à partir de sauvegardes d'appareils iOS, et en temps réel et à proximité d'autres sources. L'API prend en charge l'accès à iCloud depuis sa version d'origine.

Un client peut devoir effectuer quatre opérations principales avec le service iCloud.

  • Authentification: log-in , perform-2fa-challenge , submit-2fa-challenge
  • Énumération de périphériques: list-devices
  • Demande de flux: fetch-data
  • Demande de fichiers bruts: fichier de download-file

Travailler avec des données fictives de l'API

Afin de faciliter le développement des intégrations avec l'API, un compte fictif contenant un ensemble de données enrichies est mis à disposition. Cela permet aux clients de tester de nombreuses fonctions de l'API ricloud sans avoir à travailler avec de vraies données utilisateur.

Le compte john.appleseed@reincubate.com s'appelle Jonny Appleseed et est accessible à l'aide de l'ID de compte iCloud john.appleseed@reincubate.com et du mot de passe joshua .

Authentification

Se log-in : se log-in

La première étape pour interagir avec le service icloud est la connexion.

Pour la demande, il faut spécifier:

  • Le service pour interagir avec: icloud
  • L' action à effectuer: se log-in
  • Le paramètre account , représentant l'ID de compte iCloud tel que john.appleseed@reincubate.com
  • Les paramètres d'action requis par l'action, qui dans ce cas n'est que password
  • Nous pouvons également spécifier des paramètres d’action facultatifs répertoriés par /account/ endpoint
$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>"
    -d "service=icloud" \
    -d "action=log-in" \
    -d "account=<ACCOUNT>" \
    -d "password=<PASSWORD>" \
    <TASK_SUBMISSION_ENDPOINT>

Le point de terminaison asapi répondra, au format JSON:

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

Si vous êtes connecté au point de terminaison stream_end correct sur le point de terminaison aschannel , vous verrez un résultat correspondant au <TASK_ID_1> vous avez reçu du point de terminaison asapi .

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

Les résultats incluront un paramètre de success qui sera vrai si la tâche de connexion aboutit, avec un message et un jeton d'authentification Apple à utiliser avec d'autres actions de service.

Dépannage de la connexion

Veuillez consulter la section sur les réponses d'erreur de connexion pour les définitions d'erreur et les solutions.

2FA et 2SV

Après avoir tenté de vous connecter à un compte iCloud configuré avec 2SV ou 2FA, la connexion normale échouera et un message d'erreur similaire à celui présenté ci-dessous sera renvoyé.

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

Le dictionnaire de data contiendra une liste de périphériques, indexée par device_id . Ce sont les appareils approuvés par le compte iCloud pour effectuer la prochaine étape d'authentification.

Pour la vérification en deux étapes (2SV)

Dans le cas de 2SV, la liste des trustedDevices de trustedDevices contient un ou plusieurs périphériques. Les clients doivent sélectionner un périphérique répertorié à contester.

Pour ce faire, exécutez perform-2fa-challenge avec un challenge défini sur la clé du périphérique choisi à partir de trustedDevices .

Pour l'authentification à deux facteurs (2FA)

Dans le cas de 2FA, la liste des trustedDevices de trustedDevices sera définie sur ["Challenge all 2FA devices"] , indiquant qu'un défi doit être envoyé à tous les appareils iOS connectés à ce compte. Ceci est effectué en exécutant perform-2fa-challenge avec challenge défini sur la valeur de ["Challenge all 2FA devices"] .

Utiliser perform-2fa-challenge

Cette méthode enverra une demande en temps réel à tous les périphériques du compte dans le cas de 2FA, ou au périphérique choisi dans le cas de 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 vous répondra comme d'habitude:

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

Le point d'extrémité de récupération répondra avec:

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

Une fois le défi envoyé au périphérique de l'utilisateur, le code à deux facteurs doit être retransmis à l'API à l'aide de submit-2fa-challenge . Dans la demande ci-dessous, <CODE> est le code numérique fourni par l'utilisateur final, qui représente les codes transmis à l'appareil pour la connexion 2FA / 2SV.

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

asapi vous répondra comme d'habitude:

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

Le point d'extrémité de récupération répondra par un message de connexion normal:

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

Actualisation d'une connexion à un compte à l'aide de jetons d'authentification

ricloud fournit des jetons d'authentification à utiliser pour actualiser une connexion sans avoir à utiliser les informations d'identification complètes d'iCloud. Les utilisateurs du mécanisme de création de jetons n'ont pas besoin de conserver leurs informations d'identification.

Pour ce faire, les clients doivent utiliser le champ auth_token récupéré lors de la connexion. Cela doit être envoyé au point de terminaison de l'action de service refresh-session .

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

Ceci fait, toute action de service peut être effectuée contre le service.

Énumération de périphériques

Énumération de périphériques: list-devices

Une fois connectés à un compte, les clients peuvent énumérer les périphériques et les sauvegardes de périphériques associés au compte iCloud. Ceci est effectué en effectuant l'action list-devices sur le service iCloud.

Cela se fait de la même manière que toute autre action de service. Voici un exemple de requête curl à cette action. Le paramètre <ACCOUNT> ci-dessous peut être renseigné avec un identifiant de compte, tel que john.appleseed@reincubate.com .

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

Le point de terminaison asapi répondra, au format JSON:

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

Votre résultat apparaîtra sous peu sur le noeud final de récupération. Voici un exemple de réponse:

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

Cette réponse contient l' auth_token pour la session iCloud du compte spécifié, ainsi qu'une liste des périphériques associés à ce compte dans la section des devices . Chaque entrée de périphérique contient les clés suivantes:

  • ios_version : la version iOS de l'appareil
  • colour : colour appareil sous forme de code hexadécimal
  • device_name : nom du périphérique tel que défini par l'utilisateur
  • latest-backup : La date à laquelle le périphérique a été sauvegardé pour la dernière fois sur iCloud
  • model : le numéro de modèle de l'appareil
  • serial : Le numéro de série de l'appareil
  • name : name du produit de l'appareil tel qu'annoncé par Apple

Demande de flux

Récupération des données de fil: fetch-data

L'action d' fetch-data permet d'accéder aux flux de données JSON à partir de l'API. Il nécessite les paramètres suivants:

  • device : le périphérique sur lequel récupérer les données
  • data : un CSV des modules de flux demandé

Les paramètres facultatifs sont:

  • since : la période à partir de laquelle les résultats doivent correspondre

Vous trouverez ci-dessous un exemple d'action 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.

Par exemple, en utilisant la valeur sms dans <FEED_MODULES> dans la commande ci-dessus, vous pouvez accéder à SMS, MMS et iMessages dans une sauvegarde. En utilisant la valeur sms,whatsapp_messages,snapchat_messages dans <FEED_MODULES> dans la commande, vous pouvez accéder aux SMS, MMS et iMessages, messages WhatsApp et Snapchat, tous dans le même résultat JSON.

L' asapi répondra avec:

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

Peu de temps après, les résultats apparaîtront sur le noeud final avec le même 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
    }
  ]
}

D'autres modules de fil fournissent des informations pouvant être utilisées pour accéder à d'autres formes de contenu. Par exemple, une action d' fetch-data utilisant "photos" comme <FEED_MODULES> pour un périphérique donné ressemblerait à ceci:

$ 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>

Asapi répondra avec:

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

Le résultat suivant apparaîtra sur le noeud final approprié:

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

Formats de flux JSON

Les flux JSON sont conçus pour être aussi simples à analyser que possible. Le flux renverra tous les types de données demandés dans une seule réponse.

Chaque module de flux spécifié dans l'indicateur de module aura sa propre clé dans le dictionnaire JSON de niveau supérieur renvoyé.

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

Demander des fichiers bruts

Récupération des fichiers bruts: fichier de download-file

L'action de download-file est disponible pour télécharger des fichiers ou des pièces jointes de message directement à partir d'iCloud. Les paramètres nécessaires sont le <DEVICE_ID> cible et un <FILE_ID> .

Certains modules de flux, y compris les modules file_list et photo contiennent des références à des fichiers ou des pièces jointes disponibles au téléchargement. Ceux-ci contiennent un <FILE_ID> utilisé pour identifier et télécharger le fichier, ainsi que des métadonnées supplémentaires telles que filename de filename , file_path , size et type . S'il vous plaît voir Extracteurs d'information pour plus de détails.

La commande

$ 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 répondra par:

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

Peu de temps après, les résultats apparaîtront sur le noeud final avec le même task_id .

Dépannage des réponses d'erreur

Réponses d'erreur générales

Le tableau suivant indique les codes d'erreur pouvant être générés par toute action.

Réponse Résumé
task-failed Échec inconnu
deactivated-account Compte désactivé
deactivated-device Appareil désactivé
client-account-disabled Jeton d'API désactivé
account-locked Compte bloqué
account-credentials-blocked Compte verrouillé et protégé
push-api-timeout Temporisation interne
icloud-unauthorised Délai de session Apple
service-inactive-error Service Apple non initialisé

Échec inconnu

La tâche de connexion a échoué et la raison était inconnue. En cas d’échec de la tâche avec ce code, les clients doivent contacter l’équipe de support .

Compte désactivé

Cela signifie que le compte a été désactivé à l'aide de la commande de gestion de la désactivation du compte. Il ne sera accessible que si une commande d'activation manuelle est envoyée.

Appareil désactivé

Cela signifie que le périphérique a été désactivé à l'aide de la commande de gestion de la désactivation du périphérique. Il ne sera accessible que si une commande d'activation manuelle est envoyée.

Jeton d'API désactivé

Le jeton utilisé pour accéder à l'API a été désactivé. Veuillez contacter l'équipe de support.

Temporisation interne

Si la session de l'API expire lors de l'exécution d'autres actions de service, les clients recevront le code d'erreur: push-api-timeout et devront se reconnecter.

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

iCloud non autorisé

Si la session avec Apple a expiré avant ou est invalidée pendant une action, celle-ci doit être abandonnée et la session doit être rétablie par une nouvelle authentification via une nouvelle tâche de log-in . L'utilisation de refresh-session ne fonctionnera pas dans ce cas car le jeton utilisé pour cet appel est lié à la session avec Apple qui a maintenant expiré.

Dans certains cas, une session peut devenir partiellement expirée. Par exemple, list-devices renvoie toujours une list-devices valide et à jour, mais fetch-data échoue avec icloud-unauthorised . Dans ce cas, la session peut continuer à être utilisée pour des données accessibles, mais doit être entièrement actualisée en utilisant une tâche de log-in afin d'obtenir des données supplémentaires.

Erreur de service inactif

Cette réponse est renvoyée si l'API a tenté d'initialiser un service mais a reçu une réponse d'Apple indiquant qu'il n'a pas été inactivé sur le compte de l'utilisateur. Veuillez vérifier le paramètre correspondant au type de données interrogé et vous assurer qu'il est activé et initialisé.

Réponses d'erreur de connexion

Le tableau suivant submit-2fa-challenge les codes d'erreur que les actions de log-in et de submit-2fa-challenge peuvent générer, en plus des codes généraux ci-dessus.

Réponse Résumé
unable-to-login Les informations d'identification sont incorrectes
2fa-required 2FA requis
invalid-2fa-code Code 2FA invalide
too-many-2fa-requests Taux 2FA limité
account-locked Compte bloqué
account-credentials-blocked Compte verrouillé et protégé
terms-of-service-update-client Conditions de service non acceptées
session-creation-error Erreur récupérable lors de l'initialisation de la session
session-corrupt-error Erreur non récupérable lors de l'initialisation de la session

Les informations d'identification sont incorrectes

Les informations d'identification spécifiées pour le compte étaient incorrectes et l'authentification est impossible.

2FA requis

La connexion à des comptes utilisant une authentification à deux facteurs (2FA) ou une vérification en deux étapes (2SV) nécessite certaines étapes supplémentaires. Voir les sections "2FA et 2SV" ci-dessous.

Code 2FA invalide

Un code 2FA non valide ou autrement incorrect a été envoyé en réponse au défi 2FA.

Taux 2FA limité

Récemment, trop de demandes 2FA ont été envoyées pour le compte: le débit a été limité. Réessayez après 30 minutes.

Compte bloqué

Le compte iCloud a été verrouillé par Apple. Si une autre tentative d'accès au compte est effectuée sur une courte période, une erreur account-credentials-blocked est renvoyée.

Compte verrouillé et protégé

Le compte iCloud a été verrouillé par Apple et ricloud a déjà informé le client avec le account-locked . Ce message est substitué pour indiquer que le service ne transmet pas la demande à Apple.

Conditions de service non acceptées

Le compte iCloud est désactivé dans l'attente de l'acceptation des derniers termes et conditions d'iCloud. L'utilisateur peut les accepter sur son appareil ou en se connectant à icloud.com.

Erreur de création de session

Le système back-end d'iCloud a généré une erreur lors de l'initialisation de la session, mais une nouvelle tentative résoudra probablement le problème et aboutira.

Erreur de session corrompue

Le backend iCloud a répondu par une erreur lors de l'initialisation de la session et les nouvelles tentatives n'entraîneront pas un résultat différent. Veuillez contacter le support (de préférence avec les informations d'identification du compte) afin que ce cas d'extrémité puisse être examiné.

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 4:42 Matin 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 - 2019 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. Confidentialité et modalités. Nous recommandons l'authentification multi-facteurs. Construit avec à Londres.