Identidades gerenciadas para tradução de documentos

Artigo
02/12/2024

As identidades gerenciadas para recursos do Azure são entidades de serviço que criam uma identidade do Microsoft Entra e permissões específicas para recursos gerenciados do Azure. As identidades gerenciadas são uma maneira mais segura de conceder acesso aos dados de armazenamento e substituir o requisito de incluir tokens de assinatura de acesso compartilhado (SAS) com suas URLs de origem e de destino.

Screenshot of managed identity flow (RBAC).

Você pode usar identidades gerenciadas para conceder acesso a qualquer recurso que ofereça suporte à autenticação do Microsoft Entra, incluindo seus próprios aplicativos.
Para conceder acesso a um recurso do Azure, atribua uma função do Azure a uma identidade gerenciada usando o controle de acesso baseado em função do Azure (Azure RBAC).
Não há custo adicional para usar identidades gerenciadas no Azure.

Importante

Ao usar identidades gerenciadas, não inclua uma URL de token SAS com suas solicitações HTTP — suas solicitações falharão. O uso de identidades gerenciadas substitui o requisito de incluir tokens de assinatura de acesso compartilhado (SAS) com suas URLs de origem e de destino.
Para usar identidades gerenciadas para operações de Tradução de Documentos, você deve criar seu recurso Translator em uma região geográfica específica do Azure, como East US. Se a região de recursos do Tradutor estiver definida como Global, você não poderá usar a identidade gerenciada para a Tradução de Documentos. Você ainda pode usar tokens de Assinatura de Acesso Compartilhado (SAS) para Tradução de Documentos.
A Tradução de Documentos só está disponível no Plano de Serviço Padrão S1 (Pay-as-you-go) ou no Plano de Desconto por Volume D3. ConsultePreços dos serviços de IA do Azure — Tradutor.

Pré-requisitos

Para começar, precisa do seguinte:

Uma conta ativa do Azure — se não tiver uma, pode criar uma conta gratuita.
Um recurso de Tradutor de serviço único (não um recurso de serviços de IA do Azure multisserviços) atribuído a uma região geográfica como West US. Para obter etapas detalhadas, consulteCriar um recurso multisserviço.
Uma breve compreensão do controle de acesso baseado em função do Azure (Azure RBAC) usando o portal do Azure.
Uma conta de Armazenamento de Blobs do Azure na mesma região que o recurso do Translator. Você também precisa criar contêineres para armazenar e organizar seus dados de blob em sua conta de armazenamento.
Se sua conta de armazenamento estiver protegida por um firewall, você deverá habilitar a seguinte configuração:
1. Aceda ao portal do Azure e inicie sessão com a sua conta do Azure.
2. Selecione a conta de armazenamento.
3. No grupo Segurança + rede no painel esquerdo, selecione Rede.
4. Na guia Firewalls e redes virtuais, selecione Habilitado em redes virtuais e endereços IP selecionados.
5. Desmarque todas as caixas de seleção.
6. Verifique se o roteamento de rede da Microsoft está selecionado.
7. Na seção Instâncias de recurso, selecione Microsoft.CognitiveServices/accounts como o tipo de recurso e selecione seu recurso Translator como o nome da instância.
8. Verifique se a caixa Permitir que os serviços do Azure na lista de serviços confiáveis acessem essa conta de armazenamento está marcada. Para obter mais informações sobre como gerenciar exceções, consulteConfigurar firewalls de armazenamento do Azure e redes virtuais.
9. Selecione Guardar.
  
  Nota
  
  Pode levar até 5 minutos para que as alterações de rede se propaguem.
Embora o acesso à rede agora seja permitido, o recurso do Translator ainda não consegue acessar os dados na sua conta de armazenamento. Você precisa criar uma identidade gerenciada e atribuir uma função de acesso específica ao seu recurso do Translator.

Atribuições de identidade gerenciadas

Existem dois tipos de identidades gerenciadas: atribuídas pelo sistema e atribuídas pelo usuário. Atualmente, a Tradução de Documentos suporta a identidade gerenciada atribuída pelo sistema:

Uma identidade gerenciada atribuída ao sistema é habilitada diretamente em uma instância de serviço. Ele não está habilitado por padrão; Você deve ir para o seu recurso e atualizar a configuração de identidade.
A identidade gerenciada atribuída ao sistema está vinculada ao seu recurso durante todo o seu ciclo de vida. Se você excluir seu recurso, a identidade gerenciada também será excluída.

Nas etapas a seguir, habilitamos uma identidade gerenciada atribuída pelo sistema e concedemos ao seu recurso do Translator acesso limitado à sua conta de Armazenamento de Blob do Azure.

Habilitar uma identidade gerenciada atribuída ao sistema

Você deve conceder ao recurso do Translator acesso à sua conta de armazenamento antes que ele possa criar, ler ou excluir blobs. Depois de habilitar o recurso Translator com uma identidade gerenciada atribuída ao sistema, você pode usar o controle de acesso baseado em função do Azure (Azure RBAC), para conceder ao Translator acesso aos contêineres de armazenamento do Azure.

Aceda ao portal do Azure e inicie sessão com a sua conta do Azure.
Selecione o recurso Tradutor.
No grupo Gerenciamento de Recursos no painel esquerdo, selecione Identidade.
Na guia Sistema atribuído, ative a alternância Status.

Importante

A identidade gerenciada atribuída ao usuário não atenderá aos requisitos para o cenário de conta de armazenamento de transcrição em lote. Certifique-se de que ativa a identidade gerida atribuída pelo sistema.
Selecione Guardar.

Conceder acesso à conta de armazenamento para o recurso do Translator

Importante

