如何以非同步方式使用語言服務功能

  • 發行項

語言服務可讓您使用 REST API 或用戶端程式庫，以非同步方式傳送 API 要求。 您也可以在您的要求中包含多個不同的語言服務功能，以在您的資料上同時執行。

目前，您可以利用下列功能以非同步方式使用：

  • 實體連結
  • 文件摘要
  • 交談摘要
  • 關鍵片語擷取
  • 語言偵測
  • 具名實體辨識 (NER)
  • 客戶內容偵測
  • 情緒分析與意見挖掘
  • 健康情況的文字分析
  • 個人識別資訊 (PII)

當您傳送非同步要求時，將會根據您在要求中針對每項功能使用所包含的文字記錄數目來產生費用。 例如，如果您傳送情感分析和 NER 的文字記錄，則會將其視為傳送兩筆文字記錄，且將會根據您的定價層向您收費。

使用 REST API 提交非同步作業

若要提交非同步作業，請檢閱您將在要求中傳送的 JSON 本文參考文件。

  1. 將您的文件新增至 analysisInput 物件。
  2. 在 tasks 物件中，請包含您要對資料執行的作業。 例如，如果您想要執行情感分析，則要包含 SentimentAnalysisLROTask 物件。
  3. 您可以選擇性地執行下列動作：
    1. 選擇您資料上所使用模型的特定版本。
    2. 在 tasks 物件中包含其他語言服務特徵，以在您的資料上同時執行。

建立要求的 JSON 主體之後，請將您的金鑰新增至 Ocp-Apim-Subscription-Key 標頭。 然後將 API 要求傳送至作業建立端點。 例如：

POST https://your-endpoint.cognitiveservices.azure.com/language/analyze-text/jobs?api-version=2022-05-01

成功的呼叫會傳回 202 回應碼。 回應標頭中的 operation-location 會是您將用來擷取 API 結果的 URL。 值會如以下影 URL 所示：

GET {Endpoint}/language/analyze-text/jobs/12345678-1234-1234-1234-12345678?api-version=2022-05-01

若要取得狀態並擷取要求的結果，請將 GET 要求傳送至您在先前 API 回應 operation-location 標頭中收到的 URL。 請記得將您的金鑰包含在 Ocp-Apim-Subscription-Key 中。 回應會包含 API 呼叫的結果。

使用用戶端程式庫傳送非同步 API 要求

首先，請確定您已安裝您所選語言的用戶端程式庫。 如需安裝用戶端程式庫的步驟，請參閱您所要使用功能的快速入門文章。

之後，請使用用戶端物件將非同步呼叫傳送至 API。 要使用的方法呼叫會依您的語言而有所不同。 使用可用的範例和參考文件，協助您開始使用。

結果可用性

以非同步方式使用這項功能時，API 結果可從要求內嵌的時間起 24 小時內提供使用，且會在回應中指出。 在這段時間之後，結果將會予以清除，且無法再供擷取。

自動語言偵測

從 REST API 的版本 2022-07-01-preview 開始，您可以在文件上要求自動語言偵測。 藉由將 language 參數設定為 auto，偵測到的文字語言代碼將會以回應中的語言值傳回。 此語言偵測不會對您的語言資源產生額外費用。

資料限制

注意

  • 如果您需要分析比限制所允許的大小還要大的文件，則可以將文字分拆成較小的文字區塊，再將其傳送至 API。
  • 文件是文字字元的單一字串。

您可以在非同步要求中包含的所有文件上傳送依 StringInfo.LengthInTextElements 測量的最多 125,000 個字元。 此字元限制會高於同步要求的限制，以啟用較高的輸送量。

如果文件超過字元限制，則 API 會拒絕整個要求，並在其中有任何文件超過大小上限時傳回 400 bad request 錯誤。

另請參閱