Modelli di utilizzo

Quando lavori con l'interfaccia HTTP asincrona del servizio, puoi scegliere di conoscere lo stato del lavoro e di ricevere i risultati nei seguenti modi:

• Utilizzando le notifiche di callback:
  1. Chiama il metodo POST /v1/register_callback per registrare un URL di callback con il servizio. Puoi fornire una stringa segreta facoltativa specificata dall'utente per abilitare l'autenticazione e l'integrità dei dati per i callback inviati all'URL.
  2. Chiama il metodo POST /v1/recognitions con un URL di callback già registrato a cui il servizio invia le notifiche quando lo stato del lavoro cambia. Specifica un elenco di eventi per i quali ricevere una notifica. Per impostazione predefinita, il servizio invia le notifiche quando un lavoro viene avviato, quando viene completato e se si verifica un errore. Puoi anche richiedere i risultati della richiesta nella notifica di completamento. Altrimenti, devi utilizzare il metodo GET /v1/recognitions/{id} per richiamare i risultati.
• Eseguendo il polling del servizio:
  1. Chiama il metodo POST /v1/recognitions senza un URL di callback, eventi o token utente.
  2. Chiama periodicamente il metodo GET /v1/recognitions per controllare lo stato dei lavori più recenti o il metodo GET /v1/recognitions/{id} per controllare lo stato di un lavoro specifico.
  3. Se controlli lo stato del lavoro con il metodo GET /v1/recognitions, chiama il metodo GET /v1/recognitions/{id} per richiamare i risultati del lavoro una volta completato.

I due approcci possono essere utilizzati insieme. Puoi ancora eseguire il polling del servizio per ottenere lo stato più recente per un lavoro creato con un URL di callback. Ad esempio, potresti voler ottenere lo stato di un lavoro se la ricezione delle notifiche richiede troppo tempo. Potresti anche controllare lo stato se sospetti di aver perso una o più notifiche a causa di un errore di servizio o di rete.

Registrazione di un URL di callback

Registra un URL di callback chiamando il metodo POST /v1/register_callback. Una volta registrato un URL di callback, puoi utilizzarlo per ricevere notifiche per un numero indefinito di lavori. Il processo di registrazione comprende quattro passi:

1. Chiama il metodo POST /v1/register_callback e passa un URL di callback. Facoltativamente, puoi anche specificare un segreto specificato dall'utente. Il servizio utilizza il segreto per calcolare le firme HMAC (Keyed-Hash Message Authentication Code) e SHA-256 (Secure Hash Algorithm) per l'autenticazione e l'integrità dei dati. Il seguente esempio registra un callback dell'utente che risponde all'URL http://{user_callback_path}/results. La chiamata include il segreto utente 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. Il servizio tenta di convalidare, o inserire nell'elenco di tipi consentiti, l'URL di callback se non è già registrato inviando una richiesta GET all'URL di callback. Il servizio passa una stringa di verifica alfanumerica casuale tramite il parametro di query challenge_string della richiesta. La richiesta include un'intestazione Accept che specifica text/plain come il tipo di risposta richiesto.

   Se la chiamata al metodo register_callback include un segreto utente, la richiesta GET del servizio include anche un'intestazione X-Callback-Signature che specifica la firma HMAC-SHA256 della stringa di sfida. Il servizio calcola la firma utilizzando il segreto utente come chiave.

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

3. Rispondi alla richiesta GET dal servizio con il codice di stato 200. Includi la stringa di verifica inviata dal servizio nella risposta. Includi la stringa in testo semplice nel corpo della risposta e imposta l'intestazione di risposta Content-Type su text/plain.

   Se la richiesta iniziale POST includeva un segreto utente, è possibile calcolare una firma HMAC-SHA256 della stringa di sfida utilizzando il segreto come chiave. Se la richiesta GET è stata inviata dal servizio, la firma corrisponde al valore specificato dall'intestazione X-Callback-Signature.

   response code: 200 OK
   body: n9ArPGMQ36Hiu7QC
   

4. Il servizio controlla se la stringa di verifica viene restituita nel corpo della risposta alla sua richiesta GET. In tal caso, il servizio inserisce nell'elenco di tipi consentiti l'URL di callback e risponde alla tua richiesta POST originale con il codice di stato 201. Il corpo della risposta include un oggetto JSON con un campo status che ha il valore created e un campo url che ha il valore del tuo URL di callback.

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

Il servizio invia solo una singola richiesta GET a un URL di callback durante il processo di registrazione. Il servizio deve ricevere una risposta con il codice di risposta 200 che include la stringa di verifica nel suo corpo entro cinque secondi. In caso contrario, non inserisce l'URL nell'elenco di tipi consentiti. Invece, invia il codice di stato 400 in risposta alla richiesta POST /v1/register_callback. Se l'URL di callback è già stato inserito nell'elenco di tipi consentiti, il servizio invia il codice di stato 200 in risposta alla richiesta POST iniziale.

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"

Creazione di un lavoro

Crea un lavoro di riconoscimento chiamando il metodo POST /v1/recognitions. Il modo in cui apprendi lo stato e i risultati del lavoro dipende dall'approccio che utilizzi e dai parametri che passi:

• Per utilizzare le notifiche di callback, includi il parametro di query callback_url per specificare un URL a cui il servizio deve inviare le notifiche di callback quando lo stato del lavoro cambia. Puoi anche specificare i seguenti parametri di query facoltativi:
  • events per sottoscrivere a un elenco di eventi di notifica. Per impostazione predefinita, il servizio invia notifiche di callback quando il lavoro viene avviato (l'evento recognitions.started), quando il lavoro viene completato (l'evento recognitions.completed) e se si verifica un errore (l'evento recognitions.failed). Puoi specificare un sottoinsieme di eventi o utilizzare l'evento recognitions.completed_with_results anziché l'evento recognitions.completed per includere i risultati con la notifica di completamento del lavoro.
  • user_token per specificare una stringa che deve essere inclusa in ciascuna notifica per il lavoro. Poiché puoi utilizzare lo stesso URL di callback con un numero indefinito di lavori, puoi utilizzare i token utente per differenziare le notifiche per i diversi lavori.
• Per utilizzare il polling, ometti i parametri di query callback_url, events e user_token. Devi quindi utilizzare i metodi GET /v1/recognitions o GET /v1/recognitions/{id} per controllare lo stato del lavoro, utilizzando l'ultimo metodo per richiamare i risultati al termine del lavoro.

In entrambi i casi, puoi includere il parametro di query results_ttl per specificare il numero di minuti per i quali i risultati devono rimanere disponibili al termine del lavoro. Il nuovo lavoro appartiene all'istanza del servizio di cui vengono utilizzate le credenziali per crearlo.

Oltre ai parametri precedenti, che sono specifici per l'interfaccia asincrona, il metodo POST /v1/recognitions supporta la maggior parte degli stessi parametri delle interfacce WebSocket e HTTP sincrona. Per ulteriori informazioni, vedi il Riepilogo dei parametri.

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

Controllo dello stato e richiamo dei risultati di un lavoro

Chiama il metodo GET /v1/recognitions/{id} per controllare lo stato del lavoro specificato con il parametro di percorso id. La risposta include sempre l'ID e lo stato del lavoro e le sue ore di creazione e aggiornamento. Se lo stato è completed, la risposta include anche i risultati della richiesta di riconoscimento.

Il metodo GET /v1/recognitions/{id} è l'unico modo per richiamare i risultati del lavoro se

• Il lavoro è stato inoltrato senza un URL di callback.
• Il lavoro è stato inoltrato con un URL di callback ma senza specificare l'evento recognitions.completed_with_results.
• Il lavoro non è uno dei 100 ultimi lavori in sospeso. Quando ometti il parametro di percorso id vengono restituiti solo gli ultimi 100 lavori.

Tuttavia, puoi ancora utilizzare il metodo per richiamare i risultati per un lavoro che ha specificato un URL di callback e l'evento recognitions.completed_with_results. Puoi richiamare i risultati per qualsiasi lavoro tutte le volte che vuoi mentre rimangono disponibili. Un lavoro e i suoi risultati rimangono disponibili finché non li elimini con il metodo DELETE /v1/recognitions/{id} o finché non scade la durata (TTL) del lavoro, a seconda dell'evento che si verifica per primo. Per impostazione predefinita, i risultati scadono dopo una settimana, a meno che non specifichi una durata (TTL) diversa con il parametro results_ttl del metodo 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"
}

Controllo dello stato dei lavori più recenti

Chiama il metodo GET /v1/recognitions per controllare lo stato dei lavori più recenti. Il metodo restituisce lo stato dei 100 lavori in sospeso più recenti associati alle credenziali con cui viene chiamato. Il metodo restituisce l'ID e lo stato di ogni lavoro, insieme alle relative ore di creazione e aggiornamento. Se un lavoro è stato creato con un URL di callback e un token utente, il metodo restituisce anche il token utente per il lavoro.

La risposta include uno dei seguenti stati:

• waiting se il servizio sta preparando il lavoro per l'elaborazione. Questo è lo stato iniziale di tutti i lavori. Il lavoro rimane in questo stato finché il servizio non ha la capacità di iniziare a elaborarlo.
• processing se il servizio sta elaborando attivamente il lavoro.
• completed se il servizio ha terminato l'elaborazione del lavoro. Se il lavoro ha specificato un URL di callback e l'evento recognitions.completed_with_results, il servizio ha inviato i risultati con la notifica di callback. In caso contrario, utilizza il metodo GET /v1/recognitions/{id} per ottenere i risultati.
• failed se il lavoro non è riuscito per qualche motivo.

Un lavoro e i suoi risultati rimangono disponibili finché non li elimini con il metodo DELETE /v1/recognitions/{id} o finché non scade la durata (TTL) del lavoro, a seconda dell'evento che si verifica per primo.

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

Eliminazione di un lavoro

Puoi utilizzare il metodo DELETE /v1/recognitions/{id} per eliminare il lavoro specificato con il parametro di percorso id. In genere, elimini un lavoro dopo aver ottenuto i suoi risultati dal servizio. Una volta eliminato un lavoro, i suoi risultati non sono più disponibili. Non puoi eliminare un lavoro che il servizio sta elaborando attivamente.

Per impostazione predefinita, il servizio mantiene i risultati di ciascun lavoro fino alla scadenza della durata (TTL) del lavoro. La durata predefinita è una settimana, ma puoi utilizzare il parametro results_ttl del metodo POST /v1/recognitions per specificare il numero di minuti in cui il servizio deve mantenere i risultati.

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

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