获取所有翻译作业的状态

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

  • 使用 get translations status 方法请求用户提交的所有翻译作业的列表和状态(与资源关联)。

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

    • $top 指示要在所有页面中返回的记录总数。
    • $skip 指示根据指定的排序方法从批列表中跳过的记录数。 默认情况下,记录按开始时间以降序方式排序。
    • $maxpagesize 是单个页面中返回的最大项数。
    • 如果通过 $top 请求更多项(或者未指定 $top,但有更多项要返回),@nextLink 会包含指向下一页的链接。
    • 服务器以客户端指定的值为准。 但是,必须将客户端准备好以处理包含不同页面大小或包含延续令牌的响应。
    • 同时包括 $top$skip 时,服务器会先在集合上应用 $skip,然后再应用 $top

注意

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

  • $orderBy 查询参数可用于对返回的列表排序(示例:$orderBy=createdDateTimeUtc asc$orderBy=createdDateTimeUtc desc)。
    • 默认排序为按 createdDateTimeUtc 以降序方式排序。 一些查询参数可用于筛选返回的列表(示例:status=Succeeded,Cancelled 返回成功的和取消的操作)。
    • createdDateTimeUtcStartcreatedDateTimeUtcEnd 查询参数可以组合使用或单独使用,以指定日期/时间范围来筛选返回的列表。
    • 支持的筛选查询参数为 statusidcreatedDateTimeUtcStartcreatedDateTimeUtcEnd

请求 URL

  curl -i -X GET "{document-translation-endpoint}/translator/document/batches?api-version={date}"

重要

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

请求参数

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

查询参数 必需 类型​​ 说明
$maxpagesize query 错误 整数 (int32) $maxpagesize 是单个页面中返回的最大项数。 如果通过 $top 请求更多项(或者未指定 $top,但有更多项要返回),@nextLink 会包含指向下一页的链接。 客户端可以通过指定 $maxpagesize 首选项来请求使用特定页面大小进行的服务器驱动的分页。 如果指定的页面大小小于服务器的默认页面大小,则服务器应遵循此首选项。
$orderBy 查询 错误 array 集合的排序查询(例如:CreatedDateTimeUtc ascCreatedDateTimeUtc 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 查询 错误 字符串(日期时间) 获取项的开始日期时间。
ids query 错误 array 要在筛选中使用的 ID。
statuses 查询 错误 array 要在筛选中使用的状态。

请求标头

请求标头为:

头文件 说明 条件
Ocp-Apim-Subscription-Key 来自 Azure 门户的 Translator 服务 API 密钥。 必需
Ocp-Apim-Subscription-Region 创建资源的区域。 使用区域(地理)资源(如“中国北部”)时为必需。
&bullet.
Content-Type 有效负载的内容类型。 接受的值为 application/json 或 charset=UTF-8。 必需

响应状态代码

下面是请求可能返回的 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 获取错误的源。 例如,如果存在无效文档,它为 documentsdocument id
innerError InnerTranslationError 符合 Azure AI 服务 API 准则的新的内部错误格式。 此错误消息包含必需的属性 ErrorCode、消息和可选属性目标、详细信息(键值对)、内部错误(可以嵌套)。
innerError.code 字符串 获取代码错误字符串。
innerError.message 字符串 获取概要错误消息。
innerError.target string 获取错误的源。 例如,如果存在无效文档,它为 documentsdocument 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://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"
    }
  }
}

后续步骤

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