Query - Query Twins

  • Ссылка
Service:
Azure Digital Twins
API Version:
2023-10-31

Выполняет запрос, который позволяет просматривать связи и фильтровать по значениям свойств. Коды состояния:

  • 200 ОК
  • 400 — недопустимый запрос
    • BadRequest — недопустимый маркер продолжения.
    • SqlQueryError — запрос содержит некоторые ошибки.
    • TimeoutError — время ожидания выполнения запроса истекло через 60 секунд. Попробуйте упростить запрос или добавить условия, чтобы уменьшить размер результата.
  • 429 — слишком много запросов
  • 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

Предоставляет сведения об идентификации трассировки для конкретного поставщика и является компаньоном для traceparent.

Текст запроса

Имя Тип Описание
continuationToken

string

Маркер, используемый для получения следующего набора результатов из предыдущего запроса.
query

string

Выполняемый запрос. Это значение игнорируется, если предоставлен маркер продолжения.

Ответы

Имя Тип Описание
200 OK

QueryResult

Успешное завершение

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

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

Определения

Имя Описание
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

Выполняемый запрос. Это значение игнорируется, если предоставлен маркер продолжения.