Tutorial: Autenticar para APIs

Artigo
11/13/2024

Neste tutorial, vai aprender a autenticar-se para as APIs do plano de dados do Microsoft Purview. Qualquer pessoa que pretenda submeter dados para o Microsoft Purview, incluir o Microsoft Purview como parte de um processo automatizado ou criar a sua própria experiência de utilizador no Microsoft Purview pode utilizar as APIs para o fazer.

Pré-requisitos

Para começar, tem de ter uma conta do Microsoft Purview existente. Se não tiver um catálogo, veja o início rápido para criar uma conta do Microsoft Purview.

Criar um principal de serviço (aplicação)

Para um cliente de API aceder às APIs do plano de dados do Microsoft Purview, o cliente tem de ter um principal de serviço (aplicação) e uma identidade que o Microsoft Purview reconheça e esteja configurada para confiar. Quando fizer chamadas à API, a identidade desse principal de serviço será utilizada para autorização.

Os clientes que utilizaram principais de serviço (IDs de aplicação) existentes tiveram uma taxa elevada de falhas. Por conseguinte, recomendamos a criação de um novo principal de serviço para chamar APIs.

Para criar um novo principal de serviço:

Entre no portal do Azure.
No portal, procure e selecione Microsoft Entra ID.
Na página Microsoft Entra ID, selecione Registros de aplicativo no painel esquerdo.
Selecione Novo registro.
Na página Registar uma aplicação :
1. Introduza um Nome para a aplicação (o nome do principal de serviço).
2. Para Quem pode utilizar esta aplicação ou aceder a esta API?, selecione os tipos de contas de utilizador que espera utilizar esta API.
  
  Dica
  
  Se espera que apenas os utilizadores do seu inquilino do Microsoft Entra ID atual utilizem a API REST, selecione Contas apenas neste diretório organizacional (<apenas o nome> do inquilino – Inquilino único). Caso contrário, considere as outras opções.
3. Para URI de Redirecionamento (opcional),selecione Web e introduza um valor. Este valor não tem de ser um ponto final válido. https://exampleURI.com É para já.
4. Selecione Registrar.
Na nova página do principal de serviço, copie os valores do Nome a apresentar e do ID da Aplicação (cliente) para guardar mais tarde.

O ID da aplicação é o client_id valor no código de exemplo.

Para utilizar o principal de serviço (aplicação), precisa de saber a palavra-passe do principal de serviço que pode ser encontrada por:

No portal do Azure, procure e selecione Microsoft Entra ID e, em seguida, selecione Registros de aplicativo no painel esquerdo.
Selecione o principal de serviço (aplicação) na lista.
Selecione Certificados & segredos no painel esquerdo.
Selecione Novo segredo do cliente.
Na página Adicionar um segredo do cliente , introduza uma Descrição, selecione um tempo de expiração em Expira e, em seguida, selecione Adicionar.

Na página Segredos do cliente , a cadeia na coluna Valor do seu novo segredo é a sua palavra-passe. Guarde este valor.

Configurar a autenticação com o principal de serviço

Assim que o novo principal de serviço for criado, terá de atribuir as funções de plano de dados da sua conta purview ao principal de serviço criado acima. Siga os passos abaixo para atribuir a função correta para estabelecer confiança entre o principal de serviço e a conta do Purview:

Navegue para o portal de governação do Microsoft Purview.
Selecione o Mapa de Dados no menu esquerdo.
Selecione Coleções.
Selecione a coleção de raiz no menu coleções. Esta será a coleção principal na lista e terá o mesmo nome que a sua conta do Microsoft Purview.

Observação

Também pode atribuir a permissão do principal de serviço a sub-coleções, em vez da coleção de raiz. No entanto, todas as APIs serão confinadas a essa coleção (e subcotações que herdam permissões) e os utilizadores que tentarem chamar a API para outra coleção receberão erros.
Selecione o separador Atribuições de funções .
Atribua as seguintes funções ao principal de serviço criado anteriormente para aceder a vários planos de dados no Microsoft Purview. Para obter passos detalhados, veja Atribuir funções do Azure com o portal de governação do Microsoft Purview.
- Função de Curador de Dados para aceder ao plano de Dados do Catálogo.
- Função de Administrador de Origem de Dados para aceder ao plano Detetar Dados.
- Coleção Administração função para aceder ao Plano de Dados da Conta e ao Plano de Dados de Política de Metadados.
- Função autor de políticas para aceder à API de políticas de DevOps
Observação

Apenas os membros da função Administração coleção podem atribuir funções de plano de dados no Microsoft Purview. Para obter mais informações sobre as funções do Microsoft Purview, consulte Controle de Acesso no Microsoft Purview.

Obter token

Pode enviar um pedido POST para o seguinte URL para obter o token de acesso.

https://login.microsoftonline.com/{your-tenant-id}/oauth2/token

Pode encontrar o ID do Inquilino ao procurar Propriedades do Inquilino no portal do Azure. O ID estará disponível na página de propriedades do inquilino.

Os parâmetros seguintes têm de ser transmitidos para o URL acima:

client_id: ID de cliente da aplicação registada no Microsoft Entra ID e atribuído a uma função de plano de dados para a conta do Microsoft Purview.
client_secret: segredo do cliente criado para a aplicação acima.
grant_type: Deve ser "client_credentials".
recurso: "https://purview.azure.net"

Eis um pedido POST de exemplo no PowerShell:

$tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"

$url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
$params = @{ client_id = "a1234bcd-5678-9012-abcd-abcd1234abcd"; client_secret = "abcd~a1234bcd56789012abcdabcd1234abcd"; grant_type = "client_credentials"; resource = ‘https://purview.azure.net’ }

Invoke-WebRequest $url -Method Post -Body $params -UseBasicParsing | ConvertFrom-Json

Token de resposta de exemplo:

    {
        "token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "expires_on": "1621038348",
        "not_before": "1620951648",
        "resource": "https://purview.azure.net",
        "access_token": "<<access token>>"
    }

Dica

Se receber uma mensagem de erro a indicar: O resgate de tokens de várias origens é permitido apenas para o tipo de cliente "Aplicação de Página Única".

Verifique os cabeçalhos do pedido e confirme que o pedido não contém o cabeçalho "origem".
Confirme que o URI de redirecionamento está definido como Web no principal de serviço.
Certifique-se de que o software está atualizado para a aplicação que está a utilizar para enviar o seu pedido POST.

Utilize o token de acesso acima para chamar as APIs do Plano de dados.

Próximas etapas

Gerir origens de dados apIs REST do Plano de Dados do Microsoft Purview

Partilhar via