Richiesta di dati con asapi (v2)

aggiornato

asapi è un meccanismo di controllo asincrono per l'API ricloud . Permette agli utenti di:

  • Scopri servizi , azioni e endpoint che sono autorizzati a utilizzare
  • Registrati, cancella e scopri i conti
  • Invia attività asincrone
  • Interrogare lo stato delle attività

Una volta completati, i dati delle attività possono essere ottenuti dall'ascanale o dal asstore , a seconda del caso d'uso del cliente.

Metodi a colpo d'occhio

Servizio, azione e scoperta degli endpoint

/account/

Utilizzando il /account/ endpoint, i clienti possono ottenere informazioni su:

  • Servizi disponibili
  • Azioni disponibili e relativi parametri e permessi
  • Endpoint disponibili per l'invio e il recupero delle attività

Per fare ciò, viene fatta una richiesta di scoperta:

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

Ciò restituirà un set di JSON che descrive i servizi, le azioni e gli endpoint disponibili. L'esempio di seguito è abbreviato:

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

In questo caso, il client avrebbe accesso al servizio icloud e all'azione fetch-data . Avrebbero bisogno di inviare data parametri del device e dei data quando lo usano, e facoltativamente anche da since .

Questo ultimo parametro di data deve essere in formato elenco; questo parametro può contenere qualsiasi valore elencato nei permissions > data della sezione fetch-data .

Il task_submission_endpoint è definito in questa risposta e informa i client dove possono essere inviate le azioni per l'esecuzione.

Il stream_endpoint nell'esempio precedente è definito come aschannel.reincubate.com , il che significa che l' aschannel è configurato come endpoint dei risultati. In alternativa, questo potrebbe indirizzare i client a asstore , a seconda della configurazione del loro token.

Registrazione e cancellazione dell'account

register-account

Per presentare le azioni, è necessario informare asapi dei conti che possono avere azioni eseguite contro di loro. Per fare ciò, utilizzeremo l' /register-account/ endpoint:

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

In questa richiesta, <SERVICE> è il servizio che detiene l'azione specifica, mentre <USERNAME> rappresenta per l'account che verrà utilizzato nelle azioni.

deregister-account

Se un account non deve essere ulteriormente utilizzato, può essere cancellato. Per annullare la registrazione di un account, è possibile inviare una richiesta simile a /deregister-account/ endpoint:

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

Entrambi i metodi, in caso di successo, restituiranno una risposta di 200 con

{ "success": true
}

Possibili errori includono:

  • unique_together : "Esiste già un account con questo servizio, client e nome utente"

Invio di attività

[TASK-SUBMISSION]

Le attività asincrone possono essere inviate utilizzando l'endpoint specificato in task_submission_endpoint .

Per inviare un'attività, viene utilizzato il seguente 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 -

Su questa richiesta:

In caso di successo, la richiesta restituirà un 200 con:

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

In queste risposte: <TASK_ID> fornisce un ID per l'attività che può essere utilizzata per interrogare il suo stato e per recuperare il risultato dell'attività , se si utilizza l' asstore <RETRIEVAL_PROTOCOL> indica il metodo utilizzato per recuperare i risultati dell'attività e può assumere il valore di aschannel o asstore <STREAM> è l'ID di flusso da utilizzare nel recupero dei risultati dell'attività , se si utilizza l' aschannel *

Se la richiesta non è corretta, la proprietà "success" sarà falsa e la risposta includerà una sezione "errori" con feedback. Per esempio:

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

Eventuali errori includono: * invalid_service : 'Nome servizio non valido' * invalid_parameter_value : 'Valore non consentito per parametro' * no_such_account : 'Nessun account' * invalid : 'Valore non valido' * limit_exceeded : 'Troppi ID attività inviati' * invalid_action : 'Azione non valida' * missing-param : 'Parametro manca'

Interrogare gli stati delle attività

/task-status/

Per ogni attività inviata all'endpoint asapi , viene fornito un task_id . Il client può inviare periodicamente questo task_id all'endpoint asapi per scoprire lo stato di un'attività. Il suo stato può essere interrogato con una richiesta POST sullo /task-status/ endpoint. I clienti possono richiedere lo stato di fino a 10.000 attività contemporaneamente.

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

Dato almeno un <TASK_ID> corretto, la risposta sarà un 200 in questo formato:

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

Se <TASK_SUCCESS> è "True", i risultati sono immediatamente disponibili all'endpoint appropriato.

La proprietà status può assumere i seguenti valori:

  • Pending
  • In progress
  • Work complete
  • Publish ongoing, with result available
  • Publish complete (in questo caso, il valore di success è "true")
  • Publish failed (in questo caso il valore di success è "falso")
  • Task did not complete successfully. (in questo caso, il valore di success è "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.

Il parametro <CHECK_SUCCESS> situato nella radice dell'albero JSON si riferisce al successo del controllo dello stato stesso. Se questo è "falso", la risposta conterrà una voce aggiuntiva "errori".

Possibili errori includono:

  • invalid : "valore id_attività non valido: "
  • limit_exceeded : "Troppi ID di attività inviati, il limite è "

Di seguito è riportato un esempio di output:

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

Come possiamo aiutare?

Il nostro team di supporto è qui per aiutarti!

I nostri orari di ufficio sono dal lunedì al venerdì, dalle 9:00 alle 17:00 GMT. L'ora è attualmente 5:45 AM GMT.

Miriamo a rispondere a tutti i messaggi entro un giorno lavorativo.

Vai alla sezione di supporto › Contatta il team aziendale ›
Il nostro fantastico team di supporto

© 2008 - 2019 Reincubate Ltd. Tutti i diritti riservati. Registrato in Inghilterra e Galles #5189175, VAT GB151788978. Reincubate® è un marchio registrato. Termini e Condizioni. Raccomandiamo 2FA. Costruito con a Londra.