Iniciar traducción por lotes

Artículo
09/26/2024

Referencia
Característica: Traductor de Azure AI → Traducción de documentos
Versión de la API: 2024-05-01
Método HTTP: POST

Use el Start Translation método para ejecutar una solicitud de traducción por lotes asincrónica.
El método requiere una cuenta de Azure Blob Storage con contenedores de almacenamiento para los documentos de origen y traducidos.

URL de la solicitud

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.

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

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.	Se requiere cuando se usa un recurso regional (geográfico) como Oeste de EE. UU. &viñeta.
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

BatchRequest (cuerpo)

Cada solicitud puede contener varios documentos y debe contener un contenedor de origen y otro de destino para cada documento. Tipos de medios de origen: application/json, text/json, application/*+json.
El filtro de prefijo y sufijo (si se proporcionan) se usan para filtrar carpetas. El prefijo se aplica a la subruta después del nombre del contenedor.
Los glosarios se pueden incluir en la solicitud. Si el glosario no es válido o no se puede acceder a él durante la traducción, se indica un error en el estado del documento.
Si ya existe un archivo con el mismo nombre en el destino de destino, se produce un error en el trabajo.
El valor de targetUrl para cada idioma de destino debe ser único.


{
  "inputs": [
    {
      "source": {
        "sourceUrl": "https://myblob.blob.core.windows.net/Container/",
        "filter": {
          "prefix": "FolderA",
          "suffix": ".txt"
        },
        "language": "en",
        "storageSource": "AzureBlob"
      },
      "targets": [
        {
          "targetUrl": "https://myblob.blob.core.windows.net/TargetUrl/",
          "category": "general",
          "language": "fr",
          "glossaries": [
            {
              "glossaryUrl": "https://myblob.blob.core.windows.net/Container/myglossary.xlf",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
}

Entradas

Definición para la solicitud de traducción por lotes de entrada.

Parámetro de clave	Tipo	Obligatorio	Parámetros de solicitud	Descripción
Entradas	`array`	True	• origen (objeto) • destinos (matriz) • storageType (cadena)	Datos de origen de entrada.

inputs.source

Definición de los datos de origen.

Parámetro de clave	Tipo	Obligatorio	Parámetros de solicitud	Descripción
inputs.source	`object`	True	• sourceUrl (cadena) • filtro(objeto) • idioma(cadena) • storageSource (cadena)	Datos de origen para documentos de entrada.
inputs.source.sourceUrl	`string`	True	•cuerda	Ubicación del contenedor para el archivo o la carpeta de origen.
inputs.source.filter	`object`	False	• prefijo (cadena) • sufijo (cadena)	Cadenas que distinguen mayúsculas de minúsculas para filtrar documentos en la ruta de acceso de origen.
inputs.source.filter.prefix	`string`	False	•cuerda	Una cadena de prefijo que distingue entre mayúsculas y minúsculas para filtrar los documentos en la ruta de origen para su traducción. A menudo se usa para designar subcarpetas para la traducción. Ejemplo: "CarpetaA".
inputs.source.filter.suffix	`string`	False	•cuerda	Una cadena de sufijo que distingue entre mayúsculas y minúsculas para filtrar los documentos en la ruta de origen para su traducción. Se utiliza principalmente para las extensiones de archivo. Por ejemplo: ".txt"
inputs.source.language	`string`	False	•cuerda	El código de idioma de los documentos traducidos. Si no se especifica, se implementa la detección automática.
inputs.source.storageSource	`string`	False	•cuerda	Origen de almacenamiento para entradas. Tiene como valor predeterminado `AzureBlob`.

inputs.targets

Definición de los datos de destino y glosarios.

Parámetro de clave	Tipo	Obligatorio	Parámetros de solicitud	Descripción
inputs.targets	`array`	True	• targetUrl (cadena) • categoría (cadena) • idioma (cadena) • glosarios (matriz) • storageSource (cadena)	Destinos y datos de glosarios para documentos traducidos.
inputs.targets.targetUrl	`string`	True	•cuerda	Ubicación de la ubicación del contenedor para los documentos traducidos.
inputs.targets.category	`string`	False	•cuerda	Clasificación o categoría para la solicitud de traducción. Ejemplo: general.
inputs.targets.language	`string`	True	•cuerda	Código del idioma de destino. Ejemplo: "fr".
inputs.targets.glossaries	`array`	False	• glossaryUrl (cadena) • formato (cadena) • versión (cadena) • storageSource (cadena)	Consulte Creación y uso de glosarios
inputs.targets.glossaries.glossaryUrl	`string`	Verdadero (si se usan glosarios).	•cuerda	Ubicación del glosario. Usaremos la extensión de archivo para extraer el formato si no se proporciona el parámetro de formato. Si el par de idiomas de traducción no está presente en el glosario, no se aplica.
inputs.targets.glossaries.format	`string`	False	•cuerda	Formato de archivo especificado para el glosario. Para comprobar si se admite el formato de archivo, consulte Obtención de formatos de glosario admitidos.
inputs.targets.glossaries.version	`string`	False	•cuerda	Indicador de versión. Ejemplo: “2.0”.
inputs.targets.glossaries.storageSource	`string`	False	•cuerda	Origen de almacenamiento para glosarios. Tiene como valor predeterminado `_AzureBlob_`.
inputs.targets.storageSource	`string`	False	•cuerda	Origen de almacenamiento para targets.defaults en `_AzureBlob_`.

inputs.storageType

Definición de la entidad de almacenamiento para los documentos de entrada.

Parámetro de clave	Tipo	Obligatorio	Parámetros de solicitud	Descripción
inputs.storageType	`string`	False	•`Folder` • `File`	Tipo de almacenamiento de la cadena de origen de los documentos de entrada. Solo "Folder" o "File" son valores válidos.

Opciones

Definición para la solicitud de traducción por lotes de entrada.

Parámetro de clave	Tipo	Obligatorio	Parámetros de solicitud	Descripción
options	`object`	False	Información de origen de los documentos de entrada.
options.experimental	`boolean`	False	•`true` • `false`	Indica si la solicitud incluye una característica experimental (si procede). Solo los valores booleanos `true` o `false` son valores válidos.

Solicitud de ejemplo

Los siguientes son ejemplos de solicitudes por lotes.

Nota

En los ejemplos siguientes, se ha concedido acceso limitado al contenido de un contenedor de Azure Storage mediante un token de firma de acceso compartido (SAS).

Traducción de todos los documentos de un contenedor

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traducción de todos los documentos de un contenedor aplicando glosarios

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?{SAS-token-query-string}",
                            "format": "xliff",
                            "version": "1.2"
                        }
                    ]

                }
            ]
        }
    ]
}

Traducción de una carpeta específica en un contenedor

Asegúrese de especificar el nombre de carpeta (distingue mayúsculas de minúsculas) como prefijo en el filtro.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?{SAS-token-query-string}",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?{SAS-token-query-string}",
                    "language": "fr"
                }
            ]
        }
    ]
}

Traducción de un documento específico en un contenedor

Especifique "storageType": File.
Cree la dirección URL de origen y el token de SAS para el blob o documento específicos.
Asegúrese de haber especificado el nombre del archivo de destino como parte de la dirección URL de destino, aunque el token de SAS sigue siendo para el contenedor.

Esta solicitud de ejemplo muestra un único documento traducido a dos idiomas de destino.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en/source-english.docx?{SAS-token-query-string}"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?{SAS-token-query-string}",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?{SAS-token-query-string}",
                    "language": "de"
                }
            ]
        }
    ]
}

Sugerencia

Este método devuelve el parámetro job id para las cadenas de consulta de consulta get-translation-status, get-documents-status, get-document-status y cancel-translation request.

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 ids.

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

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
202	Accepted. Solicitud aceptada y solicitud de lote creada. La cabecera Operation-Location indica una url de estado con el ID de la operación.HeadersOperation-Location: string
400	Solicitud incorrecta. Solicitud no válida. Compruebe los parámetros de entrada.
401	No autorizado. Compruebe sus credenciales.
429	La tasa de solicitudes es demasiado alta.
500	Error interno del servidor.
503	El servicio no está disponible en este momento. Vuelva a intentarlo más tarde.
Otros códigos de estado	• Demasiadas solicitudes. El servidor no está disponible temporalmente

Respuesta de error

Parámetro de clave	Tipo	Descripción
code	`string`	Enumeraciones que contiene códigos de error de alto nivel. Valores posibles:</br/>• InternalServerError • InvalidArgument • InvalidRequest • RequestRateTooHigh • ResourceNotFound • ServiceUnavailable • No autorizado
message	`string`	Obtiene un mensaje de error de alto nivel.
innerError	InnerTranslationError	Nuevo formato de error interno, que cumple las directrices de la API de los servicios de Azure AI. Este mensaje de error contiene las propiedades necesarias: ErrorCode, message y propiedades opcionales de destino, details(key value pair) y inner error(it can be nested).
inner.Errorcode	`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 el documento no es válido.

Respuesta de error de ejemplo

{
  "error": {
    "code": "ServiceUnavailable",
    "message": "Service is temporary unavailable",
    "innerError": {
      "code": "ServiceTemporaryUnavailable",
      "message": "Service is currently unavailable.  Please try again later"
    }
  }
}

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

Compartir vía