Criar recursos com a API REST

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.

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

• Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
• Tem de ter uma conta do Microsoft Purview existente. Se não o fizer, marcar se a sua organização tem acesso à versão gratuita do Microsoft Purview ou utilize este início rápido para criar uma conta do Microsoft Purview.

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.

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.

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.

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

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