Serviço Apple iCloud (v2)

Atualizada

O serviço icloud da API ricloud fornece funcionalidade para acessar informações armazenadas no iCloud, tanto em forma de lote a partir de backups de dispositivos iOS, quanto em tempo real e em tempo quase de outras fontes. A API suportou o acesso ao iCloud desde o lançamento original.

Existem quatro operações principais que um cliente pode precisar realizar com o serviço iCloud.

  • Autenticação: log-in , perform-2fa-challenge , submit-2fa-challenge
  • Enumeração de dispositivos: list-devices
  • Solicitando feeds: fetch-data
  • Solicitando arquivos raw: download-file

Trabalhando com dados simulados da API

Para auxiliar o desenvolvimento de integrações com a API, uma conta simulada preenchida com um conjunto de dados ricos é disponibilizada. Isso permite que os clientes testem muitas das funções da API do ricloud sem precisar trabalhar com dados reais do usuário.

A conta simulada chama-se Jonny Appleseed, e pode ser acessada usando o ID da conta do iCloud john.appleseed@reincubate.com e senha joshua .

Autenticação

Login: log-in

O primeiro passo para interagir com o serviço icloud é o login.

Para o pedido, devemos especificar:

  • O service para interagir com: icloud
  • A action a executar: log-in
  • A account parâmetro, representando o ID da conta do iCloud, como john.appleseed@reincubate.com
  • Os parâmetros de ação requeridos pela ação, que neste caso é apenas password
  • Podemos também especificar parâmetros de ação opcionais listados pelo /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>

O ponto de extremidade asapi responderá no formato JSON:

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

Se você estiver conectado ao stream_endpoint correto no endpoint aschannel , verá um resultado correspondente ao <TASK_ID_1> recebido do endpoint asapi .

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

Os resultados incluirão um parâmetro de success que será verdadeiro se a tarefa de login for bem-sucedida, junto com uma mensagem e um token de autenticação da Apple para uso com outras ações de serviço.

Solução de problemas de login

Consulte a seção sobre respostas a erros de login para definições e soluções de erro.

2FA e 2SV

Depois de tentar efetuar login em uma conta do iCloud que esteja configurada com 2SV ou 2FA, o login normal falhará e uma mensagem de erro será retornada semelhante à mostrada abaixo.

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

O dicionário de data conterá uma lista de dispositivos, codificados por device_id . Esses são os dispositivos confiáveis da conta do iCloud para executar a próxima etapa de autenticação.

Para verificação em duas etapas (2SV)

No caso do 2SV, a lista de trustedDevices conterá um ou mais dispositivos. Os clientes devem selecionar um dispositivo listado para contestar.

Isso é feito executando perform-2fa-challenge com challenge definido para a chave do dispositivo escolhido de trustedDevices .

Para autenticação de dois fatores (2FA)

No caso do 2FA, a lista de trustedDevices será definida como ["Challenge all 2FA devices"] , indicando que um desafio deve ser enviado a todos os dispositivos iOS conectados a essa conta. Isso é feito executando perform-2fa-challenge com challenge definido para o valor de ["Challenge all 2FA devices"] .

Usando o perform-2fa-challenge

Esse método enviará uma solicitação em tempo real para todos os dispositivos na conta no caso de 2FA, ou o dispositivo escolhido no caso de 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"

o asapi responderá normalmente:

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

O ponto final de recuperação responderá com:

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

Depois que o desafio for enviado ao dispositivo do usuário, o código de dois fatores deve ser retransmitido de volta para a API usando o submit-2fa-challenge . Na solicitação abaixo, <CODE> é o código numérico fornecido pelo usuário final, que representa os códigos transmitidos ao dispositivo para o login 2FA / 2SV.

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

o asapi responderá normalmente:

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

O terminal de recuperação responderá com uma mensagem de login normal:

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

Atualizando um login da conta usando tokens de autenticação

O ricloud fornece tokens de autenticação para uso na atualização de logins sem a necessidade de usar credenciais completas do iCloud. Os usuários do mecanismo de tokenização não precisam persistir nenhuma credencial de usuário.

Para fazer isso, os clientes devem usar o campo auth_token recuperado durante o login. Isso deve ser enviado para o ponto de extremidade da ação de serviço da 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>

Com isso, qualquer ação de serviço pode ser executada contra o serviço.