Para atribuir uma função de identidade gerenciada atribuída ao sistema, você precisa de permissões Microsoft.Authorization/roleAssignments/write, como Proprietário ou Administrador de Acesso de Usuário no escopo de armazenamento do recurso de armazenamento.

Aceda ao portal do Azure e inicie sessão com a sua conta do Azure.
Selecione o recurso Tradutor.
No grupo Gerenciamento de Recursos no painel esquerdo, selecione Identidade.
Em Permissões , selecione Atribuições de função do Azure:
Na página Atribuições de função do Azure que foi aberta, escolha sua assinatura no menu suspenso e selecione + Adicionar atribuição de função.

Em seguida, atribua uma função de Colaborador de Dados de Blob de Armazenamento ao seu recurso de serviço de Tradutor. A função de Colaborador de Dados de Blob de Armazenamento dá ao Tradutor (representado pela identidade gerenciada atribuída pelo sistema) acesso de leitura, gravação e exclusão ao contêiner de blob e aos dados. Na janela pop-up Adicionar atribuição de função, preencha os campos da seguinte forma e selecione Guardar:

Campo	Valor
Scope	*Armazenamento*.
Subscrição	*A subscrição associada ao seu recurso* de armazenamento.
Recurso	*O nome do recurso* de armazenamento.
Função	*Contribuidor* de dados de Blob de armazenamento.

Screenshot: add role assignments page in the Azure portal.

Depois que a mensagem de confirmação Atribuição de função adicionada for exibida, atualize a página para ver a atribuição de função adicionada.
Se você não vir a nova atribuição de função imediatamente, aguarde e tente atualizar a página novamente. Quando você atribui ou remove atribuições de função, pode levar até 30 minutos para que as alterações entrem em vigor.

Pedidos HTTP

Uma solicitação de tradução em lote assíncrona é enviada ao ponto de extremidade do serviço Translator por meio de uma solicitação POST.
Com a identidade gerenciada e Azure RBACo , você não precisa mais incluir URLs SAS.
Se for bem-sucedido, o método POST retorna um código de 202 Accepted resposta e o serviço cria uma solicitação em lote.
Os documentos traduzidos aparecem no contêiner de destino.

Cabeçalhos

Os cabeçalhos a seguir estão incluídos em cada solicitação da API de Tradução de Documentos:

Cabeçalho HTTP	Description
Ocp-Apim-Subscription-Key	Obrigatório: o valor é a chave do Azure para o seu Tradutor ou recurso de serviços de IA do Azure.
Tipo de Conteúdo	Obrigatório: especifica o tipo de conteúdo da carga útil. Os valores aceitos são application/json ou charset=UTF-8.

Organismo de pedido POST

O URL do pedido é POST https://<NAME-OF-YOUR-RESOURCE>.cognitiveservices.azure.com/translator/text/batch/v1.1/batches.
O corpo da solicitação é um objeto JSON chamado inputs.
O inputs objeto contém endereços de targetURL contêiner sourceURL para seus pares de idiomas de origem e de destino. Com a identidade gerenciada atribuída ao sistema, você usa uma URL de conta de armazenamento simples (sem SAS ou outras adições). O formato é https://<storage_account_name>.blob.core.windows.net/<container_name>.
Os prefix campos e suffix (opcional) são usados para filtrar documentos no contêiner, incluindo pastas.
Um valor para o campo (opcional) é aplicado quando o glossaries documento está sendo traduzido.
O targetUrl para cada língua de chegada deve ser único.

Importante

Se já existir um arquivo com o mesmo nome no destino, o trabalho falhará. Ao usar identidades gerenciadas, não inclua uma URL de token SAS com suas solicitações HTTP. Se o fizer, os seus pedidos falharão.

Traduzir todos os documentos em um contêiner

Este corpo de solicitação de exemplo faz referência a um contêiner de origem para todos os documentos a serem traduzidos para um idioma de destino.

Para obter mais informações, consulteparâmetros de solicitação.

{
    "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"
                }
            ]
        }
    ]
}

Traduzir um documento específico em um contêiner

Este corpo de solicitação de exemplo faz referência a um único documento de origem a ser traduzido em dois idiomas de destino.

Importante

Além dos parâmetros de solicitação observados anteriormente, você deve incluir "storageType": "File". Caso contrário, presume-se que o URL de origem esteja no nível do contêiner.

{
    "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"
                }
            ]
        }
    ]
}

Traduzir todos os documentos em um contêiner usando um glossário personalizado

Este corpo de solicitação de exemplo faz referência a um contêiner de origem para todos os documentos a serem traduzidos para um idioma de destino usando um glossário.

Para obter mais informações, consulteparâmetros de solicitação.

{
    "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"
                        }
                    ]
                }
            ]
        }
    ]
}

Excelente! Você acabou de aprender como habilitar e usar uma identidade gerenciada atribuída ao sistema. Com a identidade gerenciada para Recursos do Azure e Azure RBAC, você concedeu direitos de acesso específicos do Translator ao seu recurso de armazenamento sem incluir tokens SAS com suas solicitações HTTP.

Próximos passos

Guia de início rápido: introdução à tradução de documentos

Tutorial: Acessar o Armazenamento do Azure a partir de um aplicativo Web usando identidades gerenciadas

Identidades gerenciadas para tradução de documentos

Pré-requisitos

Atribuições de identidade gerenciadas

Habilitar uma identidade gerenciada atribuída ao sistema

Conceder acesso à conta de armazenamento para o recurso do Translator

Pedidos HTTP

Cabeçalhos

Organismo de pedido POST

Traduzir todos os documentos em um contêiner

Traduzir um documento específico em um contêiner

Traduzir todos os documentos em um contêiner usando um glossário personalizado

Próximos passos

Recursos adicionais