Query - Query Twins

  • Referência
Service:
Azure Digital Twins
API Version:
2023-10-31

Executa uma consulta que permite a passagem de relações e a filtragem por valores de propriedade. Códigos de status:

  • 200 OK
  • 400 Solicitação Inválida
    • BadRequest - O token de continuação é inválido.
    • SqlQueryError – a consulta contém alguns erros.
    • TimeoutError - A execução da consulta atingiu o tempo limite após 60 segundos. Tente simplificar a consulta ou adicionar condições para reduzir o tamanho do resultado.
  • 429 Número excessivo de solicitações
  • QuotaReachedError - O limite máximo de taxa de consulta foi atingido.
POST https://digitaltwins-hostname/query?api-version=2023-10-31

Parâmetros de URI

Nome Em Obrigatório Tipo Description
api-version
 query True

string

A versão da API solicitada.

Cabeçalho da solicitação

Nome Obrigatório Tipo Description
max-items-per-page

integer

O número máximo de itens a serem recuperados por solicitação. O servidor pode optar por retornar menos do que o número solicitado.
traceparent

string

Identifica a solicitação em um sistema de rastreamento distribuído.
tracestate

string

Fornece informações de identificação de rastreamento específicas do fornecedor e é um complemento para o rastreamentoparente.

Corpo da solicitação

Nome Tipo Description
continuationToken

string

Um token usado para recuperar o próximo conjunto de resultados de uma consulta anterior.
query

string

A consulta a ser executada. Esse valor será ignorado se um token de continuação for fornecido.

Respostas

Nome Tipo Description
200 OK

QueryResult

Sucesso

Headers

query-charge: number
Other Status Codes

ErrorResponse

Resposta padrão.

Headers

x-ms-error-code: string

Segurança

oauth2

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

Exemplos

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

Definições

Nome Description
Error

Definição de erro.
ErrorResponse

Resposta de erro.
InnerError

Uma descrição de erro mais específica do que foi fornecida pelo erro que contém.
QueryResult

Os resultados de uma operação de consulta e um token de continuação opcional.
QuerySpecification

Uma especificação de consulta que contém uma instrução de consulta ou um token de continuação de um resultado de consulta anterior.

Error

Definição de erro.

Nome Tipo Description
code

string

Código de erro específico do serviço que serve como substatus para o código de erro HTTP.
details

Error[]

Detalhes do erro interno.
innererror

InnerError

Um objeto que contém informações mais específicas do que o objeto atual sobre o erro.
message

string

Uma representação legível pelo homem do erro.

ErrorResponse

Resposta de erro.

Nome Tipo Description
error

Error

Os detalhes do erro.

InnerError

Uma descrição de erro mais específica do que foi fornecida pelo erro que contém.

Nome Tipo Description
code

string

Um código de erro mais específico do que foi fornecido pelo erro que contém.
innererror

InnerError

Um objeto que contém informações mais específicas do que o objeto atual sobre o erro.

QueryResult

Os resultados de uma operação de consulta e um token de continuação opcional.

Nome Tipo Description
continuationToken

string

Um token que pode ser usado para construir uma nova QuerySpecification para recuperar o próximo conjunto de resultados.
value

object[]

Os resultados da consulta.

QuerySpecification

Uma especificação de consulta que contém uma instrução de consulta ou um token de continuação de um resultado de consulta anterior.

Nome Tipo Description
continuationToken

string

Um token usado para recuperar o próximo conjunto de resultados de uma consulta anterior.
query

string

A consulta a ser executada. Esse valor será ignorado se um token de continuação for fornecido.