Compartilhar via

日志引入 API 在 Azure Monitor 中

使用 Azure Monitor 中的日志引入 API，可以使用 REST API 调用或 client 库将数据发送到Log Analytics工作区。 API 允许您将数据发送到受支持的 Azure 表或您创建的自定义表。 可以通过为 Azure 表的架构添加自定义列来接受更多数据。

重要

从 2026 年 3 月 1 日起， 日志引入 API 将强制实施 TLS 1.2 或更高版本的连接。 有关详细信息，请参阅传输中的安全日志数据。

基本操作

可以从任何可以调用 REST API 的应用程序将数据发送到日志引入 API。 这可能是你创建的自定义应用程序，也可能是了解如何将数据发送到 API 的应用程序或代理。 它指定数据收集规则 (DCR)，其中包括目标表和工作区，以及有权访问指定 DCR 的应用注册的凭据。 它将数据发送到 DCR 指定的终结点，而如果使用专用链接，则发送到数据收集终结点 (DCE)。

应用程序发送到 API 的数据必须采用 JSON 格式，并匹配 DCR 所需的结构。 这些数据不一定需要匹配目标表的结构，因为 DCR 可以包含转换，以将这些数据转换为匹配该表的结构。 你可以通过修改 DCR 来修改目标表和工作区，无需对 API 调用或源数据做出任何更改。

显示日志引入 API 概述的关系图。

配置

下表描述了Azure中必须配置的每个组件，然后才能使用日志引入 API。

注意

有关自动配置这些组件的 PowerShell 脚本，请参阅 Sample 代码，使用日志引入 API 将数据发送到Azure Monitor。

组件 函数
应用注册和机密 应用程序注册用于对 API 调用进行身份验证。 必须向其授予对下面所述的 DCR 的权限。 API 调用包括应用程序的“应用程序（客户端）ID”和“目录（租户）ID”，以及应用程序机密的“值”。

请参阅 创建可以访问资源的Microsoft Entra应用程序和服务主体和创建新的应用程序机密。
Log Analytics 工作区中的表 必须先存在Log Analytics工作区中的表，然后才能将数据发送到该工作区。 可以使用其中一个 受支持的 Azure 表，或者使用任何可用的方法创建自定义表。 如果您使用 Azure 门户来创建表，那么系统将为您创建 DCR，并在需要时包括转换。 使用任何其他方法时，需要按照下一部分所述手动创建 DCR。

请参阅创建自定义表。
数据收集规则 (DCR) Azure Monitor使用 Data 收集规则 （DCR）来了解传入数据的结构及其用途。 如果表的结构和传入数据不匹配，则 DCR 可以包含转换，以将源数据转换为匹配目标表的结构。 还可通过转换来筛选源数据并执行任何其他计算或转换。

如果使用 Azure 门户创建自定义表，将根据提供的示例数据创建 DCR 和转换。 如果使用现有表或使用其他方法创建自定义表，则必须使用以下部分中的详细信息手动创建 DCR。

创建 DCR 后，必须为在第一步中创建的应用程序授予对它的访问权限。 在 Azure 门户中的 Monitor 菜单中，选择 Data 集合规则，然后选择创建的 DCR。 选择 DCR 的 Access Control （IAM），然后选择 Add 角色分配以添加 Monitoring Metrics Publisher 角色。

终结点

日志引入 API 的 REST API 端点可以是数据收集终结点 (DCE) 或 DCR 日志引入终结点。

创建用于直接引入的 DCR 时，会生成 DCR 日志引入终结点。 若要检索此终结点，请在Azure门户中的 JSON 视图中打开 DCR。 可能需要将 API 版本更改为要显示的终结点的最新版本。

显示 DCR 中的日志引入终结点的屏幕截图。

仅当使用 专用链接连接到 Log Analytics 工作区或者 DCR 中不包含日志引入终结点时，才需要 DCE。 如果使用较旧的 DCR，或者创建了不带参数的 "kind": "Direct" DCR，则可能是这种情况。 有关更多详细信息，请参阅下面的“数据收集规则 (DCR)”。

注意

logsIngestion 属性于 2024 年 3 月 31 日添加。 在此日期之前，日志引入 API 需要 DCE。 不能将终结点添加到现有 DCR，但可以将任何现有 DCR 与现有 DCE 一起使用。 如果要移动到 DCR 终结点，则必须创建新的 DCR 来替换现有 DCR。 具有终结点的 DCR 也可以使用 DCE。 在这种情况下，您可以为使用 DCR 的每个客户端选择是使用 DCE 终结点还是 DCR 终结点。

数据收集规则 (DCR)

