Query - Query Twins

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

Ejecuta una consulta que permite recorrer relaciones y filtrar por valores de propiedad. Códigos de estado:

  • 200 OK
  • 400 - Solicitud incorrecta
    • BadRequest: el token de continuación no es válido.
    • SqlQueryError: la consulta contiene algunos errores.
    • TimeoutError: la ejecución de la consulta agota el tiempo de espera después de 60 segundos. Intente simplificar la consulta o agregar condiciones para reducir el tamaño del resultado.
  • 429 Demasiadas solicitudes
  • QuotaReachedError: se ha alcanzado el límite máximo de frecuencia de consulta.
POST https://digitaltwins-hostname/query?api-version=2023-10-31

Parámetros de identificador URI

Nombre En Requerido Tipo Description
api-version
 query True

string

La versión de API solicitada.

Encabezado de la solicitud

Nombre Requerido Tipo Description
max-items-per-page

integer

Número máximo de elementos que se van a recuperar por solicitud. El servidor puede optar por devolver menos que el número solicitado.
traceparent

string

Identifica la solicitud en un sistema de seguimiento distribuido.
tracestate

string

Proporciona información de identificación de seguimiento específica del proveedor y es un complemento de traceparent.

Cuerpo de la solicitud

Nombre Tipo Description
continuationToken

string

Token que se usa para recuperar el siguiente conjunto de resultados de una consulta anterior.
query

string

Consulta que se va a ejecutar. Este valor se omite si se proporciona un token de continuación.

Respuestas

Nombre Tipo Description
200 OK

QueryResult

Correcto

Headers

query-charge: number
Other Status Codes

ErrorResponse

Respuesta predeterminada.

Headers

x-ms-error-code: string

Seguridad

oauth2

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

Ejemplos

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

Definiciones

Nombre Description
Error

Definición de error.
ErrorResponse

Respuesta de error.
InnerError

Una descripción de error más específica de la proporcionada por el error contenedor.
QueryResult

Los resultados de una operación de consulta y un token de continuación opcional.
QuerySpecification

Especificación de consulta que contiene una instrucción de consulta o un token de continuación de un resultado de consulta anterior.

Error

Definición de error.

Nombre Tipo Description
code

string

Código de error específico del servicio que actúa como subestado para el código de error HTTP.
details

Error[]

Detalles internos del error.
innererror

InnerError

Objeto que contiene información más específica que el objeto actual sobre el error.
message

string

Representación legible del error.

ErrorResponse

Respuesta de error.

Nombre Tipo Description
error

Error

Los detalles del error.

InnerError

Una descripción de error más específica de la proporcionada por el error contenedor.

Nombre Tipo Description
code

string

Código de error más específico del proporcionado por el error contenedor.
innererror

InnerError

Objeto que contiene información más específica que el objeto actual sobre el error.

QueryResult

Los resultados de una operación de consulta y un token de continuación opcional.

Nombre Tipo Description
continuationToken

string

Token que se puede usar para construir un nuevo QuerySpecification para recuperar el siguiente conjunto de resultados.
value

object[]

Resultados de la consulta.

QuerySpecification

Especificación de consulta que contiene una instrucción de consulta o un token de continuación de un resultado de consulta anterior.

Nombre Tipo Description
continuationToken

string

Token que se usa para recuperar el siguiente conjunto de resultados de una consulta anterior.
query

string

Consulta que se va a ejecutar. Este valor se omite si se proporciona un token de continuación.