Share via

Criar ativos usando a API REST

  • Artigo

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.

Observação

Se você estiver usando a versão gratuita do Microsoft Purview, somente os usuários do grupo de funções de curador de dados poderão acessar esses ativos.

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

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.

  1. Navegue até o portal de governança do Microsoft Purview.

  2. Selecione o Mapa de Dados no menu à esquerda.

  3. Selecione Coleções.

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

  5. Selecione a guia Atribuições de função .

  6. Atribua a função de Curador de Dados à entidade de serviço criada anteriormente. Para obter etapas detalhadas, consulte Atribuir funções do Azure usando o portal de governança do Microsoft Purview.

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.

Importante

Os pontos de extremidade da URL de solicitação dependem da experiência do Microsoft Purview que você está usando: a experiência clássica do Microsoft Purview ou o novo portal do Microsoft Purview

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.

Importante

Para usar este exemplo para seus recursos do Azure, substitua esses valores na carga:

  • Typename
  • Proprietário
  • Qualifiedname
  • nome
  • ID de especialista
  • Informações de especialistas
  • ID do proprietário
  • Informações do proprietário
  • Createdby
  • Atualizado por

URL de solicitação: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

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

Importante

Para usar este exemplo para seus recursos do Azure, substitua esses valores na carga:

  • Typename
  • Proprietário
  • Qualifiedname
  • nome
  • type
  • ID de especialista
  • Informações de especialistas
  • ID do proprietário
  • Informações do proprietário
  • Createdby
  • Atualizado por

URL de solicitação: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

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

Gerenciar fontes de dadosReferência de API REST da Entidade do Microsoft Purview