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 substituem o requisito de incluir tokens de assinatura de acesso compartilhado (SAS) com seus URLs de origem e destino.

Screenshot of managed identity flow (RBAC).

Você pode usar identidades gerenciadas para conceder acesso a qualquer recurso que dê 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á nenhum 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. Elas falharão. O uso de identidades gerenciadas substitui o requisito para incluir tokens de assinatura de acesso compartilhado (SAS) nas suas URLs de origem e destino.
Para usar identidades gerenciadas para operações de Tradução de Documentos, você deve criar seu recurso de Tradução em uma região geográfica específica do Azure, como no Leste dos EUA. Se a região dos recursos de Tradução 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 Standard S1 (pago conforme o uso) ou no plano de desconto por volume D3. ConsultePreços dos serviços de IA do Azure: Tradutor.

Pré-requisitos

Para começar, você precisa do seguinte:

Uma conta do Azure ativa - caso não tenha uma, você pode criar uma conta gratuita.
Um recurso de Tradução de serviço único (não um Serviço de IA do Azure de vários serviços) atribuído a uma região geográfica, como Oeste dos EUA. Para obter etapas detalhadas, consulteCriar um recurso de vários serviços.
Uma breve reconhecimento 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 Tradutor. Você também precisa criar contêineres para armazenar e organizar dados de blob em sua conta de armazenamento.
Se sua conta de armazenamento estiver atrás de um firewall, você deverá habilitar a seguinte configuração:
1. Vá para o portal do Azure e entre em sua conta do Azure.
2. Selecione a conta de armazenamento.
3. No grupo Segurança + sistema de rede no painel esquerdo, selecione Sistema de Rede.
4. Na guia Firewalls e redes virtuais, selecione Habilitado entre redes virtuais selecionadas e endereços IP.
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 o recurso Tradutor 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 esta conta de armazenamento está selecionada. Para obter mais informações sobre como gerenciar exceções, vejaConfigurar redes virtuais e firewalls do Armazenamento do Microsoft Azure.
9. Selecione Salvar.
  
  Observação
  
  Pode levar até 5 minutos para propagar as alterações de rede.
Embora o acesso à rede seja agora permitido, seu recurso de Tradução ainda não consegue acessar os dados em sua conta de armazenamento. Você precisa criar uma identidade gerenciada para e atribuir uma função específica de acesso ao seu recurso de Tradução.

Atribuições de identidade gerenciada

Há dois tipos de identidades gerenciadas: atribuídas pelo sistema e atribuídas pelo usuário. Atualmente, a tradução de documento dá suporte à identidade gerenciada atribuída pelo sistema:

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

Nas etapas a seguir, habilitaremos uma identidade gerenciada atribuída pelo sistema e concederemos a seu recurso Tradutor acesso limitado à sua conta de Armazenamento de Blobs do Azure.

Habilitar uma identidade gerenciada atribuída ao sistema

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

Vá para o portal do Azure e entre em sua conta do Azure.
Selecione o recurso Tradutor.
No grupo Gerenciamento de Recursos no painel esquerdo, selecione Identidade.
Na guia Atribuído pelo sistema, ative a alternância de Status.

Importante

A identidade gerenciada atribuída pelo usuário não atenderá aos requisitos para o cenário da conta de armazenamento de transcrição em lote. Habilite a identidade gerenciada atribuída pelo sistema.
Selecione Salvar.

Conceder acesso à conta de armazenamento para o recurso Tradutor

Importante

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

Vá para o portal do Azure e entre em 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 é aberta, escolha sua assinatura no menu suspenso e, em seguida, selecione + Adicionar atribuição de função.

Em seguida, atribua uma função de Colaborador de Armazenamento de Dados do Blob ao seu recurso de serviço de Tradução. A função Colaborador de Dados do Armazenamento de Blobs fornece ao Tradutor (representado pela identidade gerenciada atribuída pelo sistema) acesso de leitura, gravação e exclusão ao contêiner de blobs e aos dados. Na janela pop-up Adicionar atribuição de função, preencha os campos como segue, e selecione Salvar:

Campo	Valor
Escopo	*Armazenamento*.
Assinatura	*A assinatura associada ao recurso de armazenamento*.
Recurso	*O nome do recurso de armazenamento*.
Função	*Colaborador 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 aparecer, 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.

Solicitações HTTP

Uma solicitação de tradução em lote assíncrona é enviada para o ponto de extremidade de serviço de Tradução de Texto por meio de uma solicitação POST.
Com a identidade gerenciada e o Azure RBAC, você não precisa mais incluir URLs da SAS.
Se for bem-sucedido, o método POST retornará um código de resposta 202 Accepted e a solicitação em lote será criada pelo serviço.
Os documentos traduzidos são exibidos no contêiner de destino.

Cabeçalhos

Os seguintes cabeçalhos estão incluídos em cada solicitação de API de Tradução de Documento:

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

Corpo da solicitação HTTP

A URL da solicitação é 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 objeto inputs contém os ambos os endereços de contêiner sourceURL e o targetURL para os pares de idiomas de origem e de destino. Com a identidade gerenciada atribuída pelo sistema, você usará 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 campos prefix e suffix (opcionais) são usados para filtrar documentos no contêiner, incluindo pastas.
Um valor para o campo glossaries (opcional) é aplicado quando o documento está sendo traduzido.
O targetUrl para cada idioma de destino deve ser exclusivo.

Importante

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

Traduzir todos os documentos em um contêiner

Este corpo de solicitação de exemplo faz referencia a um contêiner de origem para que todos os documentos sejam traduzidos para um idioma de destino.

Para obter mais informações, vejaparâ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 traduzidos em dois idiomas de destino.

Importante

Além dos parâmetros de solicitação observados anteriormente, você deve incluir "storageType": "File". Caso contrário, supõe-se que a 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 que todos os documentos sejam traduzidos de um idioma de destino usando um glossário.

Para obter mais informações, vejaparâ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"
                        }
                    ]
                }
            ]
        }
    ]
}

Ótimo! Você acabou de aprender a habilitar e usar uma identidade gerenciada atribuída pelo sistema. Com a identidade gerenciada para recursos do Azure e o Azure RBAC, você permitiu ao Tradutor direitos de acesso específicos no recurso de armazenamento sem incluir tokens SAS nas solicitações HTTP.

Próximas etapas

Início Rápido: Introdução à Tradução de Documento

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

Identidades gerenciadas para Tradução de Documentos

Pré-requisitos

Atribuições de identidade gerenciada

Habilitar uma identidade gerenciada atribuída ao sistema

Conceder acesso à conta de armazenamento para o recurso Tradutor

Solicitações HTTP

Cabeçalhos

Corpo da solicitação HTTP

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óximas etapas

Recursos adicionais