Enumeração de dispositivos

Enumeração de dispositivos: list-devices

Um logado em uma conta, os clientes podem enumerar dispositivos e backups de dispositivos associados à conta do iCloud. Isso é feito executando a ação list-devices no serviço iCloud.

Isso é feito da mesma maneira que qualquer outra ação de serviço. Aqui está um exemplo de solicitação de curl para essa ação. O parâmetro <ACCOUNT> abaixo pode ser preenchido com um ID de conta, como john.appleseed@reincubate.com .

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

O ponto de extremidade asapi responderá no formato JSON:

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

Seu resultado aparecerá em breve no endpoint de recuperação. Abaixo está um exemplo de resposta:

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

Essa resposta contém o auth_token da sessão do iCloud da conta especificada, junto com uma lista de dispositivos associados a essa conta na seção de devices . Cada entrada do dispositivo contém as seguintes chaves:

  • ios_version : a versão do iOS do dispositivo
  • colour : a cor do dispositivo como um código hexadecimal
  • device_name : o nome do dispositivo conforme definido pelo usuário
  • latest-backup : a data em que o dispositivo foi copiado pela última vez para o iCloud
  • model : o número do modelo do dispositivo
  • serial : o número de série do dispositivo
  • name : o name do produto do dispositivo conforme anunciado pela Apple

Solicitando feeds

Recuperação de dados do feed: fetch-data

A ação fetch-data é usada para acessar feeds de dados JSON da API. Requer os seguintes parâmetros:

  • device : o dispositivo para recuperar dados de ou sobre
  • data : um CSV dos módulos de feed solicitados

Parâmetros opcionais são:

  • since : O período de tempo a partir do qual os resultados devem corresponder

Abaixo está um exemplo fetch-data ação de 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.

Por exemplo, usando o valor sms em <FEED_MODULES> no comando acima, pode-se acessar SMS, MMS e iMessages em um backup. Usando o valor sms,whatsapp_messages,snapchat_messages em <FEED_MODULES> no comando, podemos acessar mensagens SMS, MMS e iMessages, WhatsApp e Snapchat, tudo no mesmo resultado JSON.

O asapi responderá com:

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

Logo após, os resultados aparecerão no endpoint de resultados com o mesmo 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
    }
  ]
}

Outros módulos de feed fornecem informações que podem ser usadas para acessar outras formas de conteúdo. Por exemplo, uma ação de fetch-data usando 'fotos' como <FEED_MODULES> para um determinado dispositivo ficaria assim:

$ 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á com que o asapi responda com:

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

O seguinte resultado aparecerá no endpoint apropriado:

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

Formatos de feed JSON

Os feeds JSON são projetados para serem tão simples quanto possível. O feed retornará todos os tipos de dados solicitados em uma única resposta.

Cada módulo de feed especificado no flag do módulo terá sua própria chave no dicionário JSON de nível superior que é retornado.

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

Solicitando arquivos raw

Recuperação de arquivos raw: download-file

A ação do download-file está disponível para o download de arquivos ou anexos de mensagens diretamente do iCloud. Os parâmetros necessários são o destino <DEVICE_ID> e um <FILE_ID> .

Alguns dos módulos de feed, incluindo os módulos file_list e photo, contêm referências a arquivos ou anexos disponíveis para download. Eles contêm um <FILE_ID> usado para identificar e baixar o arquivo e, com frequência, alguns metadados extras, como filename , file_path , size e type . Por favor, veja Extratores de Informação para mais detalhes.

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

o asapi responderá com:

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

Logo após os resultados aparecerão no endpoint com o mesmo task_id .

Solução de problemas de respostas de erros

Respostas gerais de erro

A tabela a seguir mostra os códigos de erro que qualquer ação pode aumentar.

Resposta Resumo
task-failed Falha desconhecida
deactivated-account Conta desativada
deactivated-device Dispositivo desativado
client-account-disabled Token de API desativado
account-locked Conta bloqueada
account-credentials-blocked Conta bloqueada e protegida
push-api-timeout Tempo limite interno
icloud-unauthorised Tempo limite da sessão da Apple
service-inactive-error Serviço da Apple não inicializado

Falha desconhecida

A tarefa de login falhou e o motivo era desconhecido. No caso de falha na tarefa com esse código, os clientes devem entrar em contato com a equipe de suporte .

