Inicio de traducción

Artículo
02/23/2024

Servicio de referencia
: Traducción de documentos de Azure AI
Versión de API: v1.1

Use esta API para iniciar una solicitud de traducción al servicio de traducción de documentos. Cada solicitud puede contener varios documentos y debe contener un contenedor de origen y otro de destino para cada documento.

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/memorias de traducción pueden incluirse en la solicitud y el servicio los aplica cuando se traduce el documento.

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, el trabajo producirá errores. El valor de targetUrl para cada idioma de destino debe ser único.

URL de la solicitud

Envíe una solicitud POST a:

POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches

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.

Encabezados de solicitud

Los encabezados de solicitud son:

encabezados	Descripción
Ocp-Apim-Subscription-Key	Encabezado de solicitud obligatorio

BatchRequest (cuerpo)

Definición para la solicitud de traducción por lotes de entrada. 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.


{
  "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.tsv",
              "format": "XLIFF",
              "version": "2.0",
              "storageSource": "AzureBlob"
            }
          ],
          "storageSource": "AzureBlob"
        }
      ],
      "storageType": "Folder"
    }
  ],
  "options": {
    "experimental": true
  }
}

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	•Cadena	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	•Cadena	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	•Cadena	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	•Cadena	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	•Cadena	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	•Cadena	Ubicación de la ubicación del contenedor para los documentos traducidos.
inputs.targets.category	`string`	False	•Cadena	Clasificación o categoría para la solicitud de traducción. Ejemplo: general.
inputs.targets.language	`string`	True	•Cadena	Código del idioma de destino. Ejemplo: "fr".
inputs.targets.glossaries	`array`	False	• glossaryUrl (cadena) • formato (cadena) • versión (cadena) • storageSource (cadena)	ConsulteCreación y uso de glosarios
inputs.targets.glossaries.glossaryUrl	`string`	Verdadero (si se usan glosarios).	•Cadena	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	•Cadena	Formato de archivo especificado para el glosario. Para comprobar si se admite el formato de archivo, consulteObtención de formatos de glosario admitidos.
inputs.targets.glossaries.version	`string`	False	•Cadena	Indicador de versión. Ejemplo: “2.0”.
inputs.targets.glossaries.storageSource	`string`	False	•Cadena	Origen de almacenamiento para glosarios. Tiene como valor predeterminado `_AzureBlob_`.
inputs.targets.storageSource	`string`	False	•Cadena	Origen de almacenamiento para destinos. El valor predeterminado es `_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?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr"
                }
            ]
        }
    ]
}

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

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://my.blob.core.windows.net/source-en?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "language": "fr",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://my.blob.core.windows.net/glossaries/en-fr.xlf?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=BsciG3NWoOoRjOYesTaUmxlXzyjsX4AgVkt2AsxJ9to%3D",
                            "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?sv=2019-12-12&st=2021-03-05T17%3A45%3A25Z&se=2021-03-13T17%3A45%3A00Z&sr=c&sp=rl&sig=SDRPMjE4nfrH3csmKLILkT%2Fv3e0Q6SWpssuuQl1NmfM%3D",
                "filter": {
                    "prefix": "MyFolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target-fr?sv=2019-12-12&st=2021-03-05T17%3A49%3A02Z&se=2021-03-13T17%3A49%3A00Z&sr=c&sp=wdl&sig=Sq%2BYdNbhgbq4hLT0o1UUOsTnQJFU590sWYo4BOhhQhs%3D",
                    "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?sv=2019-12-12&st=2021-01-26T18%3A30%3A20Z&se=2021-02-05T18%3A30%3A00Z&sr=c&sp=rl&sig=d7PZKyQsIeE6xb%2B1M4Yb56I%2FEEKoNIF65D%2Fs0IFsYcE%3D"
            },
            "targets": [
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-Spanish.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "es"
                },
                {
                    "targetUrl": "https://my.blob.core.windows.net/target/try/Target-German.docx?sv=2019-12-12&st=2021-01-26T18%3A31%3A11Z&se=2021-02-05T18%3A31%3A00Z&sr=c&sp=wl&sig=AgddSzXLXwHKpGHr7wALt2DGQJHCzNFF%2F3L94JHAWZM%3D",
                    "language": "de"
                }
            ]
        }
    ]
}

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 • Servidor temporal no disponible

Respuesta de error

Parámetro de clave	Tipo	Descripción
code	`string`	Enumeraciones que contiene códigos de error de alto nivel. Valores posibles: 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.

Ejemplos

Ejemplo de respuesta correcta

La siguiente información se devuelve en una respuesta correcta.

Puede encontrar el identificador del trabajo en el valor de la URL de Operation-Location del encabezado de respuesta. El último parámetro de la dirección URL es el identificador del trabajo de la operación (la cadena que sigue a "/operation/").

Operation-Location: https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/operation/0FA2822F-4C2A-4317-9C20-658C801E0E55

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

Share via