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:
Normalmente, cuando se crea un recurso de Azure AI en el Azure Portal, se tiene la opción de crear una clave multiservicio o una clave de servicio único. Sin embargo, la traducción de documentos solo se admite actualmente en el recurso Traductor (servicio único), y no se incluye en el recurso Azure AI services (multiservicio).
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. ConsultePrecios de los servicios de Azure AI: Translator.
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).
Un recurso Translator de servicio único (no un recurso multiservicio de servicios de Azure AI):
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
keyydocument translation endpointen una ubicación adecuada, como el Bloc de notas de Microsoft. Solo se necesita una clave para realizar una llamada API.Va a pegar
keyydocument translation endpointen 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. ConsulteCreació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 del servicio Traductor de Azure AI, consulteLí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
inputscontiene las direcciones de contenedorsourceURLytargetURLde los pares de idioma de origen y destino. - Las cadenas
prefixysuffixdistinguen entre mayúsculas y minúsculas para filtrar los documentos en la ruta de acceso de origen para su traducción. El campoprefixa menudo se usa para delinear las subcarpetas para la traducción. El camposuffixse 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
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": "{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"
}
]
}
]
}
]
}
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:
endpointbasePathkeysourceURLtargetURLglossaryURLid(id. del trabajo)
Búsqueda del valor de id
- Puede encontrar el valor de
iddel trabajo en el valor de la dirección URLOperation-Locationdel 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. Cuando administre su suscripción en el portal Azure, asegúrese de que está utilizando el recurso de servicio único Translatory no el recurso multiservicio Servicios de Azure AI. |
| 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. |
Saber más
Pasos siguientes
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de