Anfordern von Daten mit asapi (v2)

Aktualisierte

asapi ist ein asynchroner Kontrollmechanismus für die Ricloud- API. Es ermöglicht Benutzern Folgendes:

  • Entdecken Sie Dienste , Aktionen und Endpunkte, zu deren Verwendung sie berechtigt sind
  • Registrieren, abmelden und mehr über Konten erfahren
  • Übermitteln Sie asynchrone Aufgaben
  • Fragen Sie den Status von Aufgaben ab

Sobald die Aufgaben abgeschlossen sind, können die Daten je nach Anwendungsfall des Kunden entweder über den A- Channel oder den A- Store abgerufen werden.

Methoden auf einen Blick

Service-, Aktions- und Endpunkterkennung

/account/

Mit dem Befehl /account/ endpoint können Clients Informationen zu folgenden Themen abrufen:

  • Verfügbare Dienste
  • Verfügbare Aktionen sowie deren Parameter und Berechtigungen
  • Endpunkte, die zum Senden und Abrufen von Aufgaben zur Verfügung stehen

Dazu wird eine Discovery-Anfrage gestellt:

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

Dadurch wird eine JSON-Gruppe zurückgegeben, die die verfügbaren Dienste, Aktionen und Endpunkte beschreibt. Das folgende Beispiel wird abgekürzt:

{ "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 diesem Fall hätte der Client Zugriff auf den icloud Dienst und die Aktion zum fetch-data . Sie müßten einreichen device und data , wenn es verwendet wird , und gegebenenfalls auch since .

Diese letzten data - Parameter muss in Listenformat sein; Dieser Parameter kann alle Werte enthalten, die im Abschnitt " permissions > data des fetch-data .

Der task_submission_endpoint wird in dieser Antwort definiert und informiert Clients, wo Aktionen zur Ausführung übermittelt werden können.

Der stream_endpoint im obigen Beispiel ist als aschannel.reincubate.com definiert, was bedeutet, dass aschannel als Ergebnisendpunkt konfiguriert ist. Alternativ könnte dies Clients in Abhängigkeit von der Konfiguration ihres Tokens an einen Speicher weiterleiten .

Kontoregistrierung und -abmeldung

register-account

Um Aktionen einzureichen, müssen wir asapi über die Konten informieren, auf denen möglicherweise Aktionen ausgeführt werden. Dazu verwenden wir den /register-account/ endpoint:

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

In dieser Anforderung ist <SERVICE> ein Dienst, dem die bestimmte Aktion gehört, während <USERNAME> für das Konto steht, das in den Aktionen verwendet wird.

deregister-account

Wenn ein Konto nicht mehr verwendet werden soll, kann es abgemeldet werden. Zum Abmelden eines Kontos kann eine ähnliche Anfrage an den /deregister-account/ Endpunkt gesendet werden:

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

Beide Methoden geben im Erfolgsfall eine Antwort von 200 mit zurück

{ "success": true
}

Mögliche Fehler sind:

  • unique_together : "Account mit diesem Service, Client und Benutzername existiert bereits"

Aufgabe übergeben

[TASK-SUBMISSION]

Asynchrone Aufgaben können unter Verwendung des in task_submission_endpoint angegebenen Endpunkts task_submission_endpoint .

Um eine Aufgabe zu senden, wird der folgende Befehl verwendet:

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

Auf diese Anfrage:

Bei Erfolg gibt die Anfrage 200 mit:

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

In diesen Antworten: <TASK_ID> gibt eine ID für die Aufgabe an, mit der der Status abgefragt und das Ergebnis der Aufgabe abgerufen werden kann, wenn der asstore verwendet wird <RETRIEVAL_PROTOCOL> gibt die Methode zum Abrufen der Taskergebnisse an und kann den Wert eines Kanals oder eines Speichers annehmen. <STREAM> ist die Stream-ID zum Abrufen der Taskergebnisse , wenn der a- Kanal verwendet wird.

Wenn die Anforderung fehlerhaft war, ist die Eigenschaft "success" falsch und die Antwort enthält einen Abschnitt "errors" mit Rückmeldung. Zum Beispiel:

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

Mögliche Fehler sind: * invalid_service : 'Ungültiger Servicename' * invalid_parameter_value : 'Wert für Parameter nicht zulässig' * no_such_account : 'Kein solches Konto' * invalid : 'Ungültiger Wert' * limit_exceeded : 'Zu viele Aufgaben-IDs übermittelt' * invalid_action : 'Ungültige Aktion' * missing-param : 'Parameter wird vermisst'

Taskstatus abfragen

/task-status/

Für jede an den asapi- Endpunkt übermittelte Aufgabe wird eine task_id bereitgestellt. Der Client kann diese task_id an den asapi- Endpunkt task_id , um den Status einer Task zu ermitteln. Sein Status kann mit einer POST Anfrage auf dem /task-status/ endpoint abgefragt werden. Clients können den Status von bis zu 10.000 Aufgaben gleichzeitig anfordern.

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

Bei mindestens einer korrekten <TASK_ID> die Antwort 200 in diesem Format:

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

Wenn <TASK_SUCCESS> "True" ist, sind die Ergebnisse sofort am entsprechenden Endpunkt verfügbar.

Die status Eigenschaft kann die folgenden Werte annehmen:

  • Pending
  • In progress
  • Work complete
  • Publish ongoing, with result available
  • Publish complete (in diesem Fall ist der success "wahr")
  • Publish failed (in diesem Fall ist der success "false")
  • Task did not complete successfully. (in diesem Fall ist der success "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.

Der Parameter <CHECK_SUCCESS> im Stammverzeichnis des JSON-Baums verweist auf den Erfolg der <CHECK_SUCCESS> . Wenn dies "falsch" ist, enthält die Antwort einen zusätzlichen Eintrag "Fehler".

Mögliche Fehler sind:

  • invalid : "Ungültiger task_id-Wert: "
  • limit_exceeded : "Zu viele Aufgaben-IDs übermittelt, limit ist "

Ein Beispiel für die Ausgabe ist unten dargestellt:

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

Wie können wir helfen?

Unser Support-Team hilft Ihnen gerne weiter!

Unsere Bürozeiten sind Montag bis Freitag von 9 bis 17 Uhr GMT. Die Zeit ist aktuell 9:16 nachm. GMT.

Wir bemühen uns, auf alle Mitteilungen innerhalb eines Arbeitstages zu antworten.

Zum Support-Bereich gehen › Wenden Sie sich an das Unternehmensteam ›
Unser großartiges Supportteam

© 2008 - 2019 Reincubate Ltd. Alle Rechte vorbehalten. Registriert in England und Wales #5189175, VAT GB151788978. Reincubate® ist eine eingetragene Marke. Datenschutz. Wir empfehlen die Multi-Faktor-Authentifizierung. Mit Liebe in London gebaut.