Solicitando datos con asapi (v2)

Actualizado

asapi es un mecanismo de control asíncrono para la API de ricloud . Permite a los usuarios:

  • Descubra servicios , acciones y puntos finales que están autorizados a usar.
  • Regístrese, cancele el registro y conozca las cuentas.
  • Enviar tareas asíncronas.
  • Consultar el estado de las tareas.

Una vez completados, los datos de las tareas se pueden obtener del canal o del almacén , según el caso de uso del cliente.

Métodos de un vistazo

Servicio, acción y descubrimiento de puntos finales.

/account/

Usando /account/ endpoint, los clientes pueden obtener información sobre:

  • Servicios disponibles
  • Acciones disponibles y sus parámetros y permisos.
  • Puntos finales disponibles para el envío y recuperación de tareas

Para ello, se realiza una solicitud de descubrimiento:

$ curl \
    -X GET \
    -H 'Authorization: Token <TOKEN>' \
    https://asapi.reincubate.com/account/ -D -

Esto devolverá un conjunto de JSON que describe los servicios, acciones y puntos finales disponibles. El siguiente ejemplo es abreviado:

{ "services": [{
    "name": "iCloud",
    "actions": [{
      "description": "",
      "parameters": [{
        "type": "string",
        "description": "",
        "optional": false,
        "name": "Device",
        "slug": "device"
      }, {
        "type": "date",
        "description": "",
        "optional": true,
        "name": "Since",
        "slug": "since"
      }],
      "name": "Fetch Data",
      "execution": "Asynchronous",
      "slug": "fetch-data",
      "permissions": {
        "data": ["sms"]
      }
    }],
    "slug": "icloud"
  }],
  "task_submission_endpoint": {
    "host": "asapi.reincubate.com",
    "protocol": "https",
    "uri": "/submit-task/"
  },
  "stream_endpoints": [{
    "host": "aschannel.reincubate.com",
    "protocol": "https",
    "uri": "/stream/"
  }]
}

En este caso, el cliente tendría acceso al servicio de icloud y la acción de fetch-data . Tendrían que enviar parámetros de device y data cuando lo usen, y opcionalmente también since .

Este último parámetro de data debe estar en formato de lista; este parámetro puede contener cualquier valor listado en los permissions > data de la sección de fetch-data .

El task_submission_endpoint se define en esta respuesta e informa a los clientes dónde se pueden enviar las acciones para su ejecución.

El stream_endpoint en el ejemplo anterior se define como aschannel.reincubate.com , lo que significa que aschannel está configurado como el punto final de los resultados. Alternativamente, esto podría dirigir a los clientes a un almacén , dependiendo de la configuración de su token.

Registro y cancelación de la cuenta.

register-account

Para poder enviar acciones, debemos informar lo antes posible de las cuentas que puedan tener acciones realizadas en su contra. Para hacerlo, usaremos el /register-account/ endpoint:

$ curl \
    -X POST \
    -H 'Authorization: Token <TOKEN>' \
    -d "service=<SERVICE>" \
    -d "username=<USERNAME>" \
    https://asapi.reincubate.com/register-account/ -D -

En esta solicitud, <SERVICE> es un servicio que posee la acción específica, mientras que <USERNAME> representa para la cuenta que se utilizará en las acciones.

deregister-account

Si una cuenta no se va a usar más, se puede cancelar el registro. Para anular el registro de una cuenta, se puede enviar una solicitud similar a /deregister-account/ endpoint:

$ curl \
    -X POST \
    -H 'Authorization: Token <TOKEN>' \
    -d "service=<SERVICE>" \
    -d "username=<USERNAME>" \
    https://asapi.reincubate.com/deregister-account/ -D -

Ambos métodos, en caso de éxito, devolverán una respuesta de 200 con

{ "success": true
}

Los posibles errores incluyen:

  • unique_together : "La cuenta con este servicio, cliente y nombre de usuario ya existe"

Envío de tareas

[TASK-SUBMISSION]

Las tareas asíncronas se pueden enviar utilizando el punto final especificado en task_submission_endpoint .

Para enviar una tarea, se utiliza el siguiente comando:

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=<SERVICE>" \
    -d "action=<ACTION>" \
    -d "account=<ACCOUNT>" \
    -d "param1=<VALUE1>" \
    -d "param2=<VALUE2>" \
    <TASK_SUBMISSION_ENDPOINT> -D -

En esa solicitud:

En caso de éxito, la solicitud devolverá un 200 con:

{ "task_id": "<TASK_ID>",
  "retrieval_protocol": "<RETRIEVAL_PROTOCOL>",
  "stream": "<STREAM>",
  "success": true
}

