通过

使用 HTTP 数据收集器 API 将日志数据发送到 Azure Monitor （已弃用）

  • 项目

本文介绍如何使用 HTTP 数据收集器 API 从 REST API 客户端将日志数据发送到 Azure Monitor。 本文介绍如何设置脚本或应用程序收集的数据的格式，将其包含在请求中，并让 Azure Monitor 授权该请求。 我们提供了 Azure PowerShell、C# 和 Python 的示例。

注意

Azure Monitor HTTP 数据收集器 API 已弃用，自 2026 年 9 月 14 日起将不再正常运行。 它已被 日志引入 API替换。

概念

可以使用 HTTP 数据收集器 API 从任何可调用 REST API 的客户端将日志数据发送到 Azure Monitor 中的 Log Analytics 工作区。 客户端可能是在 Azure 自动化中运行的运行手册，用于从 Azure 或其他云收集管理数据；也可能是使用 Azure Monitor 合并和分析日志数据的另一种管理系统。

Log Analytics 工作区中的所有数据都存储为具有特定记录类型的记录。 将数据格式化为以 JavaScript 对象表示法（JSON）中的多个记录发送到 HTTP 数据收集器 API。 提交数据时，将为请求有效负载中的每个记录在存储库中创建单个记录。

显示 HTTP 数据收集器概述的屏幕截图。

创建请求

若要使用 HTTP 数据收集器 API，请创建一个 POST 请求，其中包含要在 JSON 中发送的数据。 接下来的三个表列出了每个请求所需的属性。 本文稍后将更详细地介绍每个属性。

请求 URI

属性 财产
方法 发布
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 标头。
Log-Type 指定要提交的数据的记录类型。 它只能包含字母、数字和下划线（_）字符，并且不能超过 100 个字符。
x-ms-date 以 RFC 1123 格式处理请求的日期。
x-ms-AzureResourceId 数据应与之关联的 Azure 资源的资源 ID。 它填充 _ResourceId 属性，并允许数据包含在 资源上下文 查询中。 如果未指定此字段，数据将不会包含在资源上下文查询中。
时间生成字段 数据中包含数据项时间戳的字段的名称。 如果指定了字段，则会使用其内容来生成 TimeGenerated。 如果未指定此字段，则 TimeGenerated 的默认值是引入消息的时间。 消息字段的内容应遵循 ISO 8601 格式 YYYY-MM-DDThh：mm：ssZ。 “生成时间”值不能早于接收时间 2 天前或超过接收时间的一天后。 在这种情况下，将使用消息接收或处理的时间。

授权

对 Azure Monitor HTTP 数据收集器 API 的任何请求都必须包含授权标头。 若要对请求进行身份验证，请使用发出请求的工作区的主密钥或辅助密钥对请求进行签名。 然后，将此签名作为请求的一部分传递。

下面是授权标头的格式：

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

如果具有签名字符串，请使用 UTF-8 编码字符串上的 HMAC-SHA256 算法对其进行编码，然后将结果编码为 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"
    }
]

记录类型和属性

通过 Azure Monitor HTTP 数据收集器 API 提交数据时，可以定义自定义记录类型。 目前，无法将数据写入其他数据类型和解决方案创建的现有记录类型。 Azure Monitor 读取传入数据，然后创建与输入的值的数据类型匹配的属性。

对数据收集器 API 的每个请求都必须包含一个 日志类型 标头，其中包含记录类型的名称。 输入的名称会自动附加后缀 _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 的屏幕截图。

保留属性

以下属性是保留的，不应在自定义记录类型中使用。 如果有效负载包含以下任一属性名称，则会收到错误：

  • 租户
  • TimeGenerated
  • RawData

数据限制

发布到 Azure Monitor 数据收集 API 的数据受特定的约束:

  • 发布到 Azure Monitor 数据收集器 API 的每个帖子最多 30 MB。 这是单个帖子的大小限制。 如果单个帖子中的数据超过 30 MB，则应将数据拆分为较小的区块并同时发送它们。
  • 字段值的最大大小为 32 KB。 如果字段值大于 32 KB，将截断数据。
  • 建议针对某一给定类型最多 50 个字段。 从可用性和搜索体验的角度来看，这是一个实际限制。
  • Log Analytics 工作区中的表仅支持最多 500 列（本文中称为字段）。
  • 列名称最多为 45 个字符。

返回代码

