Tutoriel : Modifier une règle de collecte de données (DCR)

Article
11/03/2024

Ce tutoriel explique comment modifier la définition des règles de collecte de données (DCR) qui a déjà été approvisionnée en utilisant les outils de ligne de commande.

Dans ce tutoriel, vous allez apprendre à :

Tirer parti des fonctionnalités du portail existantes pour pré-créer des contrôleurs de domaine
Obtenir le contenu d’une règle de collecte de données à l’aide de l’appel d’API ARM
Appliquer des modifications à une règle de collecte de données à l’aide de l’appel d’API ARM
Automatiser le processus de mise à jour DCR à l’aide de scripts PowerShell

Remarque

Ce tutoriel décrit une méthode pour modifier une règle DCR existante. Pour obtenir les autres méthodes, consultez l’article Créer et modifier des règles de collecte de données (DCR) dans Azure Monitor.

Prérequis

Pour terminer ce tutoriel, vous avez besoin de ce qui suit :

Un espace de travail Log Analytics dans lequel vous avez au moins des droits de contributeur.
Autorisations de créer des objets de règle de collecte de données dans l’espace de travail.
Version à jour de PowerShell. L’utilisation d’Azure Cloud Shell est recommandée.

Vue d’ensemble du tutoriel

Passer par l’Assistant sur le portail est le moyen le plus simple de configurer l’ingestion de vos données personnalisées sur Log Analytics. Dans certains cas, vous pourrez mettre à jour votre règle de collecte de données ultérieurement pour :

Modifier les paramètres de collecte de données (par exemple, un point de terminaison de collecte de données, associé à la règle de collecte de données)
Mettre à jour la logique d’analyse ou de filtrage des données pour votre flux de données
Modifier la destination des données (par exemple, envoyer des données vers une table Azure, car cette option n’est pas directement proposée dans le cadre de l’Assistant Journal personnalisé basé sur une règle de collecte de données)

Dans ce tutoriel, vous configurez d’abord l’ingestion d’un journal personnalisé. Vous modifiez ensuite la transformation KQL pour votre journal personnalisé afin d’inclure un filtrage supplémentaire et d’appliquer les modifications à votre règle de collecte de données. Enfin, nous allons combiner toutes les opérations de modification en un seul script PowerShell, qui peut être utilisé pour modifier n’importe quelle DCR pour l’une des raisons mentionnées ci-dessus.

Configurer un nouveau journal personnalisé

Commencez par configurer un nouveau journal personnalisé. Suivre Tutoriel : envoyer des journaux personnalisés aux journaux Azure Monitor à l’aide du portail Azure (préversion). Notez l’ID de ressource du DCR créé.

Récupérer du contenu DCR

Pour mettre à jour la règle de collecte de données, nous allons récupérer son contenu et l’enregistrer en tant que fichier, qui peut être modifié plus tard.

Cliquez sur le bouton Cloud Shell dans le Portail Azure et vérifiez que l’environnement est défini sur PowerShell.

Exécutez les commandes suivantes pour récupérer du contenu DCR et l’enregistrer dans un fichier. Remplacez <ResourceId> par DCR ResourceID et <FilePath> par le nom du fichier pour stocker 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

Modifier DCR

Maintenant, lorsque le contenu DCR est stocké en tant que fichier JSON, vous pouvez utiliser un éditeur de votre choix pour apporter des modifications dans le DCR. Vous préférerez peut-être télécharger le fichier à partir de l’environnement Cloud Shell, si vous en utilisez un.

Vous pouvez également utiliser des éditeurs de code fournis avec l’environnement. Par exemple, si vous avez enregistré votre DCR dans un fichier nommé temp.dcr sur votre lecteur cloud, vous pouvez utiliser la commande suivante pour ouvrir DCR pour la modification directement dans la fenêtre Cloud Shell :

code "temp.dcr"

Nous allons modifier la transformation KQL dans la règle de collecte de données pour supprimer des lignes où RequestType est tout, sauf GET.

Ouvrez le fichier créé dans la partie précédente pour la modification à l’aide d’un éditeur de votre choix.

Recherchez la ligne contenant l’attribut ”transformKql”, qui, si vous avez suivi le tutoriel pour la création de journal personnalisé, doit ressembler à ceci :

"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"

Modifier la transformation KQL pour inclure un filtre supplémentaire par 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"

Enregistrez le fichier avec du contenu DCR modifié.

Appliquer les changements

Notre dernière étape consiste à mettre à jour DCR dans le système. Cela est effectué par l’appel HTTP PUT à l’API ARM, avec le contenu DCR mis à jour envoyé dans le corps de la requête HTTP.

Si vous utilisez Azure Cloud Shell, enregistrez le fichier et fermez l’éditeur incorporé ou chargez le fichier de règle de collecte de données modifié dans l’environnement Cloud Shell.
Exécutez les commandes suivantes pour charger du contenu DCR à partir du fichier et placer un appel HTTP pour mettre à jour le DCR dans le système. Remplacez <ResourceId> par DCR ResourceID et <FilePath> par le nom du fichier modifié dans la partie précédente du tutoriel. Vous pouvez omettre les deux premières lignes si vous lisez et écrivez dans le DCR dans la même session PowerShell.
```
$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 
```
Une fois l’appel réussi, vous devez obtenir la réponse avec le code d’état 200 indiquant que votre règle de collecte de données est maintenant mise à jour.
Vous pouvez désormais accéder à votre DCR et examiner son contenu sur le portail via la fonction Vue JSON, ou vous pouvez répéter la première partie du tutoriel pour récupérer du contenu de règle de collecte de données dans un fichier.

Regroupement

Maintenant que nous savons comment lire et mettre à jour le contenu d’un DCR, nous allons tout rassembler dans un script utilitaire, lequel peut être utilisé pour effectuer les deux opérations.

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

Comment utiliser cet utilitaire

En supposant que vous avez enregistré le script en tant que fichier, nommé DCREditor.ps1 et devez modifier une règle de collecte de données avec l’ID de ressource de /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/foo/providers/Microsoft.Insights/dataCollectionRules/bar, cela peut être accompli en exécutant la commande suivante :

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

Le contenu DCR s’ouvre dans l’éditeur de code incorporé. Une fois la modification terminée, indiquer « Y » à l’invite de script applique les modifications apportées au DCR.

Étapes suivantes

En savoir plus sur les règles et les options de collecte de données pour les créer.

Partager via