非同步 HTTP 介面

IBM Watson® Speech to Text 服務的非同步 HTTP 介面提供各種透過對該服務的非區塊處理呼叫來轉錄音訊的方法。該介面採用使用者指定的密碼字串和數位簽章，為透過 HTTP 通訊協定提出的要求提供安全層次。若要使用非同步介面，您可以執行下列動作：

登錄回呼 URL，該服務會自動向此 URL 通知工作狀態和結果。
輪詢服務，以手動取得工作狀態和結果。

這兩種方法並不互斥。您可以選擇接收回呼通知，但仍輪詢該服務以取得最新狀態，或聯絡該服務以手動擷取結果。下列各節說明如何搭配任一方法來使用非同步 HTTP 介面。

以單一要求提交最多 1 GB、最少 100 個位元組的音訊資料。如需關於音訊格式以及使用壓縮來最大化您可以隨請求傳送的音訊量的資訊，請參閱支援的音訊格式。有關介面個別方法的詳細資訊，請參閱 API & SDK 參考資料。

非同步 HTTP 介面不支援多部分語音辨識。您只能使用同步 HTTP 介面來處理多部分請求。如需詳細資訊，請參閱提出多部分 HTTP 語音辨識請求。

使用模型

當您使用服務的非同步 HTTP 介面時，可以透過下列方式選擇要瞭解工作狀態和接收結果：

使用回呼通知：
1. 呼叫 POST /v1/register_callback 方法，向服務登錄回呼 URL。您可以提供選用的使用者指定密碼字串，針對傳送至 URL 的回呼啟用鑑別及資料完整性。
2. 使用已登錄的回呼 URL 來呼叫 POST /v1/recognitions 方法，當工作狀態變更時，服務會將通知傳送至此 URL。請指定要收到其通知的事件清單。依預設，服務會在工作啟動時、完成時及發生錯誤時傳送通知。您也可以在完成通知中要求此要求的結果。否則，您需要使用 GET /v1/recognitions/{id} 方法來擷取結果。
輪詢服務：
1. 呼叫 POST /v1/recognitions 方法而不使用回呼 URL、事件或使用者記號。
2. 定期呼叫 GET /v1/recognitions 方法，以檢查最近工作的狀態，或呼叫 GET /v1/recognitions/{id} 方法，以檢查特定工作的狀態。
3. 如果您使用 GET /v1/recognitions 方法檢查工作狀態，請呼叫 GET /v1/recognitions/{id} 方法來擷取已完成之工作的結果。

這兩種方法可以一起使用。您仍然可以輪詢服務，以取得使用回呼 URL 建立之工作的最新狀態。例如，如果通知送達時間有點久，您可能會想要取得工作的狀態。如果您懷疑因為服務或網路錯誤而遺失一個以上的通知，也可以檢查狀態。

登錄回呼 URL

您可以呼叫 POST /v1/register_callback 方法來登錄回呼 URL。登錄回呼 URL 之後，您可以用它來接收無限個工作的通知。登錄程序包含四個步驟：

您呼叫 POST /v1/register_callback 方法，並傳遞回呼 URL。您也可以選擇性地指定使用者指定的密碼。該服務使用該機密來計算密鑰-散列訊息驗證碼 (HMAC) 安全散列演算法 ( SHA-256 ) 簽署，以進行驗證和資料完整性。下列範例會登錄一個在 URL http://{user_callback_path}/results 進行回應的使用者回呼。此呼叫包括使用者密碼 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"
```
如果尚未登錄回呼 URL，服務會將 GET 要求傳送至回呼 URL，以嘗試驗證此回呼 URL 或將其加入允許清單。服務會透過要求的 challenge_string 查詢參數，來傳遞隨機的英數字元盤查字串。該要求包括 Accept 標頭，其指定 text/plain 作為必要的回應類型。

如果對 register_callback 方法的呼叫包含使用者秘密，則從服務發出的 GET 請求也包含 X-Callback-Signature 標頭，該標頭指定了挑戰字串的 HMAC-SHA256 簽署。服務會利用使用者密碼作為金鑰來計算簽章。
```
GET http://{user_callback_path}/results?challenge_string=n9ArPGMQ36Hiu7QC
header: X-Callback-Signature {HMAC-SHA256_signature}
```
您以狀態碼 200 來回應來自服務的 GET 要求。將服務所傳送的盤查字串包含在回應中。在回應內文中包含純文字字串，並將 Content-Type 回應標頭設為 text/plain。

如果初始 POST 請求包含使用者秘密，您可以使用該秘密作為金鑰，計算出挑戰字串的 HMAC-SHA256 簽署。如果服務傳送了 GET 要求，則簽章會符合 X-Callback-Signature 標頭指定的值。
```
response code: 200 OK
body: n9ArPGMQ36Hiu7QC
```
服務會檢查對於其 GET 要求的回應內文中是否有傳回盤查字串。如果有，則服務會將回呼 URL 列入允許清單，並以狀態碼 201 來回應您的原始 POST 要求。回應內文包括的 JSON 物件具有 status 欄位（其值為 created）及 url 欄位（其值為您的回呼 URL）。
```
response code: 201 Created
body: {
  "status": "created",
  "url": "http://{user_callback_path}/results"
}
```

服務在登錄程序期間只會傳送單一 GET 要求給回呼 URL。服務必須在 5 秒內收到具有回應碼 200 的回覆，且其內文中包含了盤查字串。否則，它不會將這個 URL 列入允許清單。相反地，它會傳送狀態碼 400 來回應 POST /v1/register_callback 要求。如果回呼 URL 已順利列入允許清單，則服務會傳送狀態碼 200 來回應起始 POST 要求。

安全考量

當您順利使用 POST /v1/register_callback 方法登錄回呼 URL 時，服務會將此 URL 列入允許清單，以指出它已經過驗證，可以用於回呼通知。如果您使用登錄呼叫來指定使用者密碼，列入允許清單也表示此 URL 已經過驗證，安全性提升。對於在非同步 HTTP 介面中使用回呼 URL 的要求，指定使用者密碼可為這些要求提供鑑別和資料完整性。

服務使用使用者秘密，對其傳送至 URL 的每個回呼通知的有效負載計算 HMAC-SHA256 簽章。此服務會透過每個通知的 X-Callback-Signature 標頭來傳送簽章。用戶端可以使用密碼來計算自己對每個通知有效負載的簽章。如果其簽章符合 X-Callback-Signature 標頭的值，用戶端會知道該通知是由服務傳送，且其內容在傳輸期間未曾變更。此項資訊可保證用戶端不是中間人攻擊的受害者。

HTTPS 很適合用於正式作業應用程式。然而，在應用程式開發及原型化期間，服務支援的 HTTP 型回呼通知可以簡化並加速開發程序，因為它可避免 HTTPS 的費用。

取消登錄回呼 URL

您隨時都可以呼叫 POST /v1/unregister_callback 方法，取消登錄已列入允許清單的回呼 URL。取消登錄回呼 URL，對於使用服務來測試應用程式很有幫助。在取消登錄回呼 URL 之後，您就無法再將它用於非同步辨識要求。

取消登錄回呼 URL 示例

下列範例會取消登錄先前登錄的回呼 URL：

IBM Cloud

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

IBM Cloud Pak for Data IBM Software Hub

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

建立工作

您可以呼叫 POST /v1/recognitions 方法來建立辨識工作。如何瞭解工作的狀態及結果，視您使用的方法及所傳遞的參數而定：

若要使用回呼通知，請包含 callback_url 查詢參數，以指定服務要在工作狀態變更時傳送回呼通知到哪個 URL。您也可以指定下列選用性的查詢參數：
- events，用來訂閱通知事件清單。依預設，服務會在下列時機傳送回呼通知：工作啟動時（recognitions.started 事件）、工作完成時（recognitions.completed 事件）以及發生錯誤時（recognitions.failed 事件）。您可以指定事件的子集，或使用 recognitions.completed_with_results 事件，而不要使用 recognitions.completed 事件），在工作完成的通知中包含結果。
- user_token，用來指定字串以便包含在工作的每個通知中。因為您可以在無限個工作中使用相同的回呼 URL，所以可以運用使用者記號來區分不同工作的通知。
若要使用輪詢，請省略 callback_url、events 及 user_token 查詢參數。然後，您必須使用 GET /v1/recognitions 或 GET /v1/recognitions/{id} 方法來檢查工作的狀態，在工作完成時使用後者來擷取結果。

在這兩種情況下，您都可以包含 results_ttl 查詢參數，以指定在工作完成之後其結果保持可用的分鐘數。新工作是由使用其認證來建立該工作的服務實例所擁有。

除了非同步介面特有的前述參數之外，POST /v1/recognitions 方法還支援大部分與 WebSocket 介面和同步 HTTP 介面相同的參數。如需相關資訊，請參閱參數摘要。

回呼通知

如果是使用回呼 URL 建立工作，則當發生指定的事件時，服務會傳送 HTTP POST 回呼通知到已登錄的 URL。基本通知內文包含具有下列結構的 JSON 物件：

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

id 欄位識別產生回呼之工作的 ID，event 欄位識別觸發回呼的事件。 user_token 欄位包含工作的使用者記號（如果已指定）。否則，該欄位是空字串。如果事件是 recognitions.completed_with_results，則物件會包含 results 欄位，用來提供辨識要求的結果。用戶端可以使用狀態碼 200 來回應回呼通知。

如果登錄回呼 URL 時使用了使用者密碼，則服務也會在回呼通知中傳送 X-Callback-Signature 標頭。標頭指定請求正文的 HMAC-SHA256 簽署。服務會利用使用者密碼作為金鑰來計算簽章。用戶端可以計算回呼通知的有效負載簽章，以確定它符合標頭中的簽章。例如，下列簡易 Python 程式碼會計算 notification_payload 字串的簽章：

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')

建立具有回呼功能的工作 URL 示例

下列範例建立的工作與先前已列入允許清單的回呼 URL http://{user_callback_path}/results 相關聯。此範例會傳遞使用者記號 job25，以識別服務所傳送之回呼通知中的工作。呼叫使用預設事件，因此當服務傳送回呼通知以指出工作已完成時，使用者必須呼叫 GET /v1/recognitions/{id} 方法來擷取結果。呼叫將辨識要求的 timestamps 查詢參數設為 true。

IBM Cloud

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"

IBM Cloud Pak for Data IBM Software Hub

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"

服務會傳回要求的狀態，即 waiting，指出服務正在準備工作以進行處理。回應包含建立時間、工作 ID 以及可在該處取得工作相關資訊的 URL。

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

以輪詢範例建立工作

下列範例建立的工作與回呼 URL 無關。使用者必須輪詢服務，以瞭解工作何時完成，然後使用 GET /v1/recognitions/{id} 方法來擷取結果。如同前一個範例，呼叫將辨識要求的 timestamps 參數設為 true。

IBM Cloud

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

IBM Cloud Pak for Data IBM Software Hub

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

服務傳回 processing 的狀態，指出它已經在處理工作，另外也會傳回建立時間、工作 ID 以及取得工作相關資訊用的 URL。

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

檢查工作的狀態並擷取其結果

您呼叫 GET /v1/recognitions/{id} 方法，來檢查以 id 路徑參數指定之工作的狀態。回應一律會包含工作的 ID 和狀態，以及其建立時間和更新時間。如果狀態是 completed，則回應也包含辨識要求的結果。

GET /v1/recognitions/{id} 方法是在下列情況下擷取工作結果的唯一方法：

已提交工作，但沒有回呼 URL。
已使用回呼 URL 提交工作，但未指定 recognitions.completed_with_results 事件。
工作不是 100 個最新未完成的工作之一。當您省略 id 路徑參數時，只會傳回 100 個最新工作。

不過，對於已指定回呼 URL 和 recognitions.completed_with_results 事件的工作，您還是可以使用此方法來擷取工作的結果。只要工作結果仍然可用，您便可以依需要多次擷取任何工作的結果。在您使用 DELETE /v1/recognitions/{id} 方法刪除工作之前或工作的存活時間到期之前（以先到者為準），工作及其結果便仍然可用。除非您使用 results_ttl 方法的 POST /v1/recognitions 參數指定不同的存活時間，否則依預設，結果會在一週後到期。

檢查工作狀態無結果範例

以下範例檢查指定 ID 的工作狀態：

IBM Cloud

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

IBM Cloud Pak for Data IBM Software Hub

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

檢查工作狀態與結果範例

以下範例請求指定 ID 的工作狀態：

IBM Cloud

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

IBM Cloud Pak for Data IBM Software Hub

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

檢查最新工作的狀態

您呼叫 GET /v1/recognitions 方法，來檢查最新工作的狀態。此方法會傳回與用來呼叫之認證相關聯的最近 100 個未完成工作的狀態。方法會傳回每個工作的 ID 和狀態，以及其建立時間和更新時間。如果工作是使用回呼 URL 和使用者記號建立的，此方法也會傳回工作的使用者記號。

回應包含下列其中一種狀態：

waiting，表示服務正在準備工作以進行處理。此狀態是所有工作的起始狀態。工作將保持此狀態，直到服務有容量開始處理它為止。
processing，表示服務正積極處理工作。
completed，表示服務已完成處理工作。如果工作指定了回呼 URL 和事件 recognitions.completed_with_results，服務會在回呼通知中傳送結果。否則，請使用 GET /v1/recognitions/{id} 方法來取得結果。
failed，表示工作因故失敗。

在您使用 DELETE /v1/recognitions/{id} 方法刪除工作之前或工作的存活時間到期之前（以先到者為準），工作及其結果便仍然可用。

檢查最新工作的狀態範例

以下範例請求與呼叫者憑證相關聯的最新當前工作的狀態：

IBM Cloud

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

IBM Cloud Pak for Data IBM Software Hub

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

使用者有三個未完成的工作處於不同狀態。第一個工作是使用回呼 URL 和使用者記號建立的。

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

刪除工作

您可以使用 DELETE /v1/recognitions/{id} 方法，來刪除使用 id 路徑參數指定的工作。通常您從服務取得工作的結果之後就會刪除該工作。刪除工作之後，就無法再使用其結果。您無法刪除服務正積極處理的工作。

依預設，服務會維護每個工作的結果，直到工作的存活時間到期為止。預設存活時間為一週，但您可以使用 results_ttl 方法的 POST /v1/recognitions 參數來指定服務維護結果的分鐘數。

刪除工作範例

下列範例會刪除具有指定 ID 的工作：

IBM Cloud

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

IBM Cloud Pak for Data IBM Software Hub

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