Identidades administradas para la traducción de documentos

Artículo
02/12/2024

Las identidades administradas para los recursos de Azure son entidades de servicio que crean una identidad de Microsoft Entra y permisos específicos para los recursos administrados de Azure. Las identidades administradas son una manera más segura de conceder acceso a los datos de almacenamiento y reemplazar el requisito de incluir tokens de firma de acceso compartido (SAS) con las direcciones URL de origen y destino.

Screenshot of managed identity flow (RBAC).

Puede usar identidades administradas para conceder acceso a cualquier recurso que admita la autenticación de Microsoft Entra, incluidas sus propias aplicaciones.
Para conceder acceso a un recurso de Azure, asigne un rol de Azure a una identidad administrada mediante el control de acceso basado en roles de Azure (Azure RBAC).
El uso de identidades administradas en Azure no tiene ningún costo adicional.

Importante

Al usar identidades administradas, no incluya una dirección URL de token de SAS con las solicitudes HTTP, ya que si lo hace, se producirá un error en las solicitudes. El uso de identidades administradas reemplaza el requisito de incluir tokens de firma de acceso compartido (SAS) con las direcciones URL de origen y destino.
Para usar identidades administradas para las operaciones de traducción de documentos, debe crear el recurso de Translator en una región de Azure geográfica específica, como Este de EE. UU. Si la región de recurso de Translator está establecida en Global, no puede usar la identidad administrada para la traducción de documentos. Todavía puede usar tokens de firma de acceso compartido (SAS) para la traducción de documentos.
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. ConsultePrecios de los servicios de Azure AI: Translator.

Requisitos previos

Para empezar, necesitará lo siguiente:

Una cuenta activa de Azure: en caso de no tener una, puede crear una cuenta gratuita.
Un recurso Traductor de servicio único (no un servicio múltiple de servicios de Azure AI) asignado a una región geográfica como Oeste de EE. UU. Para ver los pasos detallados, consulteCreación de un recurso de varios servicios.
Estar algo familiarizado con el control de acceso basado en roles de Azure(Azure RBAC) mediante Azure Portal.
Una cuenta de Azure Blob Storage en la misma región que el recurso de Traductor. También necesita crear contenedores para almacenar y organizar los datos de los blobs en la cuenta de almacenamiento.
Si la cuenta de almacenamiento está detrás de un firewall, debe habilitar la configuración siguiente:
1. Vaya a Azure Portal e inicie sesión con su cuenta de Azure.
2. Seleccione la cuenta de almacenamiento.
3. En el grupo Seguridad y redes del panel izquierdo, seleccione Redes.
4. En la pestaña Firewalls y redes virtuales, seleccione Habilitado desde redes virtuales y direcciones IP seleccionadas.
5. Anule la selección de todas las casillas.
6. Asegúrese de que esté seleccionada la opción Enrutamiento de red de Microsoft.
7. En la sección Instancias de recursos, seleccione Microsoft.CognitiveServices/accounts como tipo de recurso y seleccione el recurso de Traductor como nombre de instancia.
8. Comprobar que la casilla Permitir que los servicios de Azure de la lista de servicios de confianza accedan a esta cuenta de almacenamiento esté seleccionada. Para obtener más información sobre la administración de excepciones, consulteConfiguración de firewall y redes virtuales de Azure Storage.
9. Seleccione Guardar.
  
  Nota
  
  Los cambios de red pueden tardar hasta 5 minutos en propagarse.
Aunque ahora se permite el acceso a la red, el recurso de Translator sigue sin poder acceder a los datos de la cuenta de almacenamiento. Deberá crear una identidad administrada y asignar un rol de acceso específico al recurso de Translator.

Asignaciones de identidad administrada

Hay dos tipos de identidades administradas: asignadas por el sistema y asignadas por el usuario. Actualmente, la traducción de documentos admite las identidades administradas asignadas por el sistema:

Una identidad administrada asignada por el sistema se habilita directamente en una instancia de servicio. No está habilitada de forma predeterminada; debe ir al recurso y actualizar la configuración de identidad.
La identidad administrada asignada por el sistema está vinculada al recurso a lo largo de su ciclo de vida. Si elimina el recurso, la identidad administrada se elimina también.

En los pasos siguientes, se habilita una identidad administrada asignada por el sistema y se concede al recurso de Traductor acceso limitado a la cuenta de Azure Blob Storage.

Habilitación de una identidad administrada asignada por el sistema.

Debe conceder al recurso Traductor acceso a su cuenta de almacenamiento antes de que pueda crear, leer o eliminar blobs. Una vez habilitado el recurso Traductor con una identidad administrada asignada por el sistema, puede utilizar el control de acceso basado en roles de Azure (Azure RBAC), para dar acceso al Traductor a sus contenedores de almacenamiento de Azure.

Vaya a Azure Portal e inicie sesión con su cuenta de Azure.
Selección del recurso de Traductor.
En el grupo Administración de recursos del panel izquierdo, seleccione Identidad.
En la pestaña Sistema asignado, active el botón de alternancia Estado.

Importante

Una identidad administrada asignada por el usuario no cumplirá los requisitos del escenario de cuenta de almacenamiento de transcripción por lotes. Asegúrese de habilitar la identidad administrada asignada por el sistema.
Seleccione Guardar.

Concesión de acceso a la cuenta de almacenamiento para el recurso de Translator

