Demander des données avec asapi (v2)

Mis à jour il y a plus d'une semaine

asapi est un mécanisme de contrôle asynchrone pour l'API ricloud . Il permet aux utilisateurs de:

Découvrez les services , actions et points de terminaison qu'ils sont autorisés à utiliser
Inscrivez-vous, désenregistrez-vous et découvrez les comptes
Soumettre des tâches asynchrones
Interroger le statut des tâches

Une fois terminées, les données des tâches peuvent être obtenues à partir de aschannel ou de asstore , selon le cas d'utilisation du client.

Découverte de services, d'actions et de points de terminaison

`/account/`

À l’aide du /account/ point de terminaison, les clients peuvent obtenir des informations sur:

Services disponibles
Actions disponibles, leurs paramètres et autorisations
Points de terminaison disponibles pour la soumission et la récupération de tâches

Pour ce faire, une demande de découverte est faite:

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

Cela renverra un ensemble de JSON décrivant les services, actions et points de terminaison disponibles. L'exemple ci-dessous est abrégé:

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

Dans ce cas, le client aurait accès au service icloud et à l'action d' fetch-data . Ils auraient besoin de soumettre data paramètres de device et de data lorsqu'ils l'utilisent, et éventuellement aussi since .

Ce dernier paramètre de data doit être sous forme de liste; Ce paramètre peut contenir toutes les valeurs répertoriées dans les permissions > data de la section fetch-data .

task_submission_endpoint est défini dans cette réponse et indique aux clients où des actions peuvent être soumises pour exécution.

Le stream_endpoint dans l'exemple ci - dessus est défini comme aschannel.reincubate.com , ce qui signifie que aschannel est configuré en tant que critère d' évaluation des résultats. Cela pourrait également diriger les clients vers le magasin de stockage , en fonction de la configuration de leur jeton.

Enregistrement de compte et désinscription

`register-account`

Afin de soumettre des actions, nous devons informer asapi des comptes sur lesquels des actions peuvent être effectuées à leur encontre. Pour ce faire, nous allons utiliser le /register-account/ endpoint:

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

Dans cette requête, <SERVICE> est le service qui possède l'action spécifique, alors que <USERNAME> représente le compte qui sera utilisé dans les actions.

`deregister-account`

Si un compte ne doit plus être utilisé, il peut être désenregistré. Pour annuler l'enregistrement d'un compte, une demande similaire peut être envoyée au /deregister-account/ endpoint:

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

Les deux méthodes, en cas de succès, renverront une réponse 200 avec

{ "success": true
}

Les erreurs possibles incluent:

unique_together : "Le compte avec ce service, le client et le nom d'utilisateur existe déjà"

Soumission de tâche

`[TASK-SUBMISSION]`

Les tâches asynchrones peuvent être soumises à l'aide du noeud final spécifié dans task_submission_endpoint .

Pour soumettre une tâche, la commande suivante est utilisée:

$ 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 -

Sur cette demande:

<SERVICE> et <ACTION> représentent le service et l'action cibles
<ACCOUNT> fait référence à un compte précédemment enregistré
param1 , param2 et les paramètres ultérieurs forment la charge utile spécifique de la tâche, dont les exigences sont décrites par la méthode de découverte de service, d'action et de point final

En cas de succès, la demande renverra un 200 avec:

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

Dans ces réponses: <TASK_ID> fournit un ID pour la tâche, qui peut être utilisé pour interroger son statut et extraire le résultat de la tâche, si vous utilisez asstore. <RETRIEVAL_PROTOCOL> indique la méthode utilisée pour extraire les résultats de la tâche et peut prendre la valeur aschannel ou asstore. <STREAM> est l'ID de flux à utiliser pour extraire les résultats de la tâche, si vous utilisez aschannel *

Si la demande était mal formée, la propriété "success" sera fausse et la réponse comportera une section "erreurs" avec commentaires. Par exemple:

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

Les erreurs possibles incluent: * invalid_service : 'Nom de service invalide' * invalid_parameter_value : 'Valeur non autorisée pour le paramètre' * no_such_account : 'Aucun compte de ce type' * invalid : 'Valeur invalide' * limit_exceeded : 'Trop d'ID de tâches soumis' * invalid_action : 'Action invalide' * missing-param : 'Parameter est manquant'

Interrogation des statuts de tâches

`/task-status/`

Pour chaque tâche soumise au noeud final asapi , un task_id est fourni. Le client peut soumettre périodiquement ce task_id au noeud final asapi afin de découvrir le statut d'une tâche. Son statut peut être interrogé avec une requête POST sur le /task-status/ endpoint. Les clients peuvent demander le statut de 10 000 tâches simultanément.

$ 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/

<TASK_ID> au moins un <TASK_ID> , la réponse sera un 200 au format suivant:

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

Si <TASK_SUCCESS> est "True", les résultats sont immédiatement disponibles au point de terminaison approprié.

La propriété status peut prendre les valeurs suivantes:

Pending
In progress
Work complete
Publish ongoing, with result available
Publish complete (dans ce cas, la valeur de success est "true")
Publish failed (dans ce cas, la valeur de success est "false")
Task did not complete successfully. (dans ce cas, la valeur de success soit "false")

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

Le paramètre <CHECK_SUCCESS> situé à la racine de l’arbre JSON fait référence au succès de la vérification du statut. Si cela est "faux", la réponse contiendra une entrée "erreurs" supplémentaire.