Istruzione Pattern

Si applica a: ✅Microsoft Fabric✅Esplora dati di Azure✅Monitoraggio di Azure✅Microsoft Sentinel

Un modello è un costrutto che esegue il mapping delle tuple di stringa alle espressioni tabulari.

Ogni criterio deve dichiarare un nome di modello e, facoltativamente, definire un mapping dei criteri. I modelli che definiscono un mapping restituiscono un'espressione tabulare quando viene richiamato. Separare due istruzioni con 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 KQL (Kusto Query Language) possono usare i dettagli restituiti come parte del processo per arricchire i risultati delle query KQL. Per altre informazioni, vedere Uso di applicazioni di livello intermedio.

Sintassi

• Dichiarare un modello vuoto:

  declare pattern ; PatternName

• Dichiarare e definire un modello:

  declare pattern 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

Esempi

Negli esempi di questa sezione viene illustrato come usare la sintassi per iniziare.

Definire un modello semplice

Questo esempio definisce 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

Definire un modello con ambito

Questo esempio definisce un modello per definire l'ambito dei dati e delle metriche dei dati dell'applicazione. Il modello viene richiamato per restituire un'unione dei dati.

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

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

errore semantico di output

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 usa 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, la invia nuovamente per l'elaborazione e restituisce il risultato ricevuto all'utente.

Esempio

Negli esempi un criterio viene dichiarato, definito e quindi richiamato.

Dichiarare un modello vuoto

In questo esempio un'applicazione di livello intermedio arricchisce 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 denominato map_ip_to_longlat. Quando la query viene eseguita, restituisce un errore con definizioni di criteri mancanti:

map_ip_to_longlat("10.10.10.10")

Dichiarare e definire un modello

L'applicazione non analizza questa query e pertanto non conosce l'indirizzo IP (10.10.10.10.10) è stato passato al modello. Quindi antepone la query utente con una dichiarazione di modello di map_ip_to_longlat vuota 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')"]

Richiamare un modello

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