API Support

4 Jun, 2024 |
Brian

Brian is the person behind the dcode.bi site. He is keen on helping others be better at what they do around data and intelligence.

API Support

Late May 2024 we got the first support for API in Real-Time Intelligence in Fabric.

This blog post is trying to demystify the API support and give you a quick rundown of the new features and possiblities we can do with the API.

The first endpoints

We got the first endpoints for Real-Time late May 2024 and we can now do CRUD, get and list operations on the following elements of the Real-Time services in Fabric:

  • Eventhouse
  • KQL Database
  • KQL Queryset
  • Real-Time Dashboards
  • Query management

The Fabric API in general

To access the Fabric API Micosoft has an excellent article on Learn right here.

Read and use this article to get started with the Fabric API.

Special for the Query Management API you need to access a specific endpoint:

https://help.kusto.windows.net/v2/rest/

This also has the result that you can use application registration to access the Query Management endpoint - on the opposite to the standard Fabric endpoint where you can’t use an app registration to access the elements and endpoints.

Use this guide to setup the App Registration on your KQL Database and Eventhouse.

Query Management

To start with the last item on the list, the Query Management endpoint lets you execute KQL queries using the API endpoint.

So what ever data, visualization and streams you have in your KQL database or Eventhouse, you can now use the API to send query strings towards the KQL database and get the results back.

This endpoint also lets you do management tasks on the database - like altering properties on the database.

The supported endpoints for the Query Management are:

  • query
  • mgmt

query

The first lets you send queries towards the selected engine and get the results back.

The input accepts a JSON body as the request body along with the mandatory headers for the request (Accept, Authorization, Accept-Encoding, Content-Type, Host, x-ms-client-request-id, x-ms-user-id and x-ms-app).

Example:

-- Get token for authentication

curl "https://login.microsoftonline.com/AAD_TENANT_NAME_OR_ID/oauth2/token" \
  -F "grant_type=client_credentials" \
  -F "resource=https://help.kusto.windows.net" \
  -F "client_id=AAD_APPLICATION_ID" \
  -F "client_secret=AAD_APPLICATION_KEY"

Results from the above are:

{
  "token_type": "Bearer",
  "expires_in": "3599",
  "ext_expires_in":"3599", 
  "expires_on":"1578439805",
  "not_before":"1578435905",
  "resource":"https://help.kusto.windows.net",
  "access_token":"erfJ8...dWER"
}

Then use the access_token from the above to build the final request (select count of rows from a table):

curl -d '{"db":"NYCTaxi","csl":"print Test=\"Hello Kusto Fans!\"","properties":"{\"Options\":{\"query_language\":\"sql\"}}"}"' \
-H "Accept: application/json" \
-H "Authorization: Bearer erfJ8...dWER" \
-H "Content-Type: application/json; charset=utf-8" \
-H "Host: help.kusto.windows.net" \
-H "x-ms-client-request-id: TaxiApp.Query;e9f884e4-90f0-404a-8e8b-01d883023bf1" \
-H "x-ms-user-id: dcodebi\brian" \
-H "x-ms-app: TaxiApp" \
-X POST https://help.kusto.windows.net/v1/rest/mgmt

Eventhouse, KQL Database and KQL Queryset

The Eventhouse, the KQL Database and the KQL Querysets are all a part of the CRUD, List and Get actions from the API with the following overview:

Element Create Delete Get Update List items
Eventhouse Yes Yes Yes Yes Yes
KQL Database Yes Yes Yes Yes Yes
KQL Queryset No* Yes Yes Yes Yes

*So we cannot (yet) create a KQL Queryset from the API.

All of these API endpoints uses the same standard Fabric endpoint process with the main endpoint as:

https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/

Add the needed item type to the endpoint from the list:

  • eventhouse
  • kqlDatabase
  • kqlQueryset

Use the standard API actions to CREATE, UPDATE, DELETE, LIST and GET items from ech of the item types:

  • CREATE -> use POST {api string}
  • DELETE -> use DELETE {api string}/<plural of item type>/{id of the item type}
  • UPDATE -> use PATCH {api string}/<plural of item type>/{id of the item type}
  • LIST -> use GET {api string}/<plural of item type>
  • GET -> use GET {api string}/<plural of item type>/{id of the item type}

Example to UPDATE a new Eventhouse:

PATCH https://api.fabric.microsoft.com/v1/workspaces/b22...fb9/eventhouses/d90...263

## Request body:
{
  "displayName": "Eventhouse DCODE BI",
  "description": "The new API for Eventhouse updated this description."
}

Real-Time Dashboards

The API for Dashboards can only (for now) to a list of Dashboards on the workspace.

Use below example to list your Real-Time dasbboards from a workspace:


GET https://api.fabric.microsoft.com/v1/workspaces/b22...fb9/dashboards

The response will look something like this:

{
  "value": [
    {
      "id": "832...fbf",
      "displayName": "That awesome RTI Dashboard",
      "description": "Look how nice and good looking this is :)",
      "type": "Dashboard",
      "workspaceId": "b22...fb9"
    }
  ]
}

Free-bee

I’ve made a PostMan demo so you can get started very very fast - just follow this link, and you will be running your API calls fast. Direct link to the PostMan demo

The final thoughts

I really like the API approach to the Real-Time Intelligence elements of Fabric. We can now almost fully handle all aspects of the Real-Time items. I also believe that the API work from Microsoft is not over yet. I hope we will see even more support for elements and artifacts on the list of API endpoints.

If you have any comments or ideas, don’t think twice around leaving a comment or reach out to me directly.

comments powered by Disqus