共用方式為

取得所有文件的狀態

參考
功能： Azure 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 id 方法回應標頭 start-batch-translation URL 值中找到作業 Operation-Location。 /document/ 參數後面的英數位元字串是作業的 id 作業：
回應標頭 回應 URL
Operation-Location {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec？api-version=2024-05-01

要求參數

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

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

要求標頭

要求標頭如下：

標題 描述 條件
Ocp-Apim-Subscription-Key 你的 Azure 入口網站的 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 字串 下一頁的 URL。 如果沒有其他可用的頁面，則為 Null。
value 文件狀態 [] 個別檔文件的詳細資料狀態清單。
value.path 字串 檔或資料夾的位置。
value.sourcePath 字串 源文檔的位置。
value.createdDateTimeUtc 字串 作業已建立日期時間。
value.lastActionDateTimeUtc 字串 更新作業狀態的日期時間。
value.status 狀態 作業或檔案可能的狀態清單。
• 已取消
•取消
•失敗
• 未開始
•運行
•成功
• 驗證失敗
value.to 字串 語言。
value.progress 數值 如果有的話，翻譯的進度。
value.id 字串 文件識別碼。
value.characterCharged 整數 由 API 收費的字元。

回覆錯誤

名稱 類型 描述
字碼 字串 包含高階錯誤碼的列舉。 公認價值觀：
• 內部伺服器錯誤
• 無效論證
• 無效請求
• 請求過高
• 資源未尋獲
• 服務不可用
•未經授權
訊息 字串 取得高階錯誤訊息。
目標 字串 取得錯誤的來源。 例如，對於無效的文件，這可能會是 documents 或 document id。
innerError InnerTranslationError 新的內部錯誤格式，符合 Foundry Tools 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"
    }
  }
}

下一步

請參考我們的快速入門，了解更多關於使用文件翻譯與客戶端函式庫的資訊。

開始使用文件翻譯

  • Last updated on