Começando
Para começar a usar a API do ricloud, primeiro você precisa entrar em contato para configurar sua organização. Quando 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": { "data": [], "has_more": false, "total_count": 0, "url": "/configs/storage" }, "storage_config_default": null, "webhook_configs": { "data": [], "has_more": false, "total_count": 0, "url": "/configs/webhook" }, "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:
-
permissionsexibe as permissões básicas para sua organização. -
storage_configsestorage_config_defaultestão vazios, pois ainda estamos para configurar qualquer um. -
webhook_configsewebhook_config_defaulttambém estão vazios pelo mesmo motivo. -
stateéunconfiguredque 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. Nesse caso, nossa fonte será uma conta do iCloud e a criação de uma sessão efetivamente "fará login" na conta. A sessão cuidará de acompanhar a conexão entre a API e o sistema do iCloud para solicitações futuras.
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": "<user ID from previous request>", "type": "icloud.account", "identifier": "<iCloud account username>" }, "payload": { "password": "<iCloud account password>" } }'
A resposta conterá um recurso de sessão, que estará inicialmente no estado pending enquanto a API passa pelo processo de configuração das comunicações com o serviço de terceiros.
{ "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 obter mais detalhes. Se o 2FA estiver ativado na sua conta - e você tiver a senha correta - o erro encontrado provavelmente será code-required . Você será solicitado com um código 2FA em um dos seus dispositivos iOS conectados à conta. Simplesmente faça a chamada da etapa (1) novamente, mas desta vez incluindo o código 2FA na carga útil.
curl 'https://ricloud-api.reincubate.com/sessions' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "source": { "user": "<user ID from previous request>", "type": "icloud.account", "identifier": "<iCloud account username>" }, "payload": { "password": "<iCloud account password>", "code": "<2FA code>" } }'
Se outro erro ocorreu, consulte a seção de erros para obter mais informações.
Depois que o estado se torna active a sessão está pronta para ser usada para recuperar dados e arquivos da fonte.
No entanto, como vimos anteriormente, sua organização ainda não está configurada para receber nenhum desses dados.
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.
Depois de ter uma configuração de armazenamento, você pode tentar recuperar sua organização novamente. O state agora deve estar active , e não unconfigured .
Crie uma pesquisa para dados
Para criar uma enquete, tudo o que precisamos fornecer é o ID de uma sessão ativa e alguns detalhes sobre os dados ou arquivos que queremos 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", "payload": { "data_types": ["icpl.photos"], } }'
Observe que, na chamada acima, solicitamos o tipo de dados icpl.photos . Você pode estar interessado em recuperar um tipo diferente de dados ou pode não ter permissões para esse tipo de dados em particular. Substitua esse valor conforme necessário.
Isso retornará um recurso de pesquisa, com o state pending ou em processing . Em 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).
{ "id": "f1447e76-59f1-486b-942f-6b90e3570c63", "resource": "poll", "organisation": "1", "key": "1", "user": "1", "source": "1", "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "tasks_pending": [], "tasks_processing": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"], "tasks_completed": [], "results": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors" }, "state": "processing", "date_created": "2018-11-22T14:20:52.211618Z", "date_started": "2018-11-22T14:20:52.731838Z", "date_completed": null }
Observe o atributo results , que está vazio neste momento. É aqui que veremos as referências de todos os dados ou arquivos publicados nesta pesquisa. Os resultados são publicados à medida que ficam disponíveis, para que possam ser recuperados antes que toda a pesquisa seja concluída.
Depois que todos os dados e arquivos solicitados forem publicados em seu armazenamento, o estado da pesquisa será alterado para completed .
Recuperar informação do resultado
Isso é feito observando o atributo de 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", "tasks_pending": [], "tasks_processing": [], "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"], "results": { "data": [ { "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 } ], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors" }, "state": "completed", "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
Certas funcionalidades da API são acionadas automaticamente, como resultado de acionadores externos, como um aplicativo Reincubate Relay, que encontra novos dados ou devido a uma assinatura. Nesses casos, a API precisa de uma maneira de informar ao seu sistema que mudanças ocorreram ou que novos dados foram publicados, dos quais você deve estar ciente.
Para fazer isso, a API usa notificações de webhook. Antes que a API possa começar a enviá-los, e antes que você possa começar a usar o serviço ou as assinaturas do Reincubate Relay, sua organização precisa ser configurada com uma configuração válida de webhook. Siga o guia sobre configuração do webhook para obter mais detalhes.
