API приема журналов в Azure Monitor

Статья
04/15/2024

API приема журналов в Azure Monitor позволяет отправлять данные в рабочую область Log Analytics с помощью вызова REST API или клиентских библиотек. API позволяет отправлять данные в поддерживаемые таблицы Azure или в пользовательские таблицы, которые вы создаете. Кроме того , можно расширить схему таблиц Azure с настраиваемыми столбцами , чтобы принять дополнительные данные.

Базовая операция

Данные можно отправлять в API приема журналов из любого приложения, которое может вызвать REST API. Это может быть пользовательское приложение, которое вы создаете, или это может быть приложение или агент, которое понимает, как отправлять данные в API. Приложение отправляет данные в конечную точку сбора данных (DCE), которая является уникальной точкой подключения для вашей подписки Azure. Он указывает правило сбора данных (DCR), включающее целевую таблицу и рабочую область, а также учетные данные регистрации приложения с доступом к указанному DCR.

Данные, отправленные приложением в API, должны быть отформатированы в формате JSON и соответствовать структуре, ожидаемой DCR. Она не обязательно должна соответствовать структуре целевой таблицы, так как DCR может включать преобразование для преобразования данных в соответствие со структурой таблицы. Целевая таблица и рабочая область можно изменить, изменив DCR без каких-либо изменений в вызове API или исходных данных.

Настройка

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

Примечание.

Скрипт PowerShell, который автоматизирует настройку этих компонентов, см . в примере кода для отправки данных в Azure Monitor с помощью API приема журналов.

Компонент	Function
Регистрация и секрет приложения	Регистрация приложения используется для проверки подлинности вызова API. Оно должно быть предоставлено разрешение на DCR, описанное ниже. Вызов API включает идентификатор приложения (клиента) и идентификатор каталога (клиента) приложения и значение секрета приложения. См. статью "Создание приложения и субъекта-службы Microsoft Entra", которое может получить доступ к ресурсам и создать новый секрет приложения.
Конечная точка сбора данных (DCE)	DCE предоставляет конечную точку для отправки приложения. Один DCE может поддерживать несколько контроллеров домена, поэтому можно использовать существующий DCE, если у вас уже есть один в том же регионе, что и рабочая область Log Analytics. См. статью "Создание конечной точки сбора данных".
Таблица в рабочей области Log Analytics	Прежде чем отправлять данные в рабочую область Log Analytics, таблица в рабочей области Log Analytics должна существовать. Вы можете использовать одну из поддерживаемых таблиц Azure или создать пользовательскую таблицу с помощью любого из доступных методов. Если вы используете портал Azure для создания таблицы, для вас создается DCR, включая преобразование, если это необходимо. При использовании любого другого метода необходимо вручную создать DCR, как описано в следующем разделе. См. статью "Создание настраиваемой таблицы".
Правило сбора данных (DCR)	Azure Monitor использует правило сбора данных (DCR), чтобы понять структуру входящих данных и что с ним делать. Если структура таблицы и входящих данных не совпадают, DCR может включить преобразование для преобразования исходных данных в соответствие с целевой таблицей. Вы также можете использовать преобразование для фильтрации исходных данных и выполнения других вычислений или преобразований. При создании настраиваемой таблицы с помощью портал Azure DCR и преобразования создаются на основе предоставленных примеров данных. Если вы используете существующую таблицу или создаете пользовательскую таблицу с помощью другого метода, необходимо вручную создать DCR с помощью сведений в следующем разделе. После создания DCR необходимо предоставить доступ к нему для приложения, созданного на первом шаге. В меню "Монитор" в портал Azure выберите правила сбора данных, а затем созданный DCR. Выберите контроль доступа (IAM) для DCR, а затем выберите "Добавить назначение роли", чтобы добавить роль издателя метрик мониторинга.

Создание DCR вручную

Если вы отправляете данные в таблицу, которая уже существует, необходимо создать DCR вручную. Начните с примера DCR для API приема журналов и измените следующие параметры в шаблоне. Затем используйте любой из методов, описанных в разделе "Создание и изменение правил сбора данных" в Azure Monitor для создания DCR.

Параметр	Описание
`region`	Регион для создания DCR. Это должно соответствовать региону DCE и рабочей области Log Analytics.
`dataCollectionEndpointId`	Идентификатор ресурса DCE.
`streamDeclarations`	Измените список столбцов на столбцы в входящих данных. Вам не нужно изменять имя потока, так как это просто должно соответствовать `streams` имени в `dataFlows`.
`workspaceResourceId`	Идентификатор ресурса рабочей области Log Analytics. Вам не нужно изменять имя, так как это просто должно соответствовать `destinations` имени в `dataFlows`.
`transformKql`	Запрос KQL, применяемый к входящим данным. Если схема входящих данных соответствует схеме таблицы, можно использовать `source` для преобразования, которое будет передавать входящие данные без изменений. В противном случае используйте запрос, который преобразует данные для сопоставления схемы таблицы.
`outputStream`	Имя таблицы для отправки данных. Для настраиваемой таблицы добавьте префикс Custom-table-name><. Для встроенной таблицы добавьте префикс Microsoft-table-name<>.

Клиентские библиотеки

Помимо вызова REST API, можно использовать следующие клиентские библиотеки для отправки данных в API приема журналов. Для библиотек требуются те же компоненты, которые описаны в разделе "Конфигурация". Примеры использования каждой из этих библиотек см . в примере кода для отправки данных в Azure Monitor с помощью API приема журналов.

Вызов REST API

Чтобы отправить данные в Azure Monitor с помощью вызова REST API, выполните вызов POST по протоколу HTTP. Сведения, необходимые для этого вызова, описаны в этом разделе.

URI конечной точки

URI конечной точки использует следующий формат, где Data Collection Endpoint и DCR Immutable ID определяют DCE и DCR. Неизменяемый идентификатор создается для DCR при его создании. Его можно получить из представления JSON DCR в портал Azure. Stream Name указывает на поток в DCR, который должен поддерживать пользовательские данные.

{Data Collection Endpoint URI}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01

Например:

https://my-dce-5kyl.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-000a00a000a00000a000000aa000a0aa/streams/Custom-MyTable?api-version=2023-01-01

Заголовки

В следующей таблице описаны заголовки для вызова API.

Верхний колонтитул	Обязательное?	Description
Авторизация	Да	Маркер носителя, полученный через поток учетных данных клиента. Используйте значение аудитории токенов для вашего облака: Общедоступное облако Azure — `https://monitor.azure.com` Microsoft Azure, управляемый облаком 21Vianet. `https://monitor.azure.cn` Облако Azure для государственных организаций США — `https://monitor.azure.us`
Тип контента	Да	`application/json`
Content-Encoding	No	`gzip`
x-ms-client-request-id	No	Идентификатор GUID с форматированием строк. Это идентификатор запроса, который может использоваться корпорацией Майкрософт для устранения неполадок.

Текст

Текст вызова включает в себя пользовательские данные, отправляемые в Azure Monitor. Форма данных должна быть массивом JSON с структурой элементов, которая соответствует формату, ожидаемому потоком в DCR. Если требуется отправить один элемент в вызове API, данные должны отправляться в виде массива с одним элементом.

Например:

[
{
    "TimeGenerated": "2023-11-14 15:10:02",
    "Column01": "Value01",
    "Column02": "Value02"
}
]

Убедитесь, что текст запроса правильно закодирован в UTF-8, чтобы предотвратить проблемы с передачей данных.

Пример

Пример кода для отправки данных в Azure Monitor с помощью API приема журналов см. в примере вызова API с помощью PowerShell.

Поддерживаемые таблицы

Данные, отправленные в API приема, можно отправить в следующие таблицы:

Таблицы	Description
Настраиваемые таблицы	Любая настраиваемая таблица, созданная в рабочей области Log Analytics. Целевая таблица должна существовать, прежде чем можно будет отправить в нее данные. Пользовательские таблицы должны иметь суффикс `_CL`.
Таблицы Azure	В настоящее время поддерживаются следующие таблицы Azure. Можно добавить в этот список другие таблицы по мере реализации их поддержки.

ADAssessmentRecommendation
ADSecurityAssessmentRecommendation
ASimAuditEventLogs
ASimAuthenticationEventLogs
ASimDhcpEventLogs
ASimDnsActivityLogs
ASimDnsAuditLogs
ASimFileEventLogs
ASimNetworkSessionLogs
ASimProcessEventLogs
ASimRegistryEventLogs
ASimUserManagementActivityLogs
ASimWebSessionLogs
AWSCloudTrail
AWSCloudWatch
AWSGuardDuty
AWSVPCFlow
AzureAssessmentRecommendation
CommonSecurityLog
DeviceTvmSecureConfigurationAssessment КБ
DeviceTvmSoftwareVulnerabilities КБ
ExchangeAssessmentRecommendation
ExchangeOnlineAssessmentRecommendation
GCPAuditLogs
GoogleCloudSCC
SCCMAssessmentRecommendation
SCOMAssessmentRecommendation
SecurityEvent
SfBAssessmentRecommendation
SfBOnlineAssessmentRecommendation
SharePointOnlineAssessmentRecommendation
SPAssessmentRecommendation
SQLAssessmentRecommendation
служба хранилища Аналитика AccountPropertiesDaily
служба хранилища Аналитика DailyMetrics
служба хранилища Аналитика HourlyMetrics
служба хранилища Аналитика MonthlyMetrics
служба хранилища Аналитика WeeklyMetrics
Syslog
UCClient
UCClientReadinessStatus
UCClientUpdateStatus
UCDeviceAlert
UCDOAggregatedStatus
UCDOStatus
UCServiceUpdateStatus
UCUpdateAlert
WindowsClientAssessmentRecommendation
WindowsEvent
WindowsServerAssessmentRecommendation