Verwendungsmodelle

Bei der Arbeit mit der asynchronen HTTP-Schnittstelle des Service haben Sie die folgenden Möglichkeiten, um sich über den Jobstatus zu informieren und Ergebnisse zu empfangen:

• Verwendung von Callback-Benachrichtigungen:
  1. Rufen Sie die Methode POST /v1/register_callback auf, um eine Callback-URL beim Service zu registrieren. Sie können optional eine benutzerdefinierte geheime Zeichenfolge bereitstellen, um die Authentifizierung und die Datenintegrität für Callbacks zu aktivieren, die an die URL gesendet werden.
  2. Rufen Sie die Methode POST /v1/recognitions mit einer bereits registrierten Callback-URL auf, an die der Service Benachrichtigungen sendet, wenn sich der Status des Jobs ändert. Sie geben eine Liste der Ereignisse an, über die Sie benachrichtigt werden wollen. Standardmäßig sendet der Service Benachrichtigungen, wenn ein Job gestartet wird, wenn ein Job abgeschlossen ist und wenn ein Fehler auftritt. Sie können anfordern, dass in der Abschlussbenachrichtigung auch die Ergebnisse der Anforderung gesendet werden. Andernfalls müssen Sie die Ergebnisse mit der Methode GET /v1/recognitions/{id} abrufen.
• Abfrage des Service:
  1. Rufen Sie die Methode POST /v1/recognitions ohne Callback-URL, Ereignisse oder Benutzertoken auf.
  2. Rufen Sie in regelmäßigen Abständen die Methode GET /v1/recognitions auf, um den Status der neuesten Jobs zu überprüfen, oder rufen Sie die Methode GET /v1/recognitions/{id} auf, um den Status eines bestimmten Jobs zu überprüfen.
  3. Falls Sie den Jobstatus mit der Methode GET /v1/recognitions überprüfen, rufen Sie die Methode GET /v1/recognitions/{id} auf, um nach Abschluss des Jobs die Ergebnisse abzurufen.

Die beiden Verfahren können kombiniert verwendet werden. Für einen Job, der mit einer Callback-URL erstellt wurde, können Sie trotzdem den neuesten Status beim Service abfragen. Es kann beispielsweise vorkommen, dass Sie den Status eines Jobs abrufen wollen, wenn Benachrichtigungen erst nach einer Weile eintreffen. Eine Überprüfung des Status kann außerdem sinnvoll sein, wenn Sie vermuten, dass Sie aufgrund eines Service- oder Netzfehlers eine oder mehrere Benachrichtigungen nicht erhalten haben.

Callback-URL registrieren

Zum Registrieren einer Callback-URL rufen Sie die Methode POST /v1/register_callback auf. Sobald Sie eine Callback-URL registriert haben, können Sie sie für den Empfang von Benachrichtigungen über eine unbegrenzte Anzahl von Jobs verwenden. Der Registrierungsprozess umfasst vier Schritte:

1. Rufen Sie die Methode POST /v1/register_callback auf und übergeben Sie eine Callback-URL. Optional können Sie auch einen benutzerdefinierten geheimen Schlüssel angeben. Der Dienst verwendet das Geheimnis zur Berechnung von Secure Hash Algorithm ( SHA-256 ) Signaturen zur Authentifizierung und Datenintegrität. Im folgenden Beispiel wird ein Callback für einen Benutzer registriert, der an der URL http://{user_callback_path}/results antwortet. Der Aufruf enthält den geheimen Benutzerschlüssel ThisIsMySecret.

   IBM Cloud

   curl -X POST -u "apikey:{apikey}" \
   "{url}/v1/register_callback?callback_url=http://{user_callback_path}/results&user_secret=ThisIsMySecret"
   

   IBM Cloud Pak for Data IBM Software Hub

   curl -X POST \
   --header "Authorization: Bearer {token}" \
   "{url}/v1/register_callback?callback_url=http://{user_callback_path}/results&user_secret=ThisIsMySecret"
   

