Demander des données avec asapi (v2)
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.
Méthodes en un coup d'œil
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
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 desuccess
est "true") -
Publish failed
(dans ce cas, la valeur desuccess
est "false") -
Task did not complete successfully.
(dans ce cas, la valeur desuccess
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.
Les erreurs possibles incluent:
-
invalid
: "valeur task_id invalide:" -
limit_exceeded
: "Trop d'identifiants de tâches soumis, la limite est"
Un exemple de sortie est présenté ci-dessous:
{ "<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, }