Servizio iCloud di Apple

aggiornato
Cover image for: Servizio iCloud di Apple

L'API supporta il recupero di una varietà di dati e file dai servizi iCloud di Apple.

sessioni

L'impostazione di una sessione per i servizi iCloud sull'API è semplice come un accesso a un account iCloud. Il processo può richiedere più tentativi di creazione della sessione se l'account ha abilitato l'autenticazione a più fattori, come 2FA o 2SV.

Creazione di una sessione per un account senza 2FA / 2SV

Il payload della sessione per creare una sessione per un account senza 2FA / 2SV abilitato contiene i seguenti parametri.

nome genere descrizione
password corda La password dell'account iCloud.

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

Risposta

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

Creazione di una sessione per un account con 2FA

La creazione di una sessione per un account abilitato per 2FA è una procedura in due passaggi:

  1. Tenta di creare una sessione usando solo la password dell'account iCloud. Ciò attiverà il processo 2FA, che invia un codice di autenticazione ai dispositivi iOS e macOS associati all'account. Il tentativo di creazione della sessione fallirà con error="code-required" .
  2. Usa la password dell'account iCloud e il codice di autenticazione ricevuto in (1) per creare una sessione. Se il codice viene accettato, la sessione verrà creata correttamente.

Passaggio 1: crea sessione

nome genere descrizione
password corda La password dell'account iCloud.

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

Risposta

Se il processo 2FA viene attivato come previsto, la sessione non dovrebbe essere creata con l'errore: code-required .

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

Passaggio 2: crea una sessione con il codice

nome genere descrizione
password corda La password dell'account iCloud.
code corda Il codice di autenticazione

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

Risposta

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

Creazione di una sessione per un account con 2SV

Il processo per creare una sessione per un account abilitato per 2SV prevede tre passaggi:

  1. Tentativo di creare una sessione utilizzando la password dell'account iCloud. Poiché è richiesto 2SV, ciò non funzionerà con error="choice-required" ed error_info={"choices": [<2SV enabled devices>]} .
  2. Tentare di creare nuovamente una sessione utilizzando la password dell'account iCloud e una scelta dall'elenco error_info["choices"] . Questa volta, il tentativo attiverà il processo 2SV che invia un codice di autenticazione al dispositivo scelto. Il tentativo fallirà con error="code-required" .
  3. Usa la password dell'account iCloud e il codice di autenticazione ricevuto in (2) per creare una sessione. Se il codice viene accettato, la sessione verrà creata correttamente.

Ciò attiverà il processo 2SV, che invia un codice di autenticazione ai dispositivi iOS e macOS associati all'account. Il tentativo di creazione della sessione fallirà con error="code-required" .

Passaggio 1: crea sessione

nome genere descrizione
password corda La password dell'account iCloud.

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

Risposta

Se 2SV è abilitato sull'account, il tentativo di creazione della sessione fallirà con la choice-required dell'errore choice-required .

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

Passaggio 2: creare una sessione con scelta

nome genere descrizione
password corda La password dell'account iCloud.
choice corda Il dispositivo scelto a cui inviare un codice di autenticazione.

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

Risposta

Se il processo 2FA viene attivato come previsto, la sessione non dovrebbe essere creata con l'errore: code-required .

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

Passaggio 3: creare una sessione con il codice

nome genere descrizione
password corda La password dell'account iCloud.
code corda Il codice di autenticazione

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

Risposta

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

Tipi di fonte

identificatore descrizione
icloud.account fonte principale Corrisponde a un account iCloud.

sondaggi

Il servizio iCloud supporta tutti gli attributi dello schema di payload del sondaggio.

Recupero delle informazioni sulla fonte

Questo tipo di sondaggio recupera informazioni sulla fonte mirata. I risultati sono pubblicati in formato JSON.

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

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

Recupero dati

Questo tipo di sondaggio recupera ed elabora i dati dalla sessione di destinazione. I risultati sono pubblicati in formato JSON.

Vedere l' elenco dei tipi di dati disponibili per ulteriori informazioni su tipi di dati specifici.

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

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

Recupero di file

L'attributo payload del polling dei files viene utilizzato per richiedere il recupero di file binari dall'origine di destinazione.

Gli ID vengono in genere recuperati da un sondaggio precedente per tipi di dati che includono riferimenti diretti ai file, come iCloud Photo Library, o che includono allegati, come i tipi di dati dei messaggi.

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

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

