Compartir a través de


Iniciar traducción por lotes

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.

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.