Доступ к API Azure Monitor Log Analytics

Запрос можно отправить в рабочую область с помощью конечной точки Azure Monitor Log Analytics https://api.loganalytics.azure.com. Чтобы получить доступ к конечной точке, необходимо пройти проверку подлинности через Microsoft Entra ID.

Проверка подлинности с помощью демонстрационного ключа API

Чтобы быстро изучить API без Microsoft Entra проверки подлинности, используйте демонстрационную рабочую область с примерами данных, которые поддерживают проверку подлинности ключа API.

Для проверки подлинности и выполнения запросов к образцу рабочей области используйте DEMO_WORKSPACE в качестве {workspace-id} и передайте ключ DEMO_KEYAPI.

Если идентификатор приложения или ключ API неверный, служба API возвращает ошибку 403 (запрещено).

Ключ DEMO_KEY API можно передать тремя способами в зависимости от того, нужно ли использовать заголовок, URL-адрес или обычную проверку подлинности:

• Пользовательский заголовок: укажите ключ API в пользовательском заголовке X-Api-Key.
• Параметр запроса: укажите ключ API в параметре URL- адреса api_key.
• Обычная проверка подлинности: укажите ключ API в качестве имени пользователя или пароля. Если вы предоставляете оба варианта, ключ API должен находиться в имени пользователя.

В этом примере используется идентификатор рабочей области и ключ API в заголовке:

POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
X-Api-Key: DEMO_KEY
Content-Type: application/json

{
    "query": "AzureActivity | summarize count() by Category"
}

Общедоступная конечная точка API

Конечная точка общедоступного API:

https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}

Где:

• api-version: версия API. Текущая версия v1.
• workspaceId: идентификатор рабочей области.

Запрос передается в тексте запроса.

Рассмотрим пример.

https://api.loganalytics.azure.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1

Body:
{
    "query": "Usage"
}

Настройка проверки подлинности

Чтобы получить доступ к API, зарегистрируйте клиентское приложение с помощью Microsoft Entra ID и запросите маркер.

1. Зарегистрируйте приложение в Microsoft Entra ID.

2. На странице обзора приложения выберите разрешения API.

3. Выберите Добавить разрешение.

4. На вкладке Используемые моей организацией API найдите Log Analytics и выберите API Log Analytics из списка.

   

5. Выберите Делегированные разрешения.

6. Установите флажок Data.Read.

7. Выберите Добавить разрешения.

   

Теперь, когда приложение зарегистрировано и имеет разрешения на использование API, предоставьте приложению доступ к вашей Log Analytics рабочей области.

1. На странице обзора рабочей области Log Analytics выберите Управление доступом (IAM).

2. выберите Добавить назначение ролей.

   

3. Выберите роль читателя и выберите "Участники".

   

4. На вкладке "Члены" выберите "Выбрать участников".

5. Введите имя приложения в поле "Выбор ".

6. Выберите приложение и нажмите кнопку "Выбрать".

7. Выберите кнопку Проверить + назначить.

   

8. После завершения настройки Active Directory и разрешений рабочей области запросите маркер авторизации.

Запрос токена авторизации

Прежде чем начать, убедитесь, что у вас есть все необходимые значения для успешного выполнения запроса. Для всех запросов требуется:

• Идентификатор клиента Microsoft Entra.
• Идентификатор рабочей области.
• Идентификатор клиента Microsoft Entra для приложения.
• Секретный ключ клиента Microsoft Entra для приложения.

API Log Analytics поддерживает проверку подлинности Microsoft Entra с тремя различными потоками Microsoft Entra ID OAuth2:

• Учетные данные клиента
• Код авторизации
• Неявный

Поток учетных данных клиента

В потоке учетных данных клиента токен используется с конечной точкой Log Analytics. При регистрации приложения в Microsoft Entra ID делается единый запрос на получение токена, используя учетные данные, предоставленные для вашего приложения на предыдущем шаге.

Используйте resource=https://api.loganalytics.io.

Получите токен аутентификации, используя один из следующих методов:

• интерфейс командной строки (CLI)
• REST API
• Пакет SDK

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource={resource URI of the service you want to access, e.g. https://monitoring.azure.com>'}'

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "{resource URI of the service you want to access, e.g. https://monitoring.azure.com>'}",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

az account get-access-token

Используйте маркер в запросах к конечной точке Log Analytics:

POST /v1/workspaces/your workspace id/query?timespan=P1D
Host: https://api.loganalytics.azure.com
Content-Type: application/json
Authorization: Bearer <your access token>

Body:

{
"query": "AzureActivity |summarize count() by Category"
}

Пример ответа:

{
    "tables": [
        {
            "name": "PrimaryResult",
            "columns": [
                {
                    "name": "OperationName",
                    "type": "string"
                },
                {
                    "name": "Level",
                    "type": "string"
                },
                {
                    "name": "ActivityStatus",
                    "type": "string"
                }
            ],
            "rows": [
                [
                    "Metric Alert",
                    "Informational",
                    "Resolved",
                    ...
                ],
                ...
            ]
        },
        ...
    ]
}

Поток кода авторизации

Основной поддерживаемый поток OAuth2 — через коды авторизации. Для этого метода требуется два HTTP-запроса для получения маркера, с помощью которого необходимо вызвать API Azure Monitor Log Analytics. Существует два URL-адреса с одной конечной точкой для каждого запроса. Их форматы описаны в следующих разделах.

URL-адрес кода авторизации (запрос GET)

GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
client_id=<app-client-id>
&response_type=code
&redirect_uri=<app-redirect-uri>
&resource=https://api.loganalytics.io

Когда запрос выполняется к URL для авторизации, client_id — это идентификатор вашего приложения Microsoft Entra, который скопирован из меню свойств приложения. Redirect_uri — это URL-адрес домашней страницы или входа из того же приложения Microsoft Entra. При успешном выполнении запроса эта конечная точка перенаправляет вас на страницу входа, предоставленную при регистрации с кодом авторизации, добавленным к URL-адресу. См. следующий пример.

http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID

На этом этапе вы получили код авторизации, который теперь необходимо использовать для получения токена доступа.

URL-адрес токена кода авторизации (POST-запрос)

POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=<app client id>
&code=<auth code fom GET request>
&redirect_uri=<app-client-id>
&resource=https://api.loganalytics.io
&client_secret=<app-client-secret>

Используются те же значения с некоторыми дополнениями. Код авторизации — это тот же код, который вы получили в предыдущем запросе после успешного перенаправления. Код сочетается с ключом, полученным из приложения Microsoft Entra. Если ключ не сохранен, его можно удалить и создать на вкладке "Ключи" в меню Microsoft Entra приложения. Ответ — это строка JSON, содержащая маркер со следующей схемой. Типы указаны для значений токенов.

Пример ответа:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
    "expires_in": "3600",
    "ext_expires_in": "1503641912",
    "id_token": "not_needed_for_log_analytics",
    "not_before": "1503638012",
    "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
    "resource": "https://api.loganalytics.io",
    "scope": "Data.Read",
    "token_type": "bearer"
}

Часть маркера доступа в этом ответе — это то, что вы отправляете API Log Analytics в заголовке Authorization: Bearer. Вы также можете использовать токен обновления в будущем, чтобы получить новые access_token и refresh_token, когда ваши токены устаревают. Формат и конечная точка для этого запроса:

POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=<app-client-id>
&refresh_token=<refresh-token>
&grant_type=refresh_token
&resource=https://api.loganalytics.io
&client_secret=<app-client-secret>

Пример ответа:

{
    "token_type": "Bearer",
    "expires_in": "3600",
    "expires_on": "1460404526",
    "resource": "https://api.loganalytics.io",
    "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
    "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
}

Поток учетных данных клиента

API Log Analytics поддерживает поток аутентификации OAuth2 учетные данные клиента. Этот поток подходит для вызовов между службами, где взаимодействие с пользователем не требуется.

Запрос токена учетных данных клиента

POST https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=<app-client-id>
&scope=https://api.loganalytics.io/.default
&client_secret=<app-client-secret>
&grant_type=client_credentials

Пример ответа:

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax"
}

Этот access_token можно использовать в качестве значения заголовка Authorization: Bearer при передаче в API Log Analytics для авторизации запросов.

Дополнительные сведения

См. документацию по OAuth2 с Microsoft Entra здесь:

• Microsoft Entra поток кода авторизации
• поток учетных данных клиента Microsoft Entra

Дальнейшие шаги

• формат запроса
• Формат отклика
• Запрос журналов для ресурсов Azure
• Пакетные запросы