Autorização em pontos de extremidade em lote

Os pontos de extremidade em lotes dão suporte à autenticação do Microsoft Entra ou aad_token. Isso significa que, para invocar um ponto de extremidade em lotes, o usuário deve apresentar um token de autenticação válido do Microsoft Entra para o URI do ponto de extremidade em lotes. A autorização é aplicada no nível do ponto de extremidade. O artigo a seguir explica como interagir corretamente com pontos de extremidade em lote e os requisitos de segurança relacionados.

Como funciona a autorização

Para invocar um ponto de extremidade em lotes, o usuário deve apresentar um token válido do Microsoft Entra representando uma entidade de segurança. Essa entidade de segurança pode ser uma entidade de usuário ou uma entidade de serviço. De qualquer forma, quando um ponto de extremidade é invocado, um trabalho de implantação em lote é criado na identidade associada ao token. Ela precisa das seguintes permissões para criar um trabalho com sucesso:

• Ler pontos de extremidade/implantações em lote.
• Criar trabalhos em implantações/pontos de extremidade de inferência em lote.
• Criar experimentos/execuções.
• Ler e gravar em armazenamentos de dados.
• Lista os segredos de um armazenamento de dados.

Confira Configurar o RBAC para invocação de ponto de extremidade em lote para obter uma lista detalhada de permissões RBAC.

Importante

A identidade usada para chamar um ponto de extremidade em lote não poderá ser usada para ler os dados subjacentes dependendo da configuração do armazenamento de dados. Consulte Configurar clusters de cálculo para acesso aos dados para obter mais detalhes.

Como executar trabalhos usando diferentes tipos de credenciais

Os seguintes exemplos mostram diferentes maneiras de iniciar trabalhos de implantação em lote com diferentes tipos de credenciais:

Importante

Durante o trabalho em workspaces habilitados para link privado, os pontos de extremidade em lote não podem ser invocados por meio da interface do usuário no Estúdio do Azure Machine Learning. Use a CLI v2 do Azure Machine Learning como alternativa para a criação de trabalhos.

Pré-requisitos

• Este exemplo pressupõe que você tenha um modelo implantado corretamente como um ponto de extremidade em lote. Particularmente, estamos usando o classificador de condição cardíaca criado no tutorial Usando modelos do MLflow em implantações em lote.

Executar trabalhos com as credenciais do usuário

Nesse caso, queremos executar um ponto de extremidade em lote usando a identidade do usuário conectado no momento. Siga estas etapas:

CLI do Azure

1. Use a CLI do Azure para entrar usando a autenticação de código de dispositivo ou interativa:

   az login
   

2. Depois da autenticação, use o seguinte comando para executar um trabalho de implantação em lote:

   az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                               --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci
   

Python

1. Use o SDK do Azure Machine Learning para Python para fazer logon com a autenticação interativa ou de dispositivo:

   from azure.ai.ml import MLClient
   from azure.identity import InteractiveAzureCredentials
   
   subscription_id = "<subscription>"
   resource_group = "<resource-group>"
   workspace = "<workspace>"
   
   ml_client = MLClient(InteractiveAzureCredentials(), subscription_id, resource_group, workspace)
   

2. Depois da autenticação, use o seguinte comando para executar um trabalho de implantação em lote:

   job = ml_client.batch_endpoints.invoke(
           endpoint_name,
           input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci")
       )
   

REST

Ao trabalhar com REST, recomendamos invocar pontos de extremidade em lote usando uma entidade de serviço. No entanto, se você quiser testar uma implantação específica usando REST com suas próprias credenciais, faça isso gerando um token do Microsoft Entra para sua conta. Siga estas etapas:

1. A maneira mais simples de obter um token válido para sua conta de usuário é usar a CLI do Azure. No console, execute o seguinte comando:

   az account get-access-token --resource https://ml.azure.com \
                               --query "accessToken" \
                               --output tsv
   

2. Anote a saída gerada.

3. Depois de autenticado, faça uma solicitação para o URI de invocação substituindo <TOKEN> pelo obtido anteriormente.

   Solicitação:

   POST jobs HTTP/1.1
   Host: <ENDPOINT_URI>
   Authorization: Bearer <TOKEN>
   Content-Type: application/json
   

   Corpo:

   {
       "properties": {
           "InputData": {
               "mnistinput": {
                   "JobInputType" : "UriFolder",
                   "Uri":  "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci"
               }
           }
       }
   }
   