Tipi di dati

Tipi di dati iCloud

identificatore descrizione
icpl.photos Recupera le risorse di iCloud Photo Library.
mme_contacts.contacts Recupera i dati dei Contatti iOS memorizzati su iCloud.
mme_calendar.events Recupera i dati del calendario iOS archiviati su iCloud.
mme_notes.notes Recupera i dati di iOS Notes memorizzati su iCloud.
callkit.calls Recupera i dati del telefono iOS sincronizzati con CallKit.
cloudkit_safari.history Recupera i dati storici del browser Safari memorizzati su iCloud.
fmip.devices Recupera Trova il mio dispositivo iPhone e i dati delle posizioni.

iCloud Photo Library

Foto, video e altri media

Recupera informazioni su foto, video e altri contenuti multimediali archiviati in iCloud Photo Library (ICPL).

Questo modulo richiede che iCloud Photo Library sia abilitato sull'account iCloud dell'utente.

ID tipo di dati icpl.photos
Impostazione associata Settings > [username] > iCloud > Photos > iCloud Photo Library

Attributi di dati

nome genere descrizione
id corda Un identificatore per l'elemento dati. Utile per deduplicare i dati tra più sondaggi.
filename corda Il nome del file così come è archiviato in ICPL.
files elenco di image , video , elementi audio File associati a questa risorsa ICPL. Il file originale, Live Photos, miniature saranno inclusi in questo elenco.
date_created appuntamento Quando il file è stato originariamente creato. Nel caso di foto o video ripresi su un dispositivo iOS, questa sarà la data in cui sono state scattate. Nel caso di attività esistenti importate in ICPL, questa sarà la data di importazione originale.
date_uploaded appuntamento L'ultima volta che il file è stato caricato su ICPL. Ciò corrisponderà a quando il file è stato recuperato per la prima volta tramite l'API ricloud.
local_date_created optional datetime When the asset was originally created, in local time. This attribute is only populated if sufficient metadata is stored with the asset in ICPL, and is currently supported for parsing by the API. The value of this attribute can vary by a few seconds from that of date_created, as the two are determined from different sources.

Filtri dati

nome genere descrizione
since appuntamento Include solo gli articoli con date_uploaded oltre il valore fornito.
until appuntamento Include solo gli articoli con date_uploaded precedenti al valore fornito.

Dati di esempio

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

Contatti MobileMe

Contatti

Recupera i dati dei contatti iOS memorizzati in iCloud.

ID tipo di dati mme_contacts.contacts
Impostazione associata Settings > [username] > iCloud > Contacts

Attributi di dati

Il tipo di dati mme_contacts.contact eredita la maggior parte degli attributi dal tipo di dati di contact base. La tabella seguente descrive attributi aggiuntivi o diversi.

nome genere descrizione
id corda Un identificatore per l'elemento dati. Utile per deduplicare i dati tra più sondaggi.
data_type stringa, sempre mme_contacts.contact Il tipo di dati dell'articolo.
uid corda Un identificatore univoco che può essere utilizzato per deduplicare tra diverse fonti di dati dei contatti iOS.
image elemento image nidificato, facoltativo Immagine del profilo per il contatto.

Dati di esempio

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

Eventi Calendario MobileMe mme_calendar.events

Recupera i dati del calendario iOS memorizzati di iCloud.

Note di MobileMe note mme_notes.notes

Recupera i dati di iOS Notes memorizzati su iCloud.

CallKit

Chiamate da CallKit callkit.calls

Recupera i registri delle chiamate sincronizzati con il servizio CallKit.

Errori

callkit-uninitialised

Indica che il servizio CallKit non è stato impostato per questo account. Il proprietario dell'account iCloud può risolvere questo errore utilizzando un dispositivo iOS associato all'account iCloud tramite i seguenti passaggi: - Assicurati che il dispositivo sia connesso al Wi-Fi. - Passa a Settings > [username] > iCloud . - Disattiva iCloud Drive, aspettando da 30 a 60 secondi affinché la modifica abbia effetto. - Attiva iCloud Drive una volta completata la modifica precedente. Ciò dovrebbe innescare l'inizializzazione.

Se l'errore persiste dopo aver eseguito questo processo, contattare l'assistenza.

callkit-sync-disabled

