获取翻译状态

  • 项目

参考
服务：Azure AI 文档翻译
API 版本：v1.1

获取翻译状态方法可返回提交的批处理请求列表和每个请求的状态。 此列表仅包含用户提交的批处理请求（基于资源）。

如果请求数超过了分页限制，则使用服务器端分页。 分页后的响应表示的是部分结果，且响应中包含延续令牌。 如果没有延续令牌，则表示没有其他可用页面。

$top、$skip 和 $maxpagesize 查询参数可用于指定要返回的结果数以及集合的偏移量。

$top 指示用户希望在所有页面中返回的记录总数。 $skip 指示根据指定的排序方法从批列表中跳过的记录数。 默认情况下，我们按开始时间降序排序。 $maxpagesize 是单个页面中返回的最大项数。 如果通过 $top 请求更多项（或者未指定 $top，但有更多项要返回），@nextLink 会包含指向下一页的链接。

$orderBy 查询参数可用于对返回的列表进行排序（例如“$orderBy=createdDateTimeUtc asc”或“$orderBy=createdDateTimeUtc desc”）。 默认排序按 createdDateTimeUtc 降序排序。 一些查询参数可用于筛选返回的列表（例如：“status=Succeeded,Cancelled”）会返回成功的和取消的文档。 createdDateTimeUtcStart 和 createdDateTimeUtcEnd 可以组合使用，也可以单独使用，用于指定筛选返回列表所依据的日期时间范围。 支持的筛选查询参数包括：status、IDs、createdDateTimeUtcStart、createdDateTimeUtcEnd。

服务器以客户端指定的值为准。 但是，必须将客户端准备好以处理包含不同页面大小或包含延续令牌的响应。

同时包括 $top 和 $skip 时，服务器应先在集合上应用 $skip，然后再应用 $top。

注意

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

请求 URL

将 GET 请求发送到：

GET https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.cn/translator/text/batch/v1.1/batches

了解如何查找自定义域名。

重要

  • 向文档翻译服务发出的所有 API 请求都需要一个自定义域终结点。
  • 不能使用 Azure 门户资源的“密钥和终结点”页上的终结点或者全局翻译器终结点 (api.translator.azure.cn) 来向文档翻译发出 HTTP 请求。

请求参数

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

查询参数 在 必需 类型​​ 说明
$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 query 错误 整数 (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 必需的请求标头

响应状态代码

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

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

获取翻译状态响应

成功获取翻译状态响应

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

名称 Type 说明
@nextLink 字符串 下一页的 Url。 如果没有页，则为 NULL。
值 TranslationStatus[] TranslationStatus[] Array
value.id 字符串 操作的 ID。
value.createdDateTimeUtc 字符串 操作创建的日期时间。
value.lastActionDateTimeUtc string • 更新操作状态的日期时间。
value.status 字符串 作业或文档的可能状态的列表：
• 已取消
• 正在取消
• 失败
• 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 收取费用的字符总数。

错误响应

名称 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。

示例

成功响应示例

以下 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://chinanorth.cognitiveservices.azure.cn/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"
    }
  }
}

后续步骤

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

文档翻译入门