Skip to content

Commit 6bdd57f

Browse files
ShawnJacksonShawnJackson
authored
Merge pull request #228812 from paulth1/log-articles-batch-10
[AQ] edit pass: log-articles-batch-10
2 parents 0026d09 + 800a7f4 commit 6bdd57f

File tree

5 files changed

+151
-142
lines changed

5 files changed

+151
-142
lines changed

‎articles/azure-monitor/logs/api/access-api.md

Lines changed: 81 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,33 @@
11
---
2-
title: API Access and Authentication
3-
description: How to Authenticate and access the Azure Monitor Log Analytics API.
2+
title: API access and authentication
3+
description: Learn how to authenticate and access the Azure Monitor Log Analytics API.
44
author: AbbyMSFT
55
ms.author: abbyweisberg
66
ms.date: 11/28/2022
77
ms.topic: article
88
---
99
# Access the Azure Monitor Log Analytics API
1010

11-
You can submit a query request to a workspace using the Azure Monitor Log Analytics endpoint `https://api.loganalytics.azure.com`. To access the endpoint, you must authenticate through Azure Active Directory (Azure AD).
11+
You can submit a query request to a workspace by using the Azure Monitor Log Analytics endpoint `https://api.loganalytics.azure.com`. To access the endpoint, you must authenticate through Azure Active Directory (Azure AD).
12+
1213
>[!Note]
13-
> The `api.loganalytics.io` endpoint is being replaced by `api.loganalytics.azure.com`. `api.loganalytics.io` will continue to be supported for the forseeable future.
14-
## Authenticating with a demo API key
14+
> The `api.loganalytics.io` endpoint is being replaced by `api.loganalytics.azure.com`. The `api.loganalytics.io` endpoint will continue to be supported for the forseeable future.
15+
16+
## Authenticate with a demo API key
1517

16-
To quickly explore the API without Azure Active Directory authentication, use the demonstration workspace with sample data, which supports API key authentication.
18+
To quickly explore the API without Azure AD authentication, use the demonstration workspace with sample data, which supports API key authentication.
1719

1820
To authenticate and run queries against the sample workspace, use `DEMO_WORKSPACE` as the {workspace-id} and pass in the API key `DEMO_KEY`.
1921

20-
If either the Application ID or the API key is incorrect, the API service will return a [403](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error) (Forbidden) error.
22+
If either the Application ID or the API key is incorrect, the API service returns a [403](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error) (Forbidden) error.
2123

22-
The API key `DEMO_KEY` can be passed in three different ways, depending on whether you prefer to use the URL, a header, or basic authentication.
24+
The API key `DEMO_KEY` can be passed in three different ways, depending on whether you want to use a header, the URL, or basic authentication:
2325

24-
1. **Custom header**: provide the API key in the custom header `X-Api-Key`
25-
2. **Query parameter**: provide the API key in the URL parameter `api_key`
26-
3. **Basic authentication**: provide the API key as either username or password. If you provide both, the API key must be in the username.
26+
- **Custom header**: Provide the API key in the custom header `X-Api-Key`.
27+
- **Query parameter**: Provide the API key in the URL parameter `api_key`.
28+
- **Basic authentication**: Provide the API key as either username or password. If you provide both, the API key must be in the username.
2729

28-
This example uses the Workspace ID and API key in the header:
30+
This example uses the workspace ID and API key in the header:
2931

3032
```
3133
POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
@@ -36,6 +38,7 @@ This example uses the Workspace ID and API key in the header:
3638
"query": "AzureActivity | summarize count() by Category"
3739
}
3840
```
41+
3942
## Public API endpoint
4043

