すべてのドキュメントの状態を取得する

リファレンス
機能: Azure AI Translator → Document Translation
API バージョン: 2024-05-01
HTTP メソッド: GET

重要

ドキュメント翻訳機能に対するすべての API 要求に、Azure portal のリソース概要ページにあるカスタム ドメイン エンドポイントが必要です。

• get documents status メソッドを使用して、翻訳ジョブ内のすべてのドキュメントの状態を要求します。

• $top、$skip、$maxpagesize のクエリ パラメーターを使用して、返される結果の数とコレクションのオフセットを指定できます。

  • $top は、ユーザーがすべてのページで返すレコードの総数を示します。
  • $skip は、指定した並べ替え方法に基づいて、サーバーによって保持されているドキュメントの状態の一覧からスキップするレコードの数を示します。 既定では、レコードは降順の開始時刻で並べ替えられます。
  • $maxpagesize は、1 つのページで返される項目の最大数です。
  • $top 経由でさらに多くの項目が要求された場合 (または $top が指定されておらず、返される項目がさらにある場合)、@nextLink には次のページへのリンクが含まれます。
  • 応答内のドキュメントの数がページング限度を超える場合は、サーバー側のページングが使用されます。
  • ページ分割された応答は結果の一部を示しており、応答の中に継続トークンが含まれています。 継続トークンがない場合は、他にページがないことを意味します。

Note

サーバーが $top または $skip を受け入れられない場合、サーバーでは、クエリ オプションを無視するだけではなく、そのことを通知するエラーをクライアントに返す必要があります。 これにより、返されるデータについてクライアントが憶測を立てるリスクが軽減されます。

• $orderBy クエリ パラメーターを使用して、返されたリストを並べ替えることができます (例: $orderBy=createdDateTimeUtc asc または $orderBy=createdDateTimeUtc desc)。
• 既定の並べ替えは、 createdDateTimeUtc降順です。 一部のクエリ パラメーターを使用して、返されたリストをフィルター処理できます (例: status=Succeeded,Cancelled) は、成功したドキュメントと取り消されたドキュメントのみを返します。
• createdDateTimeUtcStartおよびcreatedDateTimeUtcEndクエリ パラメーターを組み合わせて使用するか、個別に使用して、返されるリストをフィルター処理する datetime の範囲を指定できます。
• サポートされているフィルター クエリ パラメーターは (status、 id、 createdDateTimeUtcStart、および createdDateTimeUtcEnd) です。
• $top と $skip の両方が含まれている場合、サーバーはコレクションに最初に $skip を適用し、次に $top を適用する必要があります。

要求 URL

GET 要求の送信先は次のとおりです。

  curl -i -X GET "{document-translation-endpoint}/translator/document/batches/{id}/documents?api-version={date}"

id 値の検索

• ジョブ id は、POST start-batch-translation メソッドの応答ヘッダー Operation-Location の URL 値で確認します。 /document/ パラメーターの後に続く英数字の文字列は、操作のジョブ id です。

応答ヘッダー	応答 URL
Operation-Location	{document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01

• また、get-translations-status 要求を使用して、翻訳 "ジョブ" とその id の一覧を取得することもできます。

要求パラメーター

クエリ文字列に渡される要求パラメーターを次に示します。

Query parameter (クエリ パラメーター)	/	必須	タイプ	説明
id	path	True	string	操作 ID。
$maxpagesize	クエリ	×	integer int32	$maxpagesize は、1 つのページで返される項目の最大数です。 $top 経由でさらに多くの項目が要求された場合 (または $top が指定されておらず、返される項目がさらにある場合)、@nextLink には次のページへのリンクが含まれます。 クライアントは、 $maxpagesize 設定を指定することで、特定のページ サイズでサーバー駆動型ページングを要求できます。 指定したページ サイズがサーバーの既定のページ サイズよりも小さい場合、サーバーでは、この設定を優先する必要があります。
$orderBy	query	×	配列	コレクションの並べ替えクエリ (例: CreatedDateTimeUtc asc、CreatedDateTimeUtc desc)。
$skip	クエリ	×	integer int32	$skip は、指定した並べ替え方法に基づいて、サーバーによって保持されているレコードの一覧からスキップするレコードの数を示します。 既定では、降順の開始時刻で並べ替えを行います。 クライアントは、$top および $skip クエリ パラメーターを使用して、返す結果の数とコレクションへのオフセットを指定できます。 クライアントが $top と $skip の両方を返した場合、サーバーは最初に $skip を適用し、次に $top をコレクションに適用する必要があります。 サーバーが $top や $skipを受け入れることができない場合、サーバーはクエリ オプションを無視するのではなく、クライアントに通知するエラーを返す必要があります(MUST)。
$top	クエリ	×	integer int32	$top は、ユーザーがすべてのページで返すレコードの総数を示します。 クライアントは、 $top および $skip クエリ パラメーターを使用して、返される結果の数とコレクションへのオフセットを指定できます。 クライアントが $top と $skip の両方を返した場合、サーバーは最初に $skip を適用し、次に $top をコレクションに適用する必要があります。 サーバーが $top や $skipを受け入れることができない場合、サーバーはクエリ オプションを無視するのではなく、クライアントに通知するエラーを返す必要があります(MUST)。
createdDateTimeUtcEnd	query	×	string date-time	項目を取得する終了日時。
createdDateTimeUtcStart	query	×	string date-time	項目を取得する開始日時。
ids	クエリ	×	array	フィルター処理で使用する ID。
statuses	query	×	array	フィルター処理で使用する状態。

要求ヘッダー

要求ヘッダーを次に示します。

ヘッダー	説明	条件
Ocp-Apim-Subscription-Key	Azure portal からの Translator サービス API キー。	必須
Ocp-Apim-Subscription-Region	リソースが作成されたリージョン。	必須 米国西部などのリージョン (地理的) リソースを使用する場合
Content-Type	ペイロードのコンテンツ タイプ。 許容される値は application/json または charset=UTF-8 です。	必須

応答状態コード

要求によって返される可能性のある HTTP 状態コードを次に示します。

状態コード	説明
200	OK です。 要求が成功して、ドキュメントの状態を返します。 HeadersRetry-After: integerETag: string
400	無効な要求です。 入力パラメーターを確認してください。
401	権限がありません。 資格情報を確認してください。
404	リソースが見つかりません。
500	内部サーバー エラー。
その他の状態コード	• 要求が多すぎます • サーバーが一時的に使用できない

ドキュメント状態の取得の応答

ドキュメント状態の取得の応答の成功

成功した応答では、次の情報が返されます。

名前	種類	説明
@nextLink	string	次のページの URL。 追加のページがない場合は Null。
value	DocumentStatus []	個々のドキュメントの詳細ステータスのリスト。
value.path	string	ドキュメントまたはフォルダーの場所。
value.sourcePath	string	ソース ドキュメントの場所。
value.createdDateTimeUtc	string	操作が作成された日時。
value.lastActionDateTimeUtc	string	操作の状態が更新される日時。
value.status	status	ジョブまたはドキュメントの有効な状態の一覧。 •キャンセル •キャンセル •失敗 しました • NotStarted •ランニング •成功 • ValidationFailed
value.to	string	ターゲット言語。
value.progress	数値	翻訳の進行状況 (利用可能な場合)。
value.id	string	ドキュメント ID。
value.characterCharged	整数 (integer)	API によって課金される文字数。

エラー応答

名前	種類	説明
code	string	高レベルのエラー コードを含む列挙型。 指定できる値 • InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable •不正
message	string	高レベルのエラー メッセージを取得します。
ターゲット (target)	string	エラーのソースを取得します。 たとえば、無効なドキュメントの場合には documents か document id になります。
innerError	InnerTranslationError	Azure AI サービス API のガイドラインに準拠した新しい内部エラー形式。 必須プロパティとして ErrorCode、message、省略可能プロパティとして target、details (キーと値のペア)、inner error (入れ子が可能) がこのエラー メッセージに含まれています。
innerError.code	string	コード エラー文字列を取得します。
innerError.message	string	高レベルのエラー メッセージを取得します。
innerError.target	string	エラーのソースを取得します。 たとえば、無効なドキュメントがあった場合には documents か document id になります。

例

ヒント

このメソッドを使用して、get-document-status クエリ文字列のdocumentId パラメーターを取得します。

成功した応答の例

次の JSON オブジェクトは、成功時の応答の例です。

{
  "value": [
    {
      "path": "https://myblob.blob.core.windows.net/destinationContainer/fr/mydoc.txt",
      "sourcePath": "https://myblob.blob.core.windows.net/sourceContainer/fr/mydoc.txt",
      "createdDateTimeUtc": "2020-03-26T00:00:00Z",
      "lastActionDateTimeUtc": "2020-03-26T01:00:00Z",
      "status": "Running",
      "to": "fr",
      "progress": 0.1,
      "id": "273622bd-835c-4946-9798-fd8f19f6bbf2",
      "characterCharged": 0
    }
  ],
  "@nextLink": "https://westus.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55/documents?$top=5&$skip=15"
}

エラー応答の例

次の JSON オブジェクトは、エラー応答の例です。 他のエラー コードのスキーマも同じです。

状態コード: 500

{
  "error": {
    "code": "InternalServerError",
    "message": "Internal Server Error",
    "target": "Operation",
    "innerError": {
      "code": "InternalServerError",
      "message": "Unexpected internal server error has occurred"
    }
  }
}

次のステップ

クイックスタートに従って、ドキュメント翻訳とクライアント ライブラリの使用について学習します。

ドキュメント変換を使ってみる