Para comenzar

Actualizado hace más de una semana

Para comenzar a utilizar la API de ricloud, primero debe ponerse en contacto para configurar su organización. Una vez que esto se haya completado, debe tener su key_token inicial que le otorgará acceso a la 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

Una sesión representa el acceso a una fuente. En este caso, nuestra fuente será una cuenta de iCloud y la creación de una sesión efectivamente "iniciará sesión" en la cuenta. La sesión se encargará de realizar un seguimiento de la conexión entre la API y el sistema de iCloud para futuras solicitudes.

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

La respuesta contendrá un recurso de sesión, que inicialmente estará en estado pending mientras la API pasa por el proceso de configuración de comunicaciones con el servicio de terceros.

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

Si el estado failed , algo salió mal durante el proceso de inicialización. Verifique el valor del atributo de error para más detalles. Si 2FA está habilitado en su cuenta, y obtuvo su contraseña correcta, es probable que el error encontrado sea un code-required . Se le solicitará un código 2FA en uno de sus dispositivos iOS conectados a la cuenta. Simplemente realice la llamada desde el paso (1) nuevamente, pero esta vez incluyendo el código 2FA en la carga útil.

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

Si se produjo otro error, consulte la sección de errores para obtener más información.

Una vez que el estado se active la sesión está lista para usar para recuperar datos y archivos de la fuente.

Sin embargo, como vimos anteriormente, su organización aún no está configurada para recibir ninguno de estos datos.

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.

Una vez que tenga una configuración de almacenamiento, puede intentar recuperar su organización nuevamente. El state ahora debería estar active , en lugar de no unconfigured .

Crear una encuesta para los datos

Para crear una encuesta, todo lo que necesitamos proporcionar es la ID de una sesión activa y algunos detalles sobre los datos o archivos que queremos recuperar.

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

Tenga en cuenta que en la llamada anterior solicitamos el tipo de datos icpl.photos . Es posible que le interese recuperar un tipo diferente de datos o que no tenga permisos para este tipo de datos en particular. Sustituya este valor según sea necesario.

Esto devolverá un recurso de encuesta, con state pending o en processing . En segundo plano, la API también ha creado una tarea que realizará el trabajo real requerido para recuperar esta información (también se creó una tarea para configurar nuestra sesión antes).

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

Tenga en cuenta el atributo de results , que está vacío en este momento. Aquí es donde veremos aparecer referencias para cualquier dato o archivo publicado de esta encuesta. Los resultados se publican a medida que están disponibles, por lo que se pueden recuperar antes de que se complete toda la encuesta.

Una vez que todos los datos y archivos solicitados se hayan publicado en su almacenamiento, el estado de la encuesta cambiará a completed .

Recuperar información de resultados

Esto se hace mirando el atributo de results de la encuesta.

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

Ciertas funciones de la API se activan automáticamente, ya sea como resultado de activadores externos, como una aplicación Reincubate Relay que encuentra nuevos datos o debido a una suscripción. En estos casos, la API necesita una forma de decirle a su sistema que se han producido cambios o que se han publicado nuevos datos que debe tener en cuenta.

Para hacer esto, la API utiliza notificaciones de webhook. Antes de que la API pueda comenzar a enviarlos, y antes de que pueda comenzar a usar el servicio Reincubate Relay o las suscripciones, su organización debe configurarse con una configuración de webhook válida. Siga la guía sobre la configuración de webhook para más detalles.

Para comenzar

Viendo tu organización

Configuración de una sesión

Recuperando datos y archivos

Recepción de eventos webhook

¿Cómo podemos ayudar?

Boletín Reincubar