查詢 Azure Digital Twins 對應項圖表

本文提供使用 Azure Digital Twins 查詢語言 來查詢對應項圖形以取得資訊的查詢範例和指示。 (如需查詢語言簡介，請參閱查詢語言。)

本文包含範例查詢，用於說明數位對應項的查詢語言結構和常見查詢作業。 它也描述如何在撰寫查詢之後，使用 Azure Digital Twins 查詢 API 或 SDK來執行查詢。

注意

如果您使用 API 或 SDK 呼叫執行下列範例查詢，您會需要將查詢文字簡訊壓縮成單行。

參考文件

您可以在 Azure Digital Twins 文件左側目錄的 [參考] 下方找到查詢語言參考。 您也可以使用下列連結直接移至參考區段：

• 子句
  • 選取
  • FROM
  • MATCH
  • JOIN
  • WHERE
• 函數
• 運算子
• 保留關鍵字

顯示所有數位對應項

以下為會傳回執行個體中所有數位對應項清單的基本查詢：

SELECT * FROM DIGITALTWINS

依屬性查詢

依屬性取得數位對應項 (包括識別碼和中繼資料)：

SELECT  *
FROM DIGITALTWINS T  
WHERE T.firmwareVersion = '1.1'
AND T.$dtId in ['123', '456']
AND T.Temperature = 70

如上述查詢所示，可使用中繼資料欄位 $dtId 來查詢數位對應項的識別碼。

提示

如果您使用 Cloud Shell 來執行以 $ 開頭的中繼資料欄位查詢，請使用倒單引號來逸出 $，讓 Cloud Shell 知道這並不是變數，並應該以查詢文字中的常值來取用。

您也可以根據是否有定義特定屬性來取得對應項。 以下查詢會取得具有已定義 Location 屬性的對應項：

SELECT *​ FROM DIGITALTWINS WHERE IS_DEFINED(Location)

此查詢可協助您依其 tag 屬性來取得對應項，如將標籤新增至數位對應項中所述。 以下查詢會取得 red 標籤的所有對應項：

SELECT * FROM DIGITALTWINS WHERE IS_DEFINED(tags.red)

您亦可以根據類型的屬性而取得對應項。 以下為取得其 Temperature 屬性為數字的對應項查詢：

SELECT * FROM DIGITALTWINS​ T WHERE IS_NUMBER(T.Temperature)

查詢對應屬性

如果屬性屬於複雜類型 Map ，您可以直接在查詢中使用對應索引鍵和值，如下所示：

SELECT * FROM DIGITALTWINS​ T WHERE T.<propertyName>.<mapKey> = '<mapValue>'

如果對應鍵以數值字元開頭，您必須將索引鍵包裝在雙方括弧中 ([[<mapKey>]]) ，以在查詢中逸出它，類似于 使用保留關鍵字進行查詢的策略。

依模型查詢

IS_OF_MODEL 運算子可用於依據對應項的 模型來進行篩選。

如果對應項符合下列任一條件，其即會考慮繼承和模型版本設定，並將指定的對應項評估為 true：

• 對應項直接實作提供給 IS_OF_MODEL() 的模型，而且對應項上的模型版本號碼大於或等於所提供模型的版本號碼
• 對應項實作的模型可擴充提供給 IS_OF_MODEL() 的模型，而且對應項的擴充模型版本號碼大於或等於所提供模型的版本號碼

例如，如果您查詢模型 dtmi:example:widget;4 的對應項，則查詢會根據第 4 版或更新版本的小工具模型傳回所有對應項，並且根據任何繼承自小工具的第 4 版或更新版本模型傳回所有對應項。

IS_OF_MODEL 可以採用數個不同參數，而本節其餘部分則專用於其不同的多載選項。

IS_OF_MODEL 最簡單的用法僅需要 twinTypeName 參數：IS_OF_MODEL(twinTypeName)。 以下查詢範例會在此參數中傳遞一個值：

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1')

若要在有不只一項時 (例如在使用 twinCollection 時) 以指定一個搜尋的對應項，則需要新增 JOIN 參數：IS_OF_MODEL(twinCollection, twinTypeName)。 以下為新增此參數值的查詢範例：

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1')

