Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[mt][batch][document translator] Update API based on SDK team feedback #13618

Merged
merged 11 commits into from
Mar 26, 2021
Merged

[mt][batch][document translator] Update API based on SDK team feedback #13618

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
2fd11ee
update API based on SDK team feedback
alexhcheng Mar 25, 2021
09d59fa
update based on feedback
alexhcheng Mar 25, 2021
970fa2e
manually add ref
alexhcheng Mar 25, 2021
2da0d47
try to fix swagger
alexhcheng Mar 25, 2021
67741b9
update swagger based on feedback
alexhcheng Mar 25, 2021
ca709ba
update swagger based on feedback. add retry-after
alexhcheng Mar 25, 2021
b132e08
fix status type and datetime example
alexhcheng Mar 25, 2021
fd39065
update examples, added required parameters
alexhcheng Mar 25, 2021
000d716
make nextlink an urlencoded string
alexhcheng Mar 25, 2021
c1d2b21
add etag in swagger for these responses
alexhcheng Mar 26, 2021
9f593b8
re-add x-ms-enums and schema for status
alexhcheng Mar 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 121 additions & 14 deletions ...n/cognitiveservices/data-plane/TranslatorText/preview/v1.0-preview.1/TranslatorBatch.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@
"Document Translation"
],
"summary": "Returns a list of batch requests submitted and the status for each request",
"description": "Returns a list of batch requests submitted and the status for each request.\r\nThis list only contains batch requests submitted by the user (based on the subscription). The status for each request is sorted by id.\r\n \r\nIf the number of requests exceeds our paging limit, server-side paging is used. Paginated responses indicate a partial result and include a continuation token in the response.\r\nThe absence of a continuation token means that no additional pages are available.\r\n \r\n$top and $skip query parameters can be used to specify a number of results to return and an offset for the collection.\r\n \r\nThe server honors the values specified by the client. However, clients must be prepared to handle responses that contain a different page size or contain a continuation token.\r\n \r\nWhen both $top and $skip are included, the server should first apply $skip and then $top on the collection.\r\nNote: If the server can't honor $top and/or $skip, the server must return an error to the client informing about it instead of just ignoring the query options.\r\nThis reduces the risk of the client making assumptions about the data returned.",
"description": "Returns a list of batch requests submitted and the status for each request.\r\nThis list only contains batch requests submitted by the user (based on the resource).\r\n \r\nIf the number of requests exceeds our paging limit, server-side paging is used. Paginated responses indicate a partial result and include a continuation token in the response.\r\nThe absence of a continuation token means that no additional pages are available.\r\n \r\n$top, $skip and $maxpagesize query parameters can be used to specify a number of results to return and an offset for the collection.\r\n \r\n$top indicates the total number of records the user wants to be returned across all pages.\r\n$skip indicates the number of records to skip from the list of batches based on the sorting method specified. By default, we sort by descending start time.\r\n$maxpagesize is the maximum items returned in a page. If more items are requested via $top (or $top is not specified and there are more items to be returned), @nextLink will contain the link to the next page.\r\n \r\n$orderBy query parameter can be used to sort the returned list (ex \"$orderBy=createdDateTimeUtc asc\" or \"$orderBy=createdDateTimeUtc desc\").\r\nThe default sorting is descending by createdDateTimeUtc.\r\nSome query parameters can be used to filter the returned list (ex: \"status=Succeeded,Cancelled\") will only return succeeded and cancelled operations.\r\ncreatedDateTimeUtcStart and createdDateTimeUtcEnd can be used combined or separately to specify a range of datetime to filter the returned list by.\r\nThe supported filtering query parameters are (status, ids, createdDateTimeUtcStart, createdDateTimeUtcEnd).\r\n \r\nThe server honors the values specified by the client. However, clients must be prepared to handle responses that contain a different page size or contain a continuation token.\r\n \r\nWhen both $top and $skip are included, the server should first apply $skip and then $top on the collection.\r\nNote: If the server can't honor $top and/or $skip, the server must return an error to the client informing about it instead of just ignoring the query options.\r\nThis reduces the risk of the client making assumptions about the data returned.",
"operationId": "DocumentTranslation_GetOperations",
"produces": [
"application/json"
Expand All @@ -117,22 +117,70 @@
{
"in": "query",
"name": "$top",
"description": "Take the $top entries in the collection\r\nWhen both $top and $skip are supplied, $skip is applied first",
"description": "$top indicates the total number of records the user wants to be returned across all pages.\r\n \r\nClients MAY use $top and $skip query parameters to specify a number of results to return and an offset into the collection.\r\nWhen both $top and $skip are given by a client, the server SHOULD first apply $skip and then $top on the collection.\r\n \r\nNote: If the server can't honor $top and/or $skip, the server MUST return an error to the client informing about it instead of just ignoring the query options.",
"type": "integer",
"format": "int32",
"default": 50,
"maximum": 100,
"minimum": 1
"maximum": 2147483647,
"minimum": 0
},
{
"in": "query",
"name": "$skip",
"description": "Skip the $skip entries in the collection\r\nWhen both $top and $skip are supplied, $skip is applied first",
"description": "$skip indicates the number of records to skip from the list of records held by the server based on the sorting method specified. By default, we sort by descending start time.\r\n \r\nClients MAY use $top and $skip query parameters to specify a number of results to return and an offset into the collection.\r\nWhen both $top and $skip are given by a client, the server SHOULD first apply $skip and then $top on the collection.\r\n \r\nNote: If the server can't honor $top and/or $skip, the server MUST return an error to the client informing about it instead of just ignoring the query options.",
"type": "integer",
"format": "int32",
"default": 0,
"maximum": 2147483647,
"minimum": 0
},
{
"in": "query",
"name": "$maxpagesize",
"description": "$maxpagesize is the maximum items returned in the items in a page. If more items are requested via $top (or $top is not specified and there are more items to be returned), @nextLink will contain the link to the next page.\r\n \r\nClients MAY request server-driven paging with a specific page size by specifying a $maxpagesize preference. The server SHOULD honor this preference if the specified page size is smaller than the server's default page size.",
alexhcheng marked this conversation as resolved.
Show resolved Hide resolved
"type": "integer",
"format": "int32",
"default": 50,
"maximum": 100,
"minimum": 1
},
{
"in": "query",
"name": "ids",
"description": "Ids to use in filtering",
alexhcheng marked this conversation as resolved.
Show resolved Hide resolved
"type": "array",
"items": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "status",
alexhcheng marked this conversation as resolved.
Show resolved Hide resolved
"description": "Status to use in filtering",
"type": "string"
alexhcheng marked this conversation as resolved.
Show resolved Hide resolved
},
{
"in": "query",
"name": "createdDateTimeUtcStart",
"description": "the start datetime to get items after",
"type": "string",
"format": "date-time"
},
{
"in": "query",
"name": "createdDateTimeUtcEnd",
"description": "the end datetime to get items before",
"type": "string",
"format": "date-time"
},
{
"in": "query",
"name": "$orderBy",
"description": "the sorting query for the collection (ex: 'CreatedDateTimeUtc asc', 'CreatedDateTimeUtc desc')",
alexhcheng marked this conversation as resolved.
Show resolved Hide resolved
"type": "array",
"items": {
"type": "string"
}
}
],
"responses": {
Expand Down Expand Up @@ -509,7 +557,7 @@
"Document Translation"
],
"summary": "Returns the status for all documents in a batch document translation request",
"description": "Returns the status for all documents in a batch document translation request.\r\n \r\nThe documents included in the response are sorted by document Id in descending order. If the number of documents in the response exceeds our paging limit, server-side paging is used.\r\nPaginated responses indicate a partial result and include a continuation token in the response. The absence of a continuation token means that no additional pages are available.\r\n \r\n$top and $skip query parameters can be used to specify a number of results to return and an offset for the collection.\r\nThe server honors the values specified by the client. However, clients must be prepared to handle responses that contain a different page size or contain a continuation token.\r\n \r\nWhen both $top and $skip are included, the server should first apply $skip and then $top on the collection.\r\nNote: If the server can't honor $top and/or $skip, the server must return an error to the client informing about it instead of just ignoring the query options.\r\nThis reduces the risk of the client making assumptions about the data returned.",
"description": "Returns the status for all documents in a batch document translation request.\r\n \r\nIf the number of documents in the response exceeds our paging limit, server-side paging is used.\r\nPaginated responses indicate a partial result and include a continuation token in the response. The absence of a continuation token means that no additional pages are available.\r\n \r\n$top, $skip and $maxpagesize query parameters can be used to specify a number of results to return and an offset for the collection.\r\n \r\n$top indicates the total number of records the user wants to be returned across all pages.\r\n$skip indicates the number of records to skip from the list of document status held by the server based on the sorting method specified. By default, we sort by descending start time.\r\n$maxpagesize is the maximum items returned in a page. If more items are requested via $top (or $top is not specified and there are more items to be returned), @nextLink will contain the link to the next page.\r\n \r\n$orderBy query parameter can be used to sort the returned list (ex \"$orderBy=createdDateTimeUtc asc\" or \"$orderBy=createdDateTimeUtc desc\").\r\nThe default sorting is descending by createdDateTimeUtc.\r\nSome query parameters can be used to filter the returned list (ex: \"status=Succeeded,Cancelled\") will only return succeeded and cancelled documents.\r\ncreatedDateTimeUtcStart and createdDateTimeUtcEnd can be used combined or separately to specify a range of datetime to filter the returned list by.\r\nThe supported filtering query parameters are (status, ids, createdDateTimeUtcStart, createdDateTimeUtcEnd).\r\n \r\nWhen both $top and $skip are included, the server should first apply $skip and then $top on the collection.\r\nNote: If the server can't honor $top and/or $skip, the server must return an error to the client informing about it instead of just ignoring the query options.\r\nThis reduces the risk of the client making assumptions about the data returned.",
"operationId": "DocumentTranslation_GetOperationDocumentsStatus",
"produces": [
"application/json"
Expand All @@ -526,22 +574,70 @@
{
"in": "query",
"name": "$top",
"description": "Take the $top entries in the collection\r\nWhen both $top and $skip are supplied, $skip is applied first",
"description": "$top indicates the total number of records the user wants to be returned across all pages.\r\n \r\nClients MAY use $top and $skip query parameters to specify a number of results to return and an offset into the collection.\r\nWhen both $top and $skip are given by a client, the server SHOULD first apply $skip and then $top on the collection.\r\n \r\nNote: If the server can't honor $top and/or $skip, the server MUST return an error to the client informing about it instead of just ignoring the query options.",
"type": "integer",
"format": "int32",
"default": 50,
"maximum": 100,
"minimum": 1
"maximum": 2147483647,
"minimum": 0
},
{
"in": "query",
"name": "$skip",
"description": "Skip the $skip entries in the collection\r\nWhen both $top and $skip are supplied, $skip is applied first",
"description": "$skip indicates the number of records to skip from the list of records held by the server based on the sorting method specified. By default, we sort by descending start time.\r\n \r\nClients MAY use $top and $skip query parameters to specify a number of results to return and an offset into the collection.\r\nWhen both $top and $skip are given by a client, the server SHOULD first apply $skip and then $top on the collection.\r\n \r\nNote: If the server can't honor $top and/or $skip, the server MUST return an error to the client informing about it instead of just ignoring the query options.",
"type": "integer",
"format": "int32",
"default": 0,
"maximum": 2147483647,
"minimum": 0
},
{
"in": "query",
alexhcheng marked this conversation as resolved.
Show resolved Hide resolved
"name": "$maxpagesize",
"description": "$maxpagesize is the maximum items returned in the items in a page. If more items are requested via $top (or $top is not specified and there are more items to be returned), @nextLink will contain the link to the next page.\r\n \r\nClients MAY request server-driven paging with a specific page size by specifying a $maxpagesize preference. The server SHOULD honor this preference if the specified page size is smaller than the server's default page size.",
"type": "integer",
"format": "int32",
"default": 50,
"maximum": 100,
"minimum": 1
},
{
"in": "query",
"name": "ids",
"description": "Ids to use in filtering",
"type": "array",
"items": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "status",
"description": "Status to use in filtering",
"type": "string"
},
{
"in": "query",
"name": "createdDateTimeUtcStart",
"description": "the start datetime to get items after",
"type": "string",
"format": "date-time"
},
{
"in": "query",
"name": "createdDateTimeUtcEnd",
"description": "the end datetime to get items before",
"type": "string",
"format": "date-time"
},
{
"in": "query",
"name": "$orderBy",
"description": "the sorting query for the collection (ex: 'CreatedDateTimeUtc asc', 'CreatedDateTimeUtc desc')",
"type": "array",
"items": {
"type": "string"
}
}
],
"responses": {
Expand Down Expand Up @@ -863,6 +959,7 @@
"Glossary": {
"description": "Glossary / translation memory for the request",
"required": [
"format",
"glossaryUrl"
],
"type": "object",
Expand All @@ -878,7 +975,7 @@
"example": "XLIFF"
},
"version": {
"description": "Version",
"description": "Optional Version. If not specified, default is used.",
"type": "string",
"example": "2.0"
},
Expand Down Expand Up @@ -1090,6 +1187,7 @@
"ErrorV2": {
"description": "This contains an outer error with error code, message, details, target and an inner error with more descriptive details.",
"required": [
"code",
"message"
],
"type": "object",
Expand Down Expand Up @@ -1232,8 +1330,8 @@
"createdDateTimeUtc",
"id",
"lastActionDateTimeUtc",
"path",
"progress",
"sourcePath",
"status",
"to"
],
Expand All @@ -1244,6 +1342,11 @@
"type": "string",
"example": "https://myblob.blob.core.windows.net/mycontainer/fr/mydoc.txt"
},
"sourcePath": {
"description": "Location of the source document",
"type": "string",
"example": "https://myblob.blob.core.windows.net/mycontainer/fr/mydoc.txt"
},
"createdDateTimeUtc": {
"format": "date-time",
"description": "Operation created date time",
Expand Down Expand Up @@ -1330,6 +1433,10 @@
"type": "string"
}
},
"defaultVersion": {
alexhcheng marked this conversation as resolved.
Show resolved Hide resolved
"description": "Default version if none is specified",
"type": "string"
},
"versions": {
"description": "Supported Version",
"type": "array",
Expand Down
1 change: 1 addition & 0 deletions ...cognitiveservices/data-plane/TranslatorText/preview/v1.0-preview.1/examples/document.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@
},
"body": {
"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",
Expand Down
13 changes: 11 additions & 2 deletions ...ognitiveservices/data-plane/TranslatorText/preview/v1.0-preview.1/examples/documents.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,16 @@
"endpoint": "{endpoint}",
"Ocp-Apim-Subscription-Key": "{API key}",
"id": "727BF148-F327-47A0-9481-ABAE6362F11E",
"$top": 5,
"$skip": 10
"$top": 20,
"$skip": 10,
"$maxpagesize": 10,
alexhcheng marked this conversation as resolved.
Show resolved Hide resolved
"$orderBy": "CreatedDateTime asc",
"createdDateTimeUtcStart": "2021-03-23T00:03:38.0136316",
"createdDateTimeUtcEnd": "2021-03-25T00:03:38.0136316",
"Status": "Succeeded",
"ids": [
"273622bd-835c-4946-9798-fd8f19f6bbf2"
]
},
"responses": {
"401": {
Expand Down Expand Up @@ -89,6 +97,7 @@
"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",
Expand Down
Loading