言語を使用すると、REST API またはクライアント ライブラリを使用して、API 要求を非同期的に送信できます。 データに対して同時に実行される複数の異なる言語機能を要求に含めることもできます。
現時点では、次の機能を非同期的に使用できます。
- エンティティ リンク設定
- ドキュメントの概要作成
- 会話の概要作成
- キー フレーズの抽出
- 言語検出
- 名前付きエンティティの認識 (NER)
- 顧客コンテンツの検出
- 感情分析とオピニオン マイニング
- Text Analytics for Health
- 個人を特定できる情報 (PII)
非同期要求を送信すると、機能の使用ごとに、要求に含めるテキスト レコードの数に基づいて料金が発生します。 たとえば、感情分析と NER 用にテキスト レコードを送信した場合、データは 2 つのテキスト レコードの送信としてカウントされ、 価格レベルに従って両方に対して課金されます。
REST API を使用して非同期ジョブを送信する
非同期ジョブを送信するには、要求で送信する JSON 本文の リファレンス ドキュメント を確認します。
- ドキュメントを
analysisInputオブジェクトに追加します。 -
tasksオブジェクトで、データに対して実行する操作を含めます。 たとえば、センチメント分析を実行する場合は、SentimentAnalysisLROTaskオブジェクトを含めます。 - 必要に応じて、次のことができます。
- データで使用される特定のモデルのバージョンを選択します。
-
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 エラーを返します。