取得所有文件的狀態

發行項
09/01/2024

參考
功能：Azure AI Translator →文件翻譯
API 版本：2024-05-01
HTTP 方法：GET

重要

文件翻譯功能的所有 API 要求都需要自訂網域端點，其位於 Azure 入口網站中的資源概觀頁面上。

get documents status使用方法來要求翻譯作業中所有文件的狀態。
$top、$skip 和 $maxpagesize 查詢參數可以用來指定要傳回的結果數目，以及集合的位移。
- $top 表示使用者想要在所有頁面上傳回的記錄總數。
- $skip 根據指定的排序方法，從伺服器持有的文件狀態清單中指出要跳過的記錄數目。根據預設，記錄會依遞減開始時間排序。
- $maxpagesize 是在頁面中傳回的最大項目數。
- 如果透過 $top 要求更多項目 (或未指定 $top，且要傳回更多項目)，則 @nextLink 會包含下一個頁面的連結。
- 如果回應中的檔數目超過我們的分頁限制，則會使用伺服器端分頁。
- 編頁回應表示部分結果，並在回應中包含接續令牌。缺少接續令牌表示沒有其他頁面可供使用。

注意

如果伺服器無法接受 $top 及/或 $skip，伺服器必須將錯誤傳回給用戶端來進行告知，而不是忽略查詢選項。這樣可降低客戶端對傳回數據進行假設的風險。