Importante

Para asignar una función de identidad administrada asignada por el sistema, necesita permisos de Microsoft.Authorization/roleAssignments/write, como Propietario o Administrador de acceso de usuario en el ámbito de almacenamiento para el recurso de almacenamiento.

Vaya a Azure Portal e inicie sesión con su cuenta de Azure.
Selección del recurso de Traductor.
En el grupo Administración de recursos del panel izquierdo, seleccione Identidad.
En Permisos, seleccione Asignaciones de roles de Azure:
En la página Asignaciones de roles de Azure que se abre, elija su suscripción en el menú desplegable y, después, seleccione + Agregar asignación de roles.

A continuación, asigne un rol de colaborador de datos de Blob de almacenamiento a su recurso del servicio Traductor. El rol Colaborador de datos de Storage Blob proporciona al Traductor (representado por la identidad administrada asignada por el sistema) acceso de lectura, escritura y eliminación al contenedor de blobs y a los datos. En la ventana emergente Agregar asignación de roles, complete los campos como se muestra a continuación y seleccione Guardar:

Campo	Valor
Ámbito	*Storage*.
Suscripción	*La suscripción asociada al recurso de almacenamiento*.
Recurso	*El nombre del recurso de almacenamiento*.
Rol	*Colaborador de datos de Storage Blob*.

Screenshot: add role assignments page in the Azure portal.

Una vez que aparezca el mensaje de confirmación de asignación de rol agregado, actualice la página para ver la asignación de rol agregada.
Si no ve la nueva asignación de roles inmediatamente, espere e intente actualizar la página de nuevo. Al asignar o quitar asignaciones de roles, los cambios pueden tardar hasta 30 minutos en aplicarse.

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.
Con la identidad administrada y Azure RBAC, deja de ser preciso incluir direcciones URL de SAS.
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 aparecen en el contenedor de destino.

Encabezados

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.

El cuerpo de la solicitud POST

La dirección de la solicitud es POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
El cuerpo de la solicitud 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. Con la identidad administrada asignada por el sistema, se utiliza una dirección URL de cuenta de almacenamiento simple (sin SAS ni otras adiciones). El formato es https://<storage_account_name>.blob.core.windows.net/<container_name>.
Los campos prefix y suffix (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 targetUrl para cada idioma de destino debe ser único.

Importante

Si ya existe un archivo con el mismo nombre en el destino, el trabajo producirá errores. Al usar identidades administradas, no incluya una dirección URL de token de SAS con las solicitudes HTTP. Si lo hace, se producirá un error en las solicitudes.

Traducción de todos los documentos de un contenedor

Este cuerpo de solicitud de ejemplo hace referencia a un contenedor de origen para todos los documentos que deben traducirse a un idioma de destino.

Para obtener más información, consulteparámetros de solicitud.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>"
                    "language": "fr"
                }
            ]
        }
    ]
}

Traducción de un documento específico de un contenedor

Este cuerpo de solicitud de ejemplo hace referencia a un único documento de origen que se traducirá en dos idiomas de destino.

Importante

Además de los parámetros de solicitud anotados anteriormente, debe incluir "storageType": "File". De lo contrario, se supone que la dirección URL de origen está en el nivel de contenedor.

{
    "inputs": [
        {
            "storageType": "File",
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>/source-english.docx"
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-Spanish.docx"
                    "language": "es"
                },
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>/Target-German.docx",
                    "language": "de"
                }
            ]
        }
    ]
}

Traducción de todos los documentos de un contenedor mediante un glosario personalizado

Este cuerpo de solicitud de ejemplo hace referencia a un contenedor de origen para que todos los documentos se traduzcan a un idioma de destino mediante un glosario.

Para obtener más información, consulteparámetros de solicitud.

{
    "inputs": [
        {
            "source": {
                "sourceUrl": "https://<storage_account_name>.blob.core.windows.net/<source_container_name>",
                "filter": {
                    "prefix": "myfolder/"
                }
            },
            "targets": [
                {
                    "targetUrl": "https://<storage_account_name>.blob.core.windows.net/<target_container_name>",
                    "language": "es",
                    "glossaries": [
                        {
                            "glossaryUrl": "https://<storage_account_name>.blob.core.windows.net/<glossary_container_name>/en-es.xlf",
                            "format": "xliff"
                        }
                    ]
                }
            ]
        }
    ]
}

Magnífico. Acaba de aprender a habilitar y usar una identidad administrada asignada por el sistema. Con la identidad administrada para los recursos de Azure y Azure RBAC, ha concedido a Translator derechos de acceso específicos a su recurso de almacenamiento sin incluir tokens de SAS con las solicitudes HTTP.

Pasos siguientes

Inicio rápido: introducción a la traducción de documentos

Tutorial: acceder a Azure Storage desde una aplicación web mediante identidades administradas

Identidades administradas para la traducción de documentos

Requisitos previos

Asignaciones de identidad administrada

Habilitación de una identidad administrada asignada por el sistema.

Concesión de acceso a la cuenta de almacenamiento para el recurso de Translator

Solicitudes HTTP

Encabezados

El cuerpo de la solicitud POST

Traducción de todos los documentos de un contenedor

Traducción de un documento específico de un contenedor

Traducción de todos los documentos de un contenedor mediante un glosario personalizado

Pasos siguientes

Recursos adicionales