2. Der Service versucht, die Callback-URL zu validieren (oder der Zulassungsliste zuzuordnen), falls diese noch nicht registriert wurde. Hierzu sendet er eine Anforderung GET an die Callback-URL. Der Service übergibt eine zufällige alphanumerische Abfragezeichenfolge über den Abfrageparameter challenge_string der Anforderung. Die Anforderung enthält einen Header Accept, der text/plain als erforderlichen Antworttyp angibt.

   Wenn der Aufruf der Methode register_callback ein Benutzergeheimnis enthielt, enthält die GET-Anfrage des Dienstes auch einen X-Callback-Signature-Header, der die HMAC-SHA256-Signatur des Challenge-Strings angibt. Der Service berechnet die Signatur und verwendet hierzu den geheimen Benutzerschlüssel als Schlüssel.

   GET http://{user_callback_path}/results?challenge_string=n9ArPGMQ36Hiu7QC
   header: X-Callback-Signature {HMAC-SHA256_signature}
   

3. Sie antworten auf die Anforderung GET aus dem Service mit dem Statuscode 200. Beziehen Sie die vom Service gesendete Abfragezeichenfolge in die Antwort ein. Nehmen Sie die Zeichenfolge als unverschlüsselten Text in den Hauptteil der Antwort auf und legen Sie für den Antwortheader Content-Type den Wert text/plain fest.

   Wenn die ursprüngliche POST Anfrage ein Benutzergeheimnis enthielt, können Sie eine HMAC-SHA256 Signatur der Abfragezeichenfolge berechnen, indem Sie das Geheimnis als Schlüssel verwenden. Sofern die Anforderung GET durch den Service gesendet wurde, stimmt die Signatur mit dem Wert überein, der im Header X-Callback-Signature angegeben ist.

   response code: 200 OK
   body: n9ArPGMQ36Hiu7QC
   

4. Der Service überprüft, ob die Abfragezeichenfolge im Hauptteil der Antwort auf seine Anforderung GET zurückgegeben wurde. Ist dies der Fall, listet der Service die Callback-URL in der Zulassungsliste auf und antwortet auf Ihre ursprüngliche Anforderung POST mit dem Statuscode 201. Der Hauptteil der Antwort enthält ein JSON-Objekt mit einem Feld status, das den Wert created hat, und einem Feld url, das den Wert Ihrer Callback-URL enthält.

   response code: 201 Created
   body: {
     "status": "created",
     "url": "http://{user_callback_path}/results"
   }
   

Der Service sendet während des Registrierungsprozesses nur eine einzige Anforderung GET an eine Callback-URL. Der Service muss innerhalb von 5 Sekunden eine Antwort mit dem Antwortcode 200 empfangen, deren Hauptteil die Abfragezeichenfolge enthält. Andernfalls wird die URL nicht in die Zulassungsliste aufgenommen, sondern stattdessen als Antwort auf die Anforderung POST /v1/register_callback der Statuscode 400 gesendet. Falls die Callback-URL bereits erfolgreich in die Zulassungsliste aufgenommen wurde, sendet der Service als Antwort auf die ursprüngliche Anforderung POST den Statuscode 200.

curl -X POST -u "apikey:{apikey}" \
"{url}/v1/unregister_callback?callback_url=http://{user_callback_path}/results"

curl -X POST \
--header "Authorization: Bearer {token}" \
"{url}/v1/unregister_callback?callback_url=http://{user_callback_path}/results"

Job erstellen

Zum Erstellen eines Erkennungsjobs rufen Sie die Methode POST /v1/recognitions auf. Auf welche Weise Sie den Status des Jobs und die Ergebnisse erfahren, variiert abhängig von der verwendeten Strategie und den übergebenen Parametern:

• Zur Verwendung von Callback-Benachrichtigungen beziehen Sie den Abfrageparameter callback_url ein und geben Sie eine URL an, an die der Service Callback-Benachrichtigungen senden soll, sobald sich der Status des Jobs ändert. Sie können außerdem die folgenden optionalen Abfrageparameter angeben:
  • Geben Sie den Parameter events ein, um eine Liste von Benachrichtigungsereignissen zu abonnieren. Standardmäßig sendet der Service Callback-Benachrichtigungen, wenn der Job gestartet wird (Ereignis recognitions.started), wenn der Job abgeschlossen ist (Ereignis recognitions.completed) und falls ein Fehler auftritt (Ereignis recognitions.failed). Sie können eine Teilmenge der Ereignisse angeben oder das Ereignis recognitions.completed_with_results anstelle des Ereignisses recognitions.completed verwenden, damit die Ergebnisse zusammen mit der Benachrichtigung über den Jobabschluss gesendet werden.
  • Geben Sie mit dem Parameter user_token eine Zeichenfolge an, die in jeder Benachrichtigung über den Job enthalten sein soll. Da Sie dieselbe Callback-URL bei einer unbegrenzten Anzahl von Jobs verwenden können, ermöglicht die Verwendung von Benutzertokens eine Unterscheidung zwischen den Benachrichtigungen für verschiedene Jobs.
