Modelos de uso

Cuando trabaje con la interfaz HTTP asíncrona del servicio, puede ver el estado del trabajo y recibir resultados de las siguientes maneras:

• Mediante el uso de notificaciones de devolución de llamada:
  1. Llame al método POST /v1/register_callback para registrar un URL de devolución de llamada con el servicio. Puede proporcionar una serie secreta opcional especificada por el usuario para habilitar la autenticación y la integridad de los datos para las devoluciones de llamada que se envían al URL.
  2. Llame al método POST /v1/recognitions con un URL de devolución de llamada ya registrado al que el servicio envía notificaciones cuando cambia el estado de los trabajos. Debe especificar una lista de los sucesos sobre los que desea recibir notificación. De forma predeterminada, el servicio envía notificaciones cuando se inicia un trabajo, cuando finaliza y si se produce un error. También puede solicitar los resultados de la solicitud en la notificación de finalización. De lo contrario, tendrá que utilizar el método GET /v1/recognitions/{id} para recuperar los resultados.
• Mediante el sondeo del servicio:
  1. Llame al método POST /v1/recognitions sin URL de devolución de llamada, sucesos ni señal de usuario.
  2. Llame de forma periódica al método GET /v1/recognitions para comprobar el estado de los trabajos más recientes o al método GET /v1/recognitions/{id} para comprobar el estado de un trabajo específico.
  3. Si comprueba el estado del trabajo con el método GET /v1/recognitions, llame al método GET /v1/recognitions/{id} para recuperar los resultados del trabajo una vez que haya finalizado.

Los dos enfoques se pueden utilizar juntos. Puede sondear el servicio para obtener el estado más reciente de un trabajo que se ha creado con un URL de devolución de llamada. Por ejemplo, es posible que desee obtener el estado de un trabajo si las notificaciones tardan en llegar. También es posible que quiera comprobar el estado si sospecha que ha perdido una o varias notificaciones debido a un error del servicio o de la red.

Registro de un URL de devolución de llamada

Un URL de devolución de llamada se registra mediante una llamada al método POST /v1/register_callback. Una vez que haya registrado un URL de devolución de llamada, puede utilizarlo para recibir notificaciones para un número indefinido de trabajos. El proceso de registro consta de cuatro pasos:

1. Llama al método POST /v1/register_callback y pasa un URL de devolución de llamada. Si lo desea, también puede especificar un secreto especificado por el usuario. El servicio utiliza el secreto para calcular firmas de código de autenticación de mensajes HMAC (Secure Hash Algorithm) ( SHA-256 ) para la autenticación y la integridad de los datos. En el ejemplo siguiente se registra una devolución de llamada de usuario que responde en el URL http://{user_callback_path}/results. La llamada incluye el secreto de usuario 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. El servicio intenta validar, o colocar en la lista de elementos permitidos, el URL de devolución de llamada si todavía no se ha registrado enviando una solicitud GET al URL de devolución de llamada. El servicio pasa una serie alfanumérica aleatoria de cambio de código mediante el parámetro de consulta challenge_string de la solicitud. La solicitud incluye una cabecera Accept que especifica text/plain como el tipo de respuesta necesario.

   Si la llamada al método register_callback incluía un secreto de usuario, la solicitud GET del servicio también incluye una cabecera X-Callback-Signature que especifica la firma HMAC-SHA256 de la cadena de desafío. El servicio calcula la firma utilizando como clave el secreto de usuario.

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

3. El usuario responde a la solicitud GET procedente del servicio con el código de estado 200. Incluya la serie de cambio que ha enviado el servicio en la respuesta. Incluya la serie en texto sin formato en el cuerpo de la respuesta y establezca la cabecera de respuesta Content-Type en text/plain.

   Si la solicitud inicial POST incluía un secreto de usuario, puede calcular una firma HMAC-SHA256 de la cadena de desafío utilizando el secreto como clave. Si el servicio envió la solicitud GET, la firma coincide con el valor especificado por la cabecera X-Callback-Signature.

   response code: 200 OK
   body: n9ArPGMQ36Hiu7QC
   

4. El servicio comprueba si la serie de cambio se devuelve en el cuerpo de la respuesta a su solicitud GET. Si es así, el servicio coloca el URL de devolución de llamada en la lista de elementos permitidos y responde a la solicitud POST original con el código de estado 201. El cuerpo de la respuesta incluye un objeto JSON con un campo status que tiene el valor created y un campo url que tiene el valor del URL de devolución de llamada.

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

El servicio solo envía una solicitud GET a un URL de devolución de llamada durante el proceso de registro. El servicio debe recibir una respuesta con el código de respuesta 200 que incluya la serie de cambio en su cuerpo en un plazo de cinco segundos. Si no es así, no coloca el URL en la lista de elementos permitidos. En lugar de ello, envía el código de estado 400 como respuesta a la solicitud POST /v1/register_callback. Si el URL de devolución de llamada ya se había colocado correctamente en la lista de elementos permitidos, el servicio envía el código de estado 200 como respuesta a la solicitud POST inicial.

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"

Creación de un trabajo

Un trabajo de reconocimiento se crea mediante una llamada al método POST /v1/recognitions. El modo en que recibe el estado y los resultados del trabajo depende del enfoque que utilice y de los parámetros que pase:

