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


Отправка данных журнала в Azure Monitor с помощью API сборщика данных HTTP (не рекомендуется)

В этой статье показано, как с помощью API сборщика данных HTTP отправлять данные журналов в Azure Monitor из клиента REST API. Здесь также описано, как отформатировать данные, собранные скриптом или приложением, добавить их в запрос и авторизовать этот запрос в Azure Monitor. В этой статье приведены примеры для Azure PowerShell, C# и Python.

Примечание.

API сборщика http-данных Azure Monitor устарел и больше не будет работать с 9.14.2026. Он заменен API приема журналов.

Основные понятия

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

Все данные в рабочей области Log Analytics хранятся как запись определенного типа. Чтобы отправить данные в API сборщика данных HTTP, их необходимо отформатировать как несколько записей в формате нотаций объектов JavaScript (JSON). При отправке данных в репозитории для каждой записи в запрошенных полезных данных создается отдельная запись.

Снимок экрана, иллюстрирующий общие сведения о сборщике данных HTTP.

Создание запроса

Чтобы использовать API сборщика данных HTTP, необходимо создать запрос POST, содержащий данные для отправки в JSON. В следующих трех таблицах перечислены обязательные атрибуты для каждого запроса. Более подробное описание каждого из атрибутов приводится далее в этой статье.

URI запроса

Атрибут Свойство
Способ POST
URI-адрес https://<CustomerId>.ods.opinsights.azure.com/api/logs?api-version=2016-04-01
Content type application/json

Параметры URI запроса

Параметр Описание
CustomerID Уникальный идентификатор для рабочей области Log Analytics.
Ресурс Имя ресурса API: /api/logs.
Версия API Версия API для использования с этим запросом. В настоящее время это версия 2016-04-01.

Заголовки запросов

Верхний колонтитул Description
Авторизация Подпись авторизации. Далее в этой статье вы найдете сведения о том, как создать заголовок HMAC-SHA256.
Log-Type Укажите тип записи для отправляемых данных. Он может содержать только буквы, цифры и символ подчеркивания (_) и не может содержать более 100 символов.
x-ms-date Дата обработки запроса в формате RFC 1123 .
x-ms-AzureResourceId Идентификатор ресурса Azure, с которым требуется связать данные. Это значение присваивается свойству _ResourceId и дает возможность включать данные в запросы resource-context. Если в этом поле не указано значение, данные не будут включаться в запросы resource-context.
time-generated-field Имя поля данных, содержащее метку времени элемента данных. Если вы укажете здесь поле, его содержимое будет использоваться как значение параметра TimeGenerated. Если это поле не указано, по умолчанию для TimeGenerated будет использоваться время приема сообщения. Содержимое поля сообщения должно соответствовать формату ISO 8601: YYYY-MM-DDThh:mm:ssZ. Значение time Generated не может быть старше 2 дней до получения времени или более дня в будущем. В таком случае используется время приема сообщения.

Авторизация

Любой запрос к API сборщика данных HTTP в Azure Monitor должен содержать заголовок авторизации. Чтобы проверить подлинность запроса, подпишите запрос с помощью первичного или вторичного ключа для рабочей области, выполняющей запрос. Затем следует передать подпись как часть запроса.

Вот формат заголовка авторизации:

Authorization: SharedKey <WorkspaceID>:<Signature>

