通过

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 应用程序和服务主体和创建新的应用程序机密。
数据收集终结点 (DCE) 仅当使用专用链接时，才需要 DCE。 它为应用程序提供要发送到的终结点。 单个 DCE 可以支持多个 DCR，因此，如果已与 Log Analytics 工作区位于同一区域中，则可以使用现有 DCE。 如果未使用专用链接，则可以使用 DCR 终结点。

请参阅创建数据收集终结点。
Log Analytics 工作区中的表 Log Analytics 工作区中的表必须存在，然后才能将数据发送到该工作区。 可以使用支持的 Azure 表之一，也可以使用任何可用方法创建自定义表。 如果使用 Microsoft Azure 门户创建表，则会为你创建 DCR，包括必要的转换。 使用任何其他方法时，需要按照下一部分所述手动创建 DCR。

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

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

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

手动创建 DCR

如果要将数据发送到已存在的表，则必须手动创建 DCR。 从日志引入 API 的示例 DCR 开始，并在模板中修改以下参数。 然后使用在 Azure Monitor 中创建和编辑数据收集规则 (DCR) 中所述的任何方法来创建 DCR。

参数 说明
region 要创建 DCR 的区域。 这必须与 DCE 和 Log Analytics 工作区的区域匹配。
dataCollectionEndpointId DCE 的资源 ID。
streamDeclarations 将列列表更改为传入数据中的列。 无需更改流的名称，因为这只需与 dataFlows 中的 streams 名称匹配。
workspaceResourceId Log Analytics 工作区的资源 ID。 无需更改名称，因为这只需与 dataFlows 中的 destinations 名称匹配。
transformKql 要应用于传入数据的 KQL 查询。 如果传入数据的架构与表的架构匹配，则可以对转换使用 source，该转换将原封不动地传递传入数据。 否则，请使用将转换数据以匹配表架构的查询。
outputStream 要发送数据的表的名称。 对于自定义表，请添加前缀 Custom-<table-name>。 对于内置表，请添加前缀 Microsoft-<table-name>。

客户端库

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

REST API 调用

若要使用 REST API 调用将数据发送到 Azure Monitor，请通过 HTTP 进行 POST 调用。 本部分介绍了此调用所需的详细信息。

终结点 URI

终结点 URI 采用以下格式，其中 Data Collection Endpoint 和 DCR Immutable ID 标识 DCE 和 DCR。 创建 DCR 时，会为其生成不可变 ID。 可以从 Microsoft Azure 门户中 DCR 的概述页检索它。

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

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

{Data Collection Endpoint URI}/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

标头

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

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

由世纪互联运营的 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 服务限制。

后续步骤