Servicio Apple iCloud (v2)
La API de ricloud icloud servicio proporciona funcionalidad para acceder a la información almacenada en el iCloud, tanto en forma de lotes de copias de seguridad de dispositivos iOS, y en tiempo real y casi en tiempo de otras fuentes. La API ha admitido el acceso a iCloud desde su versión original.
Hay cuatro operaciones principales que un cliente puede necesitar realizar con el servicio iCloud.
- Autenticación:
log-in,perform-2fa-challenge,submit-2fa-challenge - Enumeración de dispositivos:
list-devices - Solicitando feeds:
fetch-data - Solicitando archivos en bruto:
download-file
Trabajando con datos simulados desde la API
Con el fin de ayudar al desarrollo de las integraciones con la API, se pone a disposición una cuenta simulada con un conjunto de datos enriquecidos. Esto permite a los clientes probar muchas de las funciones de la API de ricloud sin necesidad de trabajar con datos de usuarios reales.
La cuenta simulada se llama Jonny Appleseed y se puede acceder utilizando la ID de cuenta de iCloud john.appleseed@reincubate.com y la contraseña joshua .
Autenticación
Iniciar log-in : log-in
El primer paso para interactuar con el servicio icloud es iniciar sesión.
Para la solicitud, debemos especificar:
- El
servicepara interactuar con:icloud - La
actiona realizar:log-in - La
accountparámetros, que representa el ID de cuenta de iCloud, comojohn.appleseed@reincubate.com - Los parámetros de acción requeridos por la acción, que en este caso es solo una
password - También podemos especificar los parámetros de acción opcionales enumerados por
/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>
El punto final asapi responderá, en formato JSON:
{ "retrieval_protocol": "aschannel", "stream": "<STREAM>", "success": true, "task_id": "<TASK_ID_1>" }
Si está conectado al stream_endpoint correcto en el punto final de un canal , verá un resultado que coincide con el <TASK_ID_1> que recibió del punto final de asapi .
{ "message": "Log-in successful", "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG", "success": true }
Los resultados incluirán un parámetro de success que será verdadero si la tarea de inicio de sesión tuvo éxito, junto con un mensaje y un token de autenticación de Apple para usar con otras acciones de servicio.
Solución de problemas de inicio de sesión
Consulte la sección sobre respuestas de error de inicio de sesión para obtener definiciones y soluciones de errores.
2FA y 2SV
Después de intentar iniciar sesión en una cuenta de iCloud que está configurada con 2SV o 2FA, el inicio de sesión normal fallará y se mostrará un mensaje de error similar al que se muestra a continuación.
{ "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" }
El diccionario de data contendrá una lista de dispositivos, codificada por device_id . Estos son los dispositivos en los que la cuenta de iCloud confía para realizar el siguiente paso de autenticación.
Para la verificación de dos pasos (2SV)
En el caso de 2SV, la lista de trustedDevices contendrá uno o más dispositivos. Los clientes deben seleccionar un dispositivo listado para desafiar.
Esto se realiza ejecutando perform-2fa-challenge con challenge establecido en la clave del dispositivo elegido desde trustedDevices .
Para la autenticación de dos factores (2FA)
En el caso de 2FA, la lista de trustedDevices de trustedDevices se establecerá en ["Challenge all 2FA devices"] , lo que indica que se debe enviar un desafío a todos los dispositivos iOS conectados a esa cuenta. Esto se realiza ejecutando perform-2fa-challenge con challenge establecido en el valor de ["Challenge all 2FA devices"] .
Utilizando perform-2fa-challenge
Este método enviará una solicitud en tiempo real a todos los dispositivos en la cuenta en el caso de 2FA, o el dispositivo elegido en el caso 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 responderá como siempre:
{ "retrieval_protocol": "aschannel", "stream": "<STREAM>", "success": true, "task_id": "<TASK_ID_X>" }
El punto final de recuperación responderá con:
{ "message": "Challenge has been submitted.", "success": true }
Una vez que el desafío se ha enviado al dispositivo del usuario, el código de dos factores debe retransmitirse a la API utilizando submit-2fa-challenge . En la solicitud a continuación, <CODE> es el código numérico proporcionado por el usuario final, que representa los códigos transmitidos al dispositivo para el inicio de sesión de 2FA / 2SV.
$ curl \ -X POST \ -H "Authorization: Token <TOKEN>" -d "service=icloud" \ -d "action=submit-2fa-challenge" \ -d "code=<CODE>" \ <TASK_SUBMISSION_ENDPOINT>
asapi responderá como siempre:
{ "retrieval_protocol": "aschannel", "stream": "<STREAM>", "success": true, "task_id": "<TASK_ID_X>" }
El punto final de recuperación responderá con un mensaje de inicio de sesión normal:
{ "message": "Log-in successful", "auth_token": "ABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFGABCDEFG", "success": true }
Actualizar un inicio de sesión de cuenta utilizando tokens de autenticación
ricloud proporciona tokens de autenticación para usar en la actualización de inicios de sesión sin la necesidad de usar credenciales completas de iCloud. Los usuarios del mecanismo de tokenización no necesitan conservar ninguna credencial de usuario.
Para hacer esto, los clientes deben usar el campo auth_token recuperado durante el inicio de sesión. Esto debe enviarse al punto final de acción del servicio de 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>
Con esto hecho, cualquier acción de servicio se puede realizar contra el servicio.
Enumeración de dispositivos
Enumeración de dispositivos: list-devices
Al iniciar sesión en una cuenta, los clientes pueden enumerar los dispositivos y las copias de seguridad del dispositivo asociadas con la cuenta de iCloud. Esto se hace ejecutando la acción list-devices contra el servicio iCloud.
Esto se hace de la misma manera que cualquier otra acción de servicio. Aquí hay un ejemplo de solicitud de curl para esta acción. El parámetro <ACCOUNT> continuación se puede completar con un ID de cuenta, como john.appleseed@reincubate.com .
$ curl \ -X POST \ -H "Authorization: Token <TOKEN>" -d "service=icloud" \ -d "action=list-devices" \ -d "account=<ACCOUNT>" \ <TASK_SUBMISSION_ENDPOINT>
El punto final asapi responderá, en formato JSON:
{ "retrieval_protocol": "aschannel", "stream": "<STREAM>", "success": true, "task_id": "<TASK_ID_2>" }
Su resultado aparecerá en breve en el punto final de recuperación. A continuación se muestra un ejemplo de respuesta:
{ "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" } } }
Esta respuesta contiene el auth_token para la sesión de iCloud de la cuenta especificada, junto con una lista de dispositivos asociados con esa cuenta en la sección de devices . Cada entrada de dispositivo contiene las siguientes claves:
-
ios_version: la versión iOS del dispositivo -
colour: el color del dispositivo como un código hexadecimal -
device_name: el nombre del dispositivo definido por el usuario -
latest-backup: la fecha en que se realizó lalatest-backupdel dispositivo en iCloud -
model: el número de modelo del dispositivo -
serial: el número de serie del dispositivo -
name: elnamedel producto del dispositivo como lo anuncia Apple
Solicitando feeds
Recuperación de los datos de alimentación: datos de fetch-data
La acción de fetch-data se utiliza para acceder a las fuentes de datos JSON desde la API. Requiere los siguientes parámetros:
-
device: el dispositivo para recuperar datos de o sobre -
data: Un CSV de los módulos de alimentación solicitados.
Los parámetros opcionales son:
-
since: el período de tiempo desde el cual los resultados deben corresponder
A continuación se muestra un ejemplo fetch-data acción de 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.
Por ejemplo, al usar el valor sms en <FEED_MODULES> en el comando anterior, se puede acceder a SMS, MMS e iMessages en una copia de seguridad. Usando el valor sms,whatsapp_messages,snapchat_messages en <FEED_MODULES> en el comando podemos acceder a SMS, MMS e iMessages, mensajes de WhatsApp y mensajes de Snapchat, todo en el mismo resultado JSON.
El asapi responderá con:
{ "retrieval_protocol": "aschannel", "stream": "<STREAM>", "success": true, "task_id": "<TASK_ID_3>" }
Poco después, los resultados aparecerán en el punto final de resultados con el mismo 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 } ] }
Otros módulos de alimentación proporcionan información que se puede utilizar para acceder a otras formas de contenido. Por ejemplo, una acción de <FEED_MODULES> fetch-data que usa 'fotos' como <FEED_MODULES> para un dispositivo dado se vería así:
$ 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>
Hará que asapi responda con:
{ "retrieval_protocol": "aschannel", "stream": "<STREAM>", "success": true, "task_id": "<TASK_ID_4>" }
El siguiente resultado aparecerá en el punto final apropiado:
{ "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" }] }
Formatos de alimentación JSON
Los feeds JSON están diseñados para ser lo más sencillos de analizar que sea posible. La fuente devolverá todos los tipos de datos solicitados en una sola respuesta.
Cada módulo de alimentación especificado en el indicador de módulo tendrá su propia clave en el diccionario JSON de nivel superior que se devuelve.
{ "first_module_name": "Module's data", "second_module_name": "Module's data", "etc.": "etc." }
Solicitando archivos en bruto
Recuperación de archivos en bruto: download-file
La acción de download-file está disponible para descargar archivos o adjuntos de mensajes directamente desde iCloud. Los parámetros necesarios son el objetivo <DEVICE_ID> y un <FILE_ID> .
Algunos de los módulos de alimentación, incluidos la lista de file_list y los módulos de fotos, contienen referencias a archivos o archivos adjuntos disponibles para descargar. Estos contienen un <FILE_ID> usa para identificar y descargar el archivo y, a menudo, algunos metadatos adicionales, como filename , file_path , size y type . Por favor, consulte los extractores de información para más detalles.
El comando
$ 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 responderá con:
{ "retrieval_protocol": "aschannel", "stream": "<STREAM>", "success": true, "task_id": "<TASK_ID_5>" }
Poco después aparecerán los resultados en el punto final con el mismo task_id .
Solución de problemas de respuestas de error
Respuestas de error generales
La siguiente tabla muestra los códigos de error que cualquier acción puede provocar.
| Respuesta | Resumen |
|---|---|
task-failed | Falla desconocida |
deactivated-account | Cuenta desactivada |
deactivated-device | Dispositivo desactivado |
client-account-disabled | Token de API deshabilitado |
account-locked | Cuenta bloqueada |
account-credentials-blocked | Cuenta bloqueada y protegida |
push-api-timeout | Tiempo de espera interno |
icloud-unauthorised | Tiempo de espera de sesión de Apple |
service-inactive-error | Servicio de Apple sin inicializar. |
Falla desconocida
La tarea de inicio de sesión falló y la razón era desconocida. En caso de falla de la tarea con este código, los clientes deben comunicarse con el equipo de soporte .
Cuenta desactivada
Esto significa que la cuenta se ha desactivado mediante el comando de administración de desactivación de cuenta. No será accesible a menos que se envíe un comando de activación manual.
Dispositivo desactivado
Esto significa que el dispositivo se ha desactivado mediante el comando de administración de desactivación del dispositivo. No será accesible a menos que se envíe un comando de activación manual.
Token de API deshabilitado
El token que se usa para acceder a la API se ha deshabilitado, comuníquese con el equipo de soporte.
Tiempo de espera interno
Si la sesión de la API caduca al realizar otras acciones de servicio, los clientes recibirán el código de error: push-api-timeout y deben iniciar sesión nuevamente.
{ "message": "Unable to recover the session. Please re-login and try again", "error": "push-api-timeout" }
iCloud no autorizado
Si la sesión con Apple ha caducado antes o se invalida durante una acción, la acción tendrá que abortarse y la sesión debe restablecerse volviendo a autenticarse a través de una nueva tarea de log-in . El uso de refresh-session no funcionará en este caso, ya que el token utilizado para esta llamada está vinculado a la sesión con Apple, que ahora está vencida.
En ciertos casos, una sesión puede caducar parcialmente. Por ejemplo, list-devices siguen devolviendo una list-devices actualizada y válida, pero fetch-data fallan con icloud-unauthorised . En este caso, la sesión puede seguir utilizándose para datos accesibles, pero debe actualizarse completamente mediante una tarea de log-in para obtener más datos.
Error de servicio inactivo
Esta respuesta se devuelve si la API intentó inicializar un servicio pero recibió una respuesta de Apple que indica que no se ha desactivado en la cuenta del usuario. Verifique la configuración correspondiente para el tipo de datos que se consulta y asegúrese de que esté activado e inicializado.
Respuestas de error de inicio de sesión
La siguiente tabla muestra los códigos de error que pueden plantearse las acciones de log-in y submit-2fa-challenge además de los códigos generales anteriores.
| Respuesta | Resumen |
|---|---|
unable-to-login | Las credenciales son incorrectas |
2fa-required | 2FA requerido |
invalid-2fa-code | Código 2FA no válido |
too-many-2fa-requests | 2FA tasa limitada |
account-locked | Cuenta bloqueada |
account-credentials-blocked | Cuenta bloqueada y protegida |
terms-of-service-update-client | Términos de servicio no aceptados |
session-creation-error | Error recuperable durante la inicialización de la sesión. |
session-corrupt-error | Error no recuperable durante la inicialización de la sesión. |
Las credenciales son incorrectas
Las credenciales especificadas para la cuenta eran incorrectas y la autenticación no es posible.
2FA requerido
Iniciar sesión en cuentas que usan autenticación de dos factores (2FA) o verificación de dos pasos (2SV) requiere algunos pasos adicionales. Consulte las secciones "2FA y 2SV" a continuación.
Código 2FA no válido
Se envió un código 2FA inválido o incorrecto en respuesta al desafío 2FA.
2FA tasa limitada
Se han enviado demasiadas solicitudes 2FA recientemente para la cuenta: se ha limitado la tasa. Vuelva a intentarlo después de 30 minutos.
Cuenta bloqueada
La cuenta de iCloud ha sido bloqueada por Apple. Si se realiza otro intento para acceder a la cuenta en un corto período de tiempo, en su lugar se devolverá un error account-credentials-blocked .
Cuenta bloqueada y protegida
La cuenta de iCloud ha sido bloqueada por Apple y ricloud ya ha informado al cliente con la account-locked . Este mensaje se sustituye para indicar que el servicio no está retransmitiendo la solicitud a Apple.
Términos de servicio no aceptados
La cuenta de iCloud está deshabilitada en espera de la aceptación de los términos y condiciones más recientes de iCloud. El usuario puede aceptarlos en su dispositivo o iniciando sesión en icloud.com.
Error de creación de sesión
El backend de iCloud respondió con un error durante la inicialización de la sesión, pero volver a intentarlo probablemente solucionará el problema y tendrá éxito.
Error de sesión corrupta
El backend de iCloud respondió con un error durante la inicialización de la sesión y el reintento no generará un resultado diferente. Póngase en contacto con el servicio de asistencia técnica (preferiblemente con credenciales de cuenta) para que este caso perimetral se pueda investigar.
