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

HTTP 数据收集器 API 位于弃用路径上。 对旧数据收集器 API 的支持将于 2026 年 9 月 14 日结束。 现有数据引入功能仍可正常使用，但该 API 仅会获得关键安全修复。 迁移到 日志引入 API ，在引入日志和管理 表方面提供更高的处理能力和灵活性。

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

两个日期会影响 Data Collector API 的数据摄取。 2026 年 3 月 1 日，API 终结点停止接受旧版 TLS 版本;不协商 TLS 1.2 或更高版本的客户端无法引入数据。 2026 年 9 月 14 日，API 已弃用，但引入仍适用于符合 TLS 的客户端。 无论你的迁移时间如何安排，在假定数据摄取正常之前，请先验证客户端的 TLS 配置。

日志引入 API 的优点

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

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

先决条件

若要完成此迁移，需要：

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

所需的权限

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

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

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

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

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

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

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

标识经典自定义表

可通过多种方式查找使用数据收集器 API 的表：

• 表属性（门户）：查看表属性。 使用数据收集器 API 或通过旧版 Log Analytics 代理 (MMA) 引入数据的表，其 Type 属性显示为 自定义表（经典）。

• 表属性（API）：tableSubType在使用Classic操作查看Table的表属性时为。 下面是一个示例Azure CLI命令，该命令可快速查找具有以下条件的所有表：

az monitor log-analytics workspace table list \
  --resource-group myResourceGroupName --workspace-name myWorkspaceName \
  --query "[?schema.tableSubType=='Classic'].{Name:name, SubType:schema.tableSubType}" -o table

• 查询启发式： 来自单个记录的线索有助于进一步调查旧 API 使用情况。 在 SourceSystem 中值为 RestAPI 的记录表示该记录是由 HTTP 数据收集器 API 创建的，因此在创建该记录时，该表还是旧版表。 此外，某些列名后缀指示列是由旧版 API 创建的。

若要列出包含通过数据收集器 API 引入的行的工作区中的表，请运行以下查询：

由遗留 API 创建的列的后缀命名约定：

迁移注意事项

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 调用。

处理 GUID 数据类型差异

GUID 以字符串的形式存储在Azure Monitor日志中。 Tables API 接受 guid 作为列类型，但该数据类型在 Logs 查询 API 和 Logs 引入 API 中分别被视为 string 类型和写入为 string 类型。 在 string 中将数据源 GUID 声明为 streamDeclarations。 对于这两个引入 API，此行为相同，因此从数据收集器 API 迁移不会更改现有 GUID 值的存储或查询方式。 有关详细信息，请参阅 表列数据类型。

处理源数据架构更改

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

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

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

相关内容

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

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