Serviço Apple iCloud

Atualizada

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

Sessões

Configurar uma sessão para os serviços do iCloud na API é tão simples quanto um login em uma conta do iCloud. O processo pode exigir várias tentativas de criar a sessão se a conta tiver ativado a autenticação multifator, como 2FA ou 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.

Usando 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.

Usando 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.

Usando 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.

Usando 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.

Usando 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.

Usando 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,
  ...
}

Tipos de fonte

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

Pesquisas

O serviço iCloud suporta todos os atributos do esquema de carga útil da pesquisa.

Recuperando informações de origem

Este tipo de pesquisa recupera informações sobre a origem de destino. Os resultados são publicados no formato JSON.

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

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

Recuperando dados

Esse tipo de pesquisa recupera e processa dados da sessão de destino. Os resultados são publicados no formato JSON.

Consulte a lista de tipos de dados disponíveis para obter mais informações sobre tipos de dados específicos.

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

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

Recuperando Arquivos

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.

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

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

Tipos de dados

tipos de dados do iCloud

identificador descrição
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 os dados armazenados do iCloud no iOS Notes.
callkit.calls Recupera dados do telefone iOS do CallKit sincronizados.
cloudkit_safari.history Recupere os dados de histórico do navegador Safari armazenados no iCloud.
fmip.devices Recuperar dados do dispositivo Find My iPhone e locais.

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 tipo descrição
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 tipo descrição
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 os dados do Calendário iOS armazenados no iCloud.

MobileMe Notes notes mme_notes.notes

Recupera os dados armazenados do iCloud no iOS Notes.

CallKit

Chamadas de CallKit callkit.calls

Recupera logs de chamadas sincronizados com o serviço CallKit.

Erros

callkit-uninitialised

Indica que o serviço CallKit não foi configurado para esta conta. O proprietário da conta do iCloud pode resolver esse erro usando um dispositivo iOS associado à conta do iCloud através das seguintes etapas: - Verifique se o dispositivo está conectado ao Wi-Fi. - Navegue para Settings > [username] > iCloud . - Desligue o iCloud Drive, aguardando 30 a 60 segundos para que a alteração entre em vigor. - Ligue o iCloud Drive assim que a alteração anterior for concluída. Isso deve acionar a inicialização.

Se o erro persistir após a execução deste processo, entre em contato com o suporte.

callkit-sync-disabled

Nesse caso, o serviço CallKit foi inicializado, mas as condições necessárias para que os dispositivos iniciem a sincronização do histórico de chamadas para o iCloud não foram atendidas. A API resolverá isso remotamente por meio do iCloud, mas o dispositivo associado à conta do iCloud não poderá reavaliar seu estado de sincronização, pois isso é armazenado em cache.

O proprietário da conta do iCloud pode acionar um dispositivo para verificar novamente as condições de sincronização do histórico de chamadas através das seguintes etapas:

  • Navegue para Settings > [username] > iCloud .
  • Desligue o iCloud Drive, aguardando 30 a 60 segundos para que a alteração entre em vigor.
  • Ligue o iCloud Drive assim que a alteração anterior for concluída. Isso deve acionar a inicialização.

Solução de problemas

  • O histórico de chamadas recentes não está sendo retornado nos resultados da pesquisa.

Isso geralmente é causado pelo fato de o dispositivo não ter sincronizado seus registros mais recentes de histórico de chamadas com o iCloud. O serviço CallKit é um serviço interno do iOS e não pode ser ativado ou desativado nas configurações ou acionado para sincronização manual. Isso pode dificultar a depuração de dados ausentes, pois não está claro o que o dispositivo tem ou não sincronizado com o iCloud.

Esse problema é mais comum em contas que não têm muitos dados para sincronizar (menos de três chamadas), o que pode ser o caso de contas de teste.

Recomendações:

  • Verifique se o dispositivo possui mais de um punhado de registros do histórico de chamadas para sincronizar. Nossos testes mostraram que um dispositivo com apenas alguns registros do histórico de chamadas não acionará o processo de sincronização do iCloud.
  • Aguarde o dispositivo executar uma sincronização periódica. Isso pode levar até 12 horas, dependendo de como o dispositivo está sendo usado, seu estado de conectividade e seu estado de carga.
  • Conecte o dispositivo à energia. É mais provável que o dispositivo acione uma sincronização neste estado.

  • O histórico de chamadas antigas não está sendo retornado nos resultados da pesquisa.

O serviço CallKit é projetado para sincronizar registros de histórico de chamadas entre dispositivos e não para armazenar esses registros indefinidamente. Normalmente, os registros do histórico de chamadas podem ser recuperados do CallKit por aproximadamente 3 meses, mas isso pode variar entre as contas, dependendo dos processos de limpeza internos no iCloud.

CloudKit

Histórico do navegador do iCloud cloudkit_safari.history

Recupere os dados do histórico do navegador Safari armazenados no serviço de sincronização do 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 tipo descrição
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
  }
]

Tipos de arquivo

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

Como podemos ajudar?

Nossa equipe de suporte está aqui para ajudar!

Nosso horário de atendimento é de segunda a sexta, das 9h às 17h GMT. A hora é atualmente 4:45 PM GMT.

Nosso objetivo é responder a todas as mensagens dentro de um dia útil.

Vá para a seção de apoio › Entre em contato com a equipe da empresa ›
Nossa equipe de suporte incrível

© 2008 - 2020 Reincubate Ltd. Todos os direitos reservados. Registrado na Inglaterra e no País de Gales #5189175, VAT GB151788978. Reincubate® é uma marca registrada. Política de Privacidade & termos. Recomendamos 2FA. Construído com em Londres.