你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

获取所有文档的状态

项目
09/01/2024

参考
功能：Azure AI 翻译 → 文档翻译
API 版本：2024-05-01
HTTP 方法：GET

重要

对文档翻译功能的所有 API 请求都需要有位于 Azure 门户资源概述页上的自定义域终结点。

使用 get documents status 方法请求翻译作业中所有文档的状态。
$top、$skip 和 $maxpagesize 查询参数可用于指定要返回的结果数以及集合的偏移量。
- $top 指示用户希望在所有页面中返回的记录总数。
- $skip 指示要根据指定的排序方法从服务器保存的文档状态列表中跳过的记录数。默认情况下，记录按开始时间以降序方式排序。
- $maxpagesize 是单个页面中返回的最大项数。
- 如果通过 $top 请求更多项（或者未指定 $top，但有更多项要返回），@nextLink 会包含指向下一页的链接。
- 如果响应中的文档数超出了分页限制，则使用服务器端分页。
- 分页后的响应表示的是部分结果，且响应中包含延续令牌。如果没有延续令牌，则表示没有其他可用页面。

注意

如果服务器不能服从 $top 和/或 $skip，则服务器必须针对此状况向客户端返回一个错误通知，而不是简单地忽略查询选项。这降低了客户端对返回的数据进行错误假设的风险。

$orderBy 查询参数可用于对返回的列表排序（示例：$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。

请求参数

查询字符串上传递的请求参数如下：

查询参数	在	必需	类型	描述
`id`	path	正确	字符串	操作 ID。
`$maxpagesize`	query	错误	整数 (int32)	`$maxpagesize` 是单个页面中返回的最大项数。如果通过 `$top` 请求更多项（或者未指定 `$top`，但有更多项要返回），@nextLink 会包含指向下一页的链接。客户端可以通过指定 `$maxpagesize` 首选项来请求使用特定页面大小进行的服务器驱动的分页。如果指定的页面大小小于服务器的默认页面大小，则服务器应遵循此首选项。
$orderBy	query	错误	array	集合的排序查询（例如：`CreatedDateTimeUtc asc`、`CreatedDateTimeUtc desc`）。
`$skip`	query	错误	整数 (int32)	$skip 指示根据指定的排序方法从服务器保存的记录列表中跳过的记录数。默认情况下，我们按开始时间降序排序。客户端可以使用 $top 和 `$skip` 查询参数来指定要返回的结果数和集合中的偏移量。当客户端同时返回 `$top` 和 `$skip` 时，服务器应先在集合上应用 `$skip`，然后再应用 `$top`。如果服务器不能遵循 `$top` 和/或 `$skip`，则服务器必须向客户端返回错误以通知此情况，而不是简单地忽略查询选项。
`$top`	查询	错误	整数 (int32)	`$top` 指示用户希望在所有页面中返回的记录总数。客户端可以使用 `$top` 和 `$skip` 查询参数来指定要返回的结果数和集合中的偏移量。当客户端同时返回 `$top` 和 `$skip` 时，服务器应先在集合上应用 `$skip`，然后再应用 `$top`。如果服务器不能遵循 `$top` 和/或 `$skip`，则服务器必须向客户端返回错误以通知此情况，而不是简单地忽略查询选项。
createdDateTimeUtcEnd	query	错误	字符串（日期时间）	获取项的结束日期时间。
createdDateTimeUtcStart	query	错误	字符串（日期时间）	获取项的开始日期时间。
`ids`	query	错误	array	要在筛选中使用的 ID。
statuses	query	错误	array	要在筛选中使用的状态。

请求标头

请求标头为：

头文件	说明	条件
Ocp-Apim-Subscription-Key	来自 Azure 门户的 Translator 服务 API 密钥。	必需
Ocp-Apim-Subscription-Region	创建资源的区域。	使用美国西部等区域（地理）资源时需要
Content-Type	有效负载的内容类型。接受的值为 application/json 或 charset=UTF-8。	必需

响应状态代码

下面是请求可能返回的 HTTP 状态代码。

状态代码	说明
200	没问题。成功请求并返回文档的状态。 HeadersRetry-After: integerETag: string
400	请求无效。检查输入参数。
401	未授权。检查凭据。
404	找不到资源。
500	内部服务器错误。
其他状态代码	• 请求太多 • 服务器暂时不可用

获取文档状态响应

成功获取文档状态响应

成功的响应中会返回以下信息。

名称	Type	说明
@nextLink	字符串	下一页的 Url。如果没有页，则为 NULL。
值	DocumentStatus []	各个文档的详细信息状态列表。
value.path	string	文档或文件夹的位置。
value.sourcePath	字符串	源文档的位置。
value.createdDateTimeUtc	字符串	操作创建的日期时间。
value.lastActionDateTimeUtc	string	• 更新操作状态的日期时间。
value.status	status	作业或文档可能所处状态的列表。 • 已取消 • 正在取消 • 失败 • NotStarted • 正在运行 • 已成功 • ValidationFailed
value.to	字符串	目标语言。
value.progress	数字	翻译进度（如果提供）。
value.id	字符串	文档 ID。
value.characterCharged	整型	由 API 计费的字符。

错误响应

名称	Type	说明
code	string	包含错误代码概要的枚举。可能的值： • InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • 未授权
message	字符串	获取概要错误消息。
目标	string	获取错误的源。例如，对于无效文档，它为 `documents` 或 `document id`。
innerError	InnerTranslationError	符合 Azure AI 服务 API 准则的新的内部错误格式。此错误消息包含必需的属性 ErrorCode、消息和可选属性目标、详细信息（键值对）、内部错误（可以嵌套）。
innerError.code	字符串	获取代码错误字符串。
innerError.message	字符串	获取概要错误消息。
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"
    }
  }
}

后续步骤

遵循快速入门，详细了解如何使用文档翻译和客户端库。

文档翻译入门

通过

获取所有文档的状态

请求 URL

查找 `id` 值

请求参数

请求标头

响应状态代码

获取文档状态响应

成功获取文档状态响应

错误响应

示例

成功响应示例

错误响应示例

后续步骤

反馈

其他资源

通过

获取所有文档的状态

请求 URL

查找 id 值

请求参数

请求标头

响应状态代码

获取文档状态响应

成功获取文档状态响应

错误响应

示例

成功响应示例

错误响应示例

后续步骤

反馈

其他资源

查找 `id` 值