Conta desativada

Isso significa que a conta foi desativada usando o comando de gerenciamento de desativação de conta. Ele não estará acessível a menos que um comando de ativação manual seja enviado.

Dispositivo desativado

Isso significa que o dispositivo foi desativado usando o comando de gerenciamento de desativação do dispositivo. Ele não estará acessível a menos que um comando de ativação manual seja enviado.

Token de API desativado

O token usado para acessar a API foi desativado. Entre em contato com a equipe de suporte.

Tempo limite interno

Se a sessão da API expirar durante a execução de outras ações de serviço, os clientes receberão o código de erro: push-api-timeout e deverão efetuar login novamente.

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

iCloud não autorizado

Se a sessão com a Apple expirou antes ou é invalidada durante uma ação, a ação terá que ser interrompida e a sessão deverá ser restabelecida pela nova autenticação por meio de uma nova tarefa de log-in . O uso refresh-session não funcionará nesse caso, pois o token usado para essa chamada está vinculado à sessão com a Apple, que agora está expirada.

Em certos casos, uma sessão pode se tornar parcialmente expirada. Por exemplo, list-devices ainda retornam uma list-devices válida e atualizada, mas fetch-data falham com o icloud-unauthorised . Nesse caso, a sessão pode continuar a ser usada para dados acessíveis, mas deve ser totalmente atualizada usando uma tarefa de log-in para obter dados adicionais.

Erro inativo do serviço

Essa resposta é retornada se a API tentar inicializar um serviço, mas receber uma resposta da Apple indicando que ele não foi desativado na conta do usuário. Por favor, verifique a configuração correspondente para o tipo de dados que está sendo consultado e verifique se ele está ativado e inicializado.

Respostas de erro de login

A tabela a seguir mostra os códigos de erro que as ações de log-in e submit-2fa-challenge podem aumentar além dos códigos gerais acima.

Resposta Resumo
unable-to-login As credenciais estão incorretas
2fa-required 2FA exigido
invalid-2fa-code Código 2FA inválido
too-many-2fa-requests 2FA com taxa limitada
account-locked Conta bloqueada
account-credentials-blocked Conta bloqueada e protegida
terms-of-service-update-client Termos de serviço não aceitos
session-creation-error Erro recuperável durante a inicialização da sessão
session-corrupt-error Erro não recuperável durante a inicialização da sessão

As credenciais estão incorretas

As credenciais especificadas para a conta estavam incorretas e a autenticação não é possível.

2FA exigido

O login em contas que usam autenticação de dois fatores (2FA) ou verificação em duas etapas (2SV) exige algumas etapas adicionais. Veja as seções "2FA e 2SV" abaixo.

Código 2FA inválido

Um código 2FA inválido ou incorreto foi enviado em resposta ao desafio 2FA.

2FA com taxa limitada

Muitas solicitações 2FA foram enviadas recentemente para a conta: ela tem uma taxa limitada. Tente novamente após 30 minutos.

Conta bloqueada

A conta do iCloud foi bloqueada pela Apple. Se outra tentativa for feita para acessar a conta em um curto período de tempo, um erro account-credentials-blocked será retornado.

Conta bloqueada e protegida

A conta do iCloud foi bloqueada pela Apple e a ricloud já informou o cliente com account-locked . Esta mensagem é substituída para indicar que o serviço não está transmitindo a solicitação para a Apple.

Termos de serviço não aceitos

A conta do iCloud está desativada até a aceitação dos termos e condições mais recentes do iCloud. O usuário pode aceitá-las em seus dispositivos ou fazendo login no icloud.com.

Erro de criação de sessão

O back-end do iCloud respondeu com um erro durante a inicialização da sessão, mas a tentativa provavelmente resolverá o problema e será bem-sucedida.

Erro corrompido de sessão

O back-end do iCloud respondeu com um erro durante a inicialização da sessão e tentar novamente não resultará em um resultado diferente. Por favor entre em contato com o suporte (de preferência com credenciais de conta) para que este caso extremo possa ser investigado.

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 12:54 AM 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 - 2019 Reincubate Ltd. Todos os direitos reservados. Registrado na Inglaterra e no País de Gales #5189175, VAT GB151788978. Reincubate® é uma marca registrada. Privacidade e Termos. Recomendamos 2FA. Construído com em Londres.