教程：编辑数据收集规则 (DCR)

项目
12/18/2024

本教程介绍如何使用命令行工具编辑已预配的数据收集规则 (DCR) 的定义。

本教程介绍如何执行下列操作：

利用现有门户功能预先创建 DCR
使用 ARM API 调用获取数据收集规则的内容
使用 ARM API 调用将更改应用于数据收集规则
使用 PowerShell 脚本自动执行 DCR 更新过程

注意

本教程逐步讲解用于编辑现有 DCR 的一种方法。有关其他方法，请参阅在 Azure Monitor 中创建和编辑数据收集规则 (DCR)。

先决条件

要完成本教程，您需要：

Log Analytics 工作区，你在其中至少拥有参与者权限。
在工作区中创建数据收集规则对象的权限。
最新版本的 PowerShell。建议使用 Azure Cloud Shell。

教程概述

虽然在门户上完成向导中的所有步骤是设置如何将自定义数据引入 Log Analytics 的最简单方法，但在某些情况下，你可能希望稍后更新数据收集规则以实现以下目的：

更改数据收集设置（例如，与 DCR 关联的数据收集终结点）
更新数据流的数据分析或筛选逻辑
更改数据目标（例如，将数据发送到 Azure 表，因为此选项不直接作为基于 DCR 的自定义日志向导的一部分提供）

在本教程中，将首先设置自定义日志的引入。然后，将会修改自定义日志的 KQL 转换以包含其他筛选，并将更改应用于 DCR。最后，我们要将所有编辑操作合并到单个 PowerShell 脚本中，你可以出于上述任何原因而使用该脚本来编辑任何 DCR。

设置新的自定义日志

首先设置新的自定义日志。按照教程：使用 Azure 门户将自定义日志发送到 Azure Monitor 日志（预览版）执行操作。记下创建的 DCR 的资源 ID。

检索 DCR 内容

为了更新 DCR，我们将要检索其内容并将其保存为文件，该文件可供进一步编辑。

执行以下命令以检索 DCR 内容并将其保存到文件中。将 <ResourceId> 替换为 DCR ResourceID，将 <FilePath> 替换为用于存储 DCR 的文件的名称。

$ResourceId = "<ResourceId>" # Resource ID of the DCR to edit
$FilePath = "<FilePath>" # Store DCR content in this file
$DCR = Invoke-AzRestMethod -Path ("$ResourceId"+"?api-version=2022-06-01") -Method GET
$DCR.Content | ConvertFrom-Json | ConvertTo-Json -Depth 20 | Out-File -FilePath $FilePath

编辑 DCR

现在，当 DCR 内容存储为 JSON 文件时，可以使用所选编辑器在 DCR 中进行更改。

你也可以使用随环境提供的代码编辑器。例如，如果将 DCR 保存在 Cloud Drive 上名为 temp.dcr 的文件中，则可以使用以下命令直接在 PowerShell 窗口中打开 DCR 以进行编辑：

code "temp.dcr"

让我们修改 DCR 中的 KQL 转换，以删除 RequestType 为“GET”以外的任何内容的行。

打开在上一部分中创建的文件，以便使用你选择的编辑器进行编辑。

找到包含 ”transformKql” 属性的行，如果你遵循了教程来创建自定义日志，该行应如下所示：

"transformKql": "  source\n    | extend TimeGenerated = todatetime(Time)\n    | parse RawData with \n    ClientIP:string\n    ' ' *\n    ' ' *\n    ' [' * '] \"' RequestType:string\n    \" \" Resource:string\n    \" \" *\n    '\" ' ResponseCode:int\n    \" \" *\n    | where ResponseCode != 200\n    | project-away Time, RawData\n"

修改 KQL 转换以包含将 RequestType 作为筛选依据的其他筛选器

"transformKql": "  source\n    | where RawData contains \"GET\"\n     | extend TimeGenerated = todatetime(Time)\n    | parse RawData with \n    ClientIP:string\n    ' ' *\n    ' ' *\n    ' [' * '] \"' RequestType:string\n    \" \" Resource:string\n    \" \" *\n    '\" ' ResponseCode:int\n    \" \" *\n    | where ResponseCode != 200\n    | project-away Time, RawData\n"

保存带有已修改的 DCR 内容的文件。

应用更改

最后一步是将 DCR 更新回系统中。这是通过对 ARM API 的“PUT”HTTP 调用完成的，已更新的 DCR 内容会在 HTTP 请求正文中发送。

执行以下命令，以从文件中加载 DCR 内容并发出 HTTP 调用以更新系统中的 DCR。将 <ResourceId> 替换为 DCR ResourceID，将 <FilePath> 替换为在本教程上一部分中修改的文件的名称。如果在同一 PowerShell 会话中读取和写入 DCR，则可以省略前两行。
```
$ResourceId = "<ResourceId>" # Resource ID of the DCR to edit
$FilePath = "<FilePath>" # Store DCR content in this file
$DCRContent = Get-Content $FilePath -Raw 
Invoke-AzRestMethod -Path ("$ResourceId"+"?api-version=2022-06-01") -Method PUT -Payload $DCRContent 
```
成功调用后，应收到状态代码为“200”的响应，指示 DCR 现已更新。
现在，可以通过“JSON 视图”功能在门户中导航到 DCR 并检查其内容，也可以重复本教程的第一部分，将 DCR 内容检索到文件中。

将所有内容放在一起

现在，当我们知道如何读取和更新 DCR 的内容后，让我们把所有操作全都放在实用工具脚本中，该脚本可用于将这两个操作一起执行。

param ([Parameter(Mandatory=$true)] $ResourceId)

# get DCR content and put into a file
$FilePath = "temp.dcr"
$DCR = Invoke-AzRestMethod -Path ("$ResourceId"+"?api-version=2022-06-01") -Method GET
$DCR.Content | ConvertFrom-Json | ConvertTo-Json -Depth 20 | Out-File $FilePath

# Open DCR in code editor
code $FilePath | Wait-Process

#Wait for confirmation to apply changes
$Output = Read-Host "Apply changes to DCR (Y/N)? "
if ("Y" -eq $Output.toupper())
{ 
	#write DCR content back from the file
	$DCRContent = Get-Content $FilePath -Raw
	Invoke-AzRestMethod -Path ("$ResourceId"+"?api-version=2022-06-01") -Method PUT -Payload $DCRContent		
}

#Delete temporary file
Remove-Item $FilePath

如何使用此实用工具

假设已将脚本保存为文件（名为 DCREditor.ps1）并需要修改资源 ID 为 /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.Insights/dataCollectionRules/bar 的数据收集规则，则可以通过运行以下命令来实现此目的：

.\DCREditor.ps1 "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.Insights/dataCollectionRules/bar"

DCR 内容在嵌入式代码编辑器中打开。编辑完成后，在出现脚本提示时输入“Y”会将更改应用回 DCR。

后续步骤

详细了解数据收集规则和用于创建这些规则的选项。

通过