Skip to content

Latest commit

 

History

History
188 lines (114 loc) · 7.92 KB

module10.md

File metadata and controls

188 lines (114 loc) · 7.92 KB

Module 10 - REST API

< Previous Module - Home - Next Module>

🤔 Prerequisites

🔨 Tools

📢 Introduction

In addition to Purview Studio, the Azure Purview platform can be accessed via an API. This enables users to submit data directly to the catalog, include the catalog as part of an automated process, or build their own user experience on top of the catalog.

🎯 Objectives

  • Return data from the Azure Purview REST API.

Table of Contents

  1. Register an Application
  2. Generate a Client Secret
  3. Provide Service Principal Access to Azure Purview
  4. Use Postman to Call Azure Purview REST API

1. Register an Application

To invoke the REST API, we must first register an application (i.e. service principal) that will act as the identity that the Azure Purview platform reognizes and is configured to trust.

💡 Did you know?

An Azure service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources.

  1. Sign in to the Azure portal, navigate to Azure Active Directory > App registrations, and click New registration.

  2. Provide the application a name, select an account type, and click Register.

    Property Example Value
    Name purview-spn
    Account Type Accounts in this organizational directory only - Single tenant
    Redirect URI (optional) Leave blank

  3. Copy the following values for later use.

    • Application (client) ID
    • Directory (tenant) ID

2. Generate a Client Secret

  1. Navigate to Certifications & secrets and click New client secret.

  2. Provide a Description and set the expiration to In 1 year, click Add.

    Property Example Value
    Description purview-api
    Expires In 1 year

  3. Copy the client secret value for later use.

    💡 Did you know?

    A client secret is a secret string that the application uses to prove its identity when requesting a token, this can also can be referred to as an application password.

3. Provide Service Principal Access to Azure Purview

  1. Under the Azure Purview account, navigate to Access control (IAM) and click Add role assignments.

  2. Select the Purview Data Curator role, select the service principal and click Save.

4. Use Postman to Call Azure Purview REST API

  1. Open Postman, create a new HTTP request as per the details below.

    💡 Did you know?

    The OAuth2 service endpoint is used to gain access to protected resources such as Azure Purview. The HTTP request enables us to acquire an access_token in a way that is language agnostic, this will subsequently be used to query the Azure Purview API.

    Property Value
    HTTP Method POST
    URL https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/token
    Body Type x-wwww-form-urlencoded

    Navigate to Body, select x-wwww-form-urlencoded and provide the following key value pairs. Once HTTP request is ready, click Send. If successful, the response will contain an access token, copy this value for later use.

    Form Key Form Value
    grant_type client_credentials
    client_id YOUR_CLIENT_ID
    client_secret YOUR_CLIENT_SECRET
    resource https://purview.azure.net

  2. Within the Azure portal, open the Azure Purview account, navigate to Properties and find the Atlas endpoint. Copy this value for later use.

    💡 Did you know?

    The Azure Purview catalog endpoint is largely based on the open source Apache Atlas project. Therefore many of the existing Apache Atlas resources (e.g. swagger) is equally relevant for Azure Purview. There is also the official API Swagger documentation available for download - PurviewCatalogAPISwagger.zip.

    Purview Properties

  3. Using Postman once more, create a new HTTP request as per the details below.

    • Paste the copied endpoint into the URL (e.g. https://PURVIEW_ACCOUNT.catalog.purview.azure.com)
    • Add the following at the end of the URL to complete the endpoint: /api/atlas/v2/types/typedefs

    Note: Calling this particular endpoint will result in the bulk retrieval of all type definitions. A type definition in Azure Purview is the equivalent of a blueprint and determines how certain objects (e.g. entities, classifications, relationships, etc) need to be created.

    Property Value
    HTTP Method GET
    URL https://YOUR_PURVIEW_ACCOUNT.catalog.purview.azure.com/api/atlas/v2/types/typedefs

    Navigate to Headers, provide the following key value pair, click Send.

    Header Key Header Value
    Authorization Bearer YOUR_ACCESS_TOKEN

    Note: You generated an access_token in the previous request. Copy and paste this value. Ensure to include the "Bearer " prefix.

  4. If successful, Postman should return a JSON document in the body of the response. Click on the magnifying glass and search for the following phrase "name": "azure_sql_table" to jump down to the entity definition for an Azure SQL Table.

    💡 Did you know?

    While Azure Purview provides a number of system built type definitions for a variety of object types, Customers can use the API to create their own custom type definitions.

🎓 Knowledge Check

  1. The Azure Purview API is largely based on which open source project?

    A ) Apache Maven
    B ) Apache Spark
    C ) Apache Atlas

  2. The Azure Purview API only works with Python.

    A ) True
    B ) False

  3. The Azure Purview API can be used to create custom lineage between data processes and data assets.

    A ) True
    B ) False

🎉 Summary

In this module, you learned how to get started with the Azure Purview REST API. To learn more about the Azure Purview REST API, check out the Swagger documentation.