Servizio iCloud di Apple (v2)

aggiornato

Il servizio icloud ricloud API fornisce funzionalità per l'accesso alle informazioni memorizzate su iCloud, sia in forma batch dai backup dei dispositivi iOS, sia in tempo reale e quasi da altre fonti. L'API ha supportato l'accesso a iCloud dalla sua versione originale.

Esistono quattro operazioni principali che un cliente potrebbe dover eseguire con il servizio iCloud.

  • Autenticazione: log-in , perform-2fa-challenge , submit-2fa-challenge
  • Enumerazione dei dispositivi: list-devices
  • Richiesta di feed: fetch-data
  • Richiesta di file raw: download-file

Lavorare con dati falsi dall'API

Per assistere lo sviluppo delle integrazioni con l'API, viene reso disponibile un account fittizio popolato con un set di dati ricchi. Ciò consente ai clienti di testare molte delle funzioni dell'API ricloud senza la necessità di lavorare con dati utente reali.

L'account john.appleseed@reincubate.com si chiama Jonny Appleseed ed è accessibile utilizzando l'ID dell'account iCloud john.appleseed@reincubate.com e la password joshua .

Autenticazione

Accesso: log-in

Il primo passo per interagire con il servizio icloud è l'accesso.

Per la richiesta, dobbiamo specificare:

  • Il service per interagire con: icloud
  • L' action da eseguire: log-in
  • L' account parametri, che rappresenta l'ID dell'account iCloud come john.appleseed@reincubate.com
  • I parametri di azione richiesti dall'azione, che in questo caso è solo password
  • Potremmo anche specificare parametri di azione opzionali elencati dal /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>

L'endpoint asapi risponderà, in formato JSON:

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

Se si è connessi allo stream_endpoint corretto sull'endpoint ascanale , verrà visualizzato un risultato corrispondente al <TASK_ID_1> ricevuto dall'endpoint asapi .

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

I risultati includeranno un parametro di success che sarà vero se l'attività di login è riuscita, insieme a un messaggio e un token di autenticazione Apple da utilizzare con altre azioni di servizio.

Risoluzione dei problemi di accesso

Si prega di consultare la sezione sulle risposte di errore di login per le definizioni e le soluzioni degli errori.

2FA e 2SV

Dopo aver tentato di accedere a un account iCloud configurato con 2SV o 2FA, l'accesso normale non riuscirà e verrà restituito un messaggio di errore simile a quello riportato di seguito.

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

Il dizionario dei data conterrà un elenco di dispositivi, digitati da device_id . Questi sono i dispositivi che sono considerati affidabili dall'account iCloud per eseguire il prossimo passo di autenticazione.

Per la verifica in due passaggi (2SV)

Nel caso di 2SV, l'elenco di trustedDevices conterrà uno o più dispositivi. I clienti devono selezionare un dispositivo elencato da sfidare.

Questo viene fatto eseguendo perform-2fa-challenge con challenge impostato sulla chiave del dispositivo scelto da trustedDevices .

Per l'autenticazione a due fattori (2FA)

Nel caso di 2FA, l'elenco di trustedDevices sarà impostato su ["Challenge all 2FA devices"] , a indicare che è necessario inviare una sfida a tutti i dispositivi iOS collegati a tale account. Questo viene fatto eseguendo perform-2fa-challenge con challenge impostato sul valore di ["Challenge all 2FA devices"] .

Utilizzando perform-2fa-challenge

Questo metodo invierà una richiesta in tempo reale a tutti i dispositivi dell'account nel caso di 2FA o del dispositivo scelto nel caso di 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 risponderà come al solito:

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

L'endpoint di recupero risponderà con:

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

Una volta che la sfida è stata inviata al dispositivo dell'utente, il codice a due fattori deve essere ritrasferito all'API utilizzando submit-2fa-challenge . Nella richiesta sottostante, <CODE> è il codice numerico fornito dall'utente finale, che rappresenta i codici trasmessi al dispositivo per l'accesso 2FA / 2SV.

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

asapi risponderà come al solito:

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

L'endpoint di recupero risponderà con un normale messaggio di accesso:

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

Aggiornamento dell'account di accesso con i token di autenticazione

ricloud fornisce i token di autenticazione da utilizzare per l'aggiornamento di accessi senza la necessità di utilizzare le credenziali iCloud complete. Gli utenti del meccanismo di tokenizzazione non devono necessariamente conservare credenziali utente.

Per fare ciò, i client devono utilizzare il campo auth_token recuperato durante l'accesso. Questo deve essere inviato all'endpoint dell'azione di servizio della 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>

Fatto ciò, è possibile eseguire qualsiasi azione di assistenza contro il servizio.

Enumerazione dei dispositivi

Enumerazione dei dispositivi: list-devices

