言語サービス機能を非同期で使用する方法

  • [アーティクル]

言語サービスを使用すると、REST API またはクライアント ライブラリを使用して、API 要求を非同期的に送信できます。 複数の異なる言語サービス機能を要求に追加して、データに対して同時に実行されるようにすることもできます。

現時点では、次の機能を非同期的に使用できます。

  • エンティティ リンク設定
  • ドキュメントの概要作成
  • 会話の概要作成
  • キー フレーズの抽出
  • 言語検出
  • 名前付きエンティティの認識 (NER)
  • 顧客コンテンツの検出
  • 感情分析とオピニオン マイニング
  • Text Analytics for Health
  • 個人を特定できる情報 (PII)

非同期要求を送信すると、要求に含めるテキスト レコードの数に基づき、各機能の使用に対しての料金が発生します。 たとえば、感情分析と NER のテキスト レコードを送信する場合、2 つのテキスト レコードの送信としてカウントされ、価格レベルに従って両方に対して請求されます。

REST API を使用して非同期ジョブを送信する

非同期 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

ステータスと要求の結果を取得するには、前の API 応答のoperation-location ヘッダーで受け取った URL に GET 要求を送信します。 必ずキーを Ocp-Apim-Subscription-Key に含めてください。 応答には、API 呼び出しの結果が含まれます。

クライアント ライブラリを使用した非同期 API 要求の送信

最初に、選択した言語用のクライアント ライブラリがインストールされていることを確認します。 クライアント ライブラリをインストールする手順については、使用する機能のクイックスタートの記事を参照してください。

その後、クライアントオブジェクトを使用して、API への非同期呼び出しを送信します。 使用するメソッド呼び出しは、使用している言語によって異なります。 利用可能なサンプルとリファレンス ドキュメントを使用すると、開始する際の役に立ちます。

結果の可用性

この機能を非同期的に使うと、API の結果は、応答で示される要求取り込み時刻から 24 時間利用できます。 この時間が経過すると、結果は消去され、取得できなくなります。

自動言語検出

REST API のバージョン 2022-07-01-preview 以降、ドキュメントに対する自動言語検出を要求できます。 language パラメーターを auto に設定すると、検出されたテキストの言語コードが応答で言語値として返されます。 この言語検出では、言語リソースに対する追加料金は発生しません。

データ制限

Note

  • 制限を超えるドキュメントを分析する必要がある場合は、テキストを小さなチャンクに分割してから API に送信することができます。
  • ドキュメントとは、テキスト文字の 1 つの文字列です。

StringInfo.LengthInTextElements によって測定されるように、非同期要求に含まれるすべてのドキュメントで最大 125,000 文字を送信できます。 この文字数の制限は、より高いスループットを実現するために、同期要求の制限より緩くなっています。

ドキュメントが文字数制限を超えると、要求内のいずれかのドキュメントが最大サイズを超えている場合、API によってその全体が拒否されて、400 bad request エラーが返されます。

関連項目