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.

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

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

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

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

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

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

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

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.

Attributi di dati

Filtri dati

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.

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.

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.

Attributi di dati

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