Modelos de uso

Quando você trabalhar com a interface assíncrona de HTTP do serviço, será possível optar por aprender sobre o status da tarefa e receber resultados das maneiras a seguir:

• Usando notificações de retorno de chamada:
  1. Chame o método POST /v1/register_callback para registrar uma URL de retorno de chamada com o serviço. É possível fornecer uma sequência secreta especificada pelo usuário opcional para ativar a autenticação e a integridade de dados para retornos de chamada que são enviados para a URL.
  2. Chame o método POST /v1/recognitions com uma URL de retorno de chamada já registrada para a qual o serviço envia notificações quando o status da tarefa muda. Você especifica uma lista de eventos dos quais deve ser notificado. Por padrão, o serviço envia notificações quando uma tarefa é iniciada, quando ela é concluída e se ocorre um erro. Também é possível solicitar os resultados da solicitação na notificação de conclusão. Caso contrário, será necessário usar o método GET /v1/recognitions/{id} para recuperar os resultados.
• Ao pesquisar o serviço:
  1. Chame o método POST /v1/recognitions sem uma URL de retorno de chamada, eventos ou um token do usuário.
  2. Periodicamente, chame o método GET /v1/recognitions para verificar o status das tarefas mais recentes ou o método GET /v1/recognitions/{id} para verificar o status de uma tarefa específica.
  3. Se você verificar o status da tarefa com o método GET /v1/recognitions, chame o método GET /v1/recognitions/{id} para recuperar os resultados da tarefa depois que ela estiver concluída.

As duas abordagens podem ser usadas juntas. Ainda é possível pesquisar o serviço para obter o status mais recente para uma tarefa que é criada com uma URL de retorno de chamada. Por exemplo, você poderá desejar obter o status de uma tarefa se as notificações estiverem levando um tempo para chegar. Você também poderá verificar o status se suspeitar que perdeu uma ou mais notificações devido a um erro de serviço ou de rede.

Registrando uma URL de retorno de chamada

Você registra uma URL de retorno de chamada ao chamar o método POST /v1/register_callback. Depois de registrar uma URL de retorno de chamada, é possível usá-la para receber notificações para um número indefinido de tarefas. O processo de registro inclui quatro etapas:

1. Você chama o método POST /v1/register_callback e passa uma URL de retorno de chamada. Opcionalmente, é possível especificar também um segredo especificado pelo usuário. O serviço usa o segredo para calcular assinaturas de código de autenticação de mensagem de hash com chave (HMAC) Secure Hash Algorithm ( SHA-256 ) para autenticação e integridade de dados. O exemplo a seguir registra um retorno de chamada do usuário que responde na URL http://{user_callback_path}/results. A chamada inclui um segredo do usuário de 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. O serviço tentará validar a URL de retorno de chamada ou incluí-la na lista de permissões, se ela ainda não estiver registrada, enviando uma solicitação GET para ela. O serviço passa uma sequência de desafio alfanumérica aleatória por meio do parâmetro de consulta challenge_string da solicitação. A solicitação inclui um cabeçalho Accept que especifica text/plain como o tipo de resposta necessário.

   Se a chamada para o método register_callback incluiu um segredo de usuário, a solicitação GET do serviço também inclui um cabeçalho X-Callback-Signature que especifica a assinatura HMAC-SHA256 da string de desafio. O serviço calcula a assinatura usando o segredo do usuário como a chave.

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

3. Você responde à solicitação GET por meio do serviço com código de status 200. Inclua a sequência de desafio que foi enviada pelo serviço na resposta. Inclua a sequência em texto simples no corpo da resposta e configure o cabeçalho de resposta Content-Type para text/plain.

   Se a solicitação inicial POST incluir um segredo de usuário, você poderá calcular uma assinatura HMAC-SHA256 da string de desafio usando o segredo como chave. Se a solicitação GET foi enviada pelo serviço, a assinatura corresponderá ao valor especificado pelo cabeçalho X-Callback-Signature.

   response code: 200 OK
   body: n9ArPGMQ36Hiu7QC
   

4. O serviço verifica se a sequência de desafio é retornada no corpo da resposta para a sua solicitação GET. Se for, o serviço incluirá a URL de retorno de chamada na lista de permissões e responderá à sua solicitação original de POST com o código de status 201. O corpo da resposta inclui um objeto JSON com um campo status que tem o valor created e um campo url que tem o valor de sua URL de retorno de chamada.

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

O serviço envia apenas uma única solicitação GET para uma URL de retorno de chamada durante o processo de registro. O serviço deve receber uma resposta com o código de resposta 200 que inclui a sequência de desafio em seu corpo dentro de cinco segundos. Caso contrário, ele não inclui a URL na lista de permissões. Em vez disso, ele envia o código de status 400 em resposta para a solicitação POST /v1/register_callback. Se a URL de retorno de chamada já tiver sido incluída na lista de permissões com sucesso, o serviço enviará o código de status 200 em resposta à solicitação de 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"

Criando uma tarefa

Crie uma tarefa de reconhecimento chamando o método POST /v1/recognitions. Como você aprende o status e os resultados da tarefa depende da abordagem que você usa e dos parâmetros que passa:

