查詢 Azure Digital Twins 對應項圖表

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

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

注意

如果您使用 API 或 SDK 呼叫來執行下列範例查詢，則必須將查詢文字壓縮成單行。

參考文件

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

• 子句
  • SELECT
  • 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')

若要指定當有多個對應項集合時要搜尋的對應項集合（例如使用 時 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別名為 、 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')
   

其他複合查詢範例

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

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