若要執行完全比對，請新增 exact 參數：IS_OF_MODEL(twinTypeName, exact)。 以下為新增此參數值的查詢範例：

SELECT * FROM DIGITALTWINS WHERE IS_OF_MODEL('dtmi:example:thing;1', exact)

您亦可以將這三個引數一起傳遞：IS_OF_MODEL(twinCollection, twinTypeName, exact)。 以下是一個指定這三個參數值的查詢範例：

SELECT * FROM DIGITALTWINS DT WHERE IS_OF_MODEL(DT, 'dtmi:example:thing;1', exact)

依關聯性查詢

根據數位對應項的關聯性進行查詢時，Azure Digital Twins 查詢語言具有特殊語法。

關聯性會提取到 FROM 子句的查詢範圍中。 不同於「傳統」SQL 類型語言，在 FROM 子句中的每個運算式並不是資料表，而是表示跨實體關聯性周遊的 FROM 子句。 若要跨關聯性周遊，Azure Digital Twins 會使用自訂版本的 JOIN。

利用 Azure Digital Twins 模型功能來重新叫用，關聯性並不是獨立存在的對應項，表示在這裡的關聯性無法獨立查詢並且務必要繫結至對應項。 若要反映此事實，子句 RELATED 中會使用關鍵字 JOIN 提取來自對應項集合的特定關聯性類型。 然後，查詢必須在子句 WHERE 中篩選，以指出要使用對應項關聯性查詢 (使用對應項的 $dtId 值)。

下列各節提供看起來 模樣的範例。

基本關聯性查詢

這是範例關聯型的查詢。 此程式碼片段選取 ID 屬性為 ABC 的所有數位對應項，以及透過 contains 關聯性與這些數位對應項相關的所有數位對應項。

SELECT T, CT
FROM DIGITALTWINS T
JOIN CT RELATED T.contains
WHERE T.$dtId = 'ABC'

(上述範例中的 contains) 此類型的關聯性會指出使用來自其 DTDL 定義關聯性的 name 欄位。

注意

開發人員不需要將此 JOIN 與 WHERE 子句中的索引鍵值相互關聯 (或指定以 JOIN 定義內嵌的索引鍵值)。 這項相互關聯作業由系統自動計算，因為關聯性屬性本身會識別目標實體。

依關聯性的來源或目標來進行查詢

您可以使用關聯性查詢結構，來識別屬於關聯性來源或目標的數位對應項。

例如，您可以從來源對應項開始，並遵循其關聯性以尋找關聯性的目標對應項。 以下是查詢的範例，其會尋找來自對應項來源對應項關聯性的 feeds 目標對應項。

SELECT target 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE source.$dtId = 'source-twin'

您亦可以從關聯性的目標開始，並回頭追蹤其關聯性，以尋找來源對應項。 以下是查詢的範例，其會尋找與對應專案標對應項關聯性的 feeds 來源對應項。

SELECT source 
FROM DIGITALTWINS source 
JOIN target RELATED source.feeds 
WHERE target.$dtId = 'target-twin'

查詢關聯性的屬性

類似於數位對應項透過 DTDL 描述屬性的方式，關聯性也可以具有屬性。 您可以根據關聯性的屬性查詢對應項。 Azure Digital Twins 查詢語言可藉由將別名指派給 JOIN 子句內的關聯性，以允許篩選及投射關聯性。

例如，請考慮具有 reportedCondition 屬性的 servicedBy 關聯性。 在下一個範例中，會為此關聯性提供 R 的別名，以利於參考其屬性。

SELECT T, SBT, R
FROM DIGITALTWINS T
JOIN SBT RELATED T.servicedBy R
WHERE T.$dtId = 'ABC'
AND R.reportedCondition = 'clean'

在上述範例中，請注意 reportedCondition 是 servicedBy 關聯性本身的屬性 (並非某些具有 servicedBy 關聯性的數位對應項)。

使用多個 JOIN 來進行查詢

單一查詢最多支援五個 JOIN，可讓您一次周遊數個層級的關聯性。

若要取得包含關聯性的資料集，請使用單一 FROM 陳述式，緊接著 N 個 JOIN 陳述式，其中 JOIN 陳述式會表示與前一個 FROM 或 JOIN 陳述式結果的關聯性。

