Tutorial: usar as APIs REST

Artigo
08/23/2023

Neste tutorial, você aprenderá a usar as APIs REST do plano de dados do Microsoft Purview. Quem quiser enviar dados ao Microsoft Purview, incluir o Microsoft Purview como parte de um processo automatizado ou criar sua própria experiência de usuário no Microsoft Purview pode usar as APIs REST para fazê-lo.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

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

Criar uma entidade de serviço (aplicativo)

Para que um cliente de API REST acesse as APIs do plano de dados do Microsoft Purview, o cliente deve ter uma entidade de serviço (aplicativo) e uma identidade que o Microsoft Purview reconhece e está configurada para confiar. Ao fazer chamadas de API REST, a identidade da entidade de serviço será usada para autorização.

Os clientes que usaram as entidades de serviço existentes (IDs do aplicativo) tiveram uma alta taxa de falha. Portanto, recomendamos criar uma nova entidade de serviço para chamar APIs.

Para criar uma nova entidade de serviço:

Entre no portal do Azure.
No portal, pesquise e selecione Azure Active Directory.
Na página do Azure Active Directory, selecione Registros de aplicativo no painel esquerdo.
Selecione Novo registro.
Na página Registrar um aplicativo :
1. Insira um Nome para o aplicativo (o nome da entidade de serviço).
2. Selecione Contas somente neste diretório organizacional (<somente o nome> do locatário – locatário único).
3. Para URI de redirecionamento (opcional), selecione Web e insira um valor. Esse valor não precisa ser um ponto de extremidade válido. https://exampleURI.com vai fazer.
4. Selecione Registrar.
Na nova página da entidade de serviço, copie os valores do nome de exibição e da ID do aplicativo (cliente) para salvar posteriormente.

A ID do aplicativo é o client_id valor no código de exemplo.

Para usar a entidade de serviço (aplicativo), você precisa saber a senha da entidade de serviço que pode ser encontrada por:

No portal do Azure, pesquise e selecione Azure Active Directory e selecione Registros de aplicativo no painel esquerdo.
Selecione sua entidade de serviço (aplicativo) na lista.
Selecione Segredos de certificados & no painel esquerdo.
Selecione Novo segredo do cliente.
Na página Adicionar um segredo do cliente, insira uma Descrição, selecione um tempo de expiração em Expirações e selecione Adicionar.

Na página Segredos do cliente , a cadeia de caracteres na coluna Valor do novo segredo é sua senha. Salve esse valor.

Configurar a autenticação usando a entidade de serviço

Depois que a nova entidade de serviço for criada, você precisará atribuir as funções do plano de dados da sua conta purview à entidade de serviço criada acima. Siga as etapas abaixo para atribuir a função correta para estabelecer a confiança entre a entidade de serviço e a conta do Purview:

Navegue até o portal de governança do Microsoft Purview.
Selecione o Mapa de Dados no menu à esquerda.
Selecione Coleções.
Selecione a coleção raiz no menu coleções. Essa será a coleção superior da lista e terá o mesmo nome da sua conta do Microsoft Purview.

Observação

Você também pode atribuir sua permissão de entidade de serviço a quaisquer subconjuntos, em vez da coleção raiz. No entanto, todas as APIs serão escopo para essa coleção (e sub-coleções que herdam permissões) e os usuários que tentam chamar a API para outra coleção receberão erros.
Selecione a guia Atribuições de função .
Atribua as funções a seguir à entidade de serviço criada anteriormente para acessar vários planos de dados no Microsoft Purview. Para obter etapas detalhadas, consulte Atribuir funções do Azure usando o portal de governança do Microsoft Purview.
- Função de Curador de Dados para acessar o plano Dados do Catálogo.
- Função administrador de fonte de dados para acessar o plano De verificação de dados.
- A coleção Administração função para acessar o Plano de Dados da Conta e a política de metadados Data Plane.
- Função DevOps policy Author para acessar a API de políticas do DevOps
Observação

Somente membros da função Collection Administraçã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

Você pode enviar uma solicitação POST para a URL a seguir para obter o token de acesso.

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

Você pode encontrar sua ID do Locatário procurando propriedades de locatário no portal do Azure. A ID estará disponível na página de propriedades do locatário.

Os seguintes parâmetros precisam ser passados para a URL acima:

client_id: a ID do cliente do aplicativo registrado no Azure Active Directory e é atribuída a uma função de plano de dados para a conta do Microsoft Purview.
client_secret: segredo do cliente criado para o aplicativo acima.
grant_type: isso deve ser "client_credentials".
recurso: 'https://purview.azure.net'

Aqui está uma solicitação 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 você receber uma mensagem de erro que diz: o resgate de token de origem cruzada será permitido apenas para o tipo de cliente 'Aplicativo de Página Única'.

Verifique os cabeçalhos de solicitação e confirme se sua solicitação não contém o cabeçalho 'origin'.
Confirme se o URI de redirecionamento está definido como Web em sua entidade de serviço.
Se você estiver usando um aplicativo como o Postman, verifique se o software está atualizado.

Use o token de acesso acima para chamar as APIs do plano de dados.

Próximas etapas

Gerenciar APIs REST do Microsoft Purview Data Plane