Executar trabalhos usando uma entidade de serviço

Neste caso, queremos executar um ponto de extremidade em lotes usando uma entidade de serviço já criada no Microsoft Entra ID. Para concluir a autenticação, você precisará criar um segredo para executar a autenticação. Siga estas etapas:

CLI do Azure

1. Crie um segredo a ser usado para autenticação, conforme explicado na Opção 3: Criar um novo segredo do cliente.

2. Para autenticar usando uma entidade de serviço, use o comando a seguir. Para saber mais, confira Entrar com a CLI do Azure.

   az login --service-principal \
            --tenant <tenant> \
            -u <app-id> \
            -p <password-or-cert> 
   

3. Depois da autenticação, use o seguinte comando para executar um trabalho de implantação em lote:

   az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                               --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/
   

Python

1. Crie um segredo a ser usado para autenticação, conforme explicado na Opção 3: criar um novo segredo do cliente.

2. Para autenticar-se usando uma entidade de serviço, indique a ID do locatário, a ID do cliente e o segredo do cliente da entidade de serviço usando variáveis de ambiente, conforme demonstrado:

   from azure.ai.ml import MLClient
   from azure.identity import EnvironmentCredential
   
   os.environ["AZURE_TENANT_ID"] = "<TENANT_ID>"
   os.environ["AZURE_CLIENT_ID"] = "<CLIENT_ID>"
   os.environ["AZURE_CLIENT_SECRET"] = "<CLIENT_SECRET>"
   
   subscription_id = "<subscription>"
   resource_group = "<resource-group>"
   workspace = "<workspace>"
   
   ml_client = MLClient(EnvironmentCredential(), subscription_id, resource_group, workspace)
   

3. Depois da autenticação, use o seguinte comando para executar um trabalho de implantação em lote:

   job = ml_client.batch_endpoints.invoke(
           endpoint_name,
           input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci")
       )
   

REST

1. Crie um segredo a ser usado para autenticação, conforme explicado na Opção 3: criar um novo segredo do cliente.

