Iniziare
Per iniziare a utilizzare l'API ricloud, devi prima metterti in contatto per configurare la tua organizzazione. Una volta completato, dovresti avere il tuo key_token iniziale che ti garantirà l'accesso all'API.
Le chiamate API in questa sezione vengono eseguite utilizzando cURL, ma queste possono essere facilmente sostituite con chiamate equivalenti da ricloud-py .
Visualizzazione della tua organizzazione
In primo luogo, daremo un'occhiata veloce alla tua organizzazione.
curl 'https://ricloud-api.reincubate.com/organisation' \ -H 'Authorization: Token <your key_token>'
Dovresti vedere una risposta simile a quella qui sotto. Se ottieni una risposta HTTP 401, controlla il valore key_token fornito nell'intestazione 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" }
Qui puoi vedere alcune informazioni sulla tua organizzazione:
-
permissionsvisualizza le autorizzazioni di base per la tua organizzazione. -
storage_configsestorage_config_defaultsono vuoti in quanto dobbiamo ancora installarne uno. -
webhook_configsewebhook_config_defaultsono vuoti per lo stesso motivo. -
stateunconfiguredche riflette la mancanza diunconfigureddi archiviazione valide.
Torneremo ai passaggi di configurazione in seguito, poiché ciò non impedisce l'accesso ai servizi tramite l'API.
Ora che abbiamo confermato che la tua organizzazione è attiva, proviamo ad accedere a un account iCloud.
Impostazione di una sessione
Una sessione rappresenta l'accesso a una fonte. In questo caso, la nostra fonte sarà un account iCloud e la creazione di una sessione "effettuerà l'accesso" all'account. La sessione si occuperà quindi di tenere traccia della connessione tra l'API e il sistema iCloud per future richieste.
Crea un utente
Prima di poter configurare una sessione, è necessario creare un utente per definire quale utente finale desidera accedere all'origine. Questo aiuta con la gestione delle sessioni e la sicurezza dei dati sull'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>" }'
La risposta conterrà l'ID utente necessario nella prossima chiamata.
{ "id": "1", "resource": "user", "organisation": "1", "key": "1", "identifier": "<your user identifier>", "state": "active", "date_created": "2018-11-22T13:49:37.215516Z" }
Crea una sessione
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>" } }'
La risposta conterrà una risorsa di sessione, che inizialmente sarà nello stato in pending mentre l'API passa attraverso il processo di impostazione delle comunicazioni con il servizio di terze parti.
{ "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 }
È possibile controllare lo stato della sessione tramite la chiamata di recupero.
curl 'https://ricloud-api.reincubate.com/sessions/ed855b07-f72b-4983-ac1d-980fafee8a0b' \ -H 'Authorization: Token <your key_token>'
Se lo stato viene a failed , qualcosa è andato storto durante il processo di inizializzazione. Controllare il valore dell'attributo di error per maggiori dettagli. Se 2FA è abilitato sul tuo account e hai la password corretta, è probabile che l'errore riscontrato sia code-required . Ti verrà richiesto un codice 2FA su uno dei tuoi dispositivi iOS collegati all'account. Basta effettuare nuovamente la chiamata dal passaggio (1), ma questa volta includendo il codice 2FA nel payload.
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 si è verificato un altro errore, consultare la sezione errori per ulteriori informazioni.
Una volta che lo stato diventa active la sessione è pronta per essere utilizzata per recuperare dati e file dall'origine.
Tuttavia, come abbiamo visto in precedenza, la tua organizzazione non è ancora configurata per ricevere nessuno di questi dati.
Recupero di dati e file
Prima che l'API possa avviare il recupero dei dati da un'origine, è necessario sapere dove pubblicare i dati. Attualmente l'API supporta la pubblicazione su bucket di archiviazione Google Cloud Storage e Amazon S3 (AWS) , che devono essere configurati tramite una configurazione di archiviazione appartenente alla tua organizzazione. Segui i passaggi descritti nei documenti di configurazione della configurazione di archiviazione per ottenere un bucket personalizzato pronto per l'uso con l'API.
Una volta che hai una configurazione di archiviazione, puoi provare a recuperare nuovamente la tua organizzazione. Lo state dovrebbe ora essere active , piuttosto che non unconfigured .
Crea un sondaggio per i dati
Per creare un sondaggio, tutto ciò che dobbiamo fornire è l'ID di una sessione attiva e alcuni dettagli sui dati o sui file che vogliamo recuperare.
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"], } }'
Si noti che nella chiamata sopra è richiesto il tipo di dati icpl.photos . Potresti essere interessato a recuperare un diverso tipo di dati o potresti non disporre delle autorizzazioni per questo tipo di dati in particolare. Sostituire questo valore se necessario.
Ciò restituirà una risorsa di polling, con state in pending o in processing . In background, l'API ha anche creato un'attività che eseguirà il lavoro effettivo richiesto per recuperare queste informazioni (è stata creata anche un'attività per impostare la nostra sessione in precedenza).
{ "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 }
Nota l'attributo dei results , che è vuoto a questo punto. Qui è dove verranno visualizzati i riferimenti per qualsiasi dato o file pubblicato da questo sondaggio. I risultati vengono pubblicati non appena disponibili, in modo che possano essere recuperati prima che l'intero sondaggio sia completato.
Una volta che tutti i dati e i file richiesti sono stati pubblicati nella memoria, lo stato del sondaggio cambierà in completed .
Recupera informazioni sui risultati
Questo viene fatto osservando l'attributo dei results del sondaggio.
curl 'https://ricloud-api.reincubate.com/polls/f1447e76-59f1-486b-942f-6b90e3570c63' \ -H 'Authorization: Token <your key_token>'
La risposta conterrà le informazioni di cui abbiamo bisogno.
{ "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" }
L'attributo url del risultato punterà al file memorizzato nel bucket.
Ricevere eventi webhook
Alcune funzionalità dell'API vengono attivate automaticamente, a seguito di trigger esterni come un'app Reincubate Relay che trova nuovi dati o a causa di un abbonamento. In questi casi, l'API ha bisogno di un modo per comunicare al tuo sistema che sono avvenute modifiche o che sono stati pubblicati nuovi dati di cui dovresti essere a conoscenza.
Per fare ciò, l'API utilizza le notifiche webhook. Prima che l'API possa iniziare a inviarli e prima di poter iniziare a utilizzare il servizio Reincubate Relay o gli abbonamenti, l'organizzazione deve essere configurata con una configurazione webhook valida. Segui la guida sulla configurazione di webhook per maggiori dettagli.