En estas respuestas: <TASK_ID> proporciona un ID para la tarea que se puede usar para consultar su estado y recuperar el resultado de la tarea, si se utiliza el asstore <RETRIEVAL_PROTOCOL> indica el método utilizado para recuperar los resultados de la tarea y puede tomar el valor de aschannel o asstore <STREAM> es el ID de secuencia para usarlo en la recuperación de los resultados de la tarea, si se usa el aschannel *

Si la solicitud tuvo un formato incorrecto, la propiedad "éxito" será falsa y la respuesta incluirá una sección de "errores" con comentarios. Por ejemplo:

{ "errors": {
    "service": [
      ["[u'Invalid service name']", "invalid_service"]
    ]
  },
  "success": false
}

Los posibles errores incluyen: * invalid_service : 'Nombre de servicio no válido' * invalid_parameter_value : 'Valor no permitido para el parámetro' * no_such_account : 'No limit_exceeded tal cuenta' * invalid : 'Valor no válido' * limit_exceeded : 'Demasiado ID de tarea enviado' * invalid_action : 'Acción no válida' * parámetro missing-param : 'Parámetro Está perdido'

Consultar estados de tareas.

/task-status/

Para cada tarea enviada al punto final asapi , se proporciona un task_id . El cliente puede enviar periódicamente este task_id al punto final de asapi para descubrir el estado de una tarea. Se puede consultar su estado con una solicitud POST en /task-status/ endpoint. Los clientes pueden solicitar el estado de hasta 10,000 tareas simultáneamente.

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "task_ids=<TASK_ID_1>,<TASK_ID_2>,<TASK_ID_3>,<TASK_ID_4>,<TASK_ID_5>,<TASK_ID_6>,<TASK_ID_7>" \
    https://asapi.reincubate.com/task-status/

Dado al menos un <TASK_ID> correcto, la respuesta será 200 en este formato:

{ "<TASK_ID_1>": {
    "status": "<TASK_STATUS>",
    "retrieval_protocol": "<RETRIEVAL_PROTOCOL>",
    "result_retrieved": "<RETRIEVAL_STATUS>",
    "success": "<TASK_SUCCESS>"
  },
  "success": "<CHECK_SUCCESS>"
}

Si <TASK_SUCCESS> es "Verdadero", los resultados estarán inmediatamente disponibles en el punto final apropiado.

La propiedad de status puede tomar los siguientes valores:

  • Pending
  • In progress
  • Work complete
  • Publish ongoing, with result available
  • Publish complete (en este caso, el valor de success será "verdadero")
  • Publish failed (en este caso, el valor de success será "falso")
  • Task did not complete successfully. (en este caso, el valor de success será "falso")

<RETRIEVAL_PROTOCOL> indicates the method used to retrieve the task results and can take the value of aschannel or asstore depending on the token.

<RETRIEVAL_STATUS> is a boolean, indicating whether the task's results have already been consumed by a client. If <RETRIEVAL_STATUS> is "True", then the results have already been consumed and are no longer available.

El parámetro <CHECK_SUCCESS> ubicado en la raíz del árbol JSON se refiere al éxito de la comprobación de estado. Si esto es "falso", la respuesta contendrá una entrada de "errores" adicional.

Los posibles errores incluyen:

  • invalid : "valor de task_id inválido: "
  • limit_exceeded : "Demasiados limit_exceeded tareas enviados, el límite es "

A continuación se muestra un ejemplo de salida:

{
  "<TASK_ID_1>": {
    "success": false,
    "error": "No task with this ID was found."
  },
  "<TASK_ID_2>": {
    "status": "Publish complete",
    "retrieval_protocol": "aschannel",
    "result_retrieved": false,
    "success": true
  },
  "<TASK_ID_3>": {
    "status": "Publish complete",
    "retrieval_protocol": "asstore",
    "retrieval_endpoint": "https://asstore.reincubate.com/fetch/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/",
    "result_retrieved": true,
    "success": true
  },
  "<TASK_ID_4>": {
    "status": "Publish failed",
    "retrieval_endpoint": "https://asstore.reincubate.com/fetch/1111111-2222-3333-4444-555555555555/",
    "success": false,
    "error": "Task did not complete successfully.",
    "retrieval_protocol": "asstore",
    "result_retrieved": false
  },
  "<TASK_ID_5>": {
    "status": "Pending",
    "result_retrieved": false,
    "success": false
  },
  "<TASK_ID_6>": {
    "status": "In progress",
    "result_retrieved": false,
    "success": false
  },
  "<TASK_ID_7>": {
    "status": "Work complete",
    "result_retrieved": false,
    "success": false
  },
  "success": true,
}

¿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:14 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.

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