教程:使用日志引入 API(资源管理器模板)将数据发送到 Azure Monitor

Azure Monitor 中的日志引入 API 让你能将自定义数据发送到 Log Analytics 工作区。 本教程使用 Azure 资源管理器模板(ARM 模板)来逐步配置支持 API 所需的组件,然后使用 REST API 以及适用于 .NETGoJavaJavaScriptPython 的客户端库提供示例应用程序。

注意

本教程使用 ARM 模板配置支持日志引入 API 所需的组件。 有关使用 Azure 门户 UI 配置这些组件的类似教程,请参阅教程:使用日志引入 API 将数据发送到 Azure Monitor 日志(Azure 门户)

配置日志引入 API 所需的步骤如下:

  1. 创建 Microsoft Entra 应用程序 以进行针对 API 的身份验证。
  2. 在 Log Analytics 工作区中创建自定义表。 这是你将向其发送数据的表。
  3. 创建数据收集规则 (DCR) 以将数据定向到目标表。
  4. 授予 Microsoft Entra 应用程序对 DCR 的访问权限
  5. 有关使用日志引入 API 发送数据的示例代码,请参阅使用日志引入 API 将数据发送到 Azure Monitor 的示例代码

注意

本文包括使用 DCR 引入终结点或数据收集终结点 (DCE) 的选项。 可选择使用其中任何一个,但是如果使用专用链接,则日志引入 API 需要 DCE。 请参阅何时需要 DCE?

先决条件

要完成本教程,需要:

收集工作区详细信息

首先从工作区收集所需的信息。

转到 Azure 门户中“Log Analytics 工作区”菜单中的工作区。 在“属性”页中,复制“资源 ID”并保存它以供稍后使用。

显示工作区资源 ID 的屏幕截图。

创建 Microsoft Entra 应用程序

首先,注册 Microsoft Entra 应用程序以进行针对 API 的身份验证。 任何资源管理器身份验证方案均受支持,但本教程中遵循的是客户端凭据授予流方案

  1. 在 Azure 门户中的“Microsoft Entra ID”菜单上,选择“应用注册”>“新建注册”。

    显示“应用注册”屏幕的屏幕截图。

  2. 为应用程序命名,并更改租户范围(如果默认值不适合你的环境)。 不需要重定向 URI。

    显示应用详细信息的屏幕截图。

  3. 注册后,可以查看应用程序的详细信息。 记下“应用程序(客户端) ID”和“目录(租户) ID”。 在该过程中稍后需要使用这些值。

    显示应用 ID 的屏幕截图。

  4. 生成应用程序客户端密码,这类似于创建与用户名配合使用的密码。 选择“证书和密码”>“新建客户端密码”。 为该客户端密码指定一个名称以标识其用途,并选择“到期”持续时间。 此处选择了选项“12 个月”。 对于生产实现,应遵循机密轮换过程最佳做法或使用更安全的身份验证模式(如证书)。

    显示新应用的密码的屏幕截图。

  5. 选择“添加”保存该客户端密码,然后记下“值”。 请确保记录此值,因为在离开此页面后无法恢复此值。 使用在保护与用户名配合使用的密码时所采用的安全措施,因为客户端密码与之在功能上等效。

    显示新应用的密码值的屏幕截图。

创建数据收集终结点

如果使用 DCR 引入终结点,则不需要 DCE。

在 Log Analytics 工作区中创建新表

必须先创建自定义表,然后才能向其发送数据。 本教程的表格将包括以下架构中显示的五列。 nametypedescription 属性对于每列都是必需的。 如果未显式指定值,则属性 isHiddenisDefaultDisplay 均默认为 false。 可能的数据类型为 stringintlongrealbooleandateTimeguiddynamic

注意

本教程使用 PowerShell,通过 Azure Monitor API 进行 REST API 调用。 可以使用任何其他有效方法进行这些调用。

重要

自定义表必须使用后缀 _CL

  1. 复制以下 PowerShell 代码,并将 Path 参数中的变量替换为 Invoke-AzRestMethod 命令中工作区的相应值。 将其粘贴到 PowerShell 提示符下以运行。

    $tableParams = @'
    {
        "properties": {
            "schema": {
                "name": "MyTable_CL",
                "columns": [
                    {
                        "name": "TimeGenerated",
                        "type": "datetime",
                        "description": "The time at which the data was generated"
                    },
                   {
                        "name": "Computer",
                        "type": "string",
                        "description": "The computer that generated the data"
                    },
                    {
                        "name": "AdditionalContext",
                        "type": "dynamic",
                        "description": "Additional message properties"
                    },
                    {
                        "name": "CounterName",
                        "type": "string",
                        "description": "Name of the counter"
                    },
                    {
                        "name": "CounterValue",
                        "type": "real",
                        "description": "Value collected for the counter"
                    }
                ]
            }
        }
    }
    '@
    
    Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/MyTable_CL?api-version=2022-10-01" -Method PUT -payload $tableParams
    

创建数据收集规则

DCR 定义接收数据后如何处理数据。 这包括:

  • 要发送到终结点的数据的架构
  • 在将数据发送到工作区之前将应用于数据的转换
  • 将转换后的数据发送到的目标工作区和表
  1. 在 Azure 门户的搜索框中,输入“模板”,然后选择“部署自定义模板”。

    该屏幕截图显示如何部署自定义模板。

  2. 选择“在编辑器中生成自己的模板”。

    该屏幕截图显示如何在编辑器中生成模板。

  3. 将下面的 ARM 模板粘贴到编辑器中,然后选择“保存”。

    该屏幕截图显示如何编辑 ARM 模板。

    请注意此模板中定义的 DCR 中的以下详细信息:

    • streamDeclarations:传入数据的列定义。
    • destinations:目标工作区。
    • dataFlows:将流与目标工作区匹配,并指定转换查询和目标表。 目标查询的输出是将发送到目标表的内容。
    {
        "$schema": "https://schema.management.azure.com/schemas/2019-08-01/deploymentTemplate.json#",
        "contentVersion": "1.0.0.0",
        "parameters": {
            "dataCollectionRuleName": {
                "type": "string",
                "metadata": {
                    "description": "Specifies the name of the Data Collection Rule to create."
                }
            },
            "location": {
                "type": "string",
                "metadata": {
                    "description": "Specifies the location in which to create the Data Collection Rule."
                }
            },
            "workspaceResourceId": {
                "type": "string",
                "metadata": {
                    "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
                }
            }
        },
        "resources": [
            {
                "type": "Microsoft.Insights/dataCollectionRules",
                "name": "[parameters('dataCollectionRuleName')]",
                "location": "[parameters('location')]",
                "apiVersion": "2023-03-11",
                "kind": "Direct",
                "properties": {
                    "streamDeclarations": {
                        "Custom-MyTableRawData": {
                            "columns": [
                                {
                                    "name": "Time",
                                    "type": "datetime"
                                },
                                {
                                    "name": "Computer",
                                    "type": "string"
                                },
                                {
                                    "name": "AdditionalContext",
                                    "type": "string"
                                },
                                {
                                    "name": "CounterName",
                                    "type": "string"
                                },
                                {
                                    "name": "CounterValue",
                                    "type": "real"
                                }
                            ]
                        }
                    },
                    "destinations": {
                        "logAnalytics": [
                            {
                                "workspaceResourceId": "[parameters('workspaceResourceId')]",
                                "name": "myworkspace"
                            }
                        ]
                    },
                    "dataFlows": [
                        {
                            "streams": [
                                "Custom-MyTableRawData"
                            ],
                            "destinations": [
                                "myworkspace"
                            ],
                            "transformKql": "source | extend jsonContext = parse_json(AdditionalContext) | project TimeGenerated = Time, Computer, AdditionalContext = jsonContext, CounterName=tostring(jsonContext.CounterName), CounterValue=toreal(jsonContext.CounterValue)",
                            "outputStream": "Custom-MyTable_CL"
                        }
                    ]
                }
            }
        ],
        "outputs": {
            "dataCollectionRuleId": {
                "type": "string",
                "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
            }
        }
    }
    

  1. 在“自定义部署”屏幕上,指定用于存储 DCR 的“订阅”和“资源组”。 然后提供模板中定义的值。 这些值包括 DCR 的“名称”和在上一步中收集的“工作区资源 ID”。 该“位置”应与工作区位于同一位置。 “区域”将已填充,并将用作 DCR 的位置。

    该屏幕截图显示如何编辑自定义部署值。

  2. 选择“查看 + 创建”,然后在查看详细信息后选择“创建”。

  3. 部署完成后,展开“部署详细信息”框,并选择你的 DCR 以查看其详细信息。 选择“JSON 视图”。

    显示 DCR 详细信息的屏幕截图。

  4. 复制 DCR 的不可变 ID日志引入 URI使用 API 将数据发送到 Azure Monitor 时,你将使用这些数据。

    显示 DCR JSON 视图的屏幕截图。

分配对 DCR 的权限

创建 DCR 后,需要向应用程序授予其权限。 权限将允许使用正确应用程序 ID 和应用程序密钥的任何应用程序将数据发送到新的 DCR。

  1. 在 Azure 门户的 DCR 中,选择“访问控制(IAM)”>“添加角色分配”。

    显示如何将自定义角色分配添加到 DCR 的屏幕截图。

  2. 选择“监视指标发布者”,然后选择“下一步”。 可以改为创建带有 Microsoft.Insights/Telemetry/Write 数据操作的自定义操作。

    显示如何为 DCR 角色分配选择角色的屏幕截图。

  3. 为“将访问权限分配给”选择“用户、组或服务主体”,然后选择“选择成员”。 选择你创建的应用程序,然后选择“选择”。

    显示如何为 DCR 角色分配选择成员的屏幕截图。

  4. 在保存角色分配之前,选择“查看 + 分配”并验证详细信息。

    显示如何保存 DCR 角色分配的屏幕截图。

代码示例

有关使用本教程中创建的组件的示例代码,请参阅使用日志引入 API 将数据发送到 Azure Monitor 的示例代码

后续步骤