• Para usar as notificações de retorno de chamada, inclua o parâmetro de consulta callback_url para especificar uma URL para a qual o serviço deve enviar notificações de retorno de chamada quando o status das mudanças da tarefa muda. Também é possível especificar os parâmetros de consulta opcionais a seguir:
  • events para assinar uma lista de eventos de notificação. Por padrão, o serviço envia notificações de retorno de chamada quando a tarefa é iniciada (o evento recognitions.started), quando a tarefa é concluída (o evento recognitions.completed) e se ocorrer um erro (o evento recognitions.failed). É possível especificar um subconjunto dos eventos ou usar o evento recognitions.completed_with_results em vez do evento recognitions.completed para incluir os resultados com a notificação da tarefa concluída.
  • user_token para especificar uma sequência que deve ser incluída com cada notificação para a tarefa. Como é possível usar a mesma URL de retorno de chamada com um número indefinido de tarefas, é possível aproveitar os tokens do usuário para diferenciar notificações para diferentes tarefas.
• Para usar a pesquisa, omita os parâmetros de consulta callback_url, events e user_token. Deve-se, então, usar os métodos GET /v1/recognitions ou GET /v1/recognitions/{id} para verificar o status da tarefa, usando este último para recuperar os resultados quando a tarefa for concluída.

Em ambos os casos, é possível incluir o parâmetro de consulta results_ttl para especificar o número de minutos para os quais os resultados devem permanecer disponíveis após a conclusão da tarefa. A nova tarefa é de propriedade da instância do serviço cujas credenciais são usadas para criá-la.

Além dos parâmetros anteriores, que são específicos para a interface assíncrona, o método POST /v1/recognitions suporta a maioria dos mesmos parâmetros que as interfaces HTTP síncrona e do WebSocket. Para obter mais informações, consulte o Resumo de parâmetro.

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

Verificando o status e recuperando os resultados de uma tarefa

Chame o método GET /v1/recognitions/{id} para verificar o status da tarefa que é especificado com o parâmetro de caminho id. A resposta sempre inclui o ID e o status da tarefa e seus horários de criação e atualização. Se o status for completed, a resposta também incluirá os resultados da solicitação de reconhecimento.

O método GET /v1/recognitions/{id} é a única maneira de recuperar os resultados da tarefa se

• A tarefa foi enviada sem uma URL de retorno de chamada.
• A tarefa foi enviada com uma URL de retorno de chamada, mas sem especificar o evento recognitions.completed_with_results.
• A tarefa não é uma das 100 tarefas pendentes mais recentes. Quando você omitir o parâmetro de caminho id, somente as 100 tarefas mais recentes serão retornadas.

No entanto, ainda é possível usar o método para recuperar os resultados para uma tarefa que especificou uma URL de retorno de chamada e o evento recognitions.completed_with_results. É possível recuperar os resultados para qualquer tarefa quantas vezes você desejar enquanto elas permanecem disponíveis. Uma tarefa e seus resultados permanecem disponíveis até você excluí-los com o método DELETE /v1/recognitions/{id} ou até que o tempo de vida da tarefa expire, o que ocorrer primeiro. Por padrão, os resultados expiram após uma semana, a menos que você especifique um tempo de vida diferente com o parâmetro results_ttl do 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"
}

Verificando o status das tarefas mais recentes

Você chama o método GET /v1/recognitions para verificar o status das tarefas mais recentes. O método retorna o status das 100 tarefas pendentes mais recentes que estão associadas às credenciais com as quais é chamado. O método retorna o ID e o status de cada tarefa, juntamente com suas horas de criação e atualização. Se uma tarefa foi criada com uma URL de retorno de chamada e um token do usuário, o método também retornará o token do usuário para a tarefa.

A resposta inclui um dos estados a seguir:

• waiting se o serviço estiver preparando a tarefa para processamento. Esse status é o estado inicial de todas as tarefas. A tarefa permanece nesse estado até que o serviço tenha a capacidade para começar a processá-la.
• processing se o serviço estiver processando ativamente a tarefa.
• completed se o serviço tiver concluído o processamento da tarefa. Se a tarefa especificou uma URL de retorno de chamada e o evento recognitions.completed_with_results, o serviço enviou os resultados com a notificação de retorno de chamada. Caso contrário, use o método GET /v1/recognitions/{id} para obter os resultados.
• failed se a tarefa falhou por algum motivo.

Uma tarefa e seus resultados permanecem disponíveis até você excluí-los com o método DELETE /v1/recognitions/{id} ou até que o tempo de vida da tarefa expire, o que ocorrer primeiro.

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

Excluindo uma tarefa

É possível usar o método DELETE /v1/recognitions/{id} para excluir a tarefa que é especificada com o parâmetro de caminho id. Geralmente, você exclui uma tarefa depois de obter seus resultados do serviço. Depois de excluir uma tarefa, seus resultados não estarão mais disponíveis. Não é possível excluir uma tarefa que o serviço está processando ativamente.

Por padrão, o serviço mantém os resultados de cada tarefa até que o tempo de vida da tarefa expire. O tempo de vida padrão é uma semana, mas é possível usar o parâmetro results_ttl do método POST /v1/recognitions para especificar o número de minutos que o serviço deve manter os resultados.

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

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