4144
The public API endpoint is:
@@ -44,12 +47,12 @@ The public API endpoint is:
4447
https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}
4548
```
4649
where:
47-
- **api-version**: The API version. The current version is "v1"
48-
- **workspaceId**: Your workspace ID
50+
- **api-version**: The API version. The current version is "v1."
51+
- **workspaceId**: Your workspace ID.
4952

5053
The query is passed in the request body.
5154

52-
For example,
55+
For example:
5356
```
5457
https://api.loganalytics.azure.com/v1/workspaces/1234abcd-def89-765a-9abc-def1234abcde
5558
@@ -58,64 +61,68 @@ For example,
5861
"query": "Usage"
5962
}
6063
```
61-
## Set up Authentication
6264

63-
To access the API, you need to register a client app with Azure Active Directory and request a token.
64-
1. [Register an app in Azure Active Directory](./register-app-for-token.md).
65+
## Set up authentication
66+
67+
To access the API, you register a client app with Azure AD and request a token.
68+
69+
1. [Register an app in Azure AD](./register-app-for-token.md).
70+
71+
1. On the app's overview page, select **API permissions**.
72+
1. Select **Add a permission**.
73+
1. On the **APIs my organization uses** tab, search for **Log Analytics** and select **Log Analytics API** from the list.
6574

66-
1. On the app's overview page, select **API permissions**
67-
1. Select **Add a permission**
68-
1. In the **APIs my organization uses** tab search for *log analytics* and select **Log Analytics API** from the list.
69-
:::image type="content" source="../media/api-register-app/request-api-permissions.png" alt-text="A screenshot showing the Request API permissions page.":::
75+
:::image type="content" source="../media/api-register-app/request-api-permissions.png" alt-text="A screenshot that shows the Request API permissions page.":::
7076

71-
1. Select **Delegated permissions**
72-
1. Check the checkbox for **Data.Read**
73-
1. Select **Add permissions**
74-
:::image type="content" source="../media/api-register-app/add-requested-permissions.png" alt-text="A screenshot showing the continuation of the Request API permissions page.":::
77+
1. Select **Delegated permissions**.
78+
1. Select the **Data.Read** checkbox.
79+
1. Select **Add permissions**.
7580

76-
Now that your app is registered and has permissions to use the API, grant your app access to your Log Analytics Workspace.
81+
:::image type="content" source="../media/api-register-app/add-requested-permissions.png" alt-text="A screenshot that shows the continuation of the Request API permissions page.":::
7782

78-
1. From your Log analytics Workspace overview page, select **Access control (IAM)**.
83+
Now that your app is registered and has permissions to use the API, grant your app access to your Log Analytics workspace.
84+
85+
1. From your **Log Analytics workspace** overview page, select **Access control (IAM)**.
7986
1. Select **Add role assignment**.
8087

81-
:::image type="content" source="../media/api-register-app/workspace-access-control.png" alt-text="A screenshot showing the access control page for a log analytics workspace.":::
88+
:::image type="content" source="../media/api-register-app/workspace-access-control.png" alt-text="A screenshot that shows the Access control page for a Log Analytics workspace.":::
8289

83-
1. Select the **Reader** role then select **Members**
84-
85-
:::image type="content" source="../media/api-register-app/add-role-assignment.png" alt-text="A screenshot showing the add role assignment page for a log analytics workspace.":::
90+
1. Select the **Reader** role and then select **Members**.
91+
92+
:::image type="content" source="../media/api-register-app/add-role-assignment.png" alt-text="A screenshot that shows the Add role assignment page for a Log Analytics workspace.":::
8693

87-
1. In the Members tab, select **Select members**
88-
1. Enter the name of your app in the **Select** field.
89-
1. Choose your app and select **Select**
90-
1. Select **Review and assign**
91-
92-
:::image type="content" source="../media/api-register-app/select-members.png" alt-text="A screenshot showing the select members blade on the role assignment page for a log analytics workspace.":::
94+
1. On the **Members** tab, choose **Select members**.
95+
1. Enter the name of your app in the **Select** box.
96+
1. Select your app and choose **Select**.
97+
1. Select **Review + assign**.
9398

94-
1. After completing the Active Directory setup and workspace permissions, request an authorization token.
99+
:::image type="content" source="../media/api-register-app/select-members.png" alt-text="A screenshot that shows the Select members pane on the Add role assignment page for a Log Analytics workspace.":::
100+
101+
1. After you finish the Active Directory setup and workspace permissions, request an authorization token.
95102

96103
>[!Note]
97-
> For this example we applied the **Reader** role. This role is one of many built-in roles and may include more permissions than you require. More granular roles and permissions can be created. For more information, see [Manage access to Log Analytics workspaces](../../logs/manage-access.md).
104+
> For this example, we applied the Reader role. This role is one of many built-in roles and might include more permissions than you require. More granular roles and permissions can be created. For more information, see [Manage access to Log Analytics workspaces](../../logs/manage-access.md).
98105
99-
## Request an Authorization Token
106+
## Request an authorization token
100107

101-
Before beginning, make sure you have all the values required to make the request successfully. All requests require:
102-
- Your Azure Active Directory tenant ID.
108+
Before you begin, make sure you have all the values required to make the request successfully. All requests require:
109+
- Your Azure AD tenant ID.
103110
- Your workspace ID.
104-
- Your Azure Active Directory client ID for the app.
105-
- An Azure Active Directory client secret for the app.
111+
- Your Azure AD client ID for the app.
112+
- An Azure AD client secret for the app.
106113

107-
The Log Analytics API supports Azure Active Directory authentication with three different [Azure AD OAuth2](/azure/active-directory/develop/active-directory-protocols-oauth-code) flows:
108-
- Client credentials
114+
The Log Analytics API supports Azure AD authentication with three different [Azure AD OAuth2](/azure/active-directory/develop/active-directory-protocols-oauth-code) flows:
115+
- Client credentials
109116
- Authorization code
110117
- Implicit
111118

119+
### Client credentials flow
112120

113-
### Client Credentials Flow
121+
In the client credentials flow, the token is used with the Log Analytics endpoint. A single request is made to receive a token by using the credentials provided for your app in the previous step when you [register an app in Azure AD](./register-app-for-token.md).
114122

115-
In the client credentials flow, the token is used with the log analytics endpoint. A single request is made to receive a token, using the credentials provided for your app in the [Register an app for in Azure Active Directory](./register-app-for-token.md) step above.
116-
Use the `https://api.loganalytics.azure.com` endpoint.
123+
Use the `https://api.loganalytics.azure.com` endpoint.
117124

