Modèles d'utilisation

Lorsque vous utilisez l'interface HTTP asynchrone, vous pouvez choisir d'obtenir le statut du travail et de recevoir les résultats ainsi :

• Utiliser des notifications de rappel :
  1. Appelez la méthode POST /v1/register_callback pour enregistrer une URL de rappel avec le service. Vous pouvez fournir une chaîne secrète spécifiée par l'utilisateur pour permettre l'authentification et assurer l'intégrité des données pour les rappels envoyés à l'URL.
  2. Appelez la méthode POST /v1/recognitions avec une URL de rappel déjà enregistrée, à laquelle le service envoie des notifications à chaque changement de statut du travail. Vous spécifiez la liste des événements pour lesquels vous souhaitez recevoir des notifications. Par défaut, le service envoie des notifications au démarrage et à la fin d'un travail ou si une erreur se produit. Vous pouvez également demander les résultats de la demande dans une notification de fin. Autrement, vous devez utiliser la méthode GET /v1/recognitions/{id} pour extraire les résultats.
• Interroger le service :
  1. Appelez la méthode POST /v1/recognitions sans URL de rappel, événement ou jeton utilisateur.
  2. Appelez régulièrement la méthode GET /v1/recognitions pour vérifier le statut des travaux les plus récents ou la méthode GET /v1/recognitions/{id} pour vérifier le statut d'un travail spécifique.
  3. Si vous vérifiez le statut du travail avec la méthode GET /v1/recognitions, appelez la méthode GET /v1/recognitions/{id} pour extraire les résultats une fois le travail terminé.

Les deux approches peuvent être utilisées ensemble. Vous pouvez continuer à interroger le service pour obtenir le dernier statut d'un travail créé avec une URL de rappel. Par exemple, vous envisagerez peut-être d'obtenir le statut d'un travail si les notifications mettent un certain temps à arriver. Vous souhaiterez peut-être également vérifier le statut si vous suspectez que vous avez manqué une ou plusieurs notifications en raison d'une erreur de service ou d'une erreur réseau.

Enregistrement d'une URL de rappel

Vous enregistrez une URL de rappel en appelant la méthode POST /v1/register_callback. Une fois cette URL enregistrée, vous pouvez l'utiliser afin de recevoir des notifications pour un nombre indéfini de travaux. Le processus d'enregistrement comprend quatre étapes :

1. Vous appelez la méthode POST /v1/register_callback et transmettez une URL de rappel. Vous pouvez éventuellement indiquer une valeur secrète spécifiée par l'utilisateur. SHA-256 Le service utilise le secret pour calculer les signatures HMAC (Secure Hash Algorithm) pour l'authentification et l'intégrité des données. L'exemple suivant enregistre un rappel utilisateur qui répond sur l'URL http://{user_callback_path}/results. Cet appel comprend la valeur secrète de l'utilisateur 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. Le service effectue une tentative de validation ou d'inscription sur liste autorisée de l'URL de rappel si cette URL n'est pas déjà enregistrée en envoyant une demande GET à l'URL de rappel. Le service transmet une chaîne de demande d'accès alphanumérique aléatoire via le paramètre de requête challenge_string de la demande. La demande comprend un en-tête Accept qui indique text/plain comme type de réponse obligatoire.

   Si l'appel à la méthode register_callback comprend un secret d'utilisateur, la demande GET du service comprend également un en-tête X-Callback-Signature qui spécifie la signature HMAC-SHA256 de la chaîne de défi. Le service calcule la signature en utilisant la valeur secrète de l'utilisateur comme clé.

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

3. Vous répondez à la demande GET du service avec le code de statut 200. Incluez la chaîne de demande d'accès envoyée par le service dans la réponse. Incluez la chaîne en texte brut dans le corps de la réponse et définissez l'en-tête de réponse Content-Type avec la valeur text/plain.

   Si la demande initiale POST comprend un secret d'utilisateur, vous pouvez calculer une signature HMAC-SHA256 de la chaîne de défi en utilisant le secret comme clé. Si la demande GET était envoyée par le service, la signature correspond à la valeur indiquée par l'en-tête X-Callback-Signature.

   response code: 200 OK
   body: n9ArPGMQ36Hiu7QC
   

4. Le service vérifie si la chaîne de demande d'accès est renvoyée dans le corps de la réponse à sa demande GET. Si tel est le cas, le service inscrit sur liste autorisée l'URL de rappel et répond à la demande POST d'origine avec le code de statut 201. Le corps de la réponse comprend un objet JSON avec une zone status avec la valeur created et une zone url avec la valeur de votre URL de rappel.

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

Le service envoie uniquement une seule demande GET à une URL de rappel lors du processus d'enregistrement. Il doit recevoir en retour un code de réponse 200 comprenant la chaîne de demande d'accès dans le corps du message dans un délai de cinq secondes. A défaut, il n'ajoutera pas l'URL sur liste autorisée. Il enverra à la place le code de statut 400 en réponse à la demande POST /v1/register_callback. Si l'URL de rappel était déjà sur liste autorisée, le service envoie le code de statut 200 en réponse à la demande POST initiale.

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"

Création d'un travail

Vous pouvez créer un travail de reconnaissance en appelant la méthode POST /v1/recognitions. Vous découvrez le statut et les résultats du travail selon l'approche que vous utilisez et les paramètres que vous transmettez :

