Pattern 語句

適用於：✅Microsoft Fabric✅Azure 數據總管✅Azure 監視器✅Microsoft Sentinel

模式 是將字串元組對應至表格式表達式的建構。

每個模式都必須 宣告 模式名稱，並選擇性地 定義模式對應。 定義對應的模式會在叫用時傳回表格式表達式。 以分號分隔任兩個語句。

空白模式是宣告但未定義對應的模式。 叫用時，它們會傳回錯誤 SEM0036，以及 HTTP 標頭中遺漏模式定義的詳細數據。

提供 Kusto 查詢語言 （KQL） 體驗的仲介層應用程式可以使用傳回的詳細數據作為其程式的一部分，以擴充 KQL 查詢結果。 如需詳細資訊，請參閱 使用中介層應用程式。

語法

• 宣告空白模式：

  declare pattern PatternName;

• 宣告並定義模式：

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

  {

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

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

  } ;

• 叫用模式：

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

深入瞭解語法慣例。

參數

名字	類型	必填	描述
PatternName	string	✔️	模式的名稱。
ArgName	string	✔️	自變數的名稱。 模式可以有一或多個自變數。
ArgType	string	✔️	ArgName 自變數的純量數據類型。 可能的值：string
PathName	string		path 自變數的名稱。 模式不能有路徑或一個路徑。
PathArgType	string		PathArgType 自變數的類型。 可能的值：string
ArgValue	string	✔️	ArgName 和選擇性 PathName Tuple 值，以對應至表達式。
PathValue	string		要對應 PathName的值。
表示式	string	✔️	參考傳回表格式數據的函式的表格式或 Lambda 表達式。 例如：Logs | where Timestamp > ago(1h)

例子

本節中的範例示範如何使用 語法來協助您開始使用。

本文中的範例會使用公開可用的數據表，例如天氣分析中的 StormEvents 數據表，範例數據。

定義簡單模式

此範例會定義模式，此模式會將狀態對應至傳回其首都/主要城市的表達式。

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

輸出

資本
埃德蒙頓

定義範圍模式

此範例會定義一個模式來界定應用程式數據的數據和計量。 叫用模式以傳回數據的聯集。

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

輸出

應用程式	數據	指標
應用程式 #2	9
應用程式 #2	8
應用程式 #2	7
應用程式 #2	6
應用程式 #2	5
應用程式 #1		0.53674122855537532
應用程式 #1		0.78304713305654439
應用程式 #1		0.20168860732346555
應用程式 #1		0.13249123867679469
應用程式 #1		0.19388305330563443

正常化

叫用模式有語法變化。 例如，下列聯集會傳回單一模式表達式，因為所有調用都是相同的模式。

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

沒有通配符

在模式中對通配符沒有特殊待遇。 例如，下列查詢會傳回單一遺漏的模式調用。

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

輸出語意錯誤

未宣告一或多個模式參考。 偵測到的模式參考：[“app（'ApplicationX'）。['*']"]

使用中介層應用程式

仲介層應用程式可讓使用者使用 KQL，並想要透過從其內部服務擴充查詢結果，來增強體驗。

為此，應用程式會為使用者提供模式語句，以傳回其使用者可在查詢中使用的表格式數據。 模式的自變數是應用程式用來擷取擴充數據的索引鍵。

當使用者執行查詢時，應用程式不會剖析查詢本身，而是使用空模式傳回的錯誤來擷取所需的密鑰。 因此，它會在查詢前面加上空模式宣告、將它傳送至叢集進行處理，然後剖析傳回的 HTTP 標頭以擷取遺漏模式自變數的值。 應用程式會使用這些值來查閱擴充數據，並建置新的宣告來定義適當的擴充數據對應。

最後，應用程式會在查詢前面加上新的定義、重新傳送它進行處理，並將它接收的結果傳回給使用者。

例

在範例中，會宣告、定義並叫用模式。

宣告空白模式

在此範例中，中介層應用程式會擴充具有經度/緯度位置的查詢。 應用程式會使用內部服務將IP位址對應至經度/緯度位置，並提供稱為 map_ip_to_longlat的模式。 執行查詢時，它會傳回遺漏模式定義的錯誤：

map_ip_to_longlat("10.10.10.10")

宣告和定義模式

應用程式不會剖析此查詢，因此並不知道哪個IP位址 （10.10.10.10） 傳遞至模式。 因此，它會在使用者查詢前面加上空白 map_ip_to_longlat 模式宣告，並傳送它進行處理：

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

應用程式會收到下列回應錯誤。

未宣告一或多個模式參考。 偵測到的模式參考：[“map_ip_to_longlat（'10.10.10.10'）]]

叫用模式

應用程式會檢查錯誤、判斷錯誤指出遺漏的模式參考，並擷取遺漏的IP位址（10.10.10.10）。 它會使用IP位址來查閱其內部服務中的擴充數據，並建置新的模式，以定義IP位址對應至對應的經度和緯度數據。 新的模式會預先加上使用者的查詢，然後再次執行。

這次查詢會成功，因為擴充數據現在在查詢中宣告，而且結果會傳送給使用者。

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

輸出

Lat	Long
37.405992	-122.078515