Condividi tramite

Istruzione pattern

  • Articolo

Si applica a: ✅Microsoft Fabric✅Azure Esplora dati✅ Azure Monitor✅Microsoft Sentinel

Un modello è un costrutto che esegue il mapping delle tuple di stringa alle espressioni tabulari. Ogni modello deve dichiarare un nome di criterio e, facoltativamente , definire un mapping dei criteri. I modelli che definiscono un mapping restituiscono un'espressione tabulare quando viene richiamato. Le due istruzioni devono essere separate da un punto e virgola.

I modelli vuoti sono modelli dichiarati ma non definiscono un mapping. Quando viene richiamato, restituiscono l'errore SEM0036 insieme ai dettagli delle definizioni dei criteri mancanti nell'intestazione HTTP. Le applicazioni di livello intermedio che offrono un'esperienza di Linguaggio di query Kusto (KQL) possono usare i dettagli restituiti come parte del processo per arricchire i risultati delle query KQL. Per altre informazioni, vedere Uso delle applicazioni di livello intermedio.

Sintassi

  • Dichiarare un modello vuoto:

    declarepattern PatternName ;

  • Dichiarare e definire un modello:

    declarepattern PatternName = (ArgName : ArgType [, ... ]) [[ PathName : PathArgType ] ]

    {

          ( ArgValue1_1 [ , ArgValue2_1, ... ] ) [ .[ PathValue_1 ] ] { = expression1 } ;

        [ ArgValue1_2 [ (, ArgValue2_2, ... ] ) [ .[ PathValue_2 ] ] { = expression2 } ; ... ]

    } ;

  • Richiamare un modello:

    • PatternName ( ArgValue1 [, ArgValue2 ...] ).PathValue
    • PatternName ( ArgValue1 [, ArgValue2 ...] ).["PathValue"]

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Digita Obbligatorio Descrizione
PatternName string ✔️ Nome del modello.
ArgName string ✔️ Il nome dell’argomento. I modelli possono avere uno o più argomenti.
ArgType string ✔️ Tipo di dati scalare dell'argomento ArgName . Valori possibili: string
PathName string Nome dell'argomento path. I modelli non possono avere alcun percorso o un percorso.
PathArgType string Tipo dell'argomento PathArgType . Valori possibili: string
ArgValue string ✔️ I valori di tupla ArgName e PathName facoltativi di cui eseguire il mapping a un'espressione.
PathValue string Valore di cui eseguire il mapping per PathName.
expression string ✔️ Espressione tabulare o lambda che fa riferimento a una funzione che restituisce dati tabulari. Ad esempio: Logs | where Timestamp > ago(1h)

Esempi

In ognuno degli esempi seguenti viene dichiarato, definito un modello e quindi richiamato.

Definire modelli semplici

Nell'esempio seguente viene definito un modello che esegue il mapping degli stati a un'espressione che restituisce la capitale o la città principale.

declare pattern country = (name:string)[state:string]
{
  ("USA").["New York"] = { print Capital = "Albany" };
  ("USA").["Washington"] = { print Capital = "Olympia" };
  ("Canada").["Alberta"] = { print Capital = "Edmonton" };
};
country("Canada").Alberta

Output

Capitale
Edmonton

L'esempio seguente definisce un modello che definisce alcuni dati dell'applicazione con ambito.

declare pattern App = (applicationId:string)[scope:string]  
{
    ('a1').['Data']    = { range x from 1 to 5 step 1 | project App = "App #1", Data    = x };
    ('a1').['Metrics'] = { range x from 1 to 5 step 1 | project App = "App #1", Metrics = rand() };
    ('a2').['Data']    = { range x from 1 to 5 step 1 | project App = "App #2", Data    = 10 - x };
    ('a3').['Metrics'] = { range x from 1 to 5 step 1 | project App = "App #3", Metrics = rand() };
};
union App('a2').Data, App('a1').Metrics

Output

