Criar ativos usando a API REST

Neste tutorial, você aprenderá a criar ativos no Mapa de Dados do Microsoft Purview que os usuários poderão pesquisar e navegar no Catálogo unificado do Microsoft Purview.

Se você já tiver a entidade de serviço e o token de autenticação, poderá pular diretamente para as etapas para criar ativos usando a API REST. Caso contrário, siga este guia para chamar a API REST.

Pré-requisitos

• Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
• Você deve ter uma conta existente do Microsoft Purview. Caso contrário, Marque se sua organização tem acesso à versão gratuita do Microsoft Purview ou use este guia de início rápido para criar uma conta do Microsoft Purview.

Criar uma entidade de serviço (aplicativo)

Para que um cliente da API REST acesse o Microsoft Purview para criar entidades, o cliente deve ter uma entidade de serviço (aplicativo) e uma identidade que o Microsoft Purview reconheça e esteja configurado para confiar.

Os clientes que usaram entidades de serviço existentes (IDs de 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:

1. Entre no portal do Azure.

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

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

4. Selecione Novo registro.

5. Na página Registrar um aplicativo :

   1. Insira um Nome para o aplicativo (o nome da entidade de serviço).
   2. Selecione Contas somente no diretório organizacional (<somente o nome> do seu locatário - locatário único).
   3. Em 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 servirá.
   4. Selecione Registrar.

6. Na página nova entidade de serviço, copie os valores de Nome de exibição e ID do aplicativo (cliente) para salvar para mais tarde.

   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:

1. Selecione a entidade de serviço (aplicativo) na lista de 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 , insira uma Descrição, selecione um tempo de expiração em Expira e selecione Adicionar.
5. Na página Segredos do cliente , a cadeia de caracteres na coluna Valor do novo segredo é sua senha. Salve este valor.

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

Depois que a nova entidade de serviço for criada, você precisará atribuir permissões para que a entidade de serviço possa acessar sua conta do Microsoft Purview. As permissões que você precisa atribuir dependem se você está usando a experiência clássica do Microsoft Purview ou o novo portal do Microsoft Purview.

Selecione a guia da experiência que você está usando.

Depois de atribuir permissões, você precisará coletar seu token de autenticação.

1. Envie uma solicitação POST para a seguinte URL para obter o token de acesso:

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

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

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

   • client_id: ID do cliente do aplicativo registrado 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 o aplicativo acima.
   • grant_type: Deve ser "client_credentials".
   • resource: Deve ser 'https://purview.azure.net'

   Aqui está um exemplo de solicitação POST no PowerShell:

   $tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"
   
   $url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
   $params = @{ client_id = "00001111-aaaa-2222-bbbb-3333cccc4444"; 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 entre origens é permitido somente para o tipo de cliente 'Aplicativo de Página Única'.

   • Verifique os cabeçalhos da solicitação e confirme se ela não contém o cabeçalho 'origin'.
   • Confirme se o URI de redirecionamento está definido como Web na entidade de serviço.
   • Verifique se o software está atualizado para o aplicativo que você está usando para enviar sua solicitação POST.

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

Criar ativos usando a API REST

Agora que você tem um token e pode autenticar, está pronto para criar seus ativos.

Criar ativos do Azure

Aqui está um exemplo que você pode usar para criar suas entidades para recursos do Azure. Este exemplo aborda uma conta de Armazenamento do Azure, mas você pode usá-lo para qualquer outra fonte do Azure.

Método: POSTAR

Autenticação: use o token da etapa anterior como seu token de portador.

Exemplo de conteúdo:

{
  "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 ativos em várias nuvens

Aqui está um exemplo que você pode usar para criar suas entidades para recursos de várias nuvens. Este exemplo cria um recurso do Snowflake, mas você pode usá-lo para qualquer outra fonte

Método: POSTAR

Autenticação: use o token da etapa anterior como seu token de portador.

Exemplo de conteúdo:

{
  "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