Query - Query Twins

  • Referenz
Service:
Azure Digital Twins
API Version:
2023-10-31

Führt eine Abfrage aus, die das Durchlaufen von Beziehungen und das Filtern nach Eigenschaftswerten ermöglicht. Statuscodes:

  • 200 – OK
  • 400 – Ungültige Anforderung
    • BadRequest: Das Fortsetzungstoken ist ungültig.
    • SqlQueryError: Die Abfrage enthält einige Fehler.
    • TimeoutError: Bei der Abfrageausführung ist nach 60 Sekunden ein Timeout auftritt. Versuchen Sie, die Abfrage zu vereinfachen oder Bedingungen hinzuzufügen, um die Ergebnisgröße zu reduzieren.
  • 429 – Zu viele Anforderungen
  • QuotaReachedError: Die maximale Abfragerate wurde erreicht.
POST https://digitaltwins-hostname/query?api-version=2023-10-31

URI-Parameter

Name In Erforderlich Typ Beschreibung
api-version
 query True

string

Die angeforderte API-Version.

Anforderungsheader

Name Erforderlich Typ Beschreibung
max-items-per-page

integer

Die maximale Anzahl von Elementen, die pro Anforderung abgerufen werden sollen. Der Server gibt möglicherweise weniger als die angeforderte Nummer zurück.
traceparent

string

Identifiziert die Anforderung in einem verteilten Ablaufverfolgungssystem.
tracestate

string

Stellt herstellerspezifische Ablaufverfolgungsinformationen bereit und ist ein Begleiter für die Ablaufverfolgung.

Anforderungstext

Name Typ Beschreibung
continuationToken

string

Ein Token, das verwendet wird, um den nächsten Satz von Ergebnissen aus einer vorherigen Abfrage abzurufen.
query

string

Die auszuführende Abfrage. Dieser Wert wird ignoriert, wenn ein Fortsetzungstoken bereitgestellt wird.

Antworten

Name Typ Beschreibung
200 OK

QueryResult

Erfolg

Headers

query-charge: number
Other Status Codes

ErrorResponse

Standardantwort.

Headers

x-ms-error-code: string

Sicherheit

oauth2

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

Beispiele

Query for digital twins
Query for digital twins through a relationship
Retrieve paged query results

Query for digital twins

Sample Request

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

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

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
    }
  ]
}

Definitionen

Name Beschreibung
Error

Fehlerdefinition.
ErrorResponse

Fehlerantwort.
InnerError

Eine spezifischere Fehlerbeschreibung, als vom enthaltenden Fehler bereitgestellt wurde.
QueryResult

Die Ergebnisse eines Abfragevorgangs und eines optionalen Fortsetzungstokens.
QuerySpecification

Eine Abfragespezifikation, die entweder eine Abfrageanweisung oder ein Fortsetzungstoken aus einem vorherigen Abfrageergebnis enthält.

Error

Fehlerdefinition.

Name Typ Beschreibung
code

string

Dienstspezifischer Fehlercode, der als Unterstatus für den HTTP-Fehlercode dient.
details

Error[]

Interne Fehlerdetails.
innererror

InnerError

Ein -Objekt, das spezifischere Informationen enthält als das aktuelle Objekt über den Fehler.
message

string

Eine lesbare Darstellung des Fehlers.

ErrorResponse

Fehlerantwort.

Name Typ Beschreibung
error

Error

Die Fehlerdetails.

InnerError

Eine spezifischere Fehlerbeschreibung, als vom enthaltenden Fehler bereitgestellt wurde.

Name Typ Beschreibung
code

string

Ein spezifischerer Fehlercode, als vom enthaltenden Fehler bereitgestellt wurde.
innererror

InnerError

Ein -Objekt, das spezifischere Informationen enthält als das aktuelle Objekt über den Fehler.

QueryResult

Die Ergebnisse eines Abfragevorgangs und eines optionalen Fortsetzungstokens.

Name Typ Beschreibung
continuationToken

string

Ein Token, das zum Erstellen einer neuen QuerySpecification verwendet werden kann, um den nächsten Satz von Ergebnissen abzurufen.
value

object[]

Die Abfrageergebnisse.

QuerySpecification

Eine Abfragespezifikation, die entweder eine Abfrageanweisung oder ein Fortsetzungstoken aus einem vorherigen Abfrageergebnis enthält.

Name Typ Beschreibung
continuationToken

string

Ein Token, das verwendet wird, um den nächsten Satz von Ergebnissen aus einer vorherigen Abfrage abzurufen.
query

string

Die auszuführende Abfrage. Dieser Wert wird ignoriert, wenn ein Fortsetzungstoken bereitgestellt wird.