118-
##### Client Credentials Token URL (POST request)
125+
#### Client credentials token URL (POST request)
119126

120127
```http
121128
POST /<your-tenant-id>/oauth2/token
@@ -139,7 +146,7 @@ A successful request receives an access token in the response:
139146
}
140147
```
141148

142-
Use the token in requests to the log analytics endpoint:
149+
Use the token in requests to the Log Analytics endpoint:
143150

144151
```http
145152
POST /v1/workspaces/your workspace id/query?timespan=P1D
@@ -153,8 +160,7 @@ Use the token in requests to the log analytics endpoint:
153160
}
154161
```
155162

156-
157-
Example Response:
163+
Example response:
158164

159165
```http
160166
{
@@ -190,11 +196,11 @@ Example Response:
190196
}
191197
```
192198

193-
### Authorization Code Flow
199+
### Authorization code flow
194200

195-
The main OAuth2 flow supported is through [authorization codes](/azure/active-directory/develop/active-directory-protocols-oauth-code). This method requires two HTTP requests to acquire a token with which to call the Azure Monitor Log Analytics API. There are two URLs, one endpoint per request. Their formats are:
201+
The main OAuth2 flow supported is through [authorization codes](/azure/active-directory/develop/active-directory-protocols-oauth-code). This method requires two HTTP requests to acquire a token with which to call the Azure Monitor Log Analytics API. There are two URLs, with one endpoint per request. Their formats are described in the following sections.
196202

197-
#### Authorization Code URL (GET request):
203+
#### Authorization code URL (GET request)
198204

199205
```http
200206
GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
@@ -204,15 +210,15 @@ The main OAuth2 flow supported is through [authorization codes](/azure/active-di
204210
&resource=https://api.loganalytics.io
205211
```
206212

207-
When making a request to the Authorize URL, the client\_id is the Application ID from your Azure AD App, copied from the App's properties menu. The redirect\_uri is the home page/login URL from the same Azure AD App. When a request is successful, this endpoint redirects you to the sign-in page you provided at sign-up with the authorization code appended to the URL. See the following example:
213+
When a request is made to the authorize URL, the client\_id is the application ID from your Azure AD app, copied from the app's properties menu. The redirect\_uri is the homepage/login URL from the same Azure AD app. When a request is successful, this endpoint redirects you to the sign-in page you provided at sign-up with the authorization code appended to the URL. See the following example:
208214

209215
```http
210216
http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID
211217
```
212218

213-
At this point you'll have obtained an authorization code, which you need now to request an access token.
219+
At this point, you've obtained an authorization code, which you need now to request an access token.
214220

215-
#### Authorization Code Token URL (POST request)
221+
#### Authorization code token URL (POST request)
216222

