共用方式為


查詢 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 只需要參數 twinTypeNameIS_OF_MODEL(twinTypeName)。 以下是傳遞此參數中值的查詢範例:

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

若要指定當有多個對應項集合時要搜尋的對應項集合(例如使用 時 JOIN ),請新增 twinCollection 參數: 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 模型 功能時,關聯性並不存在於對應項,這表示無法獨立查詢這裡的關聯性,而且必須系結至對應項。 為了反映這個事實,在 子句中使用 JOIN 關鍵詞RELATED來提取來自對應項集合的特定關聯性集合。 然後,查詢必須在 子句中 WHERE 篩選,以指出關聯性查詢中使用的特定對應項(使用對應項 $dtId 的值)。

下列各節提供其外觀範例。

基本關聯性查詢

以下是以關聯性為基礎的範例查詢。 此代碼段會選取具有 ID 屬性 ABC的所有數字對應項,以及透過關聯性與這些數位對應項相關的所有數字 contains 對應項。

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

關聯性的類型 (contains在上述範例中) 會使用其 DTDL 定義的關聯name性字段來表示。

注意

開發人員不需要將此與 子句中的WHERE索引鍵值相互關聯JOIN(或指定與定義內嵌的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 關聯性。

例如,請考慮 servicedBy 具有 屬性的 reportedCondition 關聯性。 在下列查詢中,此關聯性會提供 的 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 進行查詢

單一查詢最多可支援 5 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

您也可以搭配 JOIN 子句使用COUNT。 以下查詢會計算會議室 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 透過 的關聯 Factory.customer性來投影取用者、Factory 和 Edge,而該關聯性會顯示為 Edge

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

您也可以使用投影傳回對應項的屬性。 下列查詢會投影Name取用者的屬性,而該取用者會透過的關聯性,而該取用者具有的Factory.customer標識符ABC

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

您也可以使用投影傳回關聯性的屬性。 如同在上一個範例中,下列查詢會透過關聯性來投影Name與 Factory 相關的取用者屬性,且標識子為 ,但現在它也會傳回該關聯性的兩個ABCFactory.customer屬性,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別名為 、 firstsecondfactoryArea

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

其他複合查詢範例

您可以使用組合運算子結合上述任何查詢類型,以在單一查詢中包含更多詳細數據。 以下是一些其他複合查詢範例,可一次查詢一種以上的對應項描述元。

  • 在 Room 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。