获取所有翻译作业的状态
参考
功能: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
返回成功的和取消的操作)。 createdDateTimeUtcStart
和createdDateTimeUtcEnd
查询参数可以组合使用或单独使用,以指定日期/时间范围来筛选返回的列表。- 支持的筛选查询参数为
status
、id
、createdDateTimeUtcStart
和createdDateTimeUtcEnd
。
- 默认排序为按
请求 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 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 |
查询 | 错误 | 字符串(日期时间) | 获取项的开始日期时间。 |
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 | 获取错误的源。 例如,如果存在无效文档,它为 documents 或 document id 。 |
innerError | InnerTranslationError | 符合 Azure AI 服务 API 准则的新的内部错误格式。 此错误消息包含必需的属性 ErrorCode、消息和可选属性目标、详细信息(键值对)、内部错误(可以嵌套)。 |
innerError.code | 字符串 | 获取代码错误字符串。 |
innerError.message | 字符串 | 获取概要错误消息。 |
innerError.target | string | 获取错误的源。 例如,如果存在无效文档,它为 documents 或 document 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"
}
}
}
后续步骤
遵循快速入门,详细了解如何使用文档翻译和客户端库。