Skip to content

Commit 87eccd1

Browse files
EdB-MSFTEdB-MSFT
committed
fixes
1 parent 6da873c commit 87eccd1

File tree

2 files changed

+36
-85
lines changed

2 files changed

+36
-85
lines changed

‎articles/azure-monitor/essentials/rest-api-walkthrough.md

Lines changed: 34 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -10,66 +10,21 @@ ms.reviewer: edbaynash
1010

1111
# Azure monitoring REST API walkthrough
1212

13-
This article shows you how to perform authentication so your code can use the [Azure Monitor REST API reference](/rest/api/monitor/).
13+
This article shows you how to use the [Azure Monitor REST API reference](/rest/api/monitor/).
1414

15-
The Azure Monitor API makes it possible to programmatically retrieve the available default metric definitions, dimension values, and metric values. The data can be saved in a separate data store such as Azure SQL Database, Azure Cosmos DB, or Azure Data Lake. From there, more analysis can be performed as needed.
16-
17-
The Azure Monitor API also makes it possible to list alert rules, view activity logs. For a full list of available operations, see the [Azure Monitor REST API reference](/rest/api/monitor/).
15+
Retrieve metric definitions, dimension values, and metric values using the Azure Monitor API and use the data in your applications, or store in a database for analysis. You can also list alert rules and view activity logs using the Azure Monitor API.
1816

1917
## Authenticate Azure Monitor requests
2018

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.
19+
Request submitted using the Azure Monitor API use the Azure Resource Manager authentication model. All requests are authenticated with Azure Active Directory. One approach to authenticating the client application is to create an Azure Active Directory service principal and retrieve the authentication token. See
2220

2321
## Create an Azure Active Directory service principal
2422

25-
### [Azure portal](#tab/portal)
26-
27-
To create an Azure Active Directory service principal using the Azure portal see [Register an App to request authorization tokens and work with APIs](../logs/api/register-app-for-token)
28-
29-
### [Azure CLI](#tab/cli)
30-
31-
32-
Run the following script to create a service principal and app.
33-
34-
```azurecli
35-
az ad sp create-for-rbac -n <Service principal display name>
36-
37-
```
38-
The response looks as follows:
39-
```JSON
40-
{
41-
"appId": "0a123b56-c987-1234-abcd-1a2b3c4d5e6f",
42-
"displayName": "AzMonAPIApp",
43-
"password": "123456.ABCDE.~XYZ876123ABcEdB7169",
44-
"tenant": "a1234bcd-5849-4a5d-a2eb-5267eae1bbc7"
45-
}
46-
47-
```
48-
>[!Important]
49-
> 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.
50-
51-
Add a role and scope for the resource that you want to access using the API
52-
53-
```azurecli
54-
az role assignment create --assignee <`appId`> --role <Role> --scope <resource URI>
55-
```
56-
57-
The example below assigns the `Reader` role to the service principal for all resources in the `rg-001`resource group:
58-
```azurecli
59-
az role assignment create --assignee 0a123b56-c987-1234-abcd-1a2b3c4d5e6f --role Reader --scope '\/subscriptions/a1234bcd-5849-4a5d-a2eb-5267eae1bbc7/resourceGroups/rg-001'
60-
```
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)
62-
23+
You can create an Azure Active Directory service principal using the Azure portal, CLI, or PowerShell. For more information, see [Register an App to request authorization tokens and work with APIs](../logs/api/register-app-for-token)
6324

