通过

Azure Monitor 中的日志引入 API

  • 项目

借助 Azure Monitor 中的日志引入 API，可以使用 REST API 调用或客户端库将数据发送到 Log Analytics 工作区。 API 允许将数据发送到支持的 Azure 表或创建的自定义表。 还可以使用自定义列来扩展 Azure 表的架构，从而接受额外数据。

基本操作

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

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

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

配置

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

注意

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

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

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

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

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

创建 DCR 后，必须为在第一步中创建的应用程序授予对它的访问权限。 在 Microsoft Azure 门户中的“监视”菜单中，选择“数据收集规则”，然后选择创建的 DCR。 为 DCR 选择“访问控制(IAM)”，然后选择“添加角色分配”以添加“监视指标发布者”角色。

终结点

日志引入 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 工作区中创建自定义表时，系统会创建一个可与日志引入 API 一起使用的 DCR。 如果要将数据发送到已存在的表，则必须手动创建 DCR。 从下面的示例 DCR 开始，替换模板中以下参数的值。 使用在 Azure Monitor 中创建和编辑数据收集规则 (DCR) 中所述的任何方法来创建 DCR。

参数 说明
region 要创建 DCR 的区域。 如果你使用 Log Analytics 工作区和 DCE，则它必须与 DCE 的区域相匹配。
dataCollectionEndpointId DCE 的资源 ID。 如果你使用 DCR 引入点，请删除此参数。
streamDeclarations 将列列表更改为传入数据中的列。 无需更改流的名称，因为这只需与 dataFlows 中的 streams 名称匹配。
workspaceResourceId Log Analytics 工作区的资源 ID。 无需更改名称，因为这只需与 dataFlows 中的 destinations 名称匹配。
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。 这些库需要配置中所述的相同组件。 有关使用这些库的示例，请参阅使用日志引入 API 将数据发送到 Azure Monitor 的示例代码。

REST API 调用

若要使用 REST API 调用将数据发送到 Azure Monitor，请通过 HTTP 进行 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。 可以从 Microsoft Azure 门户中 DCR 的概述页检索它。

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

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

标头

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

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

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

Body

调用的正文包括要发送到 Azure Monitor 的自定义数据。 数据的形式必须是 JSON 数组，其项结构与 DCR 中的流预期的格式相匹配。 如果需要在 API 调用中发送单个项，则应将数据作为单项数组发送。

例如：

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

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

示例

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

受支持的表

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

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

注意

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

限制和局限

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

后续步骤