Condividi tramite

Convenzioni di sintassi per la documentazione di riferimento

Selezionare un servizio dall'elenco a discesa a sinistra.
Si applica a: ✅ Microsoft Fabric ✅ Esplora dati ✅ di Azure Monitoraggio di Azure Microsoft ✅ Sentinel

Questo articolo descrive le convenzioni di sintassi seguite nella documentazione di riferimento sui comandi di riferimento del linguaggio di query Kusto (KQL) e dei comandi di gestione .

Un buon punto di partenza per iniziare a imparare il linguaggio di query Kusto consiste nel comprendere la struttura complessiva delle query. La prima cosa che si nota quando si esamina una query Kusto è l'uso del simbolo di pipe (|). La struttura di una query Kusto inizia con il recupero dei dati da un'origine dati e quindi il passaggio dei dati in una pipeline e ogni passaggio fornisce un certo livello di elaborazione e quindi passa i dati al passaggio successivo. Alla fine della pipeline si ottiene il risultato finale. In effetti, questa è la pipeline:

Get Data | Filter | Summarize | Sort | Select

Questo concetto di passaggio dei dati verso il basso della pipeline rende una struttura intuitiva, in quanto è facile creare un'immagine mentale dei dati in ogni passaggio.

Per illustrare questo aspetto, si esaminerà la query seguente, che esamina i log di accesso di Microsoft Entra. Durante la lettura di ogni riga, è possibile visualizzare le parole chiave che indicano cosa accade ai dati. La fase pertinente nella pipeline è stata inclusa come commento in ogni riga.

Annotazioni

È possibile aggiungere commenti a qualsiasi riga in una query precedendoli con una doppia barra (//).

SigninLogs                              // Get data
| evaluate bag_unpack(LocationDetails)  // Ignore this line for now; we'll come back to it at the end.
| where RiskLevelDuringSignIn == 'none' // Filter
   and TimeGenerated >= ago(7d)         // Filter
| summarize Count = count() by city     // Summarize
| sort by Count desc                    // Sort
| take 5                                // Select

Poiché l'output di ogni passaggio funge da input per il passaggio seguente, l'ordine dei passaggi può determinare i risultati della query e influire sulle prestazioni. È fondamentale ordinare i passaggi in base a ciò che si vuole uscire dalla query.

Suggerimento

  • Una buona regola generale consiste nel filtrare i dati in anticipo, quindi si passano solo i dati pertinenti verso il basso nella pipeline. Ciò aumenta notevolmente le prestazioni e garantisce che non si includano accidentalmente dati irrilevanti nei passaggi di riepilogo.
  • Questo articolo illustra alcune altre procedure consigliate da tenere presente. Per un elenco più completo, vedere Procedure consigliate per le query.

Convenzioni della sintassi

Convenzione Description
Block Valori letterali stringa da immettere esattamente come illustrato.
Corsivo Parametri da fornire un valore quando si usa la funzione o il comando .
[ ] Indica che l'elemento racchiuso è facoltativo.
( ) Indica che è necessario almeno uno degli elementi racchiusi.
| (pipe) Utilizzato all'interno di parentesi quadre o arrotondate per indicare che è possibile specificare uno degli elementi separati dal carattere barra verticale. In questo formato, la pipe equivale all'operatore OR logico. Quando si trova in un blocco (|), la pipe fa parte della sintassi della query KQL.
[, ...] Indica che il parametro precedente può essere ripetuto più volte, separato da virgole.
; Terminatore dell'istruzione di query.

Esempi

Funzione scalare

In questo esempio viene illustrata la sintassi e un esempio di utilizzo della funzione hash, seguita da una spiegazione del modo in cui ogni componente della sintassi viene convertito nell'utilizzo di esempio.

Sintassi

hash( source [,mod])

Esempio di utilizzo

hash("World")
  • Il nome della funzione, hashe la parentesi di apertura vengono immessi esattamente come illustrato.
  • "World" viene passato come argomento per il parametro di origine richiesto.
  • Non viene passato alcun argomento per il parametro mod , che è facoltativo come indicato dalle parentesi quadre.
  • La parentesi di chiusura viene immessa esattamente come illustrato.

Operatore tabulare

In questo esempio viene illustrata la sintassi e un esempio di utilizzo dell'operatore di ordinamento, seguita da una spiegazione del modo in cui ogni componente della sintassi viene convertito nell'utilizzo di esempio.

Sintassi

T| sort bycolumn [] [asc | descnulls first | nulls last] [, ...]

Esempio di utilizzo

StormEvents
| sort by State asc, StartTime desc
  • La tabella StormEvents viene passata come argomento per il parametro T obbligatorio.
  • | sort by viene immesso esattamente come illustrato. In questo caso, il carattere pipe fa parte della sintassi dell'istruzione dell'espressione tabulare , come rappresentato dal testo del blocco. Per altre informazioni, vedere Che cos'è un'istruzione di query.
  • La colonna State viene passata come argomento per il parametro di colonna obbligatorio con il flag facoltativo asc .
  • Dopo una virgola, viene passato un altro set di argomenti: la colonna StartTime con il flag facoltativo desc . La sintassi [, ...] indica che è possibile passare più set di argomenti, ma non sono necessari.

Uso dei parametri facoltativi

Per fornire un argomento per un parametro facoltativo successivo a un altro parametro facoltativo, è necessario specificare un argomento per il parametro precedente. Questo requisito è dovuto al fatto che gli argomenti devono seguire l'ordine specificato nella sintassi. Se non si ha un valore specifico da passare per il parametro, usare un valore vuoto dello stesso tipo.

Esempio di parametri facoltativi sequenziali

Si consideri la sintassi per il plug-in http_request:

evaluate http_request ( URI [,RequestHeaders [,Opzioni]] )

RequestHeaders e Options sono parametri facoltativi di tipo dinamico. Per specificare un argomento per il parametro Options , è necessario specificare anche un argomento per il parametro RequestHeaders . Nell'esempio seguente viene illustrato come specificare un valore vuoto per il primo parametro facoltativo , RequestHeaders, per poter specificare un valore per il secondo parametro facoltativo , Options.

evaluate http_request ( "https://contoso.com/", dynamic({}), dynamic({ EmployeeName: Nicole }) )

Contenuti correlati

  • Last updated on