64-
### [PowerShell](#tab/powershell)
65-
66-
To create an Azure Active Directory service principal using thePowershell, see [using Azure PowerShell to create a service principal for accessing 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-
68-
---
6925

7026
## 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 service principal and app:
27+
Once you've created a service principal, retrieve an access token using a REST call. Submit the following request using the `appId` and `password` for your service principal or app:
7328

7429
```HTTP
7530
@@ -108,7 +63,7 @@ A successful request receives an access token in the response:
10863

10964

11065

111-
After authenticating and retrieving a token, use the access token in your Azure Monitor API requests.
66+
After authenticating and retrieving a token, use the access token in your Azure Monitor API requests by including the header `'Authorization: Bearer <access token>'`
11267

11368
> [!NOTE]
11469
> For more information on working with the Azure REST API, see the [Azure REST API reference](/rest/api/azure/).
@@ -117,6 +72,7 @@ After authenticating and retrieving a token, use the access token in your Azure
11772
## Retrieve metric definitions
11873

11974
Use the [Azure Monitor Metric Definitions REST API](/rest/api/monitor/metricdefinitions) to access the list of metrics that are available for a service.
75+
Use the following request format to retrieve metric definitions.
12076

12177
```HTTP
12278
GET /subscriptions/<subscription id>/resourcegroups/<resourceGroupName>/providers/<resourceProviderNamespace>/<resourceType>/<resourceName>/providers/microsoft.insights/metricDefinitions?api-version=<apiVersion>
@@ -126,7 +82,7 @@ Authorization: Bearer <access token>
12682
12783
```
12884

129-
For example, The request below retrieves the metric definitions for an Azure Storage account
85+
For example, The following request retrieves the metric definitions for an Azure Storage account
13086

13187
```curl
13288
curl --location --request GET 'https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricDefinitions?api-version=2018-01-01'
@@ -162,10 +118,7 @@ In this example, only the second metric has dimensions.
162118
"timeGrain": "PT1H",
163119
"retention": "P93D"
164120
},
165-
{
166-
"timeGrain": "PT6H",
167-
"retention": "P93D"
168-
},
121+
...
169122
{
170123
"timeGrain": "PT12H",
171124
"retention": "P93D"
@@ -200,10 +153,7 @@ In this example, only the second metric has dimensions.
200153
"timeGrain": "PT5M",
201154
"retention": "P93D"
202155
},
203-
{
204-
"timeGrain": "PT15M",
205-
"retention": "P93D"
206-
},
156+
...
207157
{
208158
"timeGrain": "PT30M",
209159
"retention": "P93D"
@@ -212,14 +162,7 @@ In this example, only the second metric has dimensions.
212162
"timeGrain": "PT1H",
213163
"retention": "P93D"
214164
},
215-
{
216-
"timeGrain": "PT6H",
217-
"retention": "P93D"
218-
},
219-
{
220-
"timeGrain": "PT12H",
221-
"retention": "P93D"
222-
},
165+
...
223166
{
224167
"timeGrain": "P1D",
225168
"retention": "P93D"
@@ -249,14 +192,15 @@ In this example, only the second metric has dimensions.
249192
250193
## Retrieve dimension values
251194

252-
After the retrieving the available metric definitions for metrics with dimensions, retrieve the range of values for the dimensions. Use the dimension values to 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.
195+
After the retrieving the available metric definitions, retrieve the range of values for the metric's dimensions. Use dimension values to filter or segment the metrics in your queries. Use the [Azure Monitor Metrics REST API](/rest/api/monitor/metrics) to find all of the values for a given metric dimension.
253196

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.
197+
Use the metric's `name.value` element for filtering requests. If no filters are specified, the default metric is returned. The API only allows one dimension to have a wildcard filter.
198+
Specify the request for dimension values using the `"resultType=metadata"` query parameter. The `resultType` is omitted for a metric values request.
255199

256200
> [!NOTE]
257201
> To retrieve dimension values by using the Azure Monitor REST API, use the API version "2019-07-01" or later.
258202
>
259-
203+
Use the following request format to retrieve dimension values.
260204
```HTTP
261205
GET /subscriptions/<subscription-id>/resourceGroups/
262206
<resource-group-name>/providers/<resource-provider-namespace>/
@@ -330,9 +274,9 @@ The following JSON shows an example response body.
330274

331275
## Retrieve metric values
332276

333-
After the available metric definitions and possible dimension values are known, it's then possible to retrieve the related metric values. Use the [Azure Monitor Metrics REST API](/rest/api/monitor/metrics) to retrieve the metric values.
277+
After the available metric definitions and dimension values are known, you can then retrieve the metric values. Use the [Azure Monitor Metrics REST API](/rest/api/monitor/metrics) to retrieve the metric values.
334278

335-
Use the metric's `value` element (not `localizedValue`) for any filtering requests. If no dimension filters are specified, the rolled up, aggregated metric is returned.
279+
Use the metric's `name.value` element (not `localizedValue`) for any filtering requests. If no dimension filters are specified, the rolled up, aggregated metric is returned.
336280

337281
To fetch multiple time series with specific dimension values, specify a filter query parameter that specifies both dimension values such as `"&$filter=ApiName eq 'ListContainers' or ApiName eq 'GetBlobServiceProperties'"`.
338282

@@ -342,6 +286,8 @@ To return a time series for every value of a given dimension, use an `*` filter
342286
> To retrieve multi-dimensional metric values using the Azure Monitor REST API, use the API version "2019-07-01" or later.
343287
>
344288
289+
Use the following request format to retrieve metric values.
290+
345291
```HTTP
346292
GET /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/<resource-provider-namespace>/<resource-type>/<resource-name>/providers/microsoft.insights/metrics?metricnames=<metric>&timespan=<starttime/endtime>&$filter=<filter>&interval=<timeGrain>&aggregation=<aggreation>&api-version=<apiVersion>
347293
Host: management.azure.com
@@ -546,36 +492,42 @@ host: management.azure.com
546492

547493
**$filter** reduces the set of data collected.
548494
This argument is required and it also requires at least the start date/time.
549-
The $filter argument is very restricted and allows only the following patterns.
495+
The $filter argument accepts the following patterns:
550496
- List events for a resource group: $filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z' and resourceGroupName eq 'resourceGroupName'.
551497
- List events for resource: $filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z' and resourceUri eq 'resourceURI'.
552498
- List events for a subscription in a time range: $filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z'.
553499
- List events for a resource provider: $filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z' and resourceProvider eq 'resourceProviderName'.
554-
- List events for a correlation Id: $filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z' and correlationId eq 'correlationID'.
555-
556-
NOTE: No other syntax is allowed.
500+
- List events for a correlation ID: $filter=eventTimestamp ge '2014-07-16T04:36:37.6407898Z' and eventTimestamp le '2014-07-20T04:36:37.6407898Z' and correlationId eq 'correlationID'.
557501

558502

559-
**$select** is used to fetch events with only the given properties.
560-
The $select argument is a comma separated list of property names to be returned. Possible values are: authorization, claims, correlationId, description, eventDataId, eventName, eventTimestamp, httpRequest, level, operationId, operationName, properties, resourceGroupName, resourceProviderName, resourceId, status, submissionTimestamp, subStatus, subscriptionId
503+
**$select** is used to fetch a specified list of properties for the returned events.
504+
The $select argument is a comma separated list of property names to be returned.
505+
Valid values are:
506+
`authorization`, `claims`, `correlationId`, `description`, `eventDataId`, `eventName`, `eventTimestamp`, `httpRequest`, `level`, `operationId`, `operationName`, `properties`, `resourceGroupName`, `resourceProviderName`, `resourceId`, `status`, `submissionTimestamp`, `subStatus`, and `subscriptionId`.
561507

562508
The following sample requests use the Azure Monitor REST API to query an activity log.
563-
564509
### Get activity logs with filter:
565510

511+
The following example gets the activity logs for resource group "MSSupportGroup" between the dates 2023-03-21T20:00:00Z and 2023-03-24T20:00:00Z
512+
566513
``` HTTP
567514
GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.insights/eventtypes/management/values?api-version=2015-04-01&$filter=eventTimestamp ge '2023-03-21T20:00:00Z' and eventTimestamp le '2023-03-24T20:00:00Z' and resourceGroupName eq 'MSSupportGroup'
568515
```
569516
### Get activity logs with filter and select:
570517

518+
The following example gets the activity logs for resource group "MSSupportGroup", between the dates 2023-03-21T20:00:00Z and 2023-03-24T20:00:00Z, returning the elements eventName,operationName,status,eventTimestamp,correlationId,submissionTimestamp, and level
571519
```HTTP
572-
GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.insights/eventtypes/management/values?api-version=2015-04-01&$filter=eventTimestamp ge '2023-01-21T20:00:00Z' and eventTimestamp le '2023-01-23T20:00:00Z' and resourceGroupName eq 'MSSupportGroup'&$select=eventName,id,resourceGroupName,resourceProviderName,operationName,status,eventTimestamp,correlationId,submissionTimestamp,level
520+
GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.insights/eventtypes/management/values?api-version=2015-04-01&$filter=eventTimestamp ge '2023-03-21T20:00:00Z' and eventTimestamp le '2023-03-24T20:00:00Z'and resourceGroupName eq 'MSSupportGroup'&$select=eventName,operationName,status,eventTimestamp,correlationId,submissionTimestamp,level
573521
```
574522

575523

576524
## Troubleshooting
577525

578-
If you receive a 429, 503, or 504 error, retry the API in one minute.
526+
You may receive one of the following HTTP error statuses:
527+
* 429 Too Many Requests
528+
* 503 Service Unavailable
529+
* 504 Gateway Timeout
530+
If one of these statuses is returned, resend the request.
579531

580532
## Next steps
581533

‎articles/azure-monitor/logs/api/register-app-for-token.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -69,16 +69,15 @@ Add a role and scope for the resources that you want to access using the API
6969
az role assignment create --assignee <`appId`> --role <Role> --scope <resource URI>
7070
```
7171

72-
The CLI example below assigns the `Reader` role to the service principal for all resources in the `rg-001`resource group:
72+
The CLI following example assigns the `Reader` role to the service principal for all resources in the `rg-001`resource group:
7373

7474
```azurecli
7575
az role assignment create --assignee 0a123b56-c987-1234-abcd-1a2b3c4d5e6f --role Reader --scope '\/subscriptions/a1234bcd-5849-4a5d-a2eb-5267eae1bbc7/resourceGroups/rg-001'
7676
```
7777
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)
7878

7979
### [PowerShell](#tab/powershell)
80-
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).
81-
80+
The following sample script demonstrates creating an Azure Active Directory service principal via PowerShell. For a more detailed walkthrough, see [using Azure PowerShell to create a service principal to access resources](../../../active-directory/develop/howto-authenticate-service-principal-powershell.md)
8281

8382
```powershell
8483
$subscriptionId = "{azure-subscription-id}"

0 commit comments

Comments
 (0)