• Pour utiliser des notifications de rappel, incluez le paramètre de requête callback_url pour spécifier l'URL à laquelle le service doit envoyer des notifications de rappel à chaque changement de statut du travail. Vous pouvez également spécifier les paramètres de requête facultatifs suivants :
  • events pour vous abonner à une liste d'événements de notification. Par défaut, le service envoie des notifications de rappel au démarrage du travail (événement recognitions.started), à la fin du travail (événement recognitions.completed) et si une erreur se produit (événement recognitions.failed). Vous pouvez préciser un sous-ensemble d'événements ou utiliser l'événement recognitions.completed_with_results à la place de l'événement recognitions.completed pour inclure les résultats avec la notification d'achèvement du travail (job-completed).
  • user_token pour spécifier une chaîne à inclure dans chaque notification concernant le travail. Comme vous pouvez utiliser la même URL de rappel avec un nombre indéfini de travaux, vous pouvez tirer parti des jetons utilisateur pour distinguer les notifications de différents travaux.
• Pour utiliser l'interrogation, omettez les paramètres de requête callback_url, events et user_token. Vous devez ensuite utiliser les méthodes GET /v1/recognitions ou GET /v1/recognitions/{id} pour vérifier le statut du travail, en utilisant ce statut pour extraire les résultats une fois le travail terminé.

Dans les deux cas, vous pouvez inclure le paramètre de requête results_ttl pour spécifier la durée en minutes de la disponibilité des résultats une fois le travail terminé. Le nouveau travail appartient à l'instance du service dont les données d'identification sont utilisées pour créer le service.

En plus des paramètres précédents, qui sont propres à l'interface asynchrone, la méthode POST /v1/recognitions prend en charge la plupart des paramètres utilisés par les interfaces WebSocket et HTTP synchrone. Pour plus d'informations, voir Récapitulatif des paramètres.

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

Vérification du statut et extraction des résultats d'un travail

Vous appelez la méthode GET /v1/recognitions/{id} pour vérifier le statut du travail qui est indiqué avec le paramètre de chemin id. La réponse comprend toujours l'ID et le statut du travail et son heure de création ou de mise à jour. Si le statut est completed, la réponse comprend également les résultats de la demande de reconnaissance.

La méthode GET /v1/recognitions/{id} est le seul moyen d'extraire les résultats du travail dans les cas suivants :

• Le travail a été soumis sans URL de rappel.
• Le travail a été soumis avec une URL de rappel mais sans spécifier l'événement recognitions.completed_with_results.
• Le travail ne figure pas parmi les 100 derniers travaux en attente. Lorsque vous omettez le paramètre de chemin id, seuls les 100 derniers travaux sont renvoyés.

Cependant, vous pouvez continuer à utiliser cette méthode pour extraire les résultats d'un travail ayant spécifié une URL de rappel et l'événement recognitions.completed_with_results. Vous pouvez extraire les résultats d'un travail autant de fois que vous le souhaitez tant qu'ils sont disponibles. Un travail et ses résultats sont disponibles jusqu'à ce que vous les supprimiez avec la méthode DELETE /v1/recognitions/{id} ou jusqu'à ce que la durée de vie du travail soit écoulée, selon ce qui survient en premier. Par défaut, les résultats arrivent à expiration au bout d'une semaine sauf si vous indiquez une autre durée de vie avec le paramètre results_ttl de la méthode POST /v1/recognitions.

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

Vérification du statut des derniers travaux

Vous appelez la méthode GET /v1/recognitions pour vérifier le statut des derniers travaux. La méthode renvoie le statut des 100 travaux en attente les plus récents qui sont associés aux données d'identification avec lesquelles le service est appelé. La méthode renvoie l'ID et le statut de chaque travail, ainsi que son heure de création et de mise à jour. Si un travail a été créé avec une URL de rappel et un jeton utilisateur, la méthode renvoie également le jeton utilisateur du travail.

La réponse comprend l'un des états suivants :

• waiting si le service est en cours de préparation du travail pour le traiter. Ce statut correspond à l'état initial de tous les travaux. Le travail demeure dans cet état jusqu'à ce que le service soit en mesure de commencer son traitement.
• processing si le service est en train de traiter le travail.
• completed si le service a terminé le traitement du travail. Si le travail spécifiait une URL de rappel et l'événement recognitions.completed_with_results, le service a renvoyé les résultats avec la notification de rappel. Autrement, utilisez la méthode GET /v1/recognitions/{id} pour obtenir les résultats.
• failed si le travail a échoué pour une raison quelconque.

Un travail et ses résultats sont disponibles jusqu'à ce que vous les supprimiez avec la méthode DELETE /v1/recognitions/{id} ou jusqu'à ce que la durée de vie du travail soit écoulée, selon ce qui survient en premier.

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

Suppression d'un travail

Vous pouvez utiliser la méthode DELETE /v1/recognitions/{id} pour supprimer le travail spécifié avec le paramètre de chemin id. En général, vous supprimez un travail après avoir obtenu ses résultats du service. Dès que vous avez supprimé un travail, ses résultats ne sont plus disponibles. Vous ne pouvez pas supprimer un travail qui serait actuellement en cours de traitement par le service.

Par défaut, le service conserve les résultats de chaque travail, jusqu'à expiration de la durée de vie du travail. La durée par défaut est d'une semaine, mais vous pouvez utiliser le paramètre results_ttl de la méthode POST /v1/recognitions pour spécifier la durée de conservation des résultats par le service en nombre de minutes.

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

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