Query - Query Twins

Référence

Service:: Azure Digital Twins

API Version:: 2023-10-31

Exécute une requête qui permet de parcourir les relations et de filtrer par valeurs de propriété. Codes d’état :

200 OK
400 Demande incorrecte
- BadRequest : le jeton de continuation n’est pas valide.
- SqlQueryError : la requête contient des erreurs.
- TimeoutError : l’exécution de la requête a expiré après 60 secondes. Essayez de simplifier la requête ou d’ajouter des conditions pour réduire la taille des résultats.
429 Trop de demandes
QuotaReachedError : la limite de débit de requête maximale a été atteinte.

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

Paramètres URI

Nom	Dans	Obligatoire	Type	Description
api-version	query	True	string	Version de l’API demandée.

En-tête de la demande

Nom	Type	Description
max-items-per-page	integer	Nombre maximal d’éléments à récupérer par requête. Le serveur peut choisir de retourner moins que le nombre demandé.
traceparent	string	Identifie la demande dans un système de suivi distribué.
tracestate	string	Fournit des informations d’identification de trace spécifiques au fournisseur et est un complément à traceparent.

Corps de la demande

Nom	Type	Description
continuationToken	string	Jeton utilisé pour récupérer l’ensemble de résultats suivant à partir d’une requête précédente.
query	string	Requête à exécuter. Cette valeur est ignorée si un jeton de continuation est fourni.

Réponses

Nom	Type	Description
200 OK	QueryResult	Succès Headers query-charge: number
Other Status Codes	ErrorResponse	Réponse par défaut. Headers x-ms-error-code: string

Nom

Type

Description

200 OK

QueryResult

Succès

Headers

query-charge: number

Other Status Codes

ErrorResponse

Réponse par défaut.

Headers

x-ms-error-code: string

Sécurité

oauth2

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

Exemples

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

Définitions

Nom	Description
Error	Définition de l’erreur.
ErrorResponse	Réponse d’erreur.
InnerError	Une description de l’erreur plus spécifique que celle fournie par l’erreur contenante.
QueryResult	Résultats d’une opération de requête et d’un jeton de continuation facultatif.
QuerySpecification	Spécification de requête contenant une instruction de requête ou un jeton de continuation d’un résultat de requête précédent.

Error

Définition de l’erreur.

Nom	Type	Description
code	string	Code d’erreur spécifique au service qui sert de sous-état pour le code d’erreur HTTP.
details	Error[]	Détails de l’erreur interne.
innererror	InnerError	Objet contenant des informations plus spécifiques que l’objet actuel sur l’erreur.
message	string	Représentation lisible par l’homme de l’erreur.

ErrorResponse

Réponse d’erreur.

Nom	Type	Description
error	Error	Détails de l’erreur.

InnerError

Une description de l’erreur plus spécifique que celle fournie par l’erreur contenante.

Nom	Type	Description
code	string	Un code d’erreur plus spécifique que celui fourni par l’erreur contenante.
innererror	InnerError	Objet contenant des informations plus spécifiques que l’objet actuel sur l’erreur.

QueryResult

Résultats d’une opération de requête et d’un jeton de continuation facultatif.

Nom	Type	Description
continuationToken	string	Jeton qui peut être utilisé pour construire une nouvelle QuerySpecification afin de récupérer l’ensemble de résultats suivant.
value	object[]	Résultats de requête.

QuerySpecification

Spécification de requête contenant une instruction de requête ou un jeton de continuation d’un résultat de requête précédent.

Nom	Type	Description
continuationToken	string	Jeton utilisé pour récupérer l’ensemble de résultats suivant à partir d’une requête précédente.
query	string	Requête à exécuter. Cette valeur est ignorée si un jeton de continuation est fourni.

Partager via

Query - Query Twins

Paramètres URI

En-tête de la demande

Corps de la demande

Réponses

Sécurité

oauth2

Exemples

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

Définitions

Error

ErrorResponse

InnerError

QueryResult

QuerySpecification

Commentaires

Commentaires

Ressources supplémentaires