217223
```http
218224
POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
@@ -227,7 +233,7 @@ At this point you'll have obtained an authorization code, which you need now to
227233
&client_secret=<app-client-secret>
228234
```
229235

230-
All values are the same as before, with some additions. The authorization code is the same code you received in the previous request after a successful redirect. The code is combined with the key obtained from the Azure AD App. If you didn't save the key, you can delete it and create a new one from the keys tab of the Azure AD App menu. The response is a JSON string containing the token with the following schema. Types are indicated for the token values.
236+
All values are the same as before, with some additions. The authorization code is the same code you received in the previous request after a successful redirect. The code is combined with the key obtained from the Azure AD app. If you didn't save the key, you can delete it and create a new one from the keys tab of the Azure AD app menu. The response is a JSON string that contains the token with the following schema. Types are indicated for the token values.
231237

232238
Response example:
233239

@@ -245,7 +251,7 @@ Response example:
245251
}
246252
```
247253

248-
The access token portion of this response is what you present to the Log Analytics API in the `Authorization: Bearer` header. You may also use the refresh token in the future to acquire a new access\_token and refresh\_token when yours have gone stale. For this request, the format and endpoint are:
254+
The access token portion of this response is what you present to the Log Analytics API in the `Authorization: Bearer` header. You can also use the refresh token in the future to acquire a new access\_token and refresh\_token when yours have gone stale. For this request, the format and endpoint are:
249255

250256
```http
251257
POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
@@ -272,11 +278,11 @@ Response example:
272278
}
273279
```
274280

275-
### Implicit Code Flow
281+
### Implicit code flow
276282

277-
The Log Analytics API supports the OAuth2 [implicit flow](/azure/active-directory/develop/active-directory-dev-understanding-oauth2-implicit-grant). For this flow, only a single request is required but no refresh token can be acquired.
283+
The Log Analytics API supports the OAuth2 [implicit flow](/azure/active-directory/develop/active-directory-dev-understanding-oauth2-implicit-grant). For this flow, only a single request is required, but no refresh token can be acquired.
278284

279-
#### Implicit Code Authorize URL
285+
#### Implicit code authorize URL
280286

281287
```http
282288
GET https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/authorize?
@@ -286,25 +292,24 @@ The Log Analytics API supports the OAuth2 [implicit flow](/azure/active-director
286292
&resource=https://api.loganalytics.io
287293
```
288294

289-
A successful request will produce a redirect to your redirect URI with the token in the URL as follows.
295+
A successful request produces a redirect to your redirect URI with the token in the URL:
290296

291297
```http
292298
http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID
293299
```
294300

295-
This access\_token can be used as the `Authorization: Bearer` header value when passed to the Log Analytics API to authorize requests.
301+
This access\_token can be used as the `Authorization: Bearer` header value when it's passed to the Log Analytics API to authorize requests.
296302

297-
## More Information
303+
## More information
298304

299305
You can find documentation about OAuth2 with Azure AD here:
300-
- [Azure AD Authorization Code flow](/azure/active-directory/develop/active-directory-protocols-oauth-code)
301-
- [Azure AD Implicit Grant flow](/azure/active-directory/develop/active-directory-dev-understanding-oauth2-implicit-grant)
302-
- [Azure AD S2S Client Credentials flow](/azure/active-directory/develop/active-directory-protocols-oauth-service-to-service)
303-
306+
- [Azure AD authorization code flow](/azure/active-directory/develop/active-directory-protocols-oauth-code)
307+
- [Azure AD implicit grant flow](/azure/active-directory/develop/active-directory-dev-understanding-oauth2-implicit-grant)
308+
- [Azure AD S2S client credentials flow](/azure/active-directory/develop/active-directory-protocols-oauth-service-to-service)
304309

305310
## Next steps
306311

307-
- [Request format](./request-format.md)
308-
- [Response format](./response-format.md)
309-
- [Querying logs for Azure resources](./azure-resource-queries.md)
310-
- [Batch queries](./batch-queries.md)
312+
- [Request format](./request-format.md)
313+
- [Response format](./response-format.md)
314+
- [Querying logs for Azure resources](./azure-resource-queries.md)
315+
- [Batch queries](./batch-queries.md)

0 commit comments

Comments
 (0)