WorkspaceID — это уникальный идентификатор для рабочей области Log Analytics. Signature — это код проверки подлинности сообщения на основе хэша (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:

Снимок экрана с образцом записи 1.

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

Снимок экрана с образцом записи 2.

Если после этого вы отправите следующую запись, Azure Monitor создаст новые свойства boolean_d и string_d. Эти значения преобразовать нельзя.

Снимок экрана с образцом записи 3.

Если вы теперь отправите следующую запись, перед созданием типа записи, Azure Monitor создаст запись с тремя свойствами: number_s, boolean_s и string_s. В этой записи каждое начальное значение форматируется как строка:

Снимок экрана с образцом записи 4.

Зарезервированные свойства

Перечисленные ниже свойства зарезервированы, и их не следует использовать в пользовательских типах записей. Если полезные данные содержат свойства с каким-либо из этих имен, возникнет ошибка:

  • tenant
  • TimeGenerated
  • RawData

Ограничения данных

На данные, отправленные в API сбора данных Azure Monitor, распространяются определенные ограничения:

  • Не более 30 МБ на одну запись в API сборщика данных Azure Monitor. Это ограничение размера для одной публикации. Если данные одной публикации превышают 30 МБ, необходимо разделить данные на меньшие фрагменты и отправить их параллельно.
  • Не более 32 КБ для значений полей. Если значение поля превышает 32 КБ, данные будут усечены.
  • Рекомендуемое максимальное количество полей для данного типа — 50. Это ограничение введено для удобства поиска и использования.
  • Таблицы в рабочих областях Log Analytics поддерживают не более 500 столбцов (в этой статье они называются полями).
  • Максимальное число символов в имени столбца — 45.

Коды возврата

Код состояния HTTP 200 означает, что запрос получен для обработки. Такой результат означает, что операция завершена успешно.

Полный набор кодов состояний, которые может возвращать служба, представлен в следующей таблице:

Код Состояние Код ошибки Description
200 OK Запрос был успешно принят.
400 Недопустимый запрос InactiveCustomer Рабочая область закрыта.
400 Недопустимый запрос InvalidApiVersion Указанная версия API не распознана службой.
400 Недопустимый запрос InvalidCustomerId Указан недопустимый идентификатор рабочей области.
400 Недопустимый запрос InvalidDataFormat Отправлены недопустимые данные JSON. Текст ответа может содержать дополнительные сведения о том, как устранить ошибку.
400 Недопустимый запрос InvalidLogType Указанный тип журнала содержит специальные символы или цифры.
400 Недопустимый запрос MissingApiVersion Версия API не указана.
400 Недопустимый запрос MissingContentType Тип содержимого не указан.
400 Недопустимый запрос MissingLogType Обязательное значение типа журнала не указано.
400 Недопустимый запрос UnsupportedContentType Для типа содержимого не было задано значение application/json.
403 Запрещено InvalidAuthorization Службе не удалось проверить подлинность запроса. Проверьте правильность идентификатора и ключа подключения рабочей области.
404 Не найдено Указан неправильный URL-адрес либо запрос слишком большой.
429 Слишком много запросов В службу поступает слишком большой объем данных из вашей учетной записи. Повторите запрос позже.
500 Внутренняя ошибка сервера UnspecifiedError Служба обнаружила внутреннюю ошибку. Повторите запрос.
503 Служба недоступна ServiceUnavailable Служба сейчас недоступна для получения запросов. Повторите запрос.

Запрос данных

Чтобы выполнить запрос данных, отправленных через API сборщика данных HTTP в Azure Monitor, найдите записи, Тип которых равен указанному вами значению LogType и к которым добавлен суффикс _CL. Например, если вы использовали значение MyCustomLog, будут возвращены все записи с типом MyCustomLog_CL.

Примеры запросов

В этом разделе приведены примеры, демонстрирующие отправку данных в API сборщика http-данных Azure Monitor с помощью различных языков программирования.

Для каждого примера задайте переменные в заголовке авторизации, выполнив следующие действия:

  1. На портале Azure перейдите в свою рабочую область Log Analytics.
  2. Выберите агенты.
  3. Справа от идентификатора рабочей области щелкните значок Копировать и вставьте идентификатор как значение переменной CustomerID.
  4. Справа от первичного ключа щелкните значок Копировать и вставьте идентификатор как значение переменной SharedKey.

Также можно изменить переменные для типа журнала и данных 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. В следующей таблице перечислены возможные варианты, включая основные рекомендации:

Альтернатива Description Рабочие нагрузки
Пользовательские события: собственные средства приема на базе пакета SDK в Application Insights Служба Application Insights, обычно инструментируемая через пакет SDK в приложении, дает возможность отправлять собственные данные через пользовательские события.
  • Данные, которые создаются в приложении, но не распознаются пакетом SDK как относящиеся к одному из стандартных типов данных (запросы, зависимости, исключения и т. д.).
  • Данные, которые чаще всего коррелируют с данными из других приложений в Application Insights
API сборщика данных в журналах Azure Monitor API сборщика данных в журналах Azure Monitor — это универсальное средство приема данных. Ему можно передавать любые данные, отформатированные в виде объекта JSON. После отправки они обрабатываются и становятся доступны в журналах Monitor для корреляции с другими данными из этих журналов или другими данными Application Insights.

Вы можете без особого труда отправить данные в виде файлов в хранилище BLOB-объектов Azure, где эти файлы будут обработаны и отправлены в Log Analytics. Пример реализации см. в разделе Создание конвейера данных с помощью API сборщика данных.
  • Данные, которые не обязательно были созданы в приложении, инструментированном в Application Insights.
    Примеры включают таблицы подстановок и фактов, эталонные данные, предварительную статистику и т. д.
  • Данные, которые имеют перекрестные ссылки на другие данные Azure Monitor (сведения Application Insights, другие типы данных журналов Monitor, данные Defender для облака, аналитические сведения о контейнерах или виртуальных машинах и т. д.).
Обозреватель данных Azure Azure Data Explorer — это общедоступная платформа данных, на основе которой работают аналитика Application Insights и журналы Azure Monitor. Использование платформы данных в первоначальном виде обеспечивает полную гибкость (однако требует больших трудозатрат для управления) при настройке кластеров (управление доступом на основе ролей (RBAC) в Kubernetes, скорости хранения, схемы и т. д.). Azure Data Explorer предоставляет множество вариантов приема данных, например в виде файлов CSV, TSV и JSON.
  • Данные, которые не будут коррелировать с какими-либо другими данными в Application Insights или журналах Monitor.
  • Данные, для обработки которых необходимы продвинутые функции приема или обработки, недоступные в журналах Azure Monitor на данный момент.

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