Obtención del estado de los documentos
Servicio de referencia
: Traducción de documentos de Azure AI
Versión de API: v1.1
Si el número de documentos de la respuesta supera el límite de paginación, se usa la paginación del lado de servidor. Las respuestas paginadas indican un resultado parcial e incluyen un token de continuación en la respuesta. La ausencia de un token de continuación significa que no hay otras páginas disponibles.
$top, $skip, y $maxpagesize se pueden utilizar parámetros de consulta para especificar el número de resultados a devolver y un desplazamiento para la colección.
$top iIndica el número total de registros que el usuario quiere que se devuelvan en todas las páginas. $skip indica el número de registros que hay que omitir de la lista de estado de documentos que tiene el servidor en función del método de ordenación especificado. De manera predeterminada, se ordena por hora de inicio descendente. $maxpagesize es el máximo de elementos devueltos en una página. Si se solicitan más elementos a través de $top (o $top no se especifica y hay más elementos a devolver), @nextLink contendrá el enlace a la página siguiente.
El parámetro de consulta $orderBy se puede usar para ordenar la lista devuelta (por ejemplo, "$orderBy=createdDateTimeUtc asc" o "$orderBy=createdDateTimeUtc desc"). La ordenación predeterminada es por createdDateTimeUtc descendente. Algunos parámetros de consulta se pueden utilizar para filtrar la lista devuelta (por ejemplo: "status=Succeeded,Cancelled") sólo devuelve documentos exitosos y cancelados. createdDateTimeUtcStart y createdDateTimeUtcEnd se pueden usar combinados o por separado para especificar un intervalo de fecha y hora por el que filtrar la lista devuelta. Los parámetros de consulta de filtrado admitidos son (status, ID, createdDateTimeUtcStart y createdDateTimeUtcEnd).
Cuando se incluyen ambas $top y $skip, el servidor debe aplicar primero $skip y luego $top en la colección.
Nota:
Si el servidor no puede cumplir $top y/o $skip, debe devolver un error al cliente informando de ello en lugar de limitarse a ignorar las opciones de consulta. Esto reduce el riesgo de que el cliente realice suposiciones sobre los datos devueltos.
URL de la solicitud
Envíe una solicitud GET a:
GET https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches/{id}/documents
Aprenda a encontrar su nombre de dominio personalizado.
Importante
- Todas las solicitudes de API al servicio de traducción de documentos requieren un punto de conexión de dominio personalizado.
- No usará el punto de conexión que se encuentra en la página Claves y punto de conexión del recurso en Azure Portal, ni el punto de conexión global del traductor (
api.cognitive.microsofttranslator.com) para realizar solicitudes HTTP de traducción de documentos.
Parámetros de solicitud
Los parámetros de solicitud que se pasaron en la cadena de consulta son:
| Parámetro de consulta | En | Obligatorio | Type | Descripción |
|---|---|---|---|---|
id |
path | True | string | El identificador de la operación. |
$maxpagesize |
consulta | Falso | integer int32 | $maxpagesize es el máximo de elementos devueltos en una página. Si se solicitan más elementos a través de $top (o $top no se especifica y hay más elementos a devolver), @nextLink contendrá el enlace a la página siguiente. Los clientes pueden solicitar paginación controlada por el servidor con un tamaño de página específico especificando una $maxpagesize preferencia. El servidor DEBE respetar esta preferencia si el tamaño de página especificado es menor que el tamaño de página predeterminado del servidor. |
| $orderBy | Query | Falso | array | La consulta de ordenación de la colección (ej: CreatedDateTimeUtc asc, CreatedDateTimeUtc desc). |
$skip |
consulta | Falso | integer int32 | $skip indica el número de registros que se omitirán de la lista de registros mantenida por el servidor según el método de ordenación especificado. De manera predeterminada, se ordena por hora de inicio descendente. Los clientes PUEDEN utilizar $top y parámetros de consulta $skip para especificar el número de resultados a devolver y un desplazamiento dentro de la colección. Cuando el cliente devuelve ambos $top y $skip, el servidor DEBERÍA aplicar primero $skip y después $top en la colección. Si el servidor no puede respetar $top o $skip, el servidor DEBE devolver un error al cliente que lo informa en lugar de omitir las opciones de consulta. |
$top |
consulta | Falso | integer int32 | $top iIndica el número total de registros que el usuario quiere que se devuelvan en todas las páginas. Los clientes pueden usar $top parámetros de consulta y $skip para especificar el número de resultados que se van a devolver y un desplazamiento en la colección. Cuando el cliente devuelve ambos $top y $skip, el servidor DEBERÍA aplicar primero $skip y después $top en la colección. Si el servidor no puede respetar $top o $skip, el servidor DEBE devolver un error al cliente que lo informa en lugar de omitir las opciones de consulta. |
| createdDateTimeUtcEnd | Query | Falso | string date-time | Fecha y hora de finalización para obtener los elementos anteriores. |
| createdDateTimeUtcStart | Query | Falso | string date-time | Fecha y hora de inicio después de la cual se obtienen los elementos. |
ids |
consulta | Falso | array | Los ID que se usarán en el filtrado. |
| statuses | Query | Falso | array | Estados que se usarán en el filtrado. |
Encabezados de solicitud
Los encabezados de solicitud son:
| encabezados | Descripción |
|---|---|
| Ocp-Apim-Subscription-Key | Encabezado de solicitud obligatorio |
Códigos de estado de respuesta
A continuación se indican los códigos de estado HTTP posibles que devuelve una solicitud.
| Código de estado | Descripción |
|---|---|
| 200 | Aceptar. Solicitud correcta y devuelve el estado de los documentos. HeadersRetry-After: integerETag: string |
| 400 | Solicitud no válida. Compruebe los parámetros de entrada. |
| 401 | No autorizado. Compruebe sus credenciales. |
| 404 | No se encuentra el recurso. |
| 500 | Error interno del servidor. |
| Otros códigos de estado | • Demasiadas solicitudes • El servidor no está disponible temporalmente |
Respuesta de obtención del estado de los documentos
Respuesta correcta del estado de obtención de los documentos
En una respuesta correcta se devuelve la información siguiente.
| Nombre | Escribir | Descripción |
|---|---|---|
| @nextLink | string | Dirección URL de la página siguiente Valor NULL si no hay más páginas disponibles |
| value | DocumentStatus [] | Lista de estado detallado de documentos individuales. |
| value.path | string | Ubicación del documento o carpeta. |
| value.sourcePath | string | Ubicación del documento de origen. |
| value.createdDateTimeUtc | string | Fecha y hora de creación de la operación. |
| value.lastActionDateTimeUtc | string | Fecha y hora en la que se actualiza el estado de la operación. |
| value.status | status | Lista de posibles estados del trabajo o documento. • Cancelado •Cancelar •Fallado • NoStarted •Corriendo •Tuvo éxito • ValidationFailed |
| value.to | string | A language. |
| value.progress | number | Progreso de la traducción, si está disponible. |
| value.id | string | Identificador del documento. |
| value.characterCharged | integer | Caracteres cargados por la API. |
Respuesta de error
| Nombre | Escribir | Descripción |
|---|---|---|
| código | string | Enumeraciones que contiene códigos de error de alto nivel. Valores posibles: • InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable •Desautorizado |
| message | string | Obtiene un mensaje de error de alto nivel. |
| Destino | string | Obtiene el origen del error. Por ejemplo, sería documents o document id para un documento inválido. |
| innerError | InnerTranslationError | Nuevo formato de error interno, que cumple las directrices de la API de los servicios de Azure AI. Contiene las propiedades requeridas ErrorCode, mensaje y las propiedades opcionales de destino, detalles (par clave-valor), error interno (puede estar anidado). |
| innerError.code | string | Obtiene la cadena de error de código. |
| innerError.message | string | Obtiene un mensaje de error de alto nivel. |
| innerError.target | string | Obtiene el origen del error. Por ejemplo, sería documents o document id si hubiera un documento inválido. |
Ejemplos
Ejemplo de respuesta correcta
El siguiente objeto JSON es un ejemplo de una respuesta correcta.
{
"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"
}
Ejemplo de respuesta con error
El siguiente objeto JSON es un ejemplo de una respuesta con error. El esquema de otros códigos de error es el mismo.
Código de estado: 500
{
"error": {
"code": "InternalServerError",
"message": "Internal Server Error",
"target": "Operation",
"innerError": {
"code": "InternalServerError",
"message": "Unexpected internal server error has occurred"
}
}
}
Pasos siguientes
Siga nuestro inicio rápido para obtener más información sobre el uso de Traducción de documentos y la biblioteca cliente.