Бөлісу құралы:


Доступ к 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 из списка.

    Снимок экрана, на котором показана страница разрешений API запроса.

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

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

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

    Снимок экрана: продолжение страницы разрешений API запросов.

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

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

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

    Снимок экрана, на котором показана страница управления доступом для рабочей области Log Analytics.

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

    Снимок экрана: страница добавления назначения ролей для рабочей области Log Analytics.

  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-адрес ресурса, к которому требуется получить доступ.

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

Получение маркера с помощью запроса 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"
}

Используйте маркер в запросах к конечной точке 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 см. здесь:

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