Feature preview: Configure API Data Sources

Use API Data Source to synchronize data from an API-based Data Source, for example cloud based sources.

In the preview stage, the API Data Source is only compatible with the Microsoft Graph API in Azure.

Prerequisites

Access to your Azure Active Directory

A Registered app with permission to Read directory data on the Microsoft Graph API

For more information on how to configure a registered app, please refer to Microsoft Azure documentation.

Templates

Templates are available for the Microsoft Graph API, where some fields are pre-filled (for example URL and Array Path, see below).

Properties tab

Field	Explanation and Tips
Security context	Specify the credentials to communicate with the API. For the Microsoft Graph API, the fields map as follows: Client ID: Specify the Azure Application ID for the registered app. Client secret: Specify the value of the Key you generated for Identity Director, in the Settings of the Registered app in Azure. Tenant ID: The tenant ID for your Azure Active Directory In Building Blocks of Data Sources, credentials of the Security context fields are not included. You have to set these credentials again after you import the Building Block.
URL	Specify the URL to the resource you want to access. Example: https://graph.microsoft.com/v1.0/users
Array Path	Specify the path to the array of data for the resource you want to access.
Combine Results	Select this option to combine data from two resources. Additional choices are: (Combine results) to one: For each entry that is returned from the URL, a single value is returned from the Second URL. Example URL: https://graph.microsoft.com/v1.0/users Second URL: https://graph.microsoft.com/v1.0/users/{identifier}?$select=department Result: All users are retrieved from the URL, using the Array Path value. To each user that was retrieved, the corresponding department is added from the Second URL. (Combine results) to many from current URL: For each entry that is returned from the URL, a list of values is returned using the Second Array Path within the current URL. Example URL: https://graph.microsoft.com/v1.0/groups?$expand=members Array Path: value Second Array Path: members Result: All groups are retrieved from the URL using the Array Pathvalue. To each group that was retrieved, the corresponding members are added, using the Second Array Path members. (Combine results) to many from another URL: For each entry that is returned from the URL, a list of values is returned from the Second URL. Example URL: https://graph.microsoft.com/v1.0/groups Array Path: value Second URL: https://graph.microsoft.com/v1.0/groups/{identifier}/members?$select=id,userPrincipalName Second Array Path: value Result: All groups are retrieved using the URL using the Array Pathvalue. To each group that was retrieved, the corresponding members are added from the Second URL, using the Second Array Path value.
Property to combine by*	Specify the property that can be used to match data from the two resources (URL and Second URL).
Second URL*	Specify the URL to the second resource you want to access. Example: https://graph.microsoft.com/v1.0/users
Second Array Path*	Specify the path to the array of data for the resource you want to access using the second URL.

* Availability of these fields depends on your configuration of Combine results.

Columns tab

Configure the columns that should be returned by the Data Source.

Filter tab

Optionally, filter out irrelevant data from the external data.

Using filters can have a significant impact on the performance of retrieving data from the Data Source. In these cases, consider including filter parameters in the URL field (on the Properties tab) instead.
For more information about using filters and other query parameters, see https://developer.microsoft.com/en-us/graph/docs/concepts/query_parameters#filter-parameter.

Diagnostics tab

The Preview Data tab shows a preview of the data.
The Data Connections tab shows which data connections currently use the Data Source.