Una volta effettuato l'accesso a un account, i client possono enumerare i dispositivi e i backup del dispositivo associati all'account iCloud. Questo viene fatto eseguendo l'azione list-devices contro il servizio iCloud.

Questo viene fatto allo stesso modo di qualsiasi altra azione di servizio. Ecco un esempio di richiesta di curl a questa azione. Il seguente parametro <ACCOUNT> può essere riempito con un ID account, come john.appleseed@reincubate.com .

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

L'endpoint asapi risponderà, in formato JSON:

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

Il risultato verrà visualizzato a breve sul punto finale del recupero. Di seguito è riportata una risposta di esempio:

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

Questa risposta contiene il auth_token per la sessione iCloud dell'account specificato, insieme a un elenco di dispositivi associati a auth_token nella sezione devices . Ogni voce del dispositivo contiene i seguenti tasti:

  • ios_version : la versione iOS del dispositivo
  • colour : il colore del dispositivo come codice esadecimale
  • device_name : il nome del dispositivo impostato dall'utente
  • latest-backup : la data in cui è stato eseguito il backup dell'ultimo dispositivo su iCloud
  • model : il numero di modello del dispositivo
  • serial : il numero di serie del dispositivo
  • name : il name del prodotto del dispositivo come pubblicizzato da Apple

Richiesta di feed

Recupero dei dati del feed: fetch-data

L'azione fetch-data viene utilizzata per accedere ai feed dei dati JSON dall'API. Richiede i seguenti parametri:

  • device : il dispositivo per recuperare i dati da o su
  • data : un CSV dei moduli di alimentazione richiesti

I parametri opzionali sono:

  • since : il periodo di tempo a partire dal quale i risultati devono corrispondere

Di seguito è riportato un esempio fetch-data azione 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.

Ad esempio, utilizzando il valore sms in <FEED_MODULES> nel comando precedente è possibile accedere a SMS, MMS e iMessages in un backup. Usando il valore sms,whatsapp_messages,snapchat_messages in <FEED_MODULES> nel comando possiamo accedere a SMS, MMS e iMessage, messaggi di WhatsApp e messaggi Snapchat, tutti nello stesso risultato JSON.

Asapi risponderà con:

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

Poco dopo, i risultati appariranno sull'endpoint dei risultati con lo stesso 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
    }
  ]
}

Altri moduli di feed forniscono informazioni che possono essere utilizzate per accedere ad altre forme di contenuto. Ad esempio, un'azione di fetch-data utilizzando "foto" come <FEED_MODULES> per un dato dispositivo sarebbe simile a questa:

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

Farà in modo che Asapi risponda con:

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

Il seguente risultato apparirà sull'endpoint appropriato:

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

Formati di feed JSON

I feed JSON sono progettati per essere il più semplice da analizzare. Il feed restituirà tutti i tipi di dati richiesti all'interno di una singola risposta.

Ogni modulo di feed specificato nel flag del modulo avrà la propria chiave nel dizionario JSON di livello superiore che viene restituito.

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

Richiesta di file raw

Recupero di file raw: download-file

L'azione download-file è disponibile per scaricare file o allegati ai messaggi direttamente da iCloud. I parametri necessari sono il target <DEVICE_ID> e un <FILE_ID> .

Alcuni dei moduli di alimentazione, compresi i file file_list e foto, contengono riferimenti a file o allegati disponibili per il download. Questi contengono un <FILE_ID> utilizzato per identificare e scaricare il file e spesso alcuni metadati aggiuntivi come nome filename , file_path , size e type . Si prega di consultare Estrattori di informazioni per maggiori dettagli.

Il 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 risponderà con:

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

Poco dopo i risultati appariranno sull'endpoint con lo stesso task_id .

Risoluzione dei problemi relativi alle risposte agli errori

Risposte di errore generali

La seguente tabella mostra i codici di errore che qualsiasi azione può generare.

Risposta Sommario
task-failed Fallimento sconosciuto
deactivated-account Account disattivato
deactivated-device Dispositivo disattivato
client-account-disabled Token API disabilitato
account-locked Account bloccato
account-credentials-blocked Account bloccato e protetto
push-api-timeout Timeout interno
icloud-unauthorised Timeout sessione Apple
service-inactive-error Servizio Apple non inizializzato

Fallimento sconosciuto

L'attività di accesso non è riuscita e il motivo era sconosciuto. In caso di errore dell'attività con questo codice, i clienti devono contattare il team di supporto .

Account disattivato

Ciò significa che l'account è stato disattivato utilizzando il comando di gestione disattivazione account. Non sarà accessibile a meno che non venga inviato un comando di attivazione manuale.

Dispositivo disattivato