$orderBy query 參數可用來排序傳回的清單（例如： $orderBy=createdDateTimeUtc asc 或 $orderBy=createdDateTimeUtc desc）。
默認排序依 createdDateTimeUtc遞減。某些查詢參數可用來篩選傳回的清單（例如： status=Succeeded,Cancelled）只會傳回成功和取消的檔。
createdDateTimeUtcStart和 createdDateTimeUtcEnd 查詢參數可以結合或個別使用，以指定日期時間範圍來篩選傳回的清單。
支援的篩選查詢參數為（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` 值

您會在 POST start-batch-translation 方法回應標頭 Operation-Location URL 值中找到作業 id。 /document/ 參數後面的英數位元字串是作業的 id 作業：

回應標頭	回應 URL
Operation-Location	{document-translation-endpoint}/translator/document/`9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec`？api-version=2024-05-01

您也可以使用 get-translations-status 要求來擷取翻譯作業及其 id 的清單。

要求參數

在查詢字串上傳遞的要求參數如下：

查詢參數	In	必要	類型	描述
`id`	path	True	字串	作業標識碼。
`$maxpagesize`	query	False	整數 int32	`$maxpagesize` 是在頁面中傳回的最大項目數。如果透過 `$top` 要求更多項目 (或未指定 `$top`，且要傳回更多項目)，則 @nextLink 會包含下一個頁面的連結。用戶端可以藉由指定 `$maxpagesize` 喜好設定來要求具有特定頁面大小的伺服器驅動分頁。如果指定的頁面大小小於伺服器的默認頁面大小，伺服器應該接受此喜好設定。
$orderBy	query	False	陣列	集合的排序查詢 (例如：`CreatedDateTimeUtc asc`、`CreatedDateTimeUtc desc`)。
`$skip`	query	False	整數 int32	$skip會根據指定的排序方法，指出要略過伺服器所保留記錄清單的記錄數目。根據預設，我們會依遞減開始時間排序。用戶端可以使用 $top 和 `$skip` 查詢參數，來指定要傳回的結果數，以及集合中的位移。當用戶端同時傳回 `$top` 和 `$skip` 時，伺服器「應該」先套用 `$skip`，然後再套用 `$top` 至集合上。如果伺服器無法接受 `$top` 和/或 `$skip`，伺服器必須傳回錯誤給用戶端，告知它，而不只是忽略查詢選項。
`$top`	query	False	整數 int32	`$top` 表示使用者想要在所有頁面上傳回的記錄總數。用戶端可以使用 `$top` 和 `$skip` 查詢參數來指定要傳回的結果數目，以及集合中的位移。當用戶端同時傳回 `$top` 和 `$skip` 時，伺服器「應該」先套用 `$skip`，然後再套用 `$top` 至集合上。如果伺服器無法接受 `$top` 和/或 `$skip`，伺服器必須傳回錯誤給用戶端，告知它，而不只是忽略查詢選項。
createdDateTimeUtcEnd	query	False	字串日期-時間	要取得專案之前的結束日期時間。
createdDateTimeUtcStart	query	False	字串日期-時間	要取得項目之後的開始日期時間。
`ids`	query	False	陣列	篩選中使用的識別碼。
狀態	query	False	陣列	篩選中使用的狀態。

要求標頭

要求標頭如下：

標題	描述	條件
Ocp-Apim-Subscription-Key	來自 Azure 入口網站的翻譯工具服務 API 金鑰。	必要
Ocp-Apim-Subscription-Region	資源建立的所在區域。	使用美國西部等區域（地理）資源時需要
Content-Type	承載的內容類型。接受的值為 application/json 或 charset=UTF-8。	必要

回應狀態代碼

以下是要求傳回的可能 HTTP 狀態碼。

狀態碼	描述
200	OK. 成功要求並傳回文件的狀態。 HeadersRetry-After： integerETag： string
400	要求無效。檢查輸入參數。
401	未經授權。檢查您的認證。
404	找不到資源。
500	內部伺服器錯誤。
其他狀態碼	• 要求太多 • 伺服器暫時無法使用

取得文件狀態回應

成功取得文件狀態回應

成功回應中會傳回下列資訊。

名稱	類型	描述
@nextLink	字串	下一頁的 URL。如果沒有其他可用的頁面，則為 Null。
value	DocumentStatus []	個別檔文件的詳細資料狀態清單。
value.path	字串	檔或資料夾的位置。
value.sourcePath	字串	源文檔的位置。
value.createdDateTimeUtc	字串	作業已建立日期時間。
value.lastActionDateTimeUtc	字串	更新作業狀態的日期時間。
value.status	status	作業或檔案可能的狀態清單。 • 已取消 •取消 •失敗 • NotStarted •運行 •成功 • ValidationFailed
value.to	字串	語言。
value.progress	數值	如果有的話，翻譯的進度。
value.id	字串	文件識別碼。
value.characterCharged	整數	由 API 收費的字元。

回覆錯誤

名稱	類型	描述
code	字串	包含高階錯誤碼的列舉。可能的值： • InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable •未經授權
message	字串	取得高階錯誤訊息。
目標	字串	取得錯誤的來源。例如，對於無效的文件，這可能會是 `documents` 或 `document id`。
innerError	InnerTranslationError	符合 Azure AI 服務 API 指導方針的新內部錯誤格式。此錯誤訊息包含必要屬性 ErrorCode、訊息和選擇性屬性目標、詳細資料 ( 機碼值組)、內部錯誤 (可為巢狀)。
innerError.code	字串	取得程式代碼錯誤字串。
innerError.message	字串	取得高階錯誤訊息。
innerError.target	字串	取得錯誤的來源。例如，如果有無效文件，其會是 `documents` 或 `document id`。

範例

提示

使用這個方法來擷取 documentId get-document-status 查詢字串串的參數。

成功回應的範例

下列 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"
    }
  }
}

下一步

請遵循我們的快速入門，深入瞭解如何使用文件翻譯和客戶端連結庫。

開始使用文件翻譯

共用方式為

取得所有文件的狀態

要求 URL

尋找 `id` 值

要求參數

要求標頭

回應狀態代碼

取得文件狀態回應

成功取得文件狀態回應

回覆錯誤

範例

成功回應的範例

範例錯誤回應

下一步

意見反應

其他資源

共用方式為

取得所有文件的狀態

要求 URL

尋找 id 值

要求參數

要求標頭

回應狀態代碼

取得文件狀態回應

成功取得文件狀態回應

回覆錯誤

範例

成功回應的範例

範例錯誤回應

下一步

意見反應

其他資源

尋找 `id` 值