Funzioni nelle query di log di Monitoraggio di Azure

Una funzione è una query di log in Monitoraggio di Azure che può essere usata in altre query di log come se fosse un comando. È possibile usare le funzioni per fornire soluzioni a clienti diversi e riutilizzare anche la logica di query nel proprio ambiente. Questo articolo descrive come usare le funzioni e come creare funzioni personalizzate.

Autorizzazioni obbligatorie

Azione	Autorizzazioni obbligatorie
Visualizzare o usare funzioni	Microsoft.OperationalInsights/workspaces/query/*/read autorizzazioni per l'area di lavoro Log Analytics, come fornito dal ruolo predefinito Lettore di Log Analytics, ad esempio.
Creare o modificare funzioni	microsoft.operationalinsights/workspaces/savedSearches/write autorizzazioni per l'area di lavoro Log Analytics, come specificato dal ruolo predefinito Collaboratore Log Analytics, ad esempio.

Tipi di funzione

In Monitoraggio di Azure sono disponibili due tipi di funzioni:

• Funzioni della soluzione: le funzioni predefinite sono incluse in Monitoraggio di Azure. Queste funzioni sono disponibili in tutte le aree di lavoro di Log Analytics e non possono essere modificate.

• Funzioni dell'area di lavoro: queste funzioni vengono installate in una particolare area di lavoro di Log Analytics. Possono essere modificati e controllati dall'utente.

Visualizzare le funzioni

È possibile visualizzare le funzioni della soluzione e le funzioni dell'area di lavoro nell'area di lavoro corrente nella scheda Funzioni nel riquadro sinistro di un'area di lavoro di Log Analytics. Usare Filtra per filtrare le funzioni incluse nell'elenco. Usare Raggruppa per per modificare il raggruppamento. Immettere una stringa nella casella di ricerca per individuare una determinata funzione. Passare il puntatore del mouse su una funzione per visualizzare i dettagli su di esso, tra cui una descrizione e parametri.

Usare una funzione

Usare una funzione in una query digitandone il nome con i valori per tutti i parametri uguali a quello digitato in un comando. L'output della funzione può essere restituito come risultati o inviato tramite pipe a un altro comando.

Aggiungere una funzione alla query corrente facendo doppio clic sul nome o passando il puntatore del mouse su di essa e selezionando Usa nell'editor. Le funzioni nell'area di lavoro verranno incluse anche in IntelliSense durante la digitazione di una query.

Se una query richiede parametri, specificarli usando la sintassi function_name(param1,param2,...).

Creare una funzione

Portale

Per creare una funzione dalla query corrente nell'editor, selezionare Salva>Salva come funzione.

Creare una funzione con Log Analytics nel portale di Azure selezionando Salva e quindi specificando le informazioni richieste nella tabella seguente:

Impostazione	Descrizione
Nome funzione	Nome della funzione. Il nome potrebbe non includere uno spazio o caratteri speciali. Potrebbe anche non iniziare con un carattere di sottolineatura (_) perché questo carattere è riservato per le funzioni della soluzione.
Categoria legacy	Categoria definita dall'utente che consente di filtrare e raggruppare le funzioni.
Salva come gruppo di computer	Salva questa query come gruppo di computer.
Parametri	Aggiungere un parametro per ogni variabile nella funzione che richiede un valore quando viene usato. Per altre informazioni, vedere Parametri della funzione.

Modello di Resource Manager

L'esempio seguente usa il modello Microsoft.OperationalInsights workspaces/savedSearches per creare una funzione. Per altre informazioni sui modelli di Azure Resource Manager, vedere Comprendere la struttura e la sintassi dei modelli di Resource Manager.

Per altre informazioni su come distribuire le risorse da un modello personalizzato, vedere Distribuire risorse con i modelli di Resource Manager e portale di Azure.

Nota

Vedere esempi di Azure Resource Manager per Monitoraggio di Azure per un elenco di esempi disponibili e indicazioni sulla distribuzione nella sottoscrizione di Azure.

File del modello

{
  "$schema": "
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"
,
  "contentVersion": "1.0.0.0",
  "resources": [
    {
      "type": "Microsoft.OperationalInsights/workspaces/savedSearches",
      "apiVersion": "2020-08-01",
      "name": "[concat(parameters('workspaceName'), '/', parameters('functionName'))]",
      "location": "[parameters('location')]",
      "properties": {
        "etag": "*",
        "displayName": "[parameters('functionDisplayName')]",
        "category": "[parameters('category')]",
        "query": "[parameters('query')]",
        "functionAlias": "[parameters('functionAlias')]",
        "version": 1
      }
    }
  ],
  "parameters": {
    "workspaceName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Log Analytics workspace"
      }
    },
    "functionName": {
      "type": "string",
      "metadata": {
        "description": "Name of the function"
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "Location of the Log Analytics workspace"
      }
    },
    "functionDisplayName": {
      "type": "string",
      "metadata": {
        "description": "Display name of the function"
      }
    },
    "category": {
      "type": "string",
      "metadata": {
        "description": "Category of the function"
      }
    },
    "query": {
      "type": "string",
      "metadata": {
        "description": "Kusto query for the function"
      }
    },
    "functionAlias": {
      "type": "string",
      "metadata": {
        "description": "Alias for the function"
      }
    }
  }
}

Parametri di funzione

È possibile aggiungere parametri a una funzione in modo da poter fornire valori per determinate variabili quando viene chiamato. Di conseguenza, la stessa funzione può essere usata in query diverse, ognuna che fornisce valori diversi per i parametri. I parametri sono definiti dalle proprietà seguenti:

Impostazione	Descrizione
Tipo	Tipo di dati per il valore.
Nome	Nome del parametro. Questo nome deve essere usato nella query per sostituire con il valore del parametro.
Default value	Valore da usare per il parametro se non viene specificato un valore.

I parametri vengono ordinati durante la creazione. I parametri senza valore predefinito vengono posizionati davanti ai parametri con un valore predefinito.

Usare il codice della funzione

È possibile visualizzare il codice di una funzione per ottenere informazioni dettagliate sul funzionamento o modificare il codice per una funzione dell'area di lavoro. Selezionare Caricare il codice della funzione per aggiungere il codice della funzione alla query corrente nell'editor.

Se si aggiunge il codice della funzione a una query vuota o alla prima riga di una query esistente, il nome della funzione viene aggiunto alla scheda. Una funzione dell'area di lavoro consente di modificare i dettagli della funzione.

Modificare una funzione

Modificare le proprietà o il codice di una funzione creando una nuova query. Passare il puntatore del mouse sul nome della funzione e selezionare Carica codice funzione. Apportare le modifiche desiderate al codice e selezionare Salva. Selezionare quindi Modifica dettagli funzione. Apportare le modifiche desiderate alle proprietà e ai parametri della funzione e selezionare Salva.

Esempio

La funzione di esempio seguente restituisce tutti gli eventi nel log attività di Azure a partire da una determinata data e che corrispondono a una determinata categoria.

Iniziare con la query seguente usando valori hardcoded per verificare che la query funzioni come previsto.

AzureActivity
| where CategoryValue == "Administrative"
| where TimeGenerated > todatetime("2021/04/05 5:40:01.032 PM")

Sostituire quindi i valori hardcoded con i nomi dei parametri. Salvare quindi la funzione selezionando Salva>Salva come funzione.

AzureActivity
| where CategoryValue == CategoryParam
| where TimeGenerated > DateParam

Specificare i valori seguenti per le proprietà della funzione:

Proprietà	valore
Nome funzione	AzureActivityByCategory
Categoria legacy	Funzioni demo

Definire i parametri seguenti prima di salvare la funzione:

Type	Nome	Default value
string	CategoryParam	"Amministrativo"
datetime	DateParam

Creare una nuova query e visualizzare la nuova funzione passando il puntatore del mouse su di esso. Esaminare l'ordine dei parametri. Devono essere specificati in questo ordine quando si usa la funzione.

Selezionare Usa nell'editor per aggiungere la nuova funzione a una query. Aggiungere quindi valori per i parametri. Non è necessario specificare un valore per CategoryParam perché ha un valore predefinito.

Passaggi successivi

Per altre informazioni su come scrivere query di log di Monitoraggio di Azure, vedere Operazioni su stringhe.