In questo caso, il servizio CallKit è stato inizializzato ma non sono state soddisfatte le condizioni necessarie affinché i dispositivi inizino a sincronizzare la cronologia delle chiamate con iCloud. L'API lo risolverà da remoto tramite iCloud, ma il dispositivo associato all'account iCloud potrebbe non rivalutare il loro stato di sincronizzazione in quanto è memorizzato nella cache.

Il proprietario dell'account iCloud può attivare un dispositivo per ricontrollare le condizioni di sincronizzazione della cronologia delle chiamate tramite i seguenti passaggi:

  • Passa a Settings > [username] > iCloud .
  • Spegni iCloud Drive, aspettando da 30 a 60 secondi affinché la modifica abbia effetto.
  • Accendi iCloud Drive una volta completata la modifica precedente. Ciò dovrebbe innescare l'inizializzazione.

Risoluzione dei problemi

  • La cronologia delle chiamate recenti non viene restituita nei risultati del sondaggio.

Ciò è in genere causato dal fatto che il dispositivo non ha sincronizzato i suoi ultimi record di cronologia chiamate con iCloud. Il servizio CallKit è un servizio iOS interno e non può essere attivato o disattivato nelle impostazioni o attivato per la sincronizzazione manuale. Ciò può rendere difficile il debug dei dati mancanti poiché non è chiaro cosa ha sincronizzato o meno il dispositivo con iCloud.

Questo problema è più comune per gli account che non hanno molti dati da sincronizzare (meno di ~ 3 chiamate), il che può essere spesso il caso per verificare gli account.

raccomandazioni:

  • Assicurati che il dispositivo abbia più di una manciata di record della cronologia delle chiamate da sincronizzare. I nostri test hanno dimostrato che un dispositivo con solo un paio di record della cronologia delle chiamate non attiverà il processo di sincronizzazione di iCloud.
  • Attendere che il dispositivo esegua una sincronizzazione periodica. Questa operazione può richiedere fino a 12 ore a seconda dell'utilizzo del dispositivo, dello stato di connettività e dello stato di carica.
  • Collegare il dispositivo all'alimentazione. È più probabile che il dispositivo attivi una sincronizzazione in questo stato.

  • La cronologia delle chiamate precedenti non viene restituita nei risultati del sondaggio.

Il servizio CallKit è progettato per sincronizzare i record della cronologia delle chiamate tra dispositivi e non per archiviare questi record a tempo indeterminato. In genere, i record della cronologia delle chiamate possono essere richiamati da CallKit per circa 3 mesi, ma ciò può variare a seconda dei processi di pulizia interni in iCloud.

CloudKit

Cronologia del browser da iCloud cloudkit_safari.history

Recupera i dati della cronologia del browser Safari memorizzati nel servizio di sincronizzazione iCloud.

Trova il mio e trova il mio iPhone

Posizioni del dispositivo

Recupera Trova il mio dispositivo e i dati sulla posizione.

Si noti che questo tipo di dati può richiedere più sondaggi, con il secondo in arrivo ~ 10-30 secondi dopo il primo, al fine di restituire i dati completi. Ciò è dovuto al modo in cui Find My funziona: il primo sondaggio attiverà Find My per richiedere nuovi dati da dispositivi raggiungibili ma i dati non saranno disponibili per altri 10-30 secondi.

ID tipo di dati fmip.devices
Impostazione associata Settings > [username] > Find My

Attributi di dati

nome genere descrizione
id corda Un identificatore per l'elemento dati. Utile per deduplicare i dati tra più sondaggi.
data_type stringa, sempre fmip.devices Il tipo di dati dell'articolo.
name corda L'utente ha impostato il nome per il dispositivo.
model_name corda Nome commerciale di Apple per il modello del dispositivo.
model_identifier corda Identificatore di Apple per il modello del dispositivo.
product_type corda La categoria di prodotti del dispositivo.
location location nidificata opzionale L'ultima posizione segnalata per il dispositivo, se disponibile.
battery_status corda Lo stato corrente della batteria del dispositivo.
battery_level galleggiante Se noto, la percentuale di carica residua della batteria.

Dati di esempio

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

Tipi di file

identificatore descrizione
icpl Un file da iCloud Photo Library.
mme_contact_image Un mme_contacts.contacts contatta l'immagine del profilo.

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 2:24 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 - 2021 Reincubate Ltd. Tutti i diritti riservati. Registrato in Inghilterra e Galles #5189175, VAT GB151788978. Reincubate® e Camo® sono marchi registrati. Politica sulla riservatezza & condizioni. Costruito con a Londra.