Identidades gerenciadas para tradução de documentos

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.

• 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 existem custos adicionais para usar identidades geridas no Azure.

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, consulte Criar um recurso de serviços de IA do Azure.

• 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, consulte Configurar 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.

1. Aceda ao portal do Azure e inicie sessão com a sua conta do Azure.

2. Selecione o recurso Tradutor.

3. No grupo Gerenciamento de Recursos no painel esquerdo, selecione Identidade.

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

5. Selecione Guardar.

Conceder acesso à conta de armazenamento para o recurso do Translator

1. Aceda ao portal do Azure e inicie sessão com a sua conta do Azure.

2. Selecione o recurso Tradutor.

3. No grupo Gerenciamento de Recursos no painel esquerdo, selecione Identidade.

4. Em Permissões , selecione Atribuições de função do Azure:

   

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

   

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

   

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

   

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

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 glossaries campo (opcional) é aplicado quando o documento está sendo traduzido.
• O targetUrl para cada língua de chegada deve ser único.

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, consulte parâ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.

{
    "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, consulte parâ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