以下是多重聯結查詢的範例，其會取得會議室 1 和 2 中在光線面板內包含的所有燈泡。

SELECT LightBulb
FROM DIGITALTWINS Room
JOIN LightPanel RELATED Room.contains
JOIN LightBulb RELATED LightPanel.contains
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb ;1')
AND Room.$dtId IN ['room1', 'room2']

計數項目

您可以使用 Select COUNT 子句來計算結果集之中項目的數目：

SELECT COUNT()
FROM DIGITALTWINS

新增 WHERE 子句以計算符合指定準則項目的數目。 以下是依據對應項模型類型計算而套用的一些篩選範例 (如需此語法的詳細資訊，請參閱下列模型查詢)：

SELECT COUNT()
FROM DIGITALTWINS
WHERE IS_OF_MODEL('dtmi:sample:Room;1')

SELECT COUNT()
FROM DIGITALTWINS c
WHERE IS_OF_MODEL('dtmi:sample:Room;1') AND c.Capacity > 20

您也可以搭配使用 COUNT 和 JOIN 子句。 以下是計算會議室 1 和 2 之光線面板中涵蓋的所有燈泡查詢：

SELECT COUNT()  
FROM DIGITALTWINS Room  
JOIN LightPanel RELATED Room.contains  
JOIN LightBulb RELATED LightPanel.contains  
WHERE IS_OF_MODEL(LightPanel, 'dtmi:contoso:com:lightpanel;1')  
AND IS_OF_MODEL(LightBulb, 'dtmi:contoso:com:lightbulb;1')  
AND Room.$dtId IN ['room1', 'room2']

篩選結果：選取頂端項目

您可以使用 Select TOP 子句，以在查詢中選取數個「頂端」項目。

SELECT TOP (5)
FROM DIGITALTWINS
WHERE ...

篩選結果：指定具有投影的傳回集合

藉由在 SELECT 語句中使用投影，您可以選取將傳回查詢的資料行。 基本屬性和複雜屬性現在都支援投影。 如需使用 Azure Digital Twins 投影的詳細資訊，請參閱 SELECT 子句參考文件。

以下是使用投影傳回對應項和關聯性的查詢範例。 下列查詢會從識別碼為 ABC 的處理站來透過 Factory.customer 的關聯性投影取用者、Factory 和 Azure Stack Edge，而其關聯性會顯示為 Edge。

SELECT Consumer, Factory, Edge
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

您亦可以使用投影來傳回對應項的屬性。 下列查詢會投影取用者的 Name 屬性，而這些取用者會透過 ABC 的關聯性來與 Factory.customer 的識別碼相關。

SELECT Consumer.name
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

您亦可以使用投影來傳回相關聯的屬性。 如同上一個範例，下列查詢會透過的 Factory.customer 關聯性，投影 Name 與識別碼為 ABC 之 Factory 相關的取用者屬性，但現在亦會傳回該關聯性的兩個屬性，分別是 prop1 與 prop2。 其作法為將關聯性命名為 Edge 並收集其屬性。

SELECT Consumer.name, Edge.prop1, Edge.prop2, Factory.area
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

您亦可以使用別名來簡化投影查詢。

下列查詢會執行與上一個範例相同的作業，但會將屬性名稱設為別名 consumerName、first、second 和 factoryArea。

SELECT Consumer.name AS consumerName, Edge.prop1 AS first, Edge.prop2 AS second, Factory.area AS factoryArea
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

以下是查詢與上述相同集合的類似查詢，但僅將 Consumer.name 屬性投影為 consumerName，並將完整的 Factory 投影為對應項。

SELECT Consumer.name AS consumerName, Factory
FROM DIGITALTWINS Factory
JOIN Consumer RELATED Factory.customer Edge
WHERE Factory.$dtId = 'ABC'

使用 IN 運算子建置有效率的查詢

您可以藉由使用 IN 運算子來建置對應項的陣列和查詢，以大幅減少所需的查詢數目。

例如，考慮到建築物包含樓層而且樓層包含會議室的情節。 若要搜尋建築物內經常使用的會議室，其中一種方式是遵循下列這些步驟。

