Introducción a la traducción de documentos
En este artículo, aprenderá a usar la traducción de documentos con métodos de la API REST HTTP. Traducción de documentos es una característica basada en la nube del servicio Azure Translator. La API de traducción de documentos permite la traducción de documentos completos al tiempo que conserva la estructura del documento de origen y el formato del texto.
Requisitos previos
Nota
- Por lo general, cuando se crea un recurso de Cognitive Services en Azure Portal, tiene la opción de crear una clave de suscripción de varios servicios o una clave de suscripción de un solo servicio. Sin embargo, la traducción de documentos se admite actualmente solo en el recurso de Translator (servicio único) y no se incluye en el recurso de Cognitive Services (multiservicio).
- La traducción de documentos solo está disponible en el plan de servicio Estándar S1 (pago por uso) o en el plan de descuento por volumen D3. Consulte los precios de Cognitive Services precios: Translator.
Para empezar, necesitará lo siguiente:
Una cuenta de Azure activa. En caso de no tener ninguna, puede crear una cuenta gratuita.
Un recurso Translator de servicio único (no un recurso multiservicio de Cognitive Services).
Una cuenta de Azure Blob Storage. Creará contenedores para almacenar y organizar los datos de los blobs en la cuenta de almacenamiento.
Nombre de dominio y clave de suscripción personalizados
Importante
- Todas las solicitudes de API al servicio de traducción de documentos requieren un punto de conexión de dominio personalizado.
- No utilizará 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 de Translator (
api.cognitive.microsofttranslator.com) para realizar solicitudes HTTP de traducción de documentos.
¿Qué es el punto de conexión de dominio personalizado?
El punto de conexión de dominio personalizado es una dirección URL con el nombre del recurso, el nombre de host y los subdirectorios de Translator:
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0
Búsqueda del nombre de dominio personalizado
El parámetro NAME-OF-YOUR-RESOURCE (también llamado nombre de dominio personalizado) es el valor que especificó en el campo Nombre al crear el recurso de Translator.
Obtener tu clave de suscripción
Las solicitudes al servicio Translator requieren una clave de solo lectura para autenticar el acceso.
- Si ha creado un recurso nuevo, seleccione Ir al recurso una vez se haya implementado. Si tiene un recurso de traducción de documentos existente, vaya directamente a la página del recurso.
- En el raíl izquierdo, en Administración de recursos, seleccione Claves y punto de conexión.
- Copie y pegue la clave de suscripción en una ubicación adecuada, como el Bloc de notas de Microsoft.
- Lo pegará en el código siguiente para autenticar la solicitud en el servicio de traducción de documentos.
Creación de contenedores de Azure Blob Storage
Tendrá que crear contenedores en la cuenta de Azure Blob Storage para los archivos de origen y destino.
- Contenedor de origen. En este contenedor se cargan los archivos para su traducción (obligatorio).
- Contenedor de destino. En este contenedor se almacenarán los archivos traducidos (obligatorio).
Nota
La traducción de documentos admite glosarios en forma de blobs en contenedores de destino (no contenedores de glosario independientes). Si quiere incluir un glosario personalizado, agréguelo al contenedor de destino e incluya glossaryUrl con la solicitud. Si el par de idiomas de traducción no existe en el glosario, no se aplicará. Consulte Traducción de documentos mediante glosarios personalizados
Creación de tokens de acceso de SAS para la traducción de documentos
Los elementos sourceUrl, targetUrl y el elemento opcional glossaryUrl deben incluir un token de firma de acceso compartido (SAS), que se anexa como una cadena de consulta. El token se puede asignar al contenedor o a blobs específicos. Consulte Creación de tokens de SAS para el proceso de traducción de documentos.
- El contenedor o el blob de origen deben tener designado acceso de lectura y de lista.
- El contenedor o el blob de destino deben tener designado acceso de escritura y de lista.
- El blob de glosario debe tener acceso designado de lectura y enumeración.
Sugerencia
- Si va a traducir varios archivos (blobs) en una operación, delegue el acceso de SAS en el nivel de contenedor.
- Si va a traducir un único archivo (blob) en una operación, delegue el acceso de SAS en el nivel de blob.
Traducción de documentos: solicitudes HTTP
Una solicitud de traducción de documentos por lotes se envía al punto de conexión del servicio Translator mediante una solicitud POST. Si se realiza correctamente, el método POST devuelve un código de respuesta 202 Accepted y el servicio crea la solicitud por lotes.
Encabezados HTTP
En cada solicitud de API de traducción de documentos se incluyen los siguientes encabezados:
| Encabezado HTTP | Descripción |
|---|---|
| Ocp-Apim-Subscription-Key | Requerido: el valor es la clave de suscripción de Azure para el recurso de Translator o Cognitive Services. |
| Content-Type | Requerido: especifica el tipo de contenido de la carga. Los valores aceptados son application/json y charset=UTF-8. |
| Content-Length | Requerido: longitud del cuerpo de la solicitud. |
Propiedades del cuerpo de la solicitud POST
- La dirección URL de la solicitud POST es POST
https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches. - El cuerpo de la solicitud POST es un objeto JSON llamado
inputs. - El objeto
inputscontiene las direcciones de contenedorsourceURLytargetURLde los pares de idioma de origen y destino. - Los campos
prefixysuffix(opcional) se usan para filtrar documentos en el contenedor, incluidas las carpetas. - Cuando se traduce el documento, se aplica un valor para el campo
glossaries(opcional). - El valor de
targetUrlpara cada idioma de destino debe ser único.
Nota
Si ya existe un archivo con el mismo nombre en el destino, el trabajo producirá errores.
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 un documento específico de un contenedor
- Asegúrese de que ha especificado "storageType": "File".
- Asegúrese de haber creado la URL de origen y el token de SAS para el blob/documento específico (no para el contenedor).
- 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.
- La solicitud de ejemplo siguiente muestra un único documento que se traduce en 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"
}
]
}
]
}
Traducción de documentos mediante glosarios personalizados
{
"inputs": [
{
"source": {
"sourceUrl": "https://myblob.blob.core.windows.net/source",
"filter": {
"prefix": "myfolder/"
}
},
"targets": [
{
"targetUrl": "https://myblob.blob.core.windows.net/target",
"language": "es",
"glossaries": [
{
"glossaryUrl": "https:// myblob.blob.core.windows.net/glossary/en-es.xlf",
"format": "xliff"
}
]
}
]
}
]
}
Uso de código para enviar solicitudes de traducción de documentos
Configuración de la plataforma de codificación
- Cree un nuevo proyecto.
- Reemplace Program.cs por el código de C# que se muestra a continuación.
- Establezca los valores del punto de conexión, la clave de suscripción y la dirección URL del contenedor en Program.cs.
- Para procesar datos JSON, agregue el paquete Newtonsoft.Json mediante la CLI de .NET.
- Ejecute el programa desde el directorio del proyecto.
Importante
Para los ejemplos de código siguientes, deberá codificar de forma rígida la clave y el punto de conexión donde se indique. Recuerde quitar la clave del código cuando haya terminado y no publicarla públicamente. Consulte Seguridad de Azure Cognitive Services para saber cómo almacenar y acceder a las credenciales de forma segura.
Es posible que tenga que actualizar los campos siguientes, en función de la operación:
endpointsubscriptionKeysourceURLtargetURLglossaryURLid(identificador del trabajo)
Búsqueda del valor de id
- Encontrará el valor de
iddel trabajo en el valor de la dirección URLOperation-Locationdel encabezado de respuesta del método POST. El último parámetro de la dirección URL es el valor deiddel trabajo de la operación:
| Encabezado de respuesta | Dirección URL del resultado |
|---|---|
| Operation-Location | https://<NOMBRE-DEL-RECURSO>.cognitiveservices.azure.com/translator/text/batch/v1.0/batches/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec |
- También puede usar una solicitud Get Jobs para recuperar el valor de
idde un trabajo de traducción de documentos.
Traducción de documentos
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "/batches";
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";
private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\",\"filter\":{\"prefix\": \"Demo_1/\"} }, \"targets\": [{\"targetUrl\": \"https://YOUR-TARGET-URL-WITH-WRITE-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"category\": \"general\",\"language\": \"es\"}]}]}");
static async Task Main(string[] args)
{
using HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
StringContent content = new StringContent(json, Encoding.UTF8, "application/json");
request.Method = HttpMethod.Post;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
request.Content = content;
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
if (response.IsSuccessStatusCode)
{
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine();
Console.WriteLine($"Response Headers:");
Console.WriteLine(response.Headers);
}
else
Console.Write("Error");
}
}
}
}
Obtención de los formatos de archivo
Recupera una lista de los formatos de archivo admitidos. Si se realiza correctamente, este método devuelve un código de respuesta 200 OK.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";
static readonly string route = "/documents/formats";
private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Obtención de estado del trabajo
Obtiene el estado actual de un único trabajo y un resumen de todos los trabajos de una solicitud de traducción de documentos. Si se realiza correctamente, este método devuelve un código de respuesta 200 OK.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";
static readonly string route = "/batches/{id}";
private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Obtención del estado del documento
Información general breve
Recupera el estado de un documento específico de una solicitud de traducción de documentos. Si se realiza correctamente, este método devuelve un código de respuesta 200 OK.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";
static readonly string route = "/{id}/document/{documentId}";
private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Eliminación de un trabajo
Información general breve
Cancela el procesamiento actual o el trabajo en cola. Solo se cancelarán los documentos para los que no se haya iniciado la traducción.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string endpoint = "https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.0";
static readonly string route = "/batches/{id}";
private static readonly string subscriptionKey = "<YOUR-SUBSCRIPTION-KEY>";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(endpoint + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
HttpResponseMessage response = await client.SendAsync(request);
string result = response.Content.ReadAsStringAsync().Result;
Console.WriteLine($"Status code: {response.StatusCode}");
Console.WriteLine($"Response Headers: {response.Headers}");
Console.WriteLine();
Console.WriteLine(result);
}
}
Límites del contenido
En la tabla siguiente se enumeran los límites de los datos que se envían a la traducción de documentos.
| Atributo | Límite |
|---|---|
| Tamaño del documento | ≤40 MB |
| Número total de archivos. | ≤1000 |
| Tamaño total del contenido de un lote | ≤250 MB |
| Número de idiomas de destino en un lote | ≤10 |
| Tamaño del archivo de la memoria de traducción | ≤10 MB |
La traducción de documentos no se puede usar para traducir documentos protegidos, como aquellos con una contraseña cifrada o con acceso restringido para copiar contenido.
Solución de problemas
Códigos de estado HTTP comunes
| Código de estado HTTP | Descripción | Posible motivo |
|---|---|---|
| 200 | Aceptar | La solicitud fue correcta. |
| 400 | Bad Request | Falta un parámetro requerido, está vacío o es nulo. O bien, el valor pasado a un parámetro obligatorio u opcional no es válido. Un problema común es que el encabezado sea demasiado largo. |
| 401 | No autorizado | La solicitud no está autenticada. Asegúrese de que la clave de suscripción o el token sean válidos y de la región correcta. Al administrar la suscripción en Azure Portal, asegúrese de usar el recurso de servicio único Translator, y no el recurso multiservicios de Cognitive Services. |
| 429 | Demasiadas solicitudes | Ha superado la cuota o la tasa de solicitudes permitidas para su suscripción. |
| 502 | Puerta de enlace incorrecta | Problema de red o de servidor. Podría indicar también encabezados no válidos. |
Más información
- Referencia de la API de Translator v3
- Compatibilidad con idiomas
- Suscripciones en Azure API Management.