Iniziare

aggiornato

Per iniziare a utilizzare l'API di ricloud v3 , devi prima contattarti 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": [],
    "storage_config_default": null,
    "webhook_configs": [],
    "webhook_config_default": null,
    "state": "unconfigured",
    "date_created": "2018-11-22T12:59:57.016467Z"
}

Qui puoi vedere alcune informazioni sulla tua organizzazione:

  • permissions visualizza le autorizzazioni di base per la tua organizzazione.
  • storage_configs e storage_config_default sono vuoti in quanto dobbiamo ancora installarne uno.
  • webhook_configs e webhook_config_default sono vuoti per lo stesso motivo.
  • state unconfigured che riflette la mancanza di unconfigured di 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. Nel caso di una sorgente di account iCloud, l'API dovrà accedere all'account per creare la sessione tra sé e il servizio iCloud di Apple.

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": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
  }
}'

La risposta conterrà una risorsa di sessione, che sarà inizialmente in stato di pending mentre l'API passa attraverso il processo di impostazione delle comunicazioni con il servizio di terze parti. In questo caso, stiamo ottenendo l'accesso a 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
}

È 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 diventa failed , qualcosa è andato storto durante il processo di inizializzazione. Controlla il valore dell'attributo error per maggiori dettagli su cosa è andato storto.

Nel caso in cui 2FA sia abilitato sul tuo account, è molto probabile che l'errore riscontrato sia code-required e ti verrà richiesto il processo 2FA su uno dei tuoi dispositivi. Basta effettuare nuovamente la chiamata dal punto (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": "1",
    "type": "icloud.account",
    "identifier": "<iCloud account username>"
  },
  "payload": {
    "password": "<iCloud account password>"
    "code": "<2FA code>"
  }
}'

Se si è verificato un altro errore, si prega di controllare la sezione errori per maggiori dettagli.

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, portandoci al passaggio successivo.

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.

Crea un sondaggio per i dati

Il set di dati più semplice da recuperare da iCloud è alcune informazioni di base sull'account. Tutto ciò che serve è l'ID di una sessione attiva e alcuni specificatori per i dati che stai cercando di 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",
  "type": "data",
  "payload": {
    "data_types": ["callkit.calls"],
  }
}'

Nota che nella chiamata sopra abbiamo specificato il tipo di dati callkit.calls , ma la tua chiave potrebbe avere autorizzazioni per diversi tipi di dati o potresti essere interessato a recuperare un diverso tipo di dati, basta sostituirlo se necessario.

Ciò restituirà una risorsa sondaggio. In background, l'API ha anche creato un'attività che svolgerà l'effettivo lavoro richiesto per recuperare queste informazioni (è stata anche creata un'attività per impostare la nostra sessione in precedenza). L'ID dell'attività può essere visualizzato sotto l'attributo 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
}

Notare anche l'attributo results , che è vuoto a questo punto. Qui è dove inizieremo a vedere gli ID dei dati pubblicati dall'attività.

Ora, vogliamo aspettare fino al completamento dell'elaborazione e lo stato del sondaggio è impostato per il succeeded .

Recupera informazioni sui risultati

Questo è fatto facilmente 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",
  "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"
}

L'attributo url del risultato punterà al file memorizzato nel bucket.

Ricevere eventi webhook

Alcune funzionalità API viene attivato automaticamente, sia come risultato di trigger esterni come un'istanza asrelay trovare nuovi dati oa causa di un sondaggio pianificata. In questi casi, l'API ha bisogno di un modo per dire 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 fa uso delle notifiche webhook. Prima che l'API può iniziare a inviare questi, e prima di poter iniziare a utilizzare il servizio asrelay o sondaggi in programma, l'organizzazione deve essere configurato con un config webhook valida. Segui la guida sulla configurazione di webhook per maggiori dettagli.

Come possiamo aiutare?

Il nostro team di supporto è qui per aiutarti!

I nostri orari di ufficio sono dal lunedì al venerdì, dalle 9:00 alle 17:00 GMT. L'ora è attualmente 1:53 AM GMT.

Miriamo a rispondere a tutti i messaggi entro un giorno lavorativo.

Vai alla sezione di supporto › Contatta il team aziendale ›
Il nostro fantastico team di supporto

Possiamo migliorare questo articolo?

Ci piace ascoltare gli utenti: perché non mandarci un'email, lasciare un commento o twittare @reincubate?

© 2008 - 2019 Reincubate Ltd. Tutti i diritti riservati. Registrato in Inghilterra e Galles #5189175, VAT GB151788978. Reincubate® è un marchio registrato. Termini e Condizioni. Raccomandiamo 2FA. Costruito con a Londra.