You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -20,7 +20,7 @@ The Azure Monitor API also makes it possible to list alert rules, view activity
20
20
21
21
Tasks executed using the Azure Monitor API use the Azure Resource Manager authentication model. All requests must be authenticated with Azure Active Directory (Azure Active Directory). One approach to authenticating the client application is to create an Azure Active Directory service principal and retrieve the authentication (JWT) token.
22
22
23
-
## Create an service principal
23
+
## Create an Azure Active Directory service principal
24
24
25
25
### [Azure Portal](#tab/portal)
26
26
@@ -29,7 +29,6 @@ To create an Azure Active Directory service principal using the Azure Portal see
29
29
### [Azure CLI](#tab/cli)
30
30
31
31
32
-
##
33
32
Run the following script to create a service principal and app.
34
33
35
34
```azurecli
@@ -62,10 +61,17 @@ The example below assigns the `Reader` role to the service principal for all res
62
61
For more information on creating a service principal using Azure CLI, see [Create an Azure service principal with the Azure CLI](https://learn.microsoft.com/cli/azure/create-an-azure-service-principal-azure-cli)
63
62
64
63
64
+
### [Powershell](#tab/powershell)
65
65
66
-
To retrieve an access token using a REST call submit the following request using the `appId` and `password`:
66
+
To create an Azure Active Directory service principal using thePowershell see [using Azure PowerShell to create a service principal to access resources](/powershell/azure/create-azure-service-principal-azureps). It's also possible to [create a service principal via the Azure portal](../../active-directory/develop/howto-create-service-principal-portal.md).
67
67
68
-
```http
68
+
---
69
+
70
+
## Retrieve a token
71
+
72
+
To retrieve an access token using a REST call submit the following request using the `appId` and `password` for your servide pricipal and app:
73
+
74
+
```HTTP
69
75
70
76
POST /<appId>/oauth2/v2.0/token
71
77
Host: https://login.microsoftonline.com
@@ -91,136 +97,18 @@ curl --location --request POST 'https://login.microsoftonline.com/a1234bcd-5849-
91
97
```
92
98
A successful request receives an access token in the response:
93
99
94
-
```http
100
+
```HTTP
95
101
{
96
102
token_type": "Bearer",
97
103
"expires_in": "86399",
98
104
"ext_expires_in": "86399",
99
105
"access_token": ""eyJ0eXAiOiJKV1QiLCJ.....Ax"
100
106
}
101
107
```
102
-
Use the access token in your Azure Monitor API requests
103
-
104
-
### [Powershell](#tab/powershell)
105
-
The following sample script demonstrates creating an Azure Active Directory service principal via PowerShell. For a more detailed walkthrough, see the documentation on [using Azure PowerShell to create a service principal to access resources](/powershell/azure/create-azure-service-principal-azureps). It's also possible to [create a service principal via the Azure portal](../../active-directory/develop/howto-create-service-principal-portal.md).
To query the Azure Monitor API, the client application should use the previously created service principal to authenticate. The following example PowerShell script shows one approach that uses the [Microsoft Authentication Library (MSAL)](../../active-directory/develop/msal-overview.md) to obtain the authentication token.
Loading the certificate from a .pfx file in PowerShell can make it easier for an admin to manage certificates without having to install the certificate in the certificate store. However, this step shouldn't be done on a client machine because the user could potentially discover the file and the password for it and the method to authenticate. The client credentials flow is only intended to be run in a back-end service-to-service type of scenario where only admins have access to the machine.
216
108
217
-
---
218
109
219
110
220
-
After authenticating and retrieving a token, queries can then be executed against the Azure Monitor REST API.
221
-
For metrics, the two most used queries are:
222
-
- List the metric definitions for a resource.
223
-
- Retrieve the metric values.
111
+
After authenticating and retrieving a token, use the access token in your Azure Monitor API requests.
224
112
225
113
> [!NOTE]
226
114
> For more information on working with the Azure REST API, see the [Azure REST API reference](/rest/api/azure/).
@@ -230,29 +118,23 @@ For metrics, the two most used queries are:
230
118
231
119
Use the [Azure Monitor Metric Definitions REST API](/rest/api/monitor/metricdefinitions) to access the list of metrics that are available for a service.
GET /subscriptions/<subscription id>/resourcegroups/<resourceGroupName>/providers/<resourceProviderNamespace>/<resourceType>/<resourceName>/providers/microsoft.insights/metricDefinitions?api-version=<apiVersion>
For example, The request below retrieves the metric definitions for an Azure Storage account
248
130
131
+
```curl
132
+
curl --location --request GET 'https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricDefinitions?api-version=2018-01-01'
133
+
--header 'Authorization: Bearer eyJ0eXAiOi...xYz
249
134
```
250
135
251
-
> [!NOTE]
252
-
> Older versions of the metric definitions API didn't support dimensions. We recommend using API version "2018-01-01" or later.
253
-
>
254
-
255
-
The resulting JSON response body would be similar to the following example (note that the second metric has dimensions):
136
+
The following JSON shows an example response body.
137
+
In this example, only the second metric has dimensions.
256
138
257
139
```json
258
140
{
@@ -362,34 +244,40 @@ The resulting JSON response body would be similar to the following example (note
362
244
]
363
245
}
364
246
```
247
+
> [!NOTE]
248
+
> We recommend using API version "2018-01-01" or later. Older versions of the metric definitions API don't support dimensions.
365
249
366
250
## Retrieve dimension values
367
251
368
-
After the available metric definitions are known, there might be some metrics that have dimensions. Before you query for the metric, you might want to discover the range of values that a dimension has. Based on these dimension values, you can then choose to filter or segment the metrics based on dimension values while you query for metrics. Use the [Azure Monitor Metrics REST API](/rest/api/monitor/metrics) to find all the possible values for a given metric dimension.
252
+
After the retrieving the available metric definitions for metrics with dimensions, retrieve the range of values for the dimensions. Use the dimension valuesto filter or segment the metrics based in your queries. Use the [Azure Monitor Metrics REST API](/rest/api/monitor/metrics) to find all the possible values for a given metric dimension.
369
253
370
254
Use the metric's name `value` (not `localizedValue`) for any filtering requests. If no filters are specified, the default metric is returned. The use of this API only allows one dimension to have a wildcard filter. The key difference between a dimension values request and a metric data request is specifying the `"resultType=metadata"` query parameter.
371
255
372
256
> [!NOTE]
373
257
> To retrieve dimension values by using the Azure Monitor REST API, use the API version "2019-07-01" or later.
For example, to retrieve the list of dimension values that were emitted for the `API Name` dimension for the `Transactions` metric, where the GeoType dimension = `Primary` during the specified time range, the request would be:
381
-
382
-
```powershell
383
-
$filter = "APIName eq '*' and GeoType eq 'Primary'"
384
-
$request = "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metrics?metricnames=Transactions×pan=2018-03-01T00:00:00Z/2018-03-02T00:00:00Z&resultType=metadata&`$filter=GeoType eq 'Primary' and ApiName eq '*'&api-version=2019-07-01"
For example, to retrieve the list of dimension values that were emitted for the `API Name` dimension for the `Transactions` metric, where the GeoType dimension = `Primary` during the specified time range, the request would be:
391
274
392
-
The resulting JSON response body would be similar to the following example:
275
+
```curl
276
+
curl --location --request GET 'https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metrics?metricnames=Transactions×pan=2018-03-01T00:00:00Z/2018-03-02T00:00:00Z&resultType=metadata&$filter=GeoType eq \'Primary\' and ApiName eq \'*\'&api-version=2019-07-01'
277
+
-header 'Content-Type: application/json' \
278
+
--header 'Authorization: Bearer eyJ0e..meG1lWm9Y
279
+
```
280
+
The following JSON shows an example response body.
393
281
394
282
```json
395
283
{
@@ -445,9 +333,16 @@ Use the metric's name `value` (not `localizedValue`) for any filtering requests.
445
333
> To retrieve multi-dimensional metric values using the Azure Monitor REST API, use the API version "2019-07-01" or later.
446
334
>
447
335
336
+
```HTTP
337
+
GET /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/<resource-provider-namespace>/<resource-type>/<resource-name>/providers/microsoft.insights/metrics?metricnames=<metric>×pan=<starttime/endtime>&$filter=<filter>&interval=<timeGrain>&aggregation=<aggreation>&api-version=<apiVersion>
For example, to retrieve the top three APIs, in descending value, by the number of `Transactions` during a 5-minute range, where the GeoType was `Primary`, the request would be:
Copy file name to clipboardExpand all lines: articles/azure-monitor/logs/api/register-app-for-token.md
+70-2Lines changed: 70 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,6 +13,9 @@ To access Azure REST APIs such as the Log analytics API, or to send custom metri
13
13
14
14
## Register an App
15
15
16
+
Create a service proncipal and refister an usign the Azure Portal, Azure CLI, or Powershell.
17
+
### [Azure Portal](#tab/portal)
18
+
16
19
1. To register an app, open the Active Directory Overview page in the Azure portal.
17
20
18
21
1. Select **App registrations** from the side bar.
@@ -38,10 +41,75 @@ To access Azure REST APIs such as the Log analytics API, or to send custom metri
38
41
:::image type="content" source="../media/api-register-app/client-secret.png" alt-text="A screenshot showing the client secrets page.":::
39
42
40
43
44
+
### [Azure CLI](#tab/cli)
45
+
46
+
47
+
Run the following script to create a service principal and app.
48
+
49
+
```azurecli
50
+
az ad sp create-for-rbac -n <Service principal display name>
51
+
52
+
```
53
+
The response looks as follows:
54
+
```JSON
55
+
{
56
+
"appId": "0a123b56-c987-1234-abcd-1a2b3c4d5e6f",
57
+
"displayName": "AzMonAPIApp",
58
+
"password": "123456.ABCDE.~XYZ876123ABcEdB7169",
59
+
"tenant": "a1234bcd-5849-4a5d-a2eb-5267eae1bbc7"
60
+
}
61
+
62
+
```
63
+
>[!Important]
64
+
> The output includes credentials that you must protect. Be sure that you do not include these credentials in your code or check the credentials into your source control.
65
+
66
+
Add a role and scope for the resources that you want to access using the API
67
+
68
+
```azurecli
69
+
az role assignment create --assignee <`appId`> --role <Role> --scope <resource URI>
70
+
```
71
+
72
+
The example below assigns the `Reader` role to the service principal for all resources in the `rg-001`resource group:
73
+
```azurecli
74
+
az role assignment create --assignee 0a123b56-c987-1234-abcd-1a2b3c4d5e6f --role Reader --scope '\/subscriptions/a1234bcd-5849-4a5d-a2eb-5267eae1bbc7/resourceGroups/rg-001'
75
+
```
76
+
For more information on creating a service principal using Azure CLI, see [Create an Azure service principal with the Azure CLI](https://learn.microsoft.com/cli/azure/create-an-azure-service-principal-azure-cli)
77
+
78
+
### [Powershell](#tab/powershell)
79
+
The following sample script demonstrates creating an Azure Active Directory service principal via PowerShell. For a more detailed walkthrough, see the documentation on [using Azure PowerShell to create a service principal to access resources](/powershell/azure/create-azure-service-principal-azureps). It's also possible to [create a service principal via the Azure portal](../../active-directory/develop/howto-create-service-principal-portal.md).
Before you can generate a token using your app, client ID, and secret, assign the app to a role using Access control (IAM) for resource that you want to access.
44
-
The role will depend on the resource type and the API that you want to use.
112
+
Before you can generate a token using your app, client ID, and secret, assign the app to a role using Access control (IAM) for resource that you want to access. The role will depend on the resource type and the API that you want to use.
45
113
For example,
46
114
- To grant your app read from a Log Analytics Workspace, add your app as a member to the **Reader** role using Access control (IAM) for your Log Analytics Workspace. For more information, see [Access the API](./access-api.md)
0 commit comments