Começando

Atualizada

Para começar a usar a API ricloud v3 , primeiro você precisa entrar em contato para configurar sua organização. Depois que isso for concluído, você deverá ter seu key_token inicial que concederá acesso à API.

As chamadas de API nesta seção são realizadas usando cURL, mas elas podem ser facilmente substituídas por chamadas equivalentes do ricloud-py .

Visualizar sua organização

Primeiro, vamos dar uma olhada rápida na sua organização.

curl 'https://ricloud-api.reincubate.com/organisation' \
  -H 'Authorization: Token <your key_token>'

Você deve ver uma resposta semelhante à abaixo. Se você obtiver uma resposta HTTP 401, verifique o valor de key_token você forneceu no cabeçalho Authorization .

{
    "id": 1,
    "resource": "organisation",
    "name": "Getting started",
    "slug": "getting-started",
    "permissions": {
        "id": 1,
        "resource": "organisation_permissions",
        "identifier": "default",
        "scopes": {
            "source_type:icloud.*": [],
            "task_type:*": [],
            "data_type:icloud.account.info": [],
        },
        "date_created": "2018-11-22T12:59:57.168354Z"
    },
    "storage_configs": [],
    "storage_config_default": null,
    "webhook_configs": [],
    "webhook_config_default": null,
    "state": "unconfigured",
    "date_created": "2018-11-22T12:59:57.016467Z"
}

Aqui você pode ver algumas informações sobre sua organização:

  • permissions exibe as permissões básicas para sua organização.
  • storage_configs e storage_config_default estão vazios, pois ainda estamos para configurar qualquer um.
  • webhook_configs e webhook_config_default também estão vazios pelo mesmo motivo.
  • state é unconfigured que reflete a falta de configurações de armazenamento válidas.

Voltaremos às etapas de configuração posteriormente, pois isso não impede que você acesse serviços por meio da API.

Agora que confirmamos que sua organização está funcionando, vamos tentar acessar uma conta do iCloud.

Configurando uma sessão

Uma sessão representa o acesso a uma fonte. No caso de uma fonte de conta do iCloud, a API precisará fazer login na conta para criar a sessão entre ela e o serviço iCloud da Apple.

Crie um usuário

Antes que uma sessão possa ser configurada, um usuário precisa ser criado para definir qual usuário final deseja acessar a origem. Isso ajuda no gerenciamento de sessões e na segurança de dados na API.

curl 'https://ricloud-api.reincubate.com/users' \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "identifier": "<some identifier for the user your system will recognise>",
}'

A resposta conterá o ID do usuário necessário na próxima chamada.

{
  "id": "1",
  "resource": "user",
  "organisation": "1",
  "key": "1",
  "identifier": "<your user identifier>",
  "state": "active",
  "date_created": "2018-11-22T13:49:37.215516Z"
}

Crie uma sessão

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

A resposta conterá um recurso de sessão, que inicialmente estará no estado pending enquanto a API passa pelo processo de configuração de comunicações com o serviço de terceiros. Nesse caso, estamos obtendo acesso ao iCloud.

{
  "id": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "resource": "session",
  "organisation": "1",
  "user": "1",
  "source": "1",
  "state": "pending",
  "error": null,
  "date_created": "2018-11-22T13:50:12.628776Z",
  "date_expired": null
}

Você pode verificar o estado da sessão por meio da chamada de recuperação.

curl 'https://ricloud-api.reincubate.com/sessions/ed855b07-f72b-4983-ac1d-980fafee8a0b' \
  -H 'Authorization: Token <your key_token>'

Se o estado failed , algo deu errado durante o processo de inicialização. Verifique o valor do atributo de error para mais detalhes sobre o que deu errado.

No caso em que o 2FA está habilitado em sua conta, é muito provável que o erro encontrado seja code-required e você será solicitado com o processo 2FA em um dos seus dispositivos. Basta fazer a chamada a partir do passo (1) novamente, mas desta vez incluindo o código 2FA no payload.

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": "<2FA code>"
  }
}'

Se outro erro ocorreu, por favor, verifique a seção de erros para mais detalhes.

Quando o estado se torna active a sessão está pronta para ser usada para recuperar dados e arquivos da origem. No entanto, como vimos anteriormente, sua organização ainda não está configurada para receber esses dados, o que nos leva à próxima etapa.

Recuperando dados e arquivos

