Iniziare

aggiornato

To start using the ricloud API, you first need to get in touch to setup your organisation. Once this is completed, you should have your initial key_token which will grant you access to the 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

A session represents access to a source. In this case, our source will be an iCloud account and creating a session will effectively "login" to the account. The session will then take care of keeping track of the connection between the API and iCloud's system for future requests.

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

The response will contain a session resource, which will initially be in the pending state while the API goes through the process of setting up communications with the third-party service.

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

If the state becomes failed, something went wrong during the initialisation process. Check the value of the error attribute for more details. If 2FA is enabled on your account -- and you got your password correct -- the error encountered is likely to be code-required. You will have been prompted with a 2FA code on one of your iOS devices connected to the account. Simply make the call from step (1) again, but this time including the 2FA code in the 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>"
  }
}'

If another error occurred, please check the errors section for more information.

Once the state becomes active the session is ready for use to retrieve data and files from the source.

However, as we saw earlier, your organisation is not yet configured to receive any of this data.

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.

Once you have a storage config, you can try retrieving your organisation again. The state should now be active, rather than unconfigured.

Crea un sondaggio per i dati

To create a poll, all we need to provide is the ID of an active session and some details on the data or files we want retrieved.

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

Note that in the call above we request the icpl.photos data type. You might be interested in retrieving a different type of data, or might not have permissions for this data type in particular. Substitute this value as necessary.

This will return a poll resource, with state in pending or processing. In the background, the API has also created a task which will do the actual work required to retrieve this information (a task was also created to set up our session earlier).

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

Note the results attribute, which is empty at this point. This is where we will see references appear for any data or files published from this poll. Results are published as they become available, so they can be retrieved before the whole poll has completed.

Once all requested data and files have been published to your storage, the poll's state will change to completed.

Recupera informazioni sui risultati

This is done by looking at the results attribute of the poll.

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

Certain API functionality is triggered automatically, either as a result of external triggers such as a Reincubate Relay app finding new data or due to a subscription. In these cases, the API needs a way to tell your system that changes have happened or that new data has been published which you should be aware of.

To do this, the API makes use of webhook notifications. Before the API can start sending these, and before you can start using the Reincubate Relay service or subscriptions, your organisation needs to be configured with a valid webhook config. Follow the guide on webhook configuration for more details.

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 11:10 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® è un marchio registrato. Politica sulla riservatezza & condizioni. Raccomandiamo 2FA. Costruito con a Londra.