Partilhar via

Criar recursos com a API REST

  • Artigo

Neste tutorial, irá aprender a criar recursos no Mapa de Dados do Microsoft Purview que os utilizadores podem procurar e navegar no Catálogo unificado do Microsoft Purview.

Observação

Se estiver a utilizar a versão gratuita do Microsoft Purview, apenas os utilizadores no grupo de funções de curador de dados poderão aceder a estes recursos.

Se já tiver o principal de serviço e o token de autenticação, pode avançar diretamente para os passos para criar recursos com a API REST. Caso contrário, siga este guia para chamar a API REST.

Pré-requisitos

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

Para que um cliente da API REST aceda ao Microsoft Purview para criar entidades, 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.

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:

  1. Entre no portal do Azure.

  2. No portal, procure e selecione Microsoft Entra ID.

  3. Na página Microsoft Entra ID, selecione Registros de aplicativo no painel esquerdo.

  4. Selecione Novo registro.

  5. Na página Registar uma aplicação :

    1. Introduza um Nome para a aplicação (o nome do principal de serviço).
    2. Selecione Contas apenas neste diretório organizacional (<apenas o nome> do seu inquilino – Inquilino único).
    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.

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

  1. Selecione o principal de serviço (aplicação) na lista Registros de aplicativo.
  2. Selecione Certificados & segredos no painel esquerdo.
  3. Selecione Novo segredo do cliente.
  4. 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.
  5. 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, tem de atribuir permissões para que o principal de serviço possa aceder à sua conta do Microsoft Purview. As permissões que precisa de atribuir dependem se está a utilizar a experiência clássica do Microsoft Purview ou o novo portal do Microsoft Purview.

Selecione o separador da experiência que está a utilizar.

  1. Navegue para o portal de governação do Microsoft Purview.

  2. Selecione o Mapa de Dados no menu esquerdo.

  3. Selecione Coleções.

  4. Selecione a coleção de raiz no menu coleções. Esta é 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.

  5. Selecione o separador Atribuições de funções .

  6. Atribua a função curador de dados ao principal de serviço criado anteriormente. Para obter passos detalhados, veja Atribuir funções do Azure com o portal de governação do Microsoft Purview.

Depois de atribuir as permissões, terá de recolher o token de autenticação.

  1. Envie 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 está 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: deve ser "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.

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

Criar recursos com a API REST

Agora que tem um token e pode autenticar-se, está pronto para criar os seus recursos.

Importante

Os pontos finais do URL do pedido dependem da experiência do Microsoft Purview que está a utilizar: a experiência clássica do Microsoft Purview ou o novo portal do Microsoft Purview

Criar recursos do Azure

Eis um exemplo que pode utilizar para criar as suas entidades para recursos do Azure. Este exemplo abrange uma conta de Armazenamento do Azure, mas pode utilizá-la para outras origens do Azure.

Importante

Para utilizar este exemplo para os seus recursos do Azure, substitua estes valores no payload:

  • typeName
  • Proprietário
  • qualifiedName
  • nome
  • ID de Especialista
  • Informações de Especialista
  • ID do Proprietário
  • Informações do Proprietário
  • Createdby
  • Atualizado em

URL do pedido: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

Método: POSTAR

Autenticação: utilize o token do passo anterior como token de portador.

Exemplo de payload:

{
  "referredEntities": {},
  "entity": {
    "typeName": "azure_storage_account",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "https://exampleaccount.core.windows.net",
      "name": "ExampleStorageAccount",
      "description": null,
      "publicAccessLevel": null
    },
    "contacts": {
      "Expert": [
        {
          "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Expert Info"
        }
      ],
      "Owner": [
        {
          "id": " 30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Owner Info"
        }
      ]
    },
    "status": "ACTIVE",
    "createdBy": "ExampleCreator",
    "updatedBy": "ExampleUpdator",
    "version": 0
  }
}

Criar recursos de várias clouds

Eis um exemplo que pode utilizar para criar as suas entidades para recursos multicloud. Este exemplo cria um recurso do Snowflake, mas pode utilizá-lo para outras origens

Importante

Para utilizar este exemplo para os seus recursos do Azure, substitua estes valores no payload:

  • typeName
  • Proprietário
  • qualifiedName
  • nome
  • type
  • ID de Especialista
  • Informações de Especialista
  • ID do Proprietário
  • Informações do Proprietário
  • Createdby
  • Atualizado em

URL do pedido: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

Método: POSTAR

Autenticação: utilize o token do passo anterior como token de portador.

Exemplo de payload:

{
  "referredEntities": {},
  "entity": {
    "typeName": "snowflake_table",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "snowflake://microsoft_partner.east-us-2.azure.snowflakecomputing.com/databases/AZUREPURVIEW_TESTDB/schemas/COMPANY/tables/PROJECT_INFO",
      "name": "PROJECT_INFO",
      "description": null,
      "type": "TABLE"
    },
    "contacts": {
      "Expert": [
        {
          "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Expert Info"
        }
      ],
      "Owner": [
        {
          "id": "4b27e65f-6a15-4925-a4ef-2e640445079b",
          "info": "Example Owner Info"
        }
      ]
    },
    "status": "ACTIVE",
    "createdBy": "ExampleCreator",
    "updatedBy": "ExampleUpdator",
    "version": 0
  }
}

Próximas etapas

Gerir origens de dadosReferência da API REST de Entidades do Microsoft Purview