Criar ativos usando a API REST

Neste tutorial, você aprenderá a criar ativos no Mapa de Dados do Microsoft Purview que os usuários possam pesquisar e navegar no Catálogo de Dados 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. Se você não fizer isso, marcar se sua organização tiver acesso à versão gratuita do Microsoft Purview ou usar este 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 o Microsoft Purview para criar entidades, o cliente deve ter uma entidade de serviço (aplicativo) e uma identidade que o Microsoft Purview reconhece e está configurada para confiar.

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:

1. Entre no portal do Azure.

2. No portal, pesquise e selecione Azure Active Directory.

3. Na página do Azure Active Directory, 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 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.

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

1. Selecione sua entidade de serviço (aplicativo) na lista Registros de aplicativo.
2. Selecione Segredos de certificados & 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ções e selecione Adicionar.
5. 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 permissões para que sua 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 para a experiência que você está usando.

Depois de atribuir permissões, você precisará reunir 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 do Locatário procurando propriedades de locatário no portal do Azure. A ID está disponível na página 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: isso deve ser '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.

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á-la para qualquer outra fonte do Azure.

Método: POSTAR

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

Exemplo de carga:

{
  "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 de 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 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 carga:

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