Servizio iCloud di Apple

aggiornato

The API supports retrieval of a variety of data and files from Apple's iCloud services.

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.

Creating a session for an account without 2FA/2SV

The session payload to create a session for an account without 2FA/2SV enabled contains the following parameters.

name type description
password string The iCloud account password.

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

Response

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

Creating a session for an account with 2FA

Creating a session for a 2FA enabled account is a two step process:

  1. Attempt to create a session using just the iCloud account password. This will trigger the 2FA process, which sends an authentication code to iOS and macOS devices associated with the account. The session creation attempt will fail with error="code-required".
  2. Use the iCloud account password and the authentication code received in (1) to create a session. If the code is accepted, the session will be successfully created.

Step 1: create session

name type description
password string The iCloud account password.

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

Response

If the 2FA process is triggered as expected, the session should fail to be created with the error: code-required.

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

Step 2: create session with code

name type description
password string The iCloud account password.
code string The authentication code.

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

Response

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

Creating a session for an account with 2SV

The process to create a session for a 2SV enabled account has three steps:

  1. Attempt to create a session using the iCloud account password. As 2SV is required, this will fail with error="choice-required" and error_info={"choices": [<2SV enabled devices>]}.
  2. Attempt to create a session again using the iCloud account password and a choice from the error_info["choices"] list. This time, the attempt will trigger the 2SV process which sends an authentication code to the chosen device. The attempt will fail with error="code-required".
  3. Use the iCloud account password and the authentication code received in (2) to create a session. If the code is accepted, the session will be successfully created.

This will trigger the 2SV process, which sends an authentication code to iOS and macOS devices associated with the account. The session creation attempt will fail with error="code-required".

Step 1: create session

name type description
password string The iCloud account password.

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

Response

If 2SV is enabled on the account, the session creation attempt will fail with error choice-required.

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

Step 2: create session with choice

name type description
password string The iCloud account password.
choice string The chosen device to send an authentication code to.

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

Response

If the 2FA process is triggered as expected, the session should fail to be created with the error: code-required.

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

Step 3: create session with code

name type description
password string The iCloud account password.
code string The authentication code.

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

Response

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

Tipi di fonte

identifier description
icloud.account primary source Corresponds to an iCloud account.

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

The files poll payload attribute is used to request the retrieval of binary files from the targeted source.

The IDs will typically be retrieved from a previous poll for data types that include direct file references, like iCloud Photo Library, or that include attachments, like message data types.

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 Retrieves iCloud Photo Library assets.
mme_contacts.contacts Retrieves iCloud stored iOS Contacts data.
mme_calendar.events Retrieves iCloud stored iOS Calendar data.
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

Photos, videos and other media

Retrieves information on photos, videos and other media stored in iCloud Photo Library (ICPL).

This module requires that iCloud Photo Library is enabled on the user's iCloud account.

Data type ID icpl.photos
Associated setting Settings > [username] > iCloud > Photos > iCloud Photo Library

Data attributes

nome genere descrizione
id string An identifier for the data item. Useful for deduplicating data across multiple polls.
filename string The name of the file as it is stored in ICPL.
files list of image, video, audio items Files associated with this ICPL asset. The original file, Live Photos, thumbnails will be included in this list.
date_created datetime When the file was originally created. In the case of photos or videos taken on an iOS device, this will be the date when they were taken. In the case of existing assets imported to ICPL, this will be the original import date.
date_uploaded datetime When the file was last uploaded to ICPL. This will correspond to when the file was first retrievable via the ricloud API.

Data filters

name type description
since datetime Only includes items with a date_uploaded later than the provided value.
until datetime Only includes items with a date_uploaded earlier than the provided value.

Sample data

[
  {
    "id": "4d475a7bba2c604",
    "data_type": "icpl.asset",
    "filename": "IMG_0123.PNG",
    "files": [
      {
        "id": "icpl://ATnrIxddlwbCEjN33NBq8zXQwYgE",
        "data_type": "image",
        "extension": "png",
        "size": 119842,
        "width": 750,
        "height": 1334
      },
      {
        "id": "icpl://AcXwu8/wH8s6lfiGBDEZah6KzQjC",
        "data_type": "image",
        "extension": "jpg",
        "size": 210680,
        "width": 750,
        "height": 1334
      },
      {
        "id": "icpl://AbfMRXQ55H4WfS5YguuUWxir4hq6",
        "data_type": "image",
        "extension": "jpg",
        "size": 71032,
        "width": 310,
        "height": 554
      }
    ],
    "date_created": "2020-01-01T00:00:00.000000Z",
    "date_uploaded": "2020-01-01T00:00:00.000000Z"
  }
]

MobileMe Contacts

Contacts

Retrieves iOS Contacts data stored in iCloud.

Data type ID mme_contacts.contacts
Associated setting Settings > [username] > iCloud > Contacts

Data attributes

The mme_contacts.contact data type inherits most attributes from the base contact data type. The table below outlines additional or differing attributes.

nome genere descrizione
id string An identifier for the data item. Useful for deduplicating data across multiple polls.
data_type string, always mme_contacts.contact The data type of the item.
uid string A unique identifier that can be used to deduplicate across different sources of iOS Contacts data.
image nested image item, optional Profile image for the contact.

Sample data

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

MobileMe Calendar events mme_calendar.events

Recupera i dati del calendario iOS memorizzati di iCloud.

MobileMe Notes notes 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.

Find My and Find My iPhone

Device locations

Retrieve Find My device and location data.

Note that this data type may require multiple polls, with the second coming ~10-30 seconds after the first, in order to return complete data. This is due to how Find My operates: the first poll will trigger Find My to request new data from reachable devices but the data will not be available for another 10-30 seconds.

Data type ID fmip.devices
Associated setting Settings > [username] > Find My

Data attributes

nome genere descrizione
id string An identifier for the data item. Useful for deduplicating data across multiple polls.
data_type string, always fmip.devices The data type of the item.
name string The user set name for the device.
model_name string Apple's marketing name for the device model.
model_identifier string Apple's identifier for the device model.
product_type string The product category of the device.
location optional nested location The last reported location for the device, if one is available.
battery_status string The current battery status of the device.
battery_level float If known, the percentage battery charge remaining.

Sample data

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

identifier description
icpl A file from iCloud Photo Library.
mme_contact_image An mme_contacts.contacts contact profile image.

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 10:36 AM 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 - 2020 Reincubate Ltd. Tutti i diritti riservati. Registrato in Inghilterra e Galles #5189175, VAT GB151788978. Reincubate® è un marchio registrato. Politica sulla riservatezza & condizioni. Raccomandiamo 2FA. Costruito con a Londra.