すべての翻訳ジョブの状態を取得する
リファレンス
機能: Azure AI Translator → Document Translation
API バージョン: 2024-05-01
HTTP メソッド: GET
get translations statusメソッドを使用して、ユーザーによって送信されたすべての翻訳ジョブ (リソースに関連付けられている) の一覧と状態を要求します。$top、$skip、$maxpagesizeのクエリ パラメーターを使用して、返される結果の数とコレクションのオフセットを指定できます。$topは、すべてのページで返されるレコードの合計数を示します。$skipは、並べ替え方法に基づいて、バッチの一覧からスキップするレコードの数を示します。 既定では、レコードは降順の開始時刻で並べ替えられます。$maxpagesizeは、1 つのページで返される項目の最大数です。$top経由でさらに多くの項目が要求された場合 (または$topが指定されておらず、返される項目がさらにある場合)、@nextLinkには次のページへのリンクが含まれます。- サーバーでは、クライアントによって指定された値が受け入れられます。 ただし、異なるページ サイズや継続トークンを含む応答を処理できるようクライアントを準備する必要があります。
$topと$skipの両方が含まれている場合、サーバーは最初に$skipを適用してから、コレクションに$topします。
Note
サーバーが $top または $skip を受け入れられない場合、サーバーでは、クエリ オプションを無視するだけではなく、そのことを通知するエラーをクライアントに返す必要があります。 これにより、返されるデータについてクライアントが憶測を立てるリスクが軽減されます。
$orderByクエリ パラメーターを使用して、返されたリストを並べ替えることができます (例:$orderBy=createdDateTimeUtc ascまたは$orderBy=createdDateTimeUtc desc)。- 既定の並べ替えは、
createdDateTimeUtc降順です。 一部のクエリ パラメーターを使用して、返されたリストをフィルター処理できます (例:status=Succeeded,Cancelled) は、成功した操作と取り消された操作を返します。 createdDateTimeUtcStartおよびcreatedDateTimeUtcEndクエリ パラメーターを組み合わせて使用するか、個別に使用して、返されるリストをフィルター処理する datetime の範囲を指定できます。- サポートされているフィルター クエリ パラメーターは (
status、id、createdDateTimeUtcStart、およびcreatedDateTimeUtcEnd) です。
- 既定の並べ替えは、
要求 URL
curl -i -X GET "{document-translation-endpoint}/translator/document/batches?api-version={date}"
重要
ドキュメント翻訳機能に対するすべての API 要求に、Azure portal のリソース概要ページにあるカスタム ドメイン エンドポイントが必要です。
要求パラメーター
クエリ文字列に渡される要求パラメーターを次に示します。
| Query parameter (クエリ パラメーター) | / | 必須 | タイプ | 説明 |
|---|---|---|---|---|
$maxpagesize |
query | × | integer int32 | $maxpagesize は、1 つのページで返される項目の最大数です。 $top 経由でさらに多くの項目が要求された場合 (または $top が指定されておらず、返される項目がさらにある場合)、@nextLink には次のページへのリンクが含まれます。 クライアントは、$maxpagesize の設定を指定することによって、特定のページ サイズのサーバー駆動のページングを要求できます。 指定したページ サイズがサーバーの既定のページ サイズよりも小さい場合、サーバーでは、この設定を優先する必要があります。 |
$orderBy |
クエリ | × | 配列 | コレクションの並べ替えクエリ (例: CreatedDateTimeUtc asc、CreatedDateTimeUtc desc) |
$skip |
クエリ | × | integer int32 | $skip は、指定した並べ替え方法に基づいて、サーバーによって保持されているレコードの一覧からスキップするレコードの数を示します。 既定では、降順の開始時刻で並べ替えを行います。 クライアントは、$top および $skip クエリ パラメーターを使用して、返す結果の数とコレクションへのオフセットを指定できます。 クライアントが $top と $skip の両方を返した場合、サーバーでは、最初に $skip がコレクションに適用され、それから $top が適用される必要があります。注: サーバーが $top や $skip を受け入れられない場合、サーバーでは、クエリ オプションを無視するだけではなく、そのことを通知するエラーをクライアントに返す必要があります。 |
$top |
クエリ | × | integer int32 | $top は、ユーザーがすべてのページで返すレコードの総数を示します。 クライアントは、$top および $skip クエリ パラメーターを使用して、返す結果の数とコレクションへのオフセットを指定できます。 クライアントが $top と $skip の両方を返した場合、サーバーでは、最初に $skip がコレクションに適用され、それから $top が適用される必要があります。注: サーバーが $top や $skip を受け入れられない場合、サーバーでは、クエリ オプションを無視するだけではなく、そのことを通知するエラーをクライアントに返す必要があります。 |
createdDateTimeUtcEnd |
クエリ | × | string date-time | 項目を取得する終了日時。 |
createdDateTimeUtcStart |
クエリ | × | string date-time | 項目を取得する開始日時。 |
ids |
クエリ | × | array | フィルター処理で使用する ID。 |
statuses |
クエリ | × | 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 | 権限がありません。 資格情報を確認してください。 |
| 500 | 内部サーバー エラー。 |
| その他の状態コード | • 要求が多すぎます • サーバーの一時的な利用不可 |
翻訳状態の取得の応答
翻訳状態の取得の応答に成功
成功した応答では、次の情報が返されます。
| 名前 | 種類 | 説明 |
|---|---|---|
| @nextLink | string | 次のページの URL。 追加のページがない場合は Null。 |
| value | TranslationStatus[] | TranslationStatus[] Array |
| value.id | string | 操作の ID。 |
| value.createdDateTimeUtc | string | 操作が作成された日時。 |
| value.lastActionDateTimeUtc | string | 操作の状態が更新された日時。 |
| value.status | String | ジョブまたはドキュメントの可能な状態の一覧: •キャンセル •キャンセル •失敗 しました • NotStarted •ランニング •成功 • ValidationFailed |
| value.summary | StatusSummary[] | 一覧表示された詳細を含む概要です。 |
| value.summary.total | 整数 (integer) | ドキュメントの合計数。 |
| value.summary.failed | 整数 (integer) | ドキュメントの失敗数。 |
| value.summary.success | 整数 (integer) | 正常に翻訳されたドキュメントの数。 |
| value.summary.inProgress | 整数 (integer) | 進行中のドキュメントの数。 |
| value.summary.notYetStarted | 整数 (integer) | まだ処理を開始していないドキュメントの数。 |
| value.summary.cancelled | 整数 (integer) | キャンセルされたドキュメントの数。 |
| value.summary.totalCharacterCharged | 整数 (integer) | 課金される文字の合計数。 |
エラー応答
| 名前 | 種類 | 説明 |
|---|---|---|
| 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-translation-status クエリ文字列のジョブ id パラメーターを取得できます。
成功した応答の例
次の JSON オブジェクトは、成功時の応答の例です。
{
"value": [
{
"id": "36724748-f7a0-4db7-b7fd-f041ddc75033",
"createdDateTimeUtc": "2021-06-18T03:35:30.153374Z",
"lastActionDateTimeUtc": "2021-06-18T03:36:44.6155316Z",
"status": "Succeeded",
"summary": {
"total": 3,
"failed": 2,
"success": 1,
"inProgress": 0,
"notYetStarted": 0,
"cancelled": 0,
"totalCharacterCharged": 0
}
},
{
"id": "1c7399a7-6913-4f20-bb43-e2fe2ba1a67d",
"createdDateTimeUtc": "2021-05-24T17:57:43.8356624Z",
"lastActionDateTimeUtc": "2021-05-24T17:57:47.128391Z",
"status": "Failed",
"summary": {
"total": 1,
"failed": 1,
"success": 0,
"inProgress": 0,
"notYetStarted": 0,
"cancelled": 0,
"totalCharacterCharged": 0
}
},
{
"id": "daa2a646-4237-4f5f-9a48-d515c2d9af3c",
"createdDateTimeUtc": "2021-04-14T19:49:26.988272Z",
"lastActionDateTimeUtc": "2021-04-14T19:49:43.9818634Z",
"status": "Succeeded",
"summary": {
"total": 2,
"failed": 0,
"success": 2,
"inProgress": 0,
"notYetStarted": 0,
"cancelled": 0,
"totalCharacterCharged": 21899
}
}
],
""@nextLink": "https://westus.cognitiveservices.azure.com/translator/text/batch/v1.1/operations/727BF148-F327-47A0-9481-ABAE6362F11E/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"
}
}
}
次のステップ
クイックスタートに従って、ドキュメント翻訳とクライアント ライブラリの使用について学習します。