Uso de API REST mediante programación
La traducción de documentos es una función basada en la nube del servicio Traductor de Azure AI. Puede usar la API de traducción de documentos para traducir de forma asincrónica documentos completos en los idiomas admitidos y varios formatos de archivo, a la vez que se conserva la estructura del documento de origen y el formato de texto. En esta guía paso a paso, aprende a usar las API de traducción de documentos con un lenguaje de programación de su elección y la API REST HTTP.
Prerrequisitos
Nota:
La traducción de documentos se admite en el plan de servicio estándar S1 (pago por uso) y C2, C3, C4 y planes de descuento por volumen D3. Consulte Precios de los servicios de Azure AI: traductor.
Para empezar, necesitará lo siguiente:
Una cuenta de Azure activa. En caso de no tener ninguna, puede crear una cuenta gratuita
Una cuenta de Azure Blob Storage. También 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 almacenan los archivos traducidos (obligatorio).
-
Complete los campos de detalles de proyecto e instancia de Translator de la siguiente manera:
Suscripción. Seleccione una de las suscripciones de Azure disponibles.
Grupo de recursos. Puede crear un nuevo grupo de recursos o agregar el recurso a un grupo ya existente que comparta el mismo ciclo de vida, permisos y directivas.
Región del recurso. Elija Global a menos que su empresa o aplicación requiera una región específica. Si planea usar una identidad administrada asignada por el sistema para la autenticación, elija una región geográfica como Oeste de EE. UU.
Nombre. Escriba el nombre que eligió para el recurso. El nombre que elija debe ser único en Azure.
Nota
La traducción de documentos requiere un punto de conexión de dominio personalizado. El valor que escriba en el campo Nombre será el parámetro de nombre de dominio personalizado para el punto de conexión.
Plan de tarifa. La traducción de documentos no es compatible con el nivel gratis. Para probar el servicio, seleccione Estándar S1.
Seleccione Revisar + crear.
Revise los términos de servicio y seleccione Crear para implementar el recurso.
Una vez que el recurso se implemente correctamente, seleccione Ir al recurso para recuperar la clave y el punto de conexión.
Recuperar la clave y el punto de conexión de dominio personalizado
- Las solicitudes al servicio Translator requieren una clave de solo lectura y un punto de conexión personalizado para autenticar el acceso. 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, y está disponible en Azure Portal.
Si ha creado un nuevo recurso, después de implementarlo, seleccione Ir al recurso. 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
key
ydocument translation endpoint
en una ubicación adecuada, como el Bloc de notas de Microsoft. Solo se necesita una clave para realizar una llamada API.Va a pegar
key
ydocument translation endpoint
en los códigos de ejemplo para autenticar la solicitud en el servicio de traducción de documentos.
Obtención de la clave
Las solicitudes al servicio Translator requieren una clave de solo lectura para autenticar el acceso.
- Si ha creado un nuevo recurso, después de implementarlo, seleccione Ir al recurso. 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 en una ubicación adecuada, como el Bloc de notas de Microsoft.
- Lo pega en el código de ejemplo para autenticar la solicitud en el servicio de Traducción de documentos.
Creación de contenedores de Azure Blob Storage
Tiene 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 almacenan 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 de origen o blob debe designar acceso de lectura y de lista.
- El destino contenedor o blob debe designar escritura y acceso.
- El blob del glosario debe designar acceso de lectura y lista.
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.
- Como alternativa a los tokens de SAS, puede usar una identidad administrada asignada por el sistema para la autenticación.
Solicitudes HTTP
Una solicitud de traducción por lotes asincrónica se envía al punto de conexión del servicio Translator a través de una solicitud POST. Si se completa correctamente, el método POST devuelve un código de respuesta 202 Accepted
, y el servicio crea una solicitud por lotes. Los documentos traducidos aparecerán en el contenedor de destino.
Para obtener información detallada sobre los límites de solicitudes de Azure AI Translator Service, consulte límites de solicitudes de traducción de documentos.
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 Azure para su recurso Translator o servicios de Azure AI. |
Content-Type | Requerido: especifica el tipo de contenido de la carga. Los valores aceptados son application/json y charset=UTF-8. |
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.1/batches
. - El cuerpo de la solicitud POST es un objeto JSON llamado
inputs
. - El objeto
inputs
contiene las direcciones de contenedorsourceURL
ytargetURL
de los pares de idioma de origen y destino. - Las cadenas
prefix
ysuffix
distinguen entre mayúsculas y minúsculas para filtrar los documentos en la ruta de acceso de origen para su traducción. El campoprefix
a menudo se usa para delinear las subcarpetas para la traducción. El camposuffix
se usa con mayor frecuencia para las extensiones de archivo. - Cuando se traduce el documento, se aplica un valor para el campo
glossaries
(opcional). - El valor de
targetUrl
para 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": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "fr"
}
]
}
]
}
Traducción de un documento específico de un contenedor
- Especifique
"storageType": "File"
. - Si no usa una identidad administrada asignada por el sistema para la autenticación, asegúrese de que ha creado el token de SAS y una dirección URL de origen para el blob o documento específico (no para el contenedor).
- Asegúrese de especificar el nombre de 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 devuelve un único documento traducido a dos idiomas de destino.
{
"inputs": [
{
"storageType": "File",
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es"
},
{
"targetUrl": "{targetSASUrl}",
"language": "de"
}
]
}
]
}
Traducción de documentos mediante glosarios personalizados
{
"inputs": [
{
"source": {
"sourceUrl": "{sourceSASUrl}"
},
"targets": [
{
"targetUrl": "{targetSASUrl}",
"language": "es",
"glossaries": [
{
"glossaryUrl": "{glossaryUrl/en-es.xlf}",
"format": "xliff"
}
]
}
]
}
]
}
🆕 Traducción de texto insertado en imágenes incluidas en documentos
Nota:
- Esta característica es opcional y debe estar habilitada para cada solicitud de traducción.
- La habilitación de esta característica generará costos adicionales en función del uso. Para más información, consulte Precios de Visión de Azure AI.
- Esta característica solo está disponible actualmente con Batch Document Translation API.
- Solo se admite el formato de archivo
.docx
. - Se requiere un recurso Servicios de Azure AI (no el recurso Traductor independiente) para usar esta característica.
Configuración de la solicitud
Uso del parámetro
translateTextWithinImage
opcional en el campooptions
- Tipo de datos: (
true
ofalse
) - El valor booleano predeterminado es
false
. Establezca la opción entrue
para habilitar la traducción del texto de las imágenes.
- Tipo de datos: (
Detalles de la respuesta. Cuando la característica está habilitada, la información de procesamiento de imágenes agregada se incluye con la respuesta:
totalImageScansSucceeded
. Número de escaneos de imágenes traducidos correctamente.totalImageScansFailed
. Número de escaneos de imágenes que no se pudieron procesar.
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# de ejemplo.
- Establezca los valores del punto de conexión, la clave y la dirección URL del contenedor en Program.cs.
- Agregue el paquete Newtonsoft.Json mediante la CLI de .NET para procesar datos JSON.
- Ejecute el programa desde el directorio del proyecto.
Importante
Para los ejemplos de código siguientes, codificará de forma rígida la dirección URL de Firma de acceso compartido (SAS) donde se indica. Recuerde quitar la URL de SAS del código cuando haya terminado y nunca la haga pública. En el caso de producción, use una forma segura de almacenar sus credenciales y acceder a ellas, como la identidad administrada de Azure. Para más información, consulte Seguridad de Azure Storage.
Es posible que tenga que actualizar los campos siguientes, en función de la operación:
endpoint
basePath
key
sourceURL
targetURL
glossaryURL
id
(id. del trabajo)
Búsqueda del valor de id
- Puede encontrar el valor de
id
del trabajo en el valor de la dirección URLOperation-Location
del encabezado de respuesta del método POSTstart-batch-translation
. La cadena alfanumérica que sigue al parámetro/document/
es el trabajo de la operaciónid
:
Encabezado de respuesta | Dirección URL de respuesta |
---|---|
Operation-Location | {document-translation-endpoint}/translator/document/9dce0aa9-78dc-41ba-8cae-2e2f3c2ff8ec ?api-version={date} |
- También puede usar una solicitud get-translations-status para recuperar una lista de trabajos de traducción y sus
id
.
Iniciar traducción por lotes asincrónica
using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
class Program
{
static readonly string route = "?api-version={date}";
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches";
private static readonly string key = "{your-api-key}";
static readonly string json = ("{\"inputs\": [{\"source\": {\"sourceUrl\": \"https://YOUR-SOURCE-URL-WITH-READ-LIST-ACCESS-SAS\",\"storageSource\": \"AzureBlob\",\"language\": \"en\"}, \"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(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
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 formatos de documento admitidos
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 basePath = "{your-document-translation-endpoint}/translator/document/formats";
static readonly string route = "?api-version={date}&type=document";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
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);
}
}
Obtener el estado de un trabajo de traducción
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 basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
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);
}
}
}
Obtener el estado de un documento específico
Información general breve
Recupere el estado de un documento específico en 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 basePath = "{document-translation-endpoint}/translator/document/batches/{id}/documents/{documentId}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Get;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
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 cancelan los documentos para los que no se inicia la traducción.
using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
private static readonly string basePath = "{your-document-translation-endpoint}/translator/document/batches/{id}";
static readonly string route = "?api-version={date}";
private static readonly string key = "{your-api-key}";
static async Task Main(string[] args)
{
HttpClient client = new HttpClient();
using HttpRequestMessage request = new HttpRequestMessage();
{
request.Method = HttpMethod.Delete;
request.RequestUri = new Uri(basePath + route);
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
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);
}
}
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á autorizada. Asegúrese de que la clave o el token sean válidos y estén en la región correcta. |
429 | Demasiadas solicitudes | Ha superado la cuota o tasa de solicitudes permitidas para la suscripción. |
502 | Puerta de enlace incorrecta | Problema de red o de servidor. También puede indicar encabezados no válidos. |