1. 依據 contains 關聯性來尋找建築物中的樓層。

   SELECT Floor
   FROM DIGITALTWINS Building
   JOIN Floor RELATED Building.contains
   WHERE Building.$dtId = @buildingId
   

2. 若要尋找會議室，而不是一一查找樓層，並執行 JOIN 查詢來尋找各樓層的會議室，您可以在下列查詢中建築物樓層中的集合 (下列命名為 Floor 的樓層集合)。

   在用戶端應用程式中：

   var floors = "['floor1','floor2', ..'floorn']"; 
   

   在查詢中：

   SELECT Room
   FROM DIGITALTWINS Floor
   JOIN Room RELATED Floor.contains
   WHERE Floor.$dtId IN ['floor1','floor2', ..'floorn']
   AND Room. Temperature > 72
   AND IS_OF_MODEL(Room, 'dtmi:com:contoso:Room;1')
   

其他複合查詢範例

您可以使用組合運算子，結合上述任何類型的查詢，以在單一查詢中包含更多詳細資料。 以下為一些其他的複合查詢範例，一次查詢不只一個對應項描述項的類型。

• 在會議室 123 擁有之裝置中，傳回提供操作員角色的 MxChip 裝置

  SELECT device
  FROM DIGITALTWINS space
  JOIN device RELATED space.has
  WHERE space.$dtid = 'Room 123'
  AND device.$metadata.model = 'dtmi:contoso:com:DigitalTwins:MxChip:3'
  AND has.role = 'Operator'
  

• 取得具有名為 Contains 的關聯性且與具有識別碼 id1 的另一個對應項相關聯的對應項

  SELECT Room
  FROM DIGITALTWINS Room
  JOIN Thermostat RELATED Room.Contains
  WHERE Thermostat.$dtId = 'id1'
  

• 取得由 floor11 所包含此會議室模型的所有會議室

  SELECT Room
  FROM DIGITALTWINS Floor
  JOIN Room RELATED Floor.Contains
  WHERE Floor.$dtId = 'floor11'
  AND IS_OF_MODEL(Room, 'dtmi:contoso:com:DigitalTwins:Room;1')
  

運用 API 執行查詢

決定查詢字串之後，您可以藉由呼叫查詢 API 來執行。

您可以直接呼叫 API，或使用 Azure Digital Twins 可用的其中一個 SDK。

下列程式碼片段說明來自用戶端應用程式的 .NET (C#) SDK 呼叫：

// Run a query for all twins   
string query = "SELECT * FROM DIGITALTWINS";
AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>(query);

此呼叫中使用的查詢會傳回數位對應項的清單，上述範例會以 BasicDigitalTwin 物件表示。 每個查詢傳回的類型資料取決於您以 SELECT 語句指定的字詞：

• 開頭為 SELECT * FROM ... 的查詢會傳回數位對應項清單，(可序列化為 BasicDigitalTwin 物件，或您可能已建立的其他自訂數位對應項類型)。
• 以格式 SELECT <A>, <B>, <C> FROM ... 開頭的查詢會傳回具有索引鍵 <A>、<B> 和 <C> 的字典。
• 可以製作其他格式的 SELECT 語句，以傳回自訂資料。 您可以考慮建立自己的類別以處理自訂的結果集。

運用分頁查詢

查詢呼叫支援分頁。 以下為使用 BasicDigitalTwin 作為錯誤處理和分頁之查詢結果類型的完整範例：

AsyncPageable<BasicDigitalTwin> result = client.QueryAsync<BasicDigitalTwin>("Select * From DigitalTwins");
try
{
    await foreach (BasicDigitalTwin twin in result)
    {
        // You can include your own logic to print the result
        // The logic below prints the twin's ID and contents
        Console.WriteLine($"Twin ID: {twin.Id} \nTwin data");
        foreach (KeyValuePair<string, object> kvp in twin.Contents)
        {
            Console.WriteLine($"{kvp.Key}  {kvp.Value}");
        }
    }
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Error {ex.Status}, {ex.ErrorCode}, {ex.Message}");
    throw;
}

下一步

深入瞭解 Azure Digital Twins API 和 SDK，其中包括用來執行本文查詢的查詢 API。