Iniziare

aggiornato
Cover image for: 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:

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

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 7:39 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 - 2020 Reincubate Ltd. Tutti i diritti riservati. Registrato in Inghilterra e Galles #5189175, VAT GB151788978. Reincubate e Camo sono marchi registrati. Politica sulla riservatezza & condizioni. Raccomandiamo 2FA. Costruito con a Londra.