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

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

Примечание.

Конечная api.loganalytics.io точка заменяется api.loganalytics.azure.com. Конечная api.loganalytics.io точка будет по-прежнему поддерживаться в будущем.

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

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

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

Если идентификатор приложения или ключ 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/1234abcd-def89-765a-9abc-def1234abcde
   
   Body:
   {
       "query": "Usage"
   }

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

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

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

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, запросить маркер авторизации.

Примечание.

В этом примере мы применили роль читателя. Эта роль является одной из многих встроенных ролей и может включать больше разрешений, чем требуется. Можно создать более детализированные роли и разрешения. Дополнительные сведения см. в статье "Управление доступом к рабочим областям Log Analytics".

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

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

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

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

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

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

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

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

Получите маркер проверки подлинности с помощью любого из следующих методов:

• CLI
• REST API
• SDK

При запросе маркера необходимо указать resource параметр. Параметр resource — это URL-адрес ресурса, к которому требуется получить доступ.

В число доступных ресурсов входят:

• https://management.azure.com
• https://api.loganalytics.io
• https://monitoring.azure.com

REST

Получение маркера с помощью запроса REST

Чтобы получить маркер, используйте следующий вызов REST API. Этот запрос использует идентификатор клиента и секрет клиента для проверки подлинности запроса. Идентификатор клиента и секрет клиента получаются при регистрации приложения с помощью идентификатора Microsoft Entra. Дополнительные сведения см. в статье "Регистрация приложения для запроса маркеров авторизации" и работы с API

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=https://monitoring.azure.com'

Текст ответа отображается в следующем формате:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

CLI

Получение маркера с помощью Azure CLI

Чтобы получить маркер с помощью интерфейса командной строки, можно использовать следующую команду.

az account get-access-token 

Дополнительные сведения см. в статье az account get-access-token

SDK

Получение маркера с помощью пакетов SDK

В следующих примерах кода показано, как получить маркер с помощью:

• C#
• NodeJS
• Python

C#

В следующем коде показано, как получить маркер с помощью Azure. Библиотека удостоверений требует идентификатора клиента и секрета клиента для проверки подлинности запроса.

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

Кроме того, для получения маркера можно использовать класс DefaultAzureCredential. Этот метод использует учетные данные Azure по умолчанию для проверки подлинности запроса и не требует идентификатора клиента или секрета клиента.

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Вы также можете указать управляемое удостоверение или учетные данные субъекта-службы следующим образом:

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Дополнительные сведения см. в разделе DefaultAzureCredential Class

Node.js

Сведения о проверке подлинности с помощью JavaScript и NodeJS см. в статье "Проверка подлинности приложений JavaScript в службах Azure с помощью пакета SDK Azure для JavaScript"

В следующем коде показано, как получить маркер с помощью класса DefaultAzureCredential. Этот метод использует учетные данные Azure по умолчанию для проверки подлинности запроса и не требует идентификатора клиента или секрета клиента.

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

Вы также можете использовать InteractiveBrowserCredential класс для получения учетных данных. Этот метод предоставляет интерфейс проверки подлинности на основе браузера для пользователей для проверки подлинности с помощью служб Azure.

Дополнительные сведения см. в разделе DefaultAzureCredential Class и InteractiveBrowserCredential Class

Кроме того, для получения маркера можно использовать класс ClientSecretCredential. Для проверки подлинности запроса этот метод требует идентификатора клиента и секрета клиента.

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

Дополнительные сведения см. в разделе "Класс ClientSecretCredential"

Python

В следующем коде показано, как получить маркер с помощью класса DefaultAzureCredential. Этот метод использует учетные данные Azure по умолчанию для проверки подлинности запроса и не требует идентификатора клиента или секрета клиента.

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

Вы также можете использовать InteractiveBrowserCredential класс для получения учетных данных. Этот метод предоставляет интерфейс проверки подлинности на основе браузера для пользователей для проверки подлинности с помощью служб Azure.

Дополнительные сведения см. в разделе DefaultAzureCredential Class и InteractiveBrowserCredential Class

Кроме того, для получения маркера можно использовать класс ClientSecretCredential. Для проверки подлинности запроса этот метод требует идентификатора клиента и секрета клиента.

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token =  credential.get_token("https://management.azure.com/.default")
print(token.token)

Дополнительные сведения см. в разделе "Класс ClientSecretCredential"

Используйте маркер в запросах к конечной точке 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 Log Analytics в Azure Monitor. Существует два 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. Для этого потока требуется только один запрос, но не может быть получен маркер обновления.

Неявный URL-адрес авторизации кода

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

Успешный запрос создает перенаправление в URI перенаправления с маркером в URL-адресе:

    http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID

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

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

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

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

Следующие шаги

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