使用 Azure 门户在 Log Analytics 工作区中创建自定义表时，会自动为您创建一个可用于 Logs 引入 API 的 DCR。 如果要将数据发送到已存在的表，则必须手动创建 DCR。 从下面的示例 DCR 开始，替换模板中以下参数的值。 使用 Azure Monitor0 中创建和编辑数据收集规则（DCR）中所述的任何方法来创建 DCR。

参数 说明
region 要创建 DCR 的区域。 这必须与 Log Analytics 工作区的区域以及 DCE 匹配（如果使用）。
dataCollectionEndpointId DCE 的资源 ID。 如果你使用 DCR 引入点，请删除此参数。
streamDeclarations 将字段列表更改为传入数据中的字段。 无需更改流的名称，因为这只需与 streams 中的 dataFlows 名称匹配。
workspaceResourceId Log Analytics工作区的资源 ID。 无需更改名称，因为这只需与 destinations 中的 dataFlows 名称匹配。
transformKql 要应用于传入数据的 KQL 查询。 如果传入数据的架构与表的架构匹配，则可以对转换使用 source，该转换将原封不动地传递传入数据。 否则，请使用查询将数据转换为匹配目标表架构。
outputStream 要发送数据的表的名称。 对于自定义表，请添加前缀 Custom-<table-name>。 对于内置表，请添加前缀 Microsoft-<table-name>。 
{
    "location": "chinanorth",
    "dataCollectionEndpointId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-resource-group/providers/Microsoft.Insights/dataCollectionEndpoints/dce-chinanorth",
    "kind": "Direct",
    "properties": {
        "streamDeclarations": {
            "Custom-MyTable": {
                "columns": [
                    {
                        "name": "Time",
                        "type": "datetime"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "AdditionalContext",
                        "type": "string"
                    }
                ]
            }
        },
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/cefingestion/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "LogAnalyticsDest"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Custom-MyTable"
                ],
                "destinations": [
                    "LogAnalyticsDest"
                ],
                "transformKql": "source",
                "outputStream": "Custom-MyTable_CL"
            }
        ]
    }
}

客户端库

除了进行 REST API 调用之外，还可以使用以下客户端库将数据发送到日志引入 API。 这些库需要配置中所述的相同组件。 有关使用这些库的示例，请参阅 Sample 代码，使用日志引入 API 将数据发送到Azure Monitor。

REST API 调用

若要使用 REST API 调用将数据发送到Azure Monitor，请通过 HTTPS 进行 POST 调用。 本节描述了此调用所需的详细信息。

URI

URI 包括区域、DCE 或 DCR 引入终结点、DCR ID 和流名称。 它还指定 API 版本。

URI 使用以下格式。

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

例如：

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

在创建 DCR 时会生成 DCR Immutable ID。 可以从 Azure 门户中 DCR 的 Overview 页面检索它。

显示不可变 ID 的数据收集规则的屏幕截图。

Stream Name 指应处理自定义数据的 DCR 中的流。

请求标头

下表描述了 API 调用的请求标头。

标题 必需？ 说明
授权 是 通过客户端凭据流获取的持有者令牌。 使用云的令牌受众值（范围）：

由世纪互联云运营的 Microsoft Azure - https://monitor.azure.cn
内容类型（Content-Type） 是 application/json
内容编码 否 gzip
x-ms-client-request-id 否 字符串格式的 GUID。 这是 Microsoft 可用于任何故障排除目的的请求 ID。

请求主体

调用正文包括要发送到Azure Monitor的自定义数据。 数据的形式必须是 JSON 数组，其项结构与 DCR 中的流预期的格式相匹配。 下面是单项数组的示例。

例如：

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

确保请求正文在 UTF-8 中正确编码，以防止数据传输出现问题。

示例

有关使用 PowerShell 调用 API 的示例，请参阅 Sample 代码，使用日志引入 API 将数据发送到Azure Monitor。

受支持的表

发送到引入 API 的数据可以发送到下表：

表 说明
自定义表 在Log Analytics工作区中创建的任何自定义表。 目标表必须先存在，然后才能向它发送数据。 自定义表必须具有 _CL 后缀。
Azure表 目前支持以下Azure表。 其他表可能会添加到此列表中，随着对它们的支持功能得到实现。

注意

列名必须以字母开头，最多可包含 45 个字母数字字符和下划线 (_)。 _ResourceId、id、_SubscriptionId、TenantId、Type、UniqueId和Title保留列名称。 添加到Azure表的自定义列必须具有后缀 _CF。

限制和局限

有关与日志引入 API 相关的限制，请参阅 Azure Monitor 服务限制。

后续步骤

  • Last updated on