Query - Query Twins

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

Executa uma consulta que permite atravessar relações e filtrar por valores de propriedade. Códigos de estado:

  • 200 OK
  • 400 Pedido Incorreto
    • BadRequest - O token de continuação é inválido.
    • SqlQueryError – a consulta contém alguns erros.
    • TimeoutError – a execução da consulta excedeu o tempo limite após 60 segundos. Experimente simplificar a consulta ou adicionar condições para reduzir o tamanho dos resultados.
  • Demasiados Pedidos 429
  • QuotaReachedError – o limite máximo de taxa de consultas foi atingido.
POST https://digitaltwins-hostname/query?api-version=2023-10-31

Parâmetros do URI

Name Em Necessário Tipo Description
api-version
 query True

string

A versão da API pedida.

Cabeçalho do Pedido

Name Necessário Tipo Description
max-items-per-page

integer

O número máximo de itens a obter por pedido. O servidor pode optar por devolver menos do que o número pedido.
traceparent

string

Identifica o pedido num sistema de rastreio distribuído.
tracestate

string

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

Corpo do Pedido

Name Tipo Description
continuationToken

string

Um token que é utilizado para obter o próximo conjunto de resultados de uma consulta anterior.
query

string

A consulta a executar. Este valor é ignorado se for fornecido um token de continuação.

Respostas

Name Tipo Description
200 OK

QueryResult

Com êxito

Headers

query-charge: number
Other Status Codes

ErrorResponse

Resposta predefinida.

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

Name Description
Error

Definição de erro.
ErrorResponse

Resposta de erro.
InnerError

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

Os resultados de uma operação de consulta e de 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.

Name Tipo Description
code

string

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

Error[]

Detalhes internos do erro.
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 por humanos do erro.

ErrorResponse

Resposta de erro.

Name Tipo Description
error

Error

Os detalhes do erro.

InnerError

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

Name Tipo Description
code

string

Um código de erro mais específico do que o 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 de um token de continuação opcional.

Name Tipo Description
continuationToken

string

Um token que pode ser utilizado para construir uma nova QuerySpecification para obter 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.

Name Tipo Description
continuationToken

string

Um token que é utilizado para obter o próximo conjunto de resultados de uma consulta anterior.
query

string

A consulta a executar. Este valor é ignorado se for fornecido um token de continuação.