• Zur Verwendung von Abfragen lassen Sie die Abfrageparameter callback_url, events und user_token weg. Anschließend müssen Sie die Methoden GET /v1/recognitions oder GET /v1/recognitions/{id} verwenden, um den Status des Jobs zu überprüfen; mit der zweiten Methode werden die Ergebnisse nach dem Abschluss eines Jobs abgerufen.

In beiden Fällen können Sie durch das Hinzufügen des Abfrageparameters results_ttl angeben, wie viele Minuten die Ergebnisse nach dem Abschluss des Jobs verfügbar bleiben sollen. Eigner des neuen Jobs ist die Serviceinstanz, deren Berechtigungsnachweise beim Erstellen des Jobs verwendet wurden.

Neben den obigen Parametern, die speziell für die asynchrone Schnittstelle gelten, unterstützt die Methode POST /v1/recognitions einen Großteil derselben Parameter wie die WebSocket-Schnittstelle oder die synchrone HTTP-Schnittstelle. Weitere Informationen enthält der Abschnitt Parameterübersicht.

{
  "id": "{job_id}",
  "event": "{recognitions_status}",
  "user_token": "{user_token}"
}

import hmac
import base64
from hashlib import sha256
# 'user_secret' and 'notification_payload' must be bytes
hashed = hmac.new(user_secret, notification_payload, sha256)
signature = base64.b64encode(hashed.digest()).decode().rstrip('\n')

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @{path}audio-file.flac \
"{url}/v1/recognitions?callback_url=http://{user_callback_path}/results&user_token=job25&timestamps=true"

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @{path}audio-file.flac \
"{url}/v1/recognitions?callback_url=http://{user_callback_path}/results&user_token=job25&timestamps=true"

{
  "created": "2016-08-17T19:15:17.926Z",
  "id": "4bd734c0-e575-21f3-de03-f932aa0468a0",
  "url": "{url}/v1/recognitions/4bd734c0-e575-21f3-de03-f932aa0468a0",
  "status": "waiting"
}

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/wav" \
--data-binary @{path}audio-file.wav \
"{url}/v1/recognitions?timestamps=true"

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/wav" \
--data-binary @{path}audio-file.wav \
"{url}/v1/recognitions?timestamps=true"

{
  "created": "2016-08-17T19:13:23.622Z",
  "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "url": "{url}/v1/recognitions/4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "status": "processing"
}

Status eines Jobs überprüfen und Jobergebnisse abrufen

Durch einen Aufruf der Methode GET /v1/recognitions/{id} überprüfen Sie den Status des Jobs, der durch den Pfadparameter id angegeben wird. Die Antwort enthält immer die ID und den Status des Jobs sowie dessen Erstellungs- und Aktualisierungszeit. Falls der Status completed (= abgeschlossen) lautet, enthält die Antwort auch die Ergebnisse der Erkennungsanforderung.

In den folgenden Fällen ist die Methode GET /v1/recognitions/{id} die einzige Möglichkeit zum Abrufen von Jobergebnissen:

• Der Job wurde ohne Callback-URL übergeben.
• Der Job wurde mit einer Callback-URL, jedoch ohne Angabe des Ereignisses recognitions.completed_with_results übergeben.
• Der Job ist keiner der 100 letzten ausstehenden Jobs. Wenn Sie den Pfadparameter id weglassen, werden nur die 100 letzten Jobs zurückgegeben.

Mit der Methode können Sie jedoch immer auch die Ergebnisse für einen Job abrufen, der eine Callback-URL und das Ereignis recognitions.completed_with_results angegeben hat. Sie können die Ergebnisse für einen beliebigen Job so häufig wie gewünscht abrufen, während die Ergebnisse verfügbar bleiben. Ein Job und seine Ergebnisse bleiben verfügbar, bis Sie sie mit der Methode DELETE /v1/recognitions/{id} löschen oder bis die Lebensdauer des Jobs abläuft (je nachdem, was zuerst eintritt). Standardmäßig verfallen Ergebnisse nach einer Woche, sofern Sie mit dem Parameter results_ttl der Methode POST /v1/recognitions keine andere Lebensdauer angegeben haben.

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"

{
  "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
  "created": "2016-08-17T19:13:23.622Z",
  "updated": "2016-08-17T19:13:24.434Z",
  "status": "processing"
}

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"