Ciò significa che il dispositivo è stato disattivato tramite il comando di gestione della disattivazione del dispositivo. Non sarà accessibile a meno che non venga inviato un comando di attivazione manuale.

Token API disabilitato

Il token utilizzato per accedere all'API è stato disabilitato, contatta il team di supporto.

Timeout interno

Se la sessione API scade mentre si eseguono altre azioni di servizio, i client riceveranno il codice di errore: push-api-timeout e devono effettuare nuovamente l'accesso.

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

iCloud non autorizzato

Se la sessione con Apple è scaduta prima o viene invalidata durante un'azione, l'azione dovrà essere interrotta e la sessione dovrà essere ristabilita eseguendo nuovamente l'autenticazione tramite una nuova attività di log-in . L'uso di refresh-session non funzionerà in questo caso poiché il token utilizzato per questa chiamata è legato alla sessione con Apple che è scaduta.

In alcuni casi, una sessione può diventare parzialmente scaduta. Ad esempio, list-devices restituiscono ancora un list-devices valido e aggiornato, ma fetch-data non riescono con icloud-unauthorised . In questo caso, la sessione può continuare a essere utilizzata per i dati accessibili, ma deve essere completamente aggiornata utilizzando un'attività di log-in per ottenere ulteriori dati.

Servizio inattivo errore

Questa risposta viene restituita se l'API ha tentato di inizializzare un servizio ma ha ricevuto una risposta da Apple che indica che non è stato disattivato nell'account dell'utente. Si prega di verificare le impostazioni corrispondenti per il tipo di dati interrogati e assicurarsi che sia attivato e inizializzato.

Login risposte degli errori

La tabella seguente mostra i codici di errore che le azioni di log-in e submit-2fa-challenge possono generare in aggiunta ai codici generali di cui sopra.

Risposta Sommario
unable-to-login Le credenziali sono errate
2fa-required Richiesto 2FA
invalid-2fa-code Codice 2FA non valido
too-many-2fa-requests 2FA a tariffa limitata
account-locked Account bloccato
account-credentials-blocked Account bloccato e protetto
terms-of-service-update-client Termini di servizio non accettati
session-creation-error Errore recuperabile durante l'inizializzazione della sessione
session-corrupt-error Errore irreversibile durante l'inizializzazione della sessione

Le credenziali sono errate

Le credenziali specificate per l'account erano errate e l'autenticazione non è possibile.

Richiesto 2FA

L'accesso agli account che utilizzano l'autenticazione a due fattori (2FA) o la verifica in due passaggi (2SV) richiede alcuni passaggi aggiuntivi. Vedi sotto le sezioni "2FA e 2SV".

Codice 2FA non valido

Un codice 2FA non valido o altrimenti errato è stato inviato in risposta alla sfida 2FA.

2FA a tariffa limitata

Troppe richieste 2FA sono state inviate di recente per l'account: è stata limitata in base alla tariffa. Riprovare dopo 30 minuti.

Account bloccato

L'account iCloud è stato bloccato da Apple. Se viene effettuato un altro tentativo di accedere all'account in un breve periodo di tempo, verrà restituito un errore account-credentials-blocked .

Account bloccato e protetto

L'account iCloud è stato bloccato da Apple e ricloud ha già informato il cliente con account-locked . Questo messaggio viene sostituito per indicare che il servizio non sta inoltrando la richiesta a Apple.

Termini di servizio non accettati

L'account iCloud è disabilitato in attesa dell'accettazione dei termini e delle condizioni di iCloud più recenti. L'utente può accettarle sul proprio dispositivo o accedendo a icloud.com.

Errore di creazione della sessione

Il backend di iCloud ha risposto con un errore durante l'inizializzazione della sessione, ma il nuovo tentativo probabilmente risolverà il problema e riuscirà.

Errore corrotto della sessione

Il backend iCloud ha risposto con un errore durante l'inizializzazione della sessione e il nuovo tentativo non ha prodotto risultati diversi. Si prega di contattare l'assistenza (preferibilmente con le credenziali dell'account) in modo che questo caso limite possa essere esaminato.

Come possiamo aiutare?

Il nostro team di supporto è qui per aiutarti!

I nostri orari di ufficio sono dal lunedì al venerdì, dalle 9:00 alle 17:00 GMT. L'ora è attualmente 3:31 PM GMT.

Miriamo a rispondere a tutti i messaggi entro un giorno lavorativo.

Vai alla sezione di supporto › Contatta il team aziendale ›
Il nostro fantastico team di supporto

© 2008 - 2019 Reincubate Ltd. Tutti i diritti riservati. Registrato in Inghilterra e Galles #5189175, VAT GB151788978. Reincubate® è un marchio registrato. Termini e Condizioni. Raccomandiamo 2FA. Costruito con a Londra.