• Para utilizar notificaciones de devolución de llamada, incluya el parámetro de consulta callback_url para especificar un URL al que el servicio debe enviar notificaciones de devolución de llamada cuando cambie el estado del trabajo. También puede especificar los siguientes parámetros de consulta opcionales:
  • events para suscribirse a una lista de sucesos de notificación. De forma predeterminada, el servicio envía notificaciones de devolución de llamada cuando se inicia el trabajo (suceso recognitions.started), cuando finaliza el trabajo (suceso recognitions.completed) y si se produce un error (suceso recognitions.failed). Puede especificar un subconjunto de sucesos o utilizar el suceso recognitions.completed_with_results en lugar del suceso recognitions.completed para incluir los resultados con la notificación de finalización del trabajo.
  • user_token para especificar una serie que se va a incluir con cada notificación para el trabajo. Puesto que puede utilizar el mismo URL de devolución de llamada con un número indefinido de trabajos, puede aprovechar las señales de usuario para diferenciar las notificaciones correspondientes a distintos trabajos.
• Para utilizar el sondeo, omita los parámetros de consulta callback_url, events y user_token. Debe utilizar los métodos GET /v1/recognitions o GET /v1/recognitions/{id} para comprobar el estado del trabajo, utilizando el último para recuperar los resultados cuando finaliza el trabajo.

En ambos casos, puede incluir el parámetro de consulta results_ttl para especificar el número de minutos durante los que deben estar disponibles los resultados después de que finalice el trabajo. El nuevo trabajo propiedad de la instancia del servicio cuyas credenciales se utilizan para crearlo.

Además de los parámetros anteriores, que son específicos de la interfaz asíncrona, el método POST /v1/recognitions da soporte a la mayoría de los parámetros a los que dan soporte las interfaces WebSocket y HTTP síncrona. Para obtener más información, consulte el Resumen de parámetros.

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

Comprobación del estado y recuperación de los resultados de un trabajo

Llame al método GET /v1/recognitions/{id} para comprobar el estado del trabajo especificado con el parámetro de vía de acceso id. La respuesta siempre incluye el ID y el estado del trabajo y su hora de creación y de actualización. Si el estado es completed, la respuesta también incluye los resultados de la solicitud de reconocimiento.

El método GET /v1/recognitions/{id} es el único sistema para recuperar los resultados del trabajo si

• El trabajo se ha enviado sin un URL de devolución de llamada.
• El trabajo se ha enviado con un URL de devolución de llamada pero sin especificar el suceso recognitions.completed_with_results.
• El trabajo no es uno de los 100 trabajos pendientes más recientes. Cuando se omite el parámetro de vía de acceso id, solo se devuelven los 100 trabajos más recientes.

Sin embargo, todavía puede utilizar el método para recuperar los resultados para un trabajo que ha especificado un URL de devolución de llamada y el suceso recognitions.completed_with_results. Puede recuperar los resultados de cualquier trabajo tantas veces como desee mientras estén disponibles. Un trabajo y sus resultados están disponibles hasta que los suprime con el método DELETE /v1/recognitions/{id} o hasta que vence el tiempo de vida del trabajo, lo que se produce en primer lugar. De forma predeterminada, los resultados caducan después de una semana a menos que especifique otro tiempo de vida con el parámetro results_ttl del método 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"
}

Comprobación del estado de los trabajos más recientes

Llame al método GET /v1/recognitions para comprobar el estado de los trabajos más recientes. El método devuelve el estado de los 100 trabajos pendientes más recientes que están asociados a las credenciales con las que se llama. El método devuelve el ID y el estado de cada trabajo, junto con su hora de creación y de actualización. Si un trabajo se ha creado con un URL de devolución de llamada y una señal de usuario, el método también devuelve la señal de usuario correspondiente al trabajo.

La respuesta incluye uno de los estados siguientes:

• waiting si el servicio está preparando el trabajo para su proceso. Este estado es el estado inicial de todos los trabajos. El trabajo permanece en este estado hasta que el servicio tiene capacidad para empezar a procesarlo.
• processing si el servicio está procesando el trabajo de forma activa.
• completed si el servicio ha terminado de procesar el trabajo. Si el trabajo especificada un URL de devolución de llamada y el suceso recognitions.completed_with_results, el servicio envía los resultados con la notificación de devolución de llamada. Si no es así, utilice el método GET /v1/recognitions/{id} para obtener los resultados.
• failed si el trabajo ha fallado por algún motivo.

Un trabajo y sus resultados están disponibles hasta que los suprime con el método DELETE /v1/recognitions/{id} o hasta que vence el tiempo de vida del trabajo, lo que se produce en primer lugar.

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

Supresión de un trabajo

Puede utilizar el método DELETE /v1/recognitions/{id} para suprimir el trabajo especificado con el parámetro de vía de acceso id. Un trabajo se suele suprimir después de obtener sus resultados del servicio. Una vez que se suprime un trabajo, sus resultados dejan de estar disponibles. No puede suprimir un trabajo que el servicio esté procesando de forma activa.

De forma predeterminada, el servicio mantiene los resultados de cada trabajo hasta que caduca el tiempo de vida del trabajo. El tiempo de vida predeterminado es una semana, pero puede utilizar el parámetro results_ttl del método POST /v1/recognitions para especificar el número de minutos que el servicio debe mantener los resultados.

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

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