{
  "id": "398fcd80-330a-22ba-93ce-1a73f454dd98",
  "results": [
    {
      "result_index": 0,
      "results": [
        {
          "final": true,
          "alternatives": [
            {
              "transcript": "several tornadoes touch down as a line of severe thunderstorms swept through Colorado on Sunday ",
              "timestamps": [
                [
                  "several",
                  1,
                  1.52
                ],
                [
                  "tornadoes",
                  1.52,
                  2.15
                ],
                . . .
                [
                  "Sunday",
                  5.74,
                  6.33
                ]
              ],
              "confidence": 0.96
            }
          ]
        }
      ]
    }
  ],
  "created": "2016-08-17T19:11:04.298Z",
  "updated": "2016-08-17T19:11:16.003Z",
  "status": "completed"
}

Status der letzten Jobs überprüfen

Durch einen Aufruf der Methode GET /v1/recognitions können Sie den Status der letzten Jobs überprüfen. Die Methode gibt den Status der letzten 100 ausstehenden Jobs zurück, die den Berechtigungsnachweisen zugeordnet sind, mit denen die Methode aufgerufen wird. Die Methode gibt die ID und den Status jedes Jobs zusammen mit seiner Erstellungs- und Aktualisierungszeit zurück. Wenn ein Job mit einer Callback-URL und einem Benutzertoken erstellt wurde, gibt die Methode auch das Benutzertoken für den Job zurück.

Die Antwort enthält einen der folgenden Status:

• waiting: Der Service bereitet den Job für die Verarbeitung vor. Dieser Status ist der Anfangsstatus aller Jobs. Der Job bleibt in diesem Status, bis der Service über die Kapazität für den Beginn der Verarbeitung verfügt.
• processing: Der Service verarbeitet den Job aktiv.
• completed: Der Service hat die Verarbeitung des Jobs fertiggestellt. Falls der Job eine Callback-URL und das Ereignis recognitions.completed_with_results angegeben hat, sendet der Service zusammen mit der Callback-Benachrichtigung die Ergebnisse. Andernfalls müssen Sie die Ergebnisse mit der Methode GET /v1/recognitions/{id} abrufen.
• failed: Der Job ist aus einem nicht genauer bezeichneten Grund fehlgeschlagen.

Ein Job und seine Ergebnisse bleiben verfügbar, bis Sie sie mit der Methode DELETE /v1/recognitions/{id} löschen oder bis die Lebensdauer des Jobs abläuft (je nachdem, was zuerst eintritt).

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/recognitions"

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions"

{
  "recognitions": [
    {
      "id": "4bd734c0-e575-21f3-de03-f932aa0468a0",
      "created": "2016-08-17T19:15:17.926Z",
      "updated": "2016-08-17T19:15:17.926Z",
      "status": "waiting",
      "user_token": "job25"
    },
    {
      "id": "4bb1dca0-f6b1-11e5-80bc-71fb7b058b20",
      "created": "2016-08-17T19:13:23.622Z",
      "updated": "2016-08-17T19:13:24.434Z",
      "status": "processing"
    },
    {
      "id": "398fcd80-330a-22ba-93ce-1a73f454dd98",
      "created": "2016-08-17T19:11:04.298Z",
      "updated": "2016-08-17T19:11:16.003Z",
      "status": "completed"
    }
  ]
}

Job löschen

Mit der Methode DELETE /v1/recognitions/{id} können Sie den Job löschen, der im Pfadparameter id angegeben ist. Normalerweise löschen Sie einen Job, nachdem Sie seine Ergebnisse aus dem Service abgerufen haben. Sobald Sie einen Job gelöscht haben, sind seine Ergebnisse nicht mehr verfügbar. Ein Job, den der Service aktiv verarbeitet, kann nicht gelöscht werden.

Standardmäßig bewahrt der Service die Ergebnisse jedes Jobs auf, bis die Lebensdauer des Jobs abläuft. Die Standardlebensdauer beträgt eine Woche. Mit dem Parameter results_ttl der Methode POST /v1/recognitions können Sie jedoch angeben, wie viele Minuten der Service die Ergebnisse aufbewahren soll.

curl -X DELETE -u "apikey:{apikey}" \
"{url}/v1/recognitions/{job_id}"

curl -X DELETE \
--header "Authorization: Bearer {token}" \
"{url}/v1/recognitions/{job_id}"