Antes que a API possa começar a buscar dados de uma fonte, ela precisa saber para onde deve publicar os dados. Atualmente, a API oferece suporte à publicação nos repositórios de armazenamento do Google Cloud Storage e do Amazon S3 (AWS) , que precisam ser configurados por meio de uma configuração de armazenamento pertencente à sua organização. Siga as etapas descritas nos documentos de configuração da configuração de armazenamento para obter um bloco próprio pronto para uso com a API.

Crie uma pesquisa para dados

O conjunto mais simples de dados para recuperar do iCloud é alguma informação básica da conta. Tudo o que é necessário é o ID de uma sessão ativa e alguns especificadores para os dados que você deseja recuperar.

curl https://ricloud-api.reincubate.com/polls \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "type": "data",
  "payload": {
    "data_types": ["callkit.calls"],
  }
}'

Observe que, na chamada acima, especificamos o tipo de dados callkit.calls , mas sua chave pode ter permissões para diferentes tipos de dados ou você pode estar interessado em recuperar um tipo diferente de dados, substitua-o conforme necessário.

Isso retornará um recurso de pesquisa. No segundo plano, a API também criou uma tarefa que fará o trabalho real necessário para recuperar essas informações (uma tarefa também foi criada para configurar nossa sessão anteriormente). O ID da tarefa pode ser visto no atributo tasks .

{
  "id": "f1447e76-59f1-486b-942f-6b90e3570c63",
  "resource": "poll",
  "organisation": "1",
  "key": "1",
  "user": "1",
  "source": "1",
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "type": "data",
  "tasks_pending": [],
  "tasks_processing": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "tasks_completed": [],
  "results": [],
  "state": "processing",
  "date_created": "2018-11-22T14:20:52.211618Z",
  "date_started": "2018-11-22T14:20:52.731838Z",
  "date_completed": null
}

Observe também o atributo de results , que está vazio neste momento. É aqui que começaremos a ver os IDs dos dados publicados da tarefa.

Agora, queremos aguardar até que o processamento seja concluído e o estado da pesquisa esteja definido como succeeded - succeeded .

Recuperar informação do resultado

Isso é feito facilmente, observando o atributo results da pesquisa.

curl 'https://ricloud-api.reincubate.com/polls/f1447e76-59f1-486b-942f-6b90e3570c63' \
  -H 'Authorization: Token <your key_token>'

A resposta conterá as informações de que precisamos.

{
  "id": "f1447e76-59f1-486b-942f-6b90e3570c63",
  "resource": "poll",
  "organisation": "1",
  "key": "1",
  "user": "1",
  "source": "1",
  "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b",
  "type": "data",
  "tasks_pending": [],
  "tasks_processing": [],
  "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"],
  "results": [
    {
      "id": "754cfef0-7576-44c0-acfe-8b0d8d0dd32f",
      "resource": "result",
      "task": "6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb",
      "identifier": "data:info.account",
      "url": "<your storage config url>",
      "checksum": "2668324d21a20301ce71c28bc5e621d4",
      "size": 12345,
      "state": "available",
      "date_created": "2018-11-22T14:20:53.506542Z",
      "date_consumed": null,
      "date_deleted": null
    }
  ],
  "state": "processing",
  "date_created": "2018-11-22T14:20:52.211618Z",
  "date_started": "2018-11-22T14:20:52.731838Z",
  "date_completed": "2018-11-22T14:20:53.548372Z"
}

O atributo url do resultado apontará para o arquivo armazenado no seu intervalo.

Recebendo eventos do webhook

Determinada funcionalidade da API é acionada automaticamente, seja como resultado de gatilhos externos, como uma instância asrelay, encontrando novos dados ou devido a uma pesquisa programada. Nesses casos, a API precisa de uma maneira de informar ao seu sistema que as mudanças ocorreram ou que novos dados foram publicados, dos quais você deve estar ciente.

Para fazer isso, a API faz uso de notificações do webhook. Antes que a API possa começar a enviá-los e antes que você possa começar a usar o serviço asrelay ou as pesquisas agendadas, sua organização precisa ser configurada com uma configuração válida de webhook. Siga o guia na configuração do webhook para mais detalhes.

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 7:43 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

Podemos melhorar este artigo?

Adoramos ouvir os usuários: por que não nos enviar um e-mail, deixar um comentário ou twittar? @reincubate?

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