从 HTTP 数据收集器 API 迁移到日志引入 API

HTTP 数据收集器 API 位于弃用路径上。 对旧数据收集器 API 的支持将于 2026 年 9 月 14 日结束。 迁移到 日志引入 API，该 API 在引入日志和管理 表方面具有更高的处理能力和灵活性。

本文介绍两个 API 之间的差异以及如何迁移到日志引入 API。

日志引入 API 的优点

日志引入 API 比数据收集器 API 具有以下优势：

• 支持 转换，使你可以在将数据引入目标表之前对其进行修改，包括筛选和数据操作。
• 让你能够将数据发送到多个目标。
• 允许管理目标表架构，包括列名，以及源数据架构更改时是否向目标表添加新列。
• 支持基于角色的访问控制（RBAC），按数据收集规则和身份限制数据引入权限。

先决条件

若要完成此迁移，需要：

• Log Analytics 工作区，你在其中至少拥有参与者权限。
• 在 Log Analytics 工作区中创建数据收集规则的权限。
• 对 API 调用进行身份验证的 Microsoft Entra 应用程序或任何其他资源管理器身份验证方案。

所需的权限

日志引入 API 使用通过 Microsoft Entra 提供的基于 OAuth 的身份验证（适用于应用注册或托管身份），以及以数据收集规则（DCR）为作用域的 RBAC。 将应用程序权限授予 DCR，并使用数据收集终结点 (DCE) 或 DCR 日志引入终结点来发送引入请求。

创建日志引入 API 所需的新资源

日志引入 API 要求创建两种类型的资源，HTTP 数据收集器 API 不需要：

• 数据收集终结点，用于将收集的数据引入管道进行处理。 （可选）使用 DCR 引入终结点 进行直接引入，而无需创建单独的 DCE。
• 数据收集规则，用于定义 数据转换 和接收引入数据的目标表。

迁移现有自定义表或创建新表

如果您有一个现有的自定义表，并且当前通过数据收集器 API 向其发送数据，则您可以选择：

• 迁移表并切换到日志引入 API。
• 保留现有表和数据，并新建一个表，以便使用日志引入 API 将数据导入其中。 准备就绪后，请删除旧表。
• （不建议）迁移表，但仍使用旧数据收集器 API。 对现有数据类型的更改和对现有数据收集器 API 自定义表的多个架构更改可能会导致错误。

标识经典自定义表

若要确定哪些表使用数据收集器 API，请查看表属性。 使用数据收集器 API 或通过旧版 Log Analytics 代理 (MMA) 引入数据的表，其 Type 属性显示为 自定义表(经典)。

迁移注意事项

Microsoft Sentinel 连接器正逐步迁移到可通过内容中心获取的无代码连接器框架 (CCF) 连接器。 这些 CCF 连接器将 DCR 与日志引入 API 配合使用。 此方法提供受 DCR 管理的架构控制，应用转换来实现规范化，与旧数据收集器 API 相比提高了可靠性和可伸缩性。 迁移可能会引入新的或更新的表名称和架构。 使用旧版 HTTP 数据收集器 API 和新 CCF 连接器的旧Azure Functions连接器可能会在过渡期间暂时共存。

迁移 Sentinel 连接器时，您必须更新相关依赖项（分析规则、搜寻查询、工作簿、剧本、分析器），使其引用任何新的由 CCF 提供支持的表或已更改的架构。 验证和更新 KQL 查询、警报和内容包，以防止在迁移后引入或检测间隙。

下表汇总了每个选项的注意事项：

将表从 V1 转换为 V2

若要将使用数据收集器 API（V1）的表转换为数据收集规则和日志引入 API（V2），请对表运行迁移操作。 此调用是幂等的，因此如果该表已被转换，则不会产生任何影响。

az monitor log-analytics workspace table migrate \
  --resource-group "myResourceGroup" \
  --workspace-name "myWorkspace" \
  --table-name "myTable_CL"

$migrateTableParams = @{
    ResourceGroupName = 'myResourceGroup'
    WorkspaceName     = 'myWorkspace'
    TableName         = 'myTable_CL'
}

Invoke-AzOperationalInsightsMigrateTable @migrateTableParams

POST https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/tables/{tableName}/migrate?api-version=2025-02-01
Authorization: Bearer {accessToken}
Content-Type: application/json

该 migrate 操作启用表上所有基于 DCR 的自定义日志功能。 如果数据收集器 API 继续将数据引入现有列，则不会创建任何新列。 以前定义的任何 自定义字段 都停止获取新数据。 不要通过修改架构来创建新列，否则 Data Collector API 将停止向整个表采集数据。 应用 工作区转换 将表迁移到 DCR，以延迟切换到日志引入 API。

减少每个调用的数据大小

日志引入 API 允许每次调用最多发送 1 MB 的压缩或未压缩数据。 如果需要发送超过 1 MB 的数据，可并行发送多个调用。 此限制不同于数据收集器 API，这允许每次调用最多发送 32 MB 的数据。

若要调用日志引入 API，请参阅 日志引入 REST API 调用。

处理源数据架构更改

当源数据对象架构发生更改时，数据收集器 API 会自动调整目标旧表的架构，但日志引入 API 不会。 日志引入 API 可确保不会将新数据收集到不打算创建的列中。

源数据架构更改时的选项：

• 修改目标表架构和数据收集规则，使其与源数据架构更改保持一致。
• 在数据收集规则中定义转换，以将新数据发送到目标表中的现有列。
• 使目标表和数据收集规则保持不变。 在这种情况下，不会引入新数据。

相关内容

Microsoft MVP Morten Waltorp Knudsen为本文做出了贡献。 有关自动执行日志引入 API 的设置和持续使用的示例，请参阅他的 AzLogDcrIngestPS PowerShell 模块。

• Tutorial：使用 Azure 门户发送自定义日志
• Tutorial：使用资源管理器模板和 REST API 发送自定义日志