Para comenzar

Actualizado

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.

Las llamadas a la API en esta sección se realizan usando cURL, pero estas pueden ser fácilmente sustituidas por llamadas equivalentes de ricloud-py .

Viendo tu organización

Primero, echaremos un vistazo rápido a su organización.

curl 'https://ricloud-api.reincubate.com/organisation' \
  -H 'Authorization: Token <your key_token>'

Debería ver una respuesta similar a la de abajo. Si obtiene una respuesta HTTP 401, verifique el valor de key_token que proporcionó en el encabezado de 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"
}

Aquí puede ver información sobre su organización:

  • permissions muestra los permisos básicos para su organización.
  • storage_configs y storage_config_default están vacíos ya que todavía no hemos configurado ninguno.
  • webhook_configs y webhook_config_default también están vacíos por la misma razón.
  • state está unconfigured que refleja la falta de configuraciones de almacenamiento válidas.

Volveremos a los pasos de configuración más adelante, ya que esto no le impide acceder a los servicios a través de la API.

Ahora que hemos confirmado que su organización está en funcionamiento, intentemos acceder a una cuenta de iCloud.

Configuración de una sesión

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.

Crear un usuario

Antes de poder configurar una sesión, se debe crear un usuario para definir qué usuario final desea acceder a la fuente. Esto ayuda con la administración de la sesión y la seguridad de los datos en la 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 respuesta contendrá la ID de usuario necesaria en la próxima llamada.

{
  "id": "1",
  "resource": "user",
  "organisation": "1",
  "key": "1",
  "identifier": "<your user identifier>",
  "state": "active",
  "date_created": "2018-11-22T13:49:37.215516Z"
}

Crear una sesion

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
}

Puede verificar el estado de la sesión a través de la llamada de recuperación.

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.

Recuperando datos y archivos

Antes de que la API pueda comenzar a obtener datos de una fuente, necesita saber dónde debe publicar los datos. La API actualmente admite la publicación en Google Cloud Storage y Amazon S3 (AWS) , compartimientos de almacenamiento, que deben configurarse a través de una configuración de almacenamiento que pertenece a su organización. Siga los pasos descritos en los documentos de configuración de la configuración de almacenamiento para obtener su propio cubo listo para usar con la API.

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

Crear una encuesta para los datos

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.

Recuperar información de resultados

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 respuesta contendrá la información que necesitamos.

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

El atributo url del resultado apuntará al archivo almacenado en su depósito.

Recepción de eventos 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.

¿Cómo podemos ayudar?

¡Nuestro equipo de soporte está aquí para ayudar!

Nuestro horario de atención es de lunes a viernes de 9 a.m. a 5 p.m. GMT. El tiempo es actualmente 5:15 AM GMT.

Intentamos responder todos los mensajes en un plazo de un día laboral.

Ir a la sección de soporte › Póngase en contacto con el equipo de la empresa. ›
Nuestro increíble equipo de soporte.

¿Podemos mejorar este artículo?

Nos encanta escuchar de los usuarios: ¿por qué no enviarnos un correo electrónico, dejar un comentario o tuitear? @reincubate?

© 2008 - 2020 Reincubate Ltd. Todos los derechos reservados. Registrado en Inglaterra y Gales #5189175, VAT GB151788978. Reincubate® es una marca registrada. Política de privacidad & condiciones. Recomendamos la autenticación de múltiples factores. Construido con en Londres.