App Dati Metrica
App n. 2 9
App n. 2 8
App n. 2 7
App n. 2 6
App n. 2 5
App n. 1 0.53674122855537532
App n. 1 0.78304713305654439
App n. 1 0.20168860732346555
App n. 1 0.13249123867679469
App n. 1 0.19388305330563443

Normalizzazione

Esistono varianti di sintassi per richiamare i modelli. Ad esempio, l'unione seguente restituisce un'espressione a criterio singolo perché tutte le chiamate sono dello stesso criterio.

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database("AppX").Events | where EventType == "StartEvent" };
};
union
  app("ApplicationX").StartEvents,
  app('ApplicationX').StartEvents,
  app("ApplicationX").['StartEvents'],
  app("ApplicationX").["StartEvents"]

Nessun carattere jolly

Non c'è un trattamento speciale dato ai caratteri jolly in un modello. Ad esempio, la query seguente restituisce una singola chiamata al criterio mancante.

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database("AppX").Events | where EventType == "StartEvent" };
};
union app("ApplicationX").["*"]
| count

Restituisce un errore semantico

Uno o più riferimenti al modello non sono stati dichiarati. Riferimenti ai criteri rilevati: ["app('ApplicationX').[' *']"]

Usare applicazioni di livello intermedio

Un'applicazione di livello intermedio offre agli utenti la possibilità di usare KQL e vuole migliorare l'esperienza arricchiscendo i risultati delle query con dati estesi dal servizio interno.

A questo scopo, l'applicazione fornisce agli utenti un'istruzione pattern che restituisce dati tabulari che gli utenti possono usare nelle query. Gli argomenti del modello sono le chiavi che verranno usate dall'applicazione per recuperare i dati di arricchimento. Quando l'utente esegue la query, l'applicazione non analizza la query stessa, ma prevede di sfruttare l'errore restituito da un modello vuoto per recuperare le chiavi necessarie. Antepone quindi la query con la dichiarazione di pattern vuota, la invia al cluster per l'elaborazione e quindi analizza l'intestazione HTTP restituita per recuperare i valori degli argomenti del criterio mancanti. L'applicazione usa questi valori per cercare i dati di arricchimento e compila una nuova dichiarazione che definisce il mapping dei dati di arricchimento appropriato. Infine, l'applicazione antepone la nuova definizione alla query dell'utente, lo invia nuovamente per l'elaborazione e restituisce il risultato ricevuto all'utente.

Esempio

Nell'esempio seguente un'applicazione di livello intermedio consente di arricchire le query con posizioni di longitudine/latitudine. L'applicazione usa un servizio interno per eseguire il mapping degli indirizzi IP alle posizioni di longitudine/latitudine e fornisce un modello chiamato map_ip_to_longlat a questo scopo. Si supponga che l'applicazione ottenga la query seguente dall'utente:

map_ip_to_longlat("10.10.10.10")

L'applicazione non analizza questa query e quindi non sa quale indirizzo IP (10.10.10.10.10) è stato passato al modello. Antepone quindi la query utente con una dichiarazione di modello vuota map_ip_to_longlat e la invia per l'elaborazione:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

L'applicazione riceve l'errore seguente in risposta.

Uno o più riferimenti al modello non sono stati dichiarati. Riferimenti ai criteri rilevati: ["map_ip_to_longlat('10.10.10.10')"]

L'applicazione esamina l'errore, determina che l'errore indica un riferimento al modello mancante e recupera l'indirizzo IP mancante (10.10.10.10). Usa l'indirizzo IP per cercare i dati di arricchimento nel servizio interno e crea un nuovo modello che definisce il mapping dell'indirizzo IP ai dati di longitudine e latitudine corrispondenti. Il nuovo modello viene anteporto alla query dell'utente ed eseguito di nuovo. Questa volta la query ha esito positivo perché i dati di arricchimento sono ora dichiarati nella query e il risultato viene inviato all'utente.

declare pattern map_ip_to_longlat = (address:string)
{
  ("10.10.10.10") = { print Lat=37.405992, Long=-122.078515 };
};
map_ip_to_longlat("10.10.10.10")

Output

Lat Long
37.405992 -122.078515