Compartir a través de

Obtener el estado de todos los documentos

  • Artículo

Característica de referencia
: Azure AI Translator → versión de Document Translation
API: 2024-05-01
MÉTODO HTTP: GET

Importante

Todas las solicitudes de API a la característica de traducción de documentos requieren un punto de conexión de dominio personalizado que se encuentra en la página de información general del recurso en Azure Portal.

  • Use el get documents status método para solicitar el estado de todos los documentos de un trabajo de traducción.

  • $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 forma predeterminada, los registros se ordenan 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.
    • 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.

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.

  • $orderBy el parámetro query se puede usar para ordenar la lista devuelta (por ejemplo, $orderBy=createdDateTimeUtc asc o $orderBy=createdDateTimeUtc desc).
  • La ordenación predeterminada es descendente por createdDateTimeUtc. Algunos parámetros de consulta se pueden usar para filtrar la lista devuelta (por ejemplo: status=Succeeded,Cancelled) solo devuelve documentos correctos y cancelados.
  • Los createdDateTimeUtcStart parámetros de consulta y createdDateTimeUtcEnd se pueden usar combinados o por separado para especificar un intervalo de fecha y hora para filtrar la lista devuelta.
  • Los parámetros de consulta de filtrado admitidos son (status, id, createdDateTimeUtcStarty createdDateTimeUtcEnd).
  • Cuando se incluyen ambas $top y $skip, el servidor debe aplicar primero $skip y luego $top en la colección.

URL de la solicitud

Envíe una solicitud GET a:

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

Búsqueda del valor de id

  • Puede encontrar el valor de id del trabajo en el valor de la dirección URL Operation-Location del encabezado de respuesta del método POST start-batch-translation. La cadena alfanumérica que sigue al parámetro /document/ es el trabajo de la operación id:
Encabezado de respuesta Dirección URL de respuesta
Operation-Location {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec?api-version=2024-05-01
  • También puede usar una solicitud get-translations-status para recuperar una lista de trabajos de traducción y sus id.

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 Condición
Ocp-Apim-Subscription-Key La clave de API del servicio Translator desde Azure Portal. Obligatorio
Ocp-Apim-Subscription-Region La región donde se creó el recurso. Necesario al usar un recurso regional (geográfico) como Oeste de EE. UU.
Content-Type En este encabezado se especifica el tipo de contenido de la carga. Los valores que se aceptan son application/json o charset=UTF-8. 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
•Fracasado
• NoStarted
•Corriente
•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

Sugerencia

Use este método para recuperar el documentId parámetro de la cadena de consulta get-document-status .

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.

Introducción a la traducción de documentos