Uso de API REST mediante programación

  • Artículo

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. 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).

  • 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:

    1. Suscripción. Seleccione una de las suscripciones de Azure disponibles.

    2. 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.

    3. 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.

    4. 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.

    5. Plan de tarifa. La traducción de documentos no es compatible con el nivel gratis. Para probar el servicio, seleccione Estándar S1.

    6. Seleccione Revisar + crear.

    7. Revise los términos de servicio y seleccione Crear para implementar el recurso.

    8. 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.

  1. 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.

  2. En el raíl izquierdo, en Administración de recursos, seleccione Claves y punto de conexión.

  3. Copie y pegue key y document translation endpoint en una ubicación adecuada, como el Bloc de notas de Microsoft. Solo se necesita una clave para realizar una llamada API.

  4. Va a pegar key y document translation endpoint en los códigos de ejemplo para autenticar la solicitud en el servicio de traducción de documentos.

    Captura de pantalla que muestra el campo para obtener la clave en Azure Portal.

Obtención de la clave

Las solicitudes al servicio Translator requieren una clave de solo lectura para autenticar el acceso.

  1. 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.
  2. En el raíl izquierdo, en Administración de recursos, seleccione Claves y punto de conexión.
  3. Copie y pegue la clave en una ubicación adecuada, como el Bloc de notas de Microsoft.
  4. Lo pega en el código de ejemplo para autenticar la solicitud en el servicio de Traducción de documentos.

Imagen del campo para obtener la clave en Azure Portal.

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 contenedor sourceURL y targetURL de los pares de idioma de origen y destino.
  • Las cadenas prefix y suffix distinguen entre mayúsculas y minúsculas para filtrar los documentos en la ruta de acceso de origen para su traducción. El campo prefix a menudo se usa para delinear las subcarpetas para la traducción. El campo suffix 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"
                        }
                    ]
                }
            ]
        }
    ]
}

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 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={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

¿Qué es Custom Translator?