Query - Query Twins

リファレンス

Service:: Azure Digital Twins

API Version:: 2023-10-31

リレーションシップの走査とプロパティ値によるフィルター処理を可能にするクエリを実行します。状態コード:

200 OK
400 Bad Request
- BadRequest - 継続トークンが無効です。
- SqlQueryError - クエリにいくつかのエラーが含まれています。
- TimeoutError - クエリの実行が 60 秒後にタイムアウトしました。クエリを簡略化するか、条件を追加して結果のサイズを小さくしてみてください。
429 Too Many Requests
QuotaReachedError - クエリレートの上限に達しました。

POST https://digitaltwins-hostname/query?api-version=2023-10-31

URI パラメーター

名前	/	必須	型	説明
api-version	query	True	string	要求された API バージョン。

要求ヘッダー

名前	型	説明
max-items-per-page	integer	要求ごとに取得するアイテムの最大数。サーバーは、要求された番号より小さい値を返すように選択できます。
traceparent	string	分散トレースシステム内の要求を識別します。
tracestate	string	ベンダー固有のトレース識別情報を提供し、トレース親のコンパニオンです。

要求本文

名前	型	説明
continuationToken	string	前のクエリから次の結果セットを取得するために使用されるトークン。
query	string	実行するクエリ。継続トークンが指定されている場合、この値は無視されます。

応答

名前	型	説明
200 OK	QueryResult	Success Headers query-charge: number
Other Status Codes	ErrorResponse	既定の応答。 Headers x-ms-error-code: string

名前

型

説明

200 OK

QueryResult

Success

Headers

query-charge: number

Other Status Codes

ErrorResponse

既定の応答。

Headers

x-ms-error-code: string

セキュリティ

oauth2

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize?resource=0b07f429-9f4b-4714-9392-cc5e8e80c8b0

例

Query for digital twins

Query for digital twins through a relationship

Retrieve paged query results

Query for digital twins

Sample Request

HTTP

POST https://digitaltwins-hostname/query?api-version=2023-10-31

{
  "query": "SELECT * FROM DIGITALTWINS WHERE temp = 79"
}

Sample Response

Status code:: 200

{
  "value": [
    {
      "$dtId": "Twin-01",
      "$metadata": {
        "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
        "$model": "dtmi:com:example:Sample;1",
        "name": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        },
        "temp": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        },
        "comfortIndex": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        }
      },
      "name": "Sample01",
      "temp": 79,
      "comfortIndex": 50
    },
    {
      "$dtId": "Twin-02",
      "$metadata": {
        "$lastUpdateTime": "2022-02-28T00:29:00.1234567Z",
        "$model": "dtmi:com:example:Sample;1",
        "name": {
          "lastUpdateTime": "2022-02-28T00:29:00.1234567Z"
        },
        "temp": {
          "lastUpdateTime": "2022-02-28T00:29:00.1234567Z",
          "sourceTime": "2022-05-31T12:00:00.000125009Z"
        },
        "comfortIndex": {
          "lastUpdateTime": "2022-02-28T00:29:00.1234567Z"
        }
      },
      "name": "Sample02",
      "temp": 79,
      "comfortIndex": 50
    },
    {
      "$dtId": "Twin-03",
      "$metadata": {
        "$lastUpdateTime": "2022-02-28T00:31:00.1234567Z",
        "$model": "dtmi:com:example:Sample;1",
        "name": {
          "lastUpdateTime": "2022-02-28T00:31:00.1234567Z"
        },
        "temp": {
          "lastUpdateTime": "2022-02-28T00:31:00.1234567Z"
        },
        "comfortIndex": {
          "lastUpdateTime": "2022-02-28T00:31:00.1234567Z"
        }
      },
      "name": "Sample03",
      "temp": 79,
      "comfortIndex": 50
    }
  ],
  "continuationToken": "<token>"
}

Query for digital twins through a relationship

Sample Request

HTTP

POST https://digitaltwins-hostname/query?api-version=2023-10-31

{
  "query": "SELECT Widget, Gadget FROM DIGITALTWINS Widget JOIN Gadget RELATED Widget.Contains WHERE Widget.$dtId = 'Twin-01'"
}

Sample Response

Status code:: 200

{
  "value": [
    {
      "Widget": {
        "$dtId": "Twin-01",
        "$metadata": {
          "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
          "$model": "dtmi:com:example:Sample;1",
          "name": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          },
          "temp": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          },
          "comfortIndex": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          }
        },
        "name": "Sample01",
        "temp": 79,
        "comfortIndex": 50
      },
      "Gadget": {
        "$dtId": "Twin-02",
        "$metadata": {
          "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
          "$model": "dtmi:com:example:Sample;1",
          "name": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          },
          "temp": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          },
          "comfortIndex": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          }
        },
        "name": "Sample02",
        "temp": 79,
        "comfortIndex": 50
      }
    },
    {
      "Widget": {
        "$dtId": "Twin-01",
        "$metadata": {
          "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
          "$model": "dtmi:com:example:Sample;1",
          "name": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          },
          "temp": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          },
          "comfortIndex": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          }
        },
        "name": "Sample01",
        "temp": 79,
        "comfortIndex": 50
      },
      "Gadget": {
        "$dtId": "Twin-10",
        "$metadata": {
          "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
          "$model": "dtmi:com:example:Sample;1",
          "name": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          },
          "temp": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          },
          "comfortIndex": {
            "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
          }
        },
        "name": "Sample10",
        "temp": 79,
        "comfortIndex": 50
      }
    }
  ]
}

Retrieve paged query results

Sample Request

HTTP

POST https://digitaltwins-hostname/query?api-version=2023-10-31

{
  "continuationToken": "<continuationToken from previous query>"
}

Sample Response

Status code:: 200

{
  "value": [
    {
      "$dtId": "Twin-04",
      "$metadata": {
        "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
        "$model": "dtmi:com:example:Sample;1",
        "name": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        },
        "temp": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        },
        "comfortIndex": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        }
      },
      "name": "Sample04",
      "temp": 79,
      "comfortIndex": 50
    },
    {
      "$dtId": "Twin-05",
      "$metadata": {
        "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
        "$model": "dtmi:com:example:Sample;1",
        "name": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        },
        "temp": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        },
        "comfortIndex": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        }
      },
      "name": "Sample05",
      "temp": 79,
      "comfortIndex": 50
    },
    {
      "$dtId": "Twin-06",
      "$metadata": {
        "$lastUpdateTime": "2022-02-28T00:30:00.1234567Z",
        "$model": "dtmi:com:example:Sample;1",
        "name": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        },
        "temp": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        },
        "comfortIndex": {
          "lastUpdateTime": "2022-02-28T00:30:00.1234567Z"
        }
      },
      "name": "Sample06",
      "temp": 79,
      "comfortIndex": 50
    }
  ]
}

定義

名前	説明
Error	エラー定義。
ErrorResponse	エラー応答。
InnerError	含まれているエラーによって提供されたよりも具体的なエラーの説明。
QueryResult	クエリ操作の結果と、省略可能な継続トークン。
QuerySpecification	クエリステートメントまたは前のクエリ結果の継続トークンを含むクエリ仕様。

Error

エラー定義。

名前	型	説明
code	string	HTTP エラーコードのサブステータスとして機能するサービス固有のエラーコード。
details	Error[]	内部エラーの詳細。
innererror	InnerError	エラーに関する現在のオブジェクトよりも具体的な情報を含むオブジェクト。
message	string	エラーの人間が判読できる表現。

ErrorResponse

エラー応答。

名前	型	説明
error	Error	エラーの詳細です。

InnerError

含まれているエラーによって提供されたよりも具体的なエラーの説明。

名前	型	説明
code	string	含まれているエラーによって提供されたよりも具体的なエラーコード。
innererror	InnerError	エラーに関する現在のオブジェクトよりも具体的な情報を含むオブジェクト。

QueryResult

クエリ操作の結果と、省略可能な継続トークン。

名前	型	説明
continuationToken	string	新しい QuerySpecification を構築して次の結果セットを取得するために使用できるトークン。
value	object[]	クエリ結果。

QuerySpecification

クエリステートメントまたは前のクエリ結果の継続トークンを含むクエリ仕様。

名前	型	説明
continuationToken	string	前のクエリから次の結果セットを取得するために使用されるトークン。
query	string	実行するクエリ。継続トークンが指定されている場合、この値は無視されます。

Query - Query Twins

URI パラメーター

要求ヘッダー

要求本文

応答

セキュリティ

oauth2

例

Query for digital twins

Sample Request

Sample Response

Query for digital twins through a relationship

Sample Request

Sample Response

Retrieve paged query results

Sample Request

Sample Response

定義

Error

ErrorResponse

InnerError

QueryResult

QuerySpecification

フィードバック

フィードバック

その他のリソース