2. Use o serviço de logon do Azure para obter um token de autorização. Os tokens de autorização são emitidos para um escopo específico. O tipo de recurso do Azure Machine Learning é https://ml.azure.com. A solicitação deve ser semelhante ao seguinte:

   Solicitação:

   POST /{TENANT_ID}/oauth2/token HTTP/1.1
   Host: login.microsoftonline.com
   

   Corpo:

   grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&resource=https://ml.azure.com
   

   Importante

   Observe que o escopo de recurso para invocar pontos de extremidade em lote (https://ml.azure.com) é diferente do escopo de recurso usado para gerenciá-los. Todas as APIs de gerenciamento no Azure usam o escopo de recurso https://management.azure.com, incluindo o Azure Machine Learning.

3. Depois da autenticação, use a consulta para executar um trabalho de implantação em lote:

   Solicitação:

   POST jobs HTTP/1.1
   Host: <ENDPOINT_URI>
   Authorization: Bearer <TOKEN>
   Content-Type: application/json
   

   Corpo:

   {
       "properties": {
           "InputData": {
               "mnistinput": {
                   "JobInputType" : "UriFolder",
                   "Uri":  "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci"
               }
           }
       }
   }
   

Executar trabalhos usando uma identidade gerenciada

Você pode usar identidades gerenciadas para invocar o ponto de extremidade e as implantações em lote. Observe que essa identidade de gerenciamento não pertence ao ponto de extremidade em lotes, mas é a identidade usada para executar o ponto de extremidade e, portanto, criar um trabalho em lotes. As identidades atribuídas pelo usuário e pelo sistema podem ser usadas nesse cenário.

CLI do Azure

Nos recursos configurados para identidades gerenciadas em recursos do Azure, você pode entrar usando a identidade gerenciada. A entrada com a identidade do recurso é feito por meio do sinalizador --identity. Para saber mais, confira Entrar com a CLI do Azure.

az login --identity

Depois da autenticação, use o seguinte comando para executar um trabalho de implantação em lote:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci

Python

Nos recursos configurados para identidades gerenciadas em recursos do Azure, você pode entrar usando a identidade gerenciada. Use a ID do recurso e o objeto ManagedIdentityCredential, conforme demonstrado no seguinte exemplo:

from azure.ai.ml import MLClient
from azure.identity import ManagedIdentityCredential

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"
resource_id = "<resource-id>"

ml_client = MLClient(ManagedIdentityCredential(resource_id), subscription_id, resource_group, workspace)

Depois da autenticação, use o seguinte comando para executar um trabalho de implantação em lote:

job = ml_client.batch_endpoints.invoke(
        endpoint_name,
        input=Input(path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci")
    )

REST

Você pode usar a API REST do Azure Machine Learning para iniciar um trabalho de pontos de extremidade em lote usando uma identidade gerenciada. As etapas variam dependendo do serviço subjacente que está sendo usado. Alguns exemplos incluem, entre outros:

• Identidade Gerenciada para Azure Data Factory
• Como usar identidades gerenciadas para o Serviço de Aplicativo e o Azure Functions.
• Como usar identidades gerenciadas para recursos do Azure em uma VM do Azure para adquirir um token de acesso.

Você também pode usar a CLI do Azure para obter um token de autenticação para a identidade gerenciada e passá-lo para o URI de pontos de extremidade em lote.

Configurar o RBAC para invocação de pontos de extremidade em lote

Os pontos de extremidade em lote expõem uma API durável que os consumidores podem usar para gerar trabalhos. O invocador solicita a permissão adequada para gerar esses trabalhos. É possível usar uma das funções de segurança internas ou criar uma função personalizada para as finalidades.

Para invocar um ponto de extremidade em lote, você precisa das seguintes ações explícitas concedidas à identidade usada para invocar os pontos de extremidade. Confira Etapas para atribuir uma função do Azure a fim de obter instruções sobre como atribuí-las.

"actions": [
    "Microsoft.MachineLearningServices/workspaces/read",
    "Microsoft.MachineLearningServices/workspaces/data/versions/write",
    "Microsoft.MachineLearningServices/workspaces/datasets/registered/read",
    "Microsoft.MachineLearningServices/workspaces/datasets/registered/write",
    "Microsoft.MachineLearningServices/workspaces/datasets/unregistered/read",
    "Microsoft.MachineLearningServices/workspaces/datasets/unregistered/write",
    "Microsoft.MachineLearningServices/workspaces/datastores/read",
    "Microsoft.MachineLearningServices/workspaces/datastores/write",
    "Microsoft.MachineLearningServices/workspaces/datastores/listsecrets/action",
    "Microsoft.MachineLearningServices/workspaces/listStorageAccountKeys/action",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/read",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/write",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/deployments/read",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/deployments/write",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/deployments/jobs/write",
    "Microsoft.MachineLearningServices/workspaces/batchEndpoints/jobs/write",
    "Microsoft.MachineLearningServices/workspaces/computes/read",
    "Microsoft.MachineLearningServices/workspaces/computes/listKeys/action",
    "Microsoft.MachineLearningServices/workspaces/metadata/secrets/read",
    "Microsoft.MachineLearningServices/workspaces/metadata/snapshots/read",
    "Microsoft.MachineLearningServices/workspaces/metadata/artifacts/read",
    "Microsoft.MachineLearningServices/workspaces/metadata/artifacts/write",
    "Microsoft.MachineLearningServices/workspaces/experiments/read",
    "Microsoft.MachineLearningServices/workspaces/experiments/runs/submit/action",
    "Microsoft.MachineLearningServices/workspaces/experiments/runs/read",
    "Microsoft.MachineLearningServices/workspaces/experiments/runs/write",
    "Microsoft.MachineLearningServices/workspaces/metrics/resource/write",
    "Microsoft.MachineLearningServices/workspaces/modules/read",
    "Microsoft.MachineLearningServices/workspaces/models/read",
    "Microsoft.MachineLearningServices/workspaces/endpoints/pipelines/read",
    "Microsoft.MachineLearningServices/workspaces/endpoints/pipelines/write",
    "Microsoft.MachineLearningServices/workspaces/environments/read",
    "Microsoft.MachineLearningServices/workspaces/environments/write",
    "Microsoft.MachineLearningServices/workspaces/environments/build/action",
    "Microsoft.MachineLearningServices/workspaces/environments/readSecrets/action"
]

Configurar clusters de cálculo para acesso aos dados

Os pontos de extremidade em lote garantem que somente usuários autorizados possam invocar implantações em lote e gerar trabalhos. No entanto, dependendo de como os dados de entrada estão configurados, outras credenciais podem ser usadas para ler os dados subjacentes. Use a tabela a seguir para entender as credenciais usadas:

Tipo de entrada de dados	Credencial armazenada	Credenciais usadas	Acesso concedido por
Armazenamento de dados	Sim	Credenciais do armazenamento de dados no workspace	Chave de acesso ou SAS
Ativos de dados	Sim	Credenciais do armazenamento de dados no workspace	Chave de Acesso ou SAS
Armazenamento de dados	Não	Identidade do trabalho + identidade gerenciada do cluster de cálculo	RBAC
Ativos de dados	Não	Identidade do trabalho + identidade gerenciada do cluster de cálculo	RBAC
Armazenamento de Blobs do Azure	Não se aplica	Identidade do trabalho + identidade gerenciada do cluster de cálculo	RBAC
Azure Data Lake Storage Gen1	Não se aplica	Identidade do trabalho + identidade gerenciada do cluster de cálculo	POSIX
Azure Data Lake Storage Gen2	Não se aplica	Identidade do trabalho + identidade gerenciada do cluster de cálculo	POSIX e RBAC

Para esses itens na tabela em que a identidade do trabalho + identidade gerenciada do cluster de cálculo é exibida, a identidade gerenciada do cluster de cálculo é usada para montar e configurar contas de armazenamento. No entanto, a identidade do trabalho ainda é usada para ler os dados subjacentes, permitindo que você obtenha um controle de acesso granular. Isso significa que, para ler os dados de armazenamento, a identidade gerenciada do cluster de cálculo em que a implantação está sendo executada deve ter, pelo menos, acesso do Leitor de Dados do Blob de Armazenamento à conta de armazenamento.

Para configurar o cluster de cálculo para acesso aos dados, siga estas etapas:

1. Acesse o Estúdio do Azure Machine Learning.

2. Navegue até Computaçãoe, em seguida, Clusters de cálculo e selecione o cluster de cálculo que sua implantação está usando.

3. Atribua uma identidade gerenciada ao cluster de cálculo:

   1. Na seçãoIdentidade gerenciada, verifique se a computação tem uma identidade gerenciada atribuída. Se ela não tiver, selecione a opção Editar.

   2. Selecione Atribuir uma identidade gerenciada e a configure conforme necessário. Você pode usar uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário. Se estiver usando uma identidade gerenciada atribuída pelo sistema, ela será nomeada como "[nome do workspace]/computações/[nome do cluster de cálculo]".

   3. Salve as alterações.

   

4. Acesse o portal do Azure e navegue até a conta de armazenamento associada onde os dados estão localizados. Se sua entrada de dados for um Ativo de Dados ou um Armazenamento de Dados, procure a conta de armazenamento em que esses ativos foram colocados.

5. Atribua o nível de acesso ao Leitor de Dados do Blob de Armazenamento na conta de armazenamento:

   1. Vá para a seção Controle de acesso (IAM).

   2. Selecione a guia Atribuição de função e clique em Adicionar> Atribuição de função.

   3. Procure a função chamada Leitor de Dados do Blob de Armazenamento, selecione-a e clique em Avançar.

   4. Clique em Selecionar membros.

   5. Procure a identidade gerenciada que você criou. Se estiver usando uma identidade gerenciada atribuída pelo sistema, ela será nomeada como "[nome do workspace]/computações/[nome do cluster de cálculo]".

   6. Adicione a conta e conclua o assistente.

   

6. O ponto de extremidade está pronto para receber trabalhos e dados de entrada da conta de armazenamento selecionada.

Próximas etapas

• Isolamento de rede em pontos de extremidade em lote
• Como invocar pontos de extremidade em lote de eventos da Grade de Eventos no armazenamento.
• Como invocar pontos de extremidade em lote do Azure Data Factory.