共用方式為


查詢 Azure Digital Twins 對應項圖表

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

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

注意

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

參考文件

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

顯示所有數位對應項

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

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 欄位。

注意

開發人員不需要將此 JOINWHERE 子句中的索引鍵值相互關聯 (或指定以 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'

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

使用多個 JOIN 來進行查詢

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

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

以下是多重聯結查詢的範例,其會取得會議室 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

您也可以搭配使用 COUNTJOIN 子句。 以下是計算會議室 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 相關的取用者屬性,但現在亦會傳回該關聯性的兩個屬性,分別是 prop1prop2。 其作法為將關聯性命名為 Edge 並收集其屬性。

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

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

下列查詢會執行與上一個範例相同的作業,但會將屬性名稱設為別名 consumerNamefirstsecondfactoryArea

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。