Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
В этой статье показано, как с помощью API сборщика данных HTTP отправлять данные журналов в Azure Monitor из клиента REST API. Здесь также описано, как отформатировать данные, собранные скриптом или приложением, добавить их в запрос и авторизовать этот запрос в Azure Monitor. В этой статье приведены примеры для Azure PowerShell, C# и Python.
Примечание.
API сборщика HTTP-данных Azure Monitor объявлен устаревшим и больше не будет работать с 14.09.2026. Его заменил API обработки журналов. Кроме того, начиная с 1 марта 2026 г. сбор журналов применяет TLS 1.2 или более поздней версии для безопасного взаимодействия. Дополнительные сведения см. в разделе "Безопасные журналы" во время передачи.
Концепции
API сборщика данных HTTP можно использовать для отправки данных журналов в рабочую область Log Analytics, размещенную в Azure Monitor, из любого клиента с поддержкой REST API. Клиентом может быть ранбук в службе автоматизации Azure, который собирает данные управления из Azure или другого облака, или альтернативная система управления, использующая службу Azure Monitor для консолидации и анализа данных журналов.
Все данные в рабочей области Log Analytics хранятся как запись определенного типа. Чтобы отправить данные в API сборщика данных HTTP, их необходимо отформатировать как несколько записей в формате нотаций объектов JavaScript (JSON). При отправке данных в репозитории для каждой записи в полезной нагрузке запроса создается отдельная запись.
Создание запроса
Чтобы использовать API сборщика данных HTTP, необходимо создать запрос POST, содержащий данные для отправки в JSON. В следующих трех таблицах перечислены обязательные атрибуты для каждого запроса. Более подробное описание каждого из атрибутов приводится далее в этой статье.
Запрос URI
| Атрибут | Недвижимость |
|---|---|
| Метод | ПОСТ |
| УРИ | <https://<CustomerId>.ods.opinsights.azure.com/api/logs?api-version=2016-04-01> |
| Тип контента | application/json |
Параметры URI запроса
| Параметр | Описание |
|---|---|
| Идентификатор клиента | Уникальный идентификатор для рабочей области Log Analytics. |
| Ресурс | Имя ресурса API: /api/logs. |
| Версия API | Версия API для использования с этим запросом. В настоящее время это версия 2016-04-01. |
Заголовки запросов
| Заголовок | Описание |
|---|---|
| Авторизация | Подпись авторизации. Далее в этой статье вы найдете сведения о том, как создать заголовок HMAC-SHA256. |
| Тип журнала | Укажите тип записи для отправляемых данных. Он может содержать только буквы, цифры и символ подчеркивания (_) и не может содержать более 100 символов. |
| x-ms-date | Дата обработки запроса в формате RFC 1123 . |
| x-ms-AzureResourceId | Идентификатор ресурса Azure, с которым требуется связать данные. Он заполняет свойство _ResourceId и позволяет включать данные в запросы контекста ресурсов . Если в этом поле не указано значение, данные не будут включаться в запросы resource-context. |
| поле времени генерации | Имя поля данных, содержащее метку времени элемента данных. Если указать поле, его содержимое используется для TimeGenerated. Если это поле не указано, значение по умолчанию для TimeGenerated — это время приема сообщения. Содержимое поля сообщения должно соответствовать формату ISO 8601: YYYY-MM-DDThh:mm:ssZ. Значение времени генерации не может быть старше 2 дней на момент получения или больше, чем на один день в будущем. В таком случае используется время приема сообщения. |
Авторизация
Любой запрос к API сборщика данных HTTP в Azure Monitor должен содержать заголовок авторизации. Чтобы проверить подлинность запроса, подпишите запрос с помощью первичного или вторичного ключа для рабочей области, выполняющей запрос. Затем следует передать подпись как часть запроса.
Вот формат заголовка авторизации:
Authorization: SharedKey <WorkspaceID>:<Signature>
WorkspaceID — это уникальный идентификатор рабочей области Log Analytics. Сигнатура — это хэш-код проверки подлинности сообщений (HMAC), созданный из запроса, а затем вычисляемый с помощью алгоритма SHA256. Затем его можно закодировать с помощью кодировки Base64.
Используйте этот формат для кодирования строки подписи SharedKey :
StringToSign = VERB + "\n" +
Content-Length + "\n" +
Content-Type + "\n" +
"x-ms-date:" + x-ms-date + "\n" +
"/api/logs";
Вот пример строки подписи:
POST\n1024\napplication/json\nx-ms-date:Mon, 04 Apr 2016 08:00:00 GMT\n/api/logs
При наличии строки подписи закодируйте ее с помощью алгоритма HMAC-SHA256 в строке в кодировке UTF-8, а затем закодируйте результат в Base64. Используйте следующий формат:
Signature=Base64(HMAC-SHA256(UTF8(StringToSign)))
Примеры в следующих разделах содержат образец кода, с помощью которого вы сможете создать заголовок авторизации.
Основное содержание запроса
Текст сообщения должен иметь формат JSON. Он должен включать одну или несколько записей с парами “имя-значение” свойств, представленными в приведенном ниже формате. Имя свойства может содержать только буквы, цифры и символ подчеркивания (_).
[
{
"property 1": "value1",
"property 2": "value2",
"property 3": "value3",
"property 4": "value4"
}
]
Вы можете сгруппировать в одном запросе несколько записей, используя следующий формат. Все записи должны принадлежать к одному типу.
[
{
"property 1": "value1",
"property 2": "value2",
"property 3": "value3",
"property 4": "value4"
},
{
"property 1": "value1",
"property 2": "value2",
"property 3": "value3",
"property 4": "value4"
}
]
Тип и свойства записи
Вы определяете тип пользовательской записи при отправке данных через API сборщика данных HTTP в Azure Monitor. В настоящее время нельзя записывать данные в существующие типы записей, созданные другими типами данных и решениями. Azure Monitor считывает входящие данные, а затем создает свойства, которые соответствуют типам данных для введенных значений.
Каждый запрос к API сборщика данных должен содержать заголовок Log-Type с именем типа записи. Суффикс _CL автоматически добавляется в введенное имя, чтобы отличить его от других типов журналов как настраиваемый журнал. Например, если ввести имя MyNewRecordType, Azure Monitor создает запись с типом MyNewRecordType_CL. Это помогает избежать конфликтов между именами типов, создаваемыми пользователями, и теми, что включены в текущие или будущие решения Microsoft.
Чтобы определить тип данных для свойства, Azure Monitor добавляет суффикс к имени свойства. Если свойство содержит значение NULL, свойство не включается в эту запись. В таблице ниже перечислены типы данных свойства и соответствующие суффиксы.
| Тип данных свойства | Суффикс |
|---|---|
| Струна | _s |
| булевый | _b |
| Двойной | _d |
| Дата/время | _t |
| GUID (хранится в виде строки) | _g |
Примечание.
К строковым значениям, по виду напоминающим GUID, добавляется суффикс _g и применяется формат GUID, даже если входное значение не содержит дефисов. Например, значения "8145d822-13a7-44ad-859c-36f31a84f6dd" и "8145d82213a744ad859c36f31a84f6dd" хранятся в виде "8145d822-13a7-44ad-859c-36f31a84f6dd". Единственные отличия между этими строками — суффикс _g в имени и дефисы, которые вставляются, если они не указаны во входных данных.
Тип данных, который Azure Monitor использует для каждого свойства, зависит от того, существует ли тип записи для новой записи.
- Если тип записи не существует, Azure Monitor создает новый, используя определение типа JSON для выбора типа данных для каждого свойства новой записи.
- Если тип записи существует, Azure Monitor пытается создать новую запись на основе существующих свойств. Если тип данных для свойства в новой записи не соответствует существующему типу и не может быть преобразован в него или если запись включает свойство, которое не существует, Azure Monitor создает новое свойство с соответствующим суффиксом.
Например, следующая запись отправки создаст запись с тремя свойствами, number_d, boolean_b и string_s:
Если отправить следующую запись со всеми значениями в строковом формате, свойства не изменятся. Можно преобразовать значения в существующие типы данных.
Но если вы сделаете следующую отправку, Azure Monitor создаст новые свойства boolean_d и string_d. Эти значения преобразовать нельзя.
При отправке следующей записи перед созданием типа записи Azure Monitor создаст запись с тремя свойствами, number_s, boolean_s и string_s. В этой записи каждое начальное значение форматируется как строка:
Зарезервированные свойства
Перечисленные ниже свойства зарезервированы, и их не следует использовать в пользовательских типах записей. Если ваши данные содержат свойства с любым из этих имен, возникнет ошибка.
- арендатор
- TimeGenerated
- RawData
Ограничения данных
На данные, отправленные в API сбора данных Azure Monitor, распространяются определенные ограничения:
- Не более 30 МБ на одну запись в API сборщика данных Azure Monitor. Это ограничение размера для одной публикации. Если данные одной публикации превышают 30 МБ, необходимо разделить данные на меньшие фрагменты и отправить их параллельно.
- Не более 32 КБ для значений полей. Если значение поля превышает 32 КБ, данные будут усечены.
- Рекомендуемое максимальное количество полей для данного типа — 50. Это ограничение введено для удобства поиска и использования.
- Таблицы в рабочих областях Log Analytics поддерживают не более 500 столбцов (в этой статье они называются полями).
- Максимальное число символов в имени столбца — 45.
Коды возврата
Код состояния HTTP 200 означает, что запрос получен для обработки. Такой результат означает, что операция завершена успешно.
Полный набор кодов состояний, которые может возвращать служба, представлен в следующей таблице:
| Код | Состояние | Код ошибки | Описание |
|---|---|---|---|
| 200 | ХОРОШО | Запрос был успешно принят. | |
| 400 | Недопустимый запрос | Неактивный клиент | Рабочая область закрыта. |
| 400 | Недопустимый запрос | Недопустимая версия API | Указанная версия API не распознана службой. |
| 400 | Недопустимый запрос | Недопустимый идентификатор клиента | Указан недопустимый идентификатор рабочей области. |
| 400 | Недопустимый запрос | Неверный формат данных | Был отправлен недопустимый JSON. Текст ответа может содержать дополнительные сведения о том, как устранить ошибку. |
| 400 | Недопустимый запрос | НедопустимыйТипЛога | Указанный тип журнала содержит специальные символы или цифры. |
| 400 | Недопустимый запрос | Отсутствует версия API | Версия API не указана. |
| 400 | Недопустимый запрос | ОтсутствуетТипКонтента | Тип содержимого не указан. |
| 400 | Недопустимый запрос | ОтсутствующийТипЛога | Тип требуемого значения журнала не указан. |
| 400 | Недопустимый запрос | НеподдерживаемыйТипКонтента | Тип контента не был задан для application/json. |
| 403 | Запрещено | НевернаяАвторизация | Службе не удалось проверить подлинность запроса. Проверьте правильность идентификатора и ключа подключения рабочей области. |
| 404 | Не найдено | Указан неправильный URL-адрес либо запрос слишком большой. | |
| 429 | Слишком много запросов | В службу поступает слишком большой объем данных из вашей учетной записи. Повторите запрос позже. | |
| 500 | Внутренняя ошибка сервера | Неопределенная ошибка | Служба обнаружила внутреннюю ошибку. Повторите запрос. |
| 503 | Служба недоступна | Сервис недоступен | Служба сейчас недоступна для получения запросов. Повторите запрос. |
Запрос данных
Чтобы запросить данные, отправленные API сборщика HTTP-данных Azure Monitor, найдите записи, Тип которых совпадает с указанным вами значением LogType, к которому добавлено _CL. Например, если вы использовали MyCustomLog, вы вернете все записи с MyCustomLog_CL.
Примеры запросов
В этом разделе приведены примеры, демонстрирующие отправку данных в API сборщика http-данных Azure Monitor с помощью различных языков программирования.
Для каждого примера задайте переменные в заголовке авторизации, выполнив следующие действия:
- На портале Azure перейдите в свою рабочую область Log Analytics.
- Выберите Агенты.
- Справа от идентификатора рабочей области выберите значок "Копировать ", а затем вставьте идентификатор в качестве значения переменной идентификатора клиента .
- Справа от первичного ключа выберите значок "Копировать ", а затем вставьте идентификатор в качестве значения переменной общего ключа .
Также можно изменить переменные для типа журнала и данных JSON.
# Replace with your Workspace ID
$CustomerId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
# Replace with your Primary Key
$SharedKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# Specify the name of the record type that you'll be creating
$LogType = "MyRecordType"
# Optional name of a field that includes the timestamp for the data. If the time field is not specified, Azure Monitor assumes the time is the message ingestion time
$TimeStampField = ""
# Create two records with the same set of properties to create
$json = @"
[{ "StringValue": "MyString1",
"NumberValue": 42,
"BooleanValue": true,
"DateValue": "2019-09-12T20:00:00.625Z",
"GUIDValue": "9909ED01-A74C-4874-8ABF-D2678E3AE23D"
},
{ "StringValue": "MyString2",
"NumberValue": 43,
"BooleanValue": false,
"DateValue": "2019-09-12T20:00:00.625Z",
"GUIDValue": "8809ED01-A74C-4874-8ABF-D2678E3AE23D"
}]
"@
# Create the function to create the authorization signature
Function Build-Signature ($customerId, $sharedKey, $date, $contentLength, $method, $contentType, $resource)
{
$xHeaders = "x-ms-date:" + $date
$stringToHash = $method + "`n" + $contentLength + "`n" + $contentType + "`n" + $xHeaders + "`n" + $resource
$bytesToHash = [Text.Encoding]::UTF8.GetBytes($stringToHash)
$keyBytes = [Convert]::FromBase64String($sharedKey)
$sha256 = New-Object System.Security.Cryptography.HMACSHA256
$sha256.Key = $keyBytes
$calculatedHash = $sha256.ComputeHash($bytesToHash)
$encodedHash = [Convert]::ToBase64String($calculatedHash)
$authorization = 'SharedKey {0}:{1}' -f $customerId,$encodedHash
return $authorization
}
# Create the function to create and post the request
Function Post-LogAnalyticsData($customerId, $sharedKey, $body, $logType)
{
$method = "POST"
$contentType = "application/json"
$resource = "/api/logs"
$rfc1123date = [DateTime]::UtcNow.ToString("r")
$contentLength = $body.Length
$signature = Build-Signature `
-customerId $customerId `
-sharedKey $sharedKey `
-date $rfc1123date `
-contentLength $contentLength `
-method $method `
-contentType $contentType `
-resource $resource
$uri = "https://" + $customerId + ".ods.opinsights.azure.com" + $resource + "?api-version=2016-04-01"
$headers = @{
"Authorization" = $signature;
"Log-Type" = $logType;
"x-ms-date" = $rfc1123date;
"time-generated-field" = $TimeStampField;
}
$response = Invoke-WebRequest -Uri $uri -Method $method -ContentType $contentType -Headers $headers -Body $body -UseBasicParsing
return $response.StatusCode
}
# Submit the data to the API endpoint
Post-LogAnalyticsData -customerId $customerId -sharedKey $sharedKey -body ([System.Text.Encoding]::UTF8.GetBytes($json)) -logType $logType
Альтернативы и рекомендации
Хотя API сборщика данных покрывает большинство потребностей по сбору произвольных данных в журналы Azure, вам может понадобиться альтернативный подход, чтобы обойти некоторые ограничения API. В следующей таблице перечислены возможные варианты, включая основные рекомендации:
| Альтернатива | Описание | Наиболее подходит для |
|---|---|---|
| Пользовательские события: прием с использованием встроенного SDK в Application Insights | Служба Application Insights, обычно инструментируемая через пакет SDK в приложении, дает возможность отправлять собственные данные через пользовательские события. |
|
| API сборщика данных в журналах Azure Monitor | API сборщика данных в журнале Azure Monitor — это полностью открытый способ приема данных. Ему можно передавать любые данные, отформатированные в виде объекта JSON. После отправки они обрабатываются и становятся доступны в журналах Monitor для корреляции с другими данными из этих журналов или другими данными Application Insights. Вы можете без особого труда отправить данные в виде файлов в хранилище BLOB-объектов Azure, где эти файлы будут обработаны и отправлены в Log Analytics. Пример реализации см. в разделе "Создание конвейера данных" с помощью API сборщика данных. |
|
| Обозреватель данных Azure | Azure Data Explorer — это общедоступная платформа данных, на основе которой работают аналитика Application Insights и журналы Azure Monitor. Использование платформы данных в первоначальном виде обеспечивает полную гибкость (однако требует больших трудозатрат для управления) при настройке кластеров (управление доступом на основе ролей (RBAC) в Kubernetes, скорости хранения, схемы и т. д.). Azure Data Explorer предоставляет множество параметров приема, включая CSV,TSV и JSON-файлы . |
|
Дальнейшие действия
- Используйте API поиска по журналам для получения данных из рабочей области Log Analytics.
- Узнайте больше о том, как с помощью рабочего процесса Logic Apps создать конвейер данных с использованием API сборщика данных для Azure Monitor.