Para comenzar

Actualizado

Para comenzar a utilizar la API de ricloud v3 , primero debe ponerse en contacto para configurar su organización. Una vez que esto se haya completado, deberías tener tu key_token inicial que te 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": [],
    "storage_config_default": null,
    "webhook_configs": [],
    "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 el caso de un origen de cuenta de iCloud, la API deberá iniciar sesión en la cuenta para crear la sesión entre ella y el servicio iCloud de Apple.

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": "1",
    "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 las comunicaciones con el servicio de terceros. En este caso, estamos obteniendo acceso 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
}

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 obtener más detalles sobre lo que salió mal.

En el caso de que 2FA esté habilitado en su cuenta, es muy probable que el error encontrado sea un code-required y se le pedirá el proceso 2FA en uno de sus dispositivos. Simplemente haga la llamada desde el paso (1) de nuevo, 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": "1",
    "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 detalles.

Una vez que el estado se active la sesión está lista para ser utilizada 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, lo que nos lleva al siguiente paso.

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.

Crear una encuesta para los datos

El conjunto más simple de datos para recuperar de iCloud es información básica de la cuenta. Todo lo que se necesita es el ID de una sesión activa y algunos especificadores para los datos que desea 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",
  "type": "data",
  "payload": {
    "data_types": ["callkit.calls"],
  }
}'

Tenga en cuenta que en la llamada anterior especificamos el tipo de datos callkit.calls , pero su clave puede tener permisos para diferentes tipos de datos o puede estar interesado en recuperar un tipo diferente de datos, solo sustitúyalos según sea necesario.

Esto devolverá un recurso de encuesta. En el fondo, la API también ha creado una tarea que hará el trabajo real requerido para recuperar esta información (también se creó una tarea para configurar nuestra sesión anterior). El ID de la tarea se puede ver bajo el atributo de 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
}

También tenga en cuenta el atributo de results , que está vacío en este punto. Aquí es donde comenzaremos a ver los ID de los datos publicados de la tarea.

Ahora, queremos esperar hasta que se complete el procesamiento y el estado de la encuesta esté configurado para tener succeeded .

Recuperar información de resultados

Esto se hace fácilmente 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",
  "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"
}

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

Recepción de eventos webhook

Cierta funcionalidad de la API se activa automáticamente, ya sea como resultado de activadores externos, como una instancia de recuperación que encuentra datos nuevos o debido a una encuesta programada. En estos casos, la API necesita una forma de informarle 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 hace uso de notificaciones de webhook. Antes de que la API pueda comenzar a enviarlos, y antes de que pueda comenzar a usar el servicio de retransmisión o las encuestas programadas, su organización debe estar configurada con una configuración de webhook válida. Siga la guía en la configuración de webhook para más detalles.

¿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 6:16 PM 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 - 2019 Reincubate Ltd. Todos los derechos reservados. Registrado en Inglaterra y Gales #5189175, VAT GB151788978. Reincubate® es una marca registrada. Términos y privacidad. Recomendamos la autenticación de múltiples factores. Construido con en Londres.