HTTP 状态代码 200 表示已收到请求进行处理。 这表示操作已成功完成。

下表中列出了服务可能返回的完整状态代码集：

代码 地位 错误代码 描述
200 还行 请求已成功接受。
400 请求错误 非活跃客户 工作区已关闭。
400 请求错误 无效的API版本 服务无法识别指定的 API 版本。
400 请求错误 无效的客户ID 指定的工作区 ID 无效。
400 请求错误 无效数据格式 提交的 JSON 无效。 响应正文可能包含有关如何解决错误的详细信息。
400 请求错误 无效日志类型 指定的日志类型包含特殊字符或数字。
400 请求错误 缺少Api版本 未指定 API 版本。
400 请求错误 缺少内容类型 未指定内容类型。
400 请求错误 缺少日志类型 未指定所需的值日志类型。
400 请求错误 不支持的内容类型 内容类型未设置为 application/json。
403 禁止 授权无效 服务无法对请求进行身份验证。 验证工作区 ID 和连接密钥是否有效。
404 找不到 提供的 URL 不正确或请求太大。
429 请求过多 该服务正在处理来自您帐户的高量数据。 请稍后重试请求。
500 内部服务器错误 未指定错误 服务遇到内部错误。 请重试请求。
503 服务不可用 服务不可用 服务当前无法接收请求。 请重试请求。

查询数据

若要查询由 Azure Monitor HTTP 数据收集器 API 提交的数据，请搜索记录，其中其 类型 的值等于您指定的 LogType，并追加 _CL。 例如，如果使用 MyCustomLog，则会返回所有包含 MyCustomLog_CL的记录。

示例请求

本部分演示了如何使用各种编程语言将数据提交到 Azure Monitor HTTP 数据收集器 API 的示例。

对于每个示例，通过执行以下操作来设置授权标头的变量：

  1. 在 Azure 门户中，找到 Log Analytics 工作区。
  2. 选择 代理。
  3. 在 工作区 ID右侧，选择 复制 图标，然后将此 ID 作为 客户 ID 变量的值进行粘贴。
  4. 在主键右侧，选择 复制 图标，然后将 ID 粘贴为 共享密钥 变量的值。

或者，可以更改日志类型和 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 的某些限制。 下表列出了选项，包括主要注意事项：

备选 描述 最适合
自定义事件：Application Insights 中基于原生 SDK 的引入 Application Insights 通常通过应用程序中的 SDK 进行检测，使你能够通过自定义事件发送自定义数据。
  • 在应用程序中生成的数据，但不属于 SDK 通过默认数据类型（如请求、依赖关系、异常等）捕获的数据。
  • 与 Application Insights 中的其他应用程序数据最相关的数据。
Azure Monitor 日志中的数据收集器 API Azure Monitor 日志中的数据收集器 API 是引入数据的完全开放方式。 JSON 对象中格式化的任何数据都可以在此处发送。 发送后，它会在监视器日志中进行处理并使其可用，以便与监视器日志中的其他数据或其他 Application Insights 数据相关联。

将数据作为文件上传到 Azure Blob 存储相当容易，在这里文件将被处理，然后上传到 Log Analytics。 有关示例实现，请参阅 使用数据收集器 API创建数据管道。
  • 不一定是由使用 Application Insights 进行监控的应用程序内生成的数据。
    示例包括查找和事实数据表、引用数据、预聚合统计信息等。
  • 将与其他 Azure Monitor 数据（Application Insights、其他 Monitor 日志数据类型、Cloud Defender、容器洞察和虚拟机等）交叉比对的数据。
Azure 数据资源管理器 Azure 数据资源管理器现已公开发布，是支持 Application Insights Analytics 和 Azure Monitor 日志的数据平台。 通过使用原始形式的数据平台，您可以对群集（如 Kubernetes 基于角色的访问控制（RBAC）、保留率、架构等）拥有完全的灵活性，但这需要额外的管理工作。 Azure 数据资源管理器提供了许多引入选项，包括 CSV、TSV 和 JSON 文件。
  • 数据不会与 Application Insights 或 Monitor 日志中的任何其他数据相关联。
  • 需要目前在 Azure Monitor 日志中不可用的高级摄取或处理功能的数据。

后续步骤

  • 使用 日志搜索 API 从 Log Analytics 工作区检索数据。
  • 详细了解如何使用逻辑应用工作流向 Azure Monitor 使用数据收集器 API 创建数据管道 。