API de consulta de Azure Time Series Insights Gen1
Precaución
Este es un artículo de Gen1.
En este artículo se describen varias API de consulta REST. Las API REST son puntos de conexión de servicio que admiten conjuntos de operaciones HTTP (métodos), que permiten consultar entornos de Azure Time Series Insights Gen1.
Importante
- Azure Time Series Insights Gen1 usa el protocolo HTTPS para obtener entornos, obtener disponibilidad del entorno, obtener metadatos, obtener eventos de entorno y obtener agregados de entorno.
- Azure Time Series Insights Gen1 usa el protocolo WebSocket Secure (WSS) para las API Get Environment Events Streamed y Get Aggregates Streamed.
Get Environments API
Get Environments API devuelve la lista de entornos a los que está autorizado el autor de la llamada.
Punto de conexión y operación:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Cuerpo de la solicitud de ejemplo: no aplicable
Cuerpo de respuesta de ejemplo:
{ "environments": [ { "displayName":"Sensors", "environmentFqdn": "00000000-0000-0000-0000-000000000000.env.timeseries.azure.com", "environmentId":"00000000-0000-0000-0000-000000000000", "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/RdxProdAssetsEastUs/providers/Microsoft.TimeSeriesInsights/environments/Sensors", "roles": [ "Reader", "Contributor" ] } ] }Nota:
El entorno de la propiedad responseFqdn es un nombre de dominio único completo para el entorno que se usa en las solicitudes de LA API de consulta por entorno.
Get Environment Availability API
Get Environment Availability API devuelve la distribución del recuento de eventos a través de la marca de tiempo del evento $ts. La disponibilidad del entorno se almacena en caché y el tiempo de respuesta no depende del número de eventos de un entorno.
Sugerencia
Get Environment Availability API se puede usar para inicializar una experiencia de interfaz de usuario de front-end.
Punto de conexión y operación:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Cuerpo de la solicitud de ejemplo: no aplicable
Cuerpo de respuesta de ejemplo:
{ "range": { "from": "2016-08-01T01:02:03Z", "to": "2016-08-31T03:04:05Z" }, "intervalSize": "1h", "distribution": { "2016-08-01T00:00:00Z": 123, "2016-08-31T03:00:00Z": 345 } }Se devuelve un objeto vacío para entornos sin eventos.
Get Environment Metadata API
Get Environment Metadata API devuelve metadatos de entorno para un intervalo de búsqueda determinado. Los metadatos se devuelven como un conjunto de referencias de propiedad. Azure Time Series Insights Gen1 almacena internamente en caché y aproxima metadatos y puede devolver más propiedades presentes en los eventos exactos del intervalo de búsqueda.
Punto de conexión y operación:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Estructura de carga de entrada:
- Cláusula de intervalo de búsqueda (obligatoria)
Ejemplo del cuerpo de solicitud:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Cuerpo de respuesta de ejemplo:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }Se devuelve una matriz vacía
propertiescuando el entorno está vacío o no hay ningún evento en un intervalo de búsqueda.Las propiedades integradas no se devuelven en la lista de propiedades.
Get Environment Events API
Get Environment Events API devuelve una lista de eventos sin procesar que coinciden con el intervalo de búsqueda y el predicado.
Punto de conexión y operación:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Estructura de carga de entrada:
- Cláusula de intervalo de búsqueda (obligatoria)
- Cláusula predicado (opcional)
- Cláusula Limit (obligatoria)
Ejemplo del cuerpo de solicitud:
{ "searchSpan": { "from": { "dateTime": "2019-12-30T00:00:00.000Z" }, "to": { "dateTime": "2019-12-31T23:00:00.000Z" } }, "predicateString": "PointValue.Double = 3.14", "top": { "sort": [ { "input": { "builtInProperty": "$ts" }, "order": "Asc" } ], "count": 1000 } }Nota:
- Actualmente no se admite la ordenación anidada (es decir, la ordenación por dos o más propiedades).
- Los eventos se pueden ordenar y limitar a la parte superior.
- La ordenación se admite en todos los tipos de propiedad. La ordenación se basa en operadores de comparación definidos para expresiones booleanas.
Cuerpo de respuesta de ejemplo:
{ "warnings": [], "events": [ { "schema": { "rid": 0, "$esn" : "buildingsensors", "properties" : [{ "name" : "sensorId", "type" : "String" }, { "name" : "sensorValue", "type" : "String" }] }, "$ts" : "2016-08-30T23:20:00Z", "values" : ["IndoorTemperatureSensor", 72.123] }, { "schemaRid" : 0, "$ts" : "2016-08-30T23:21:00Z", "values" : ["IndoorTemperatureSensor", 72.345] } ] }
Get Environment Events Streamed API
Get Environment Events Streamed API devuelve una lista de eventos sin procesar que coinciden con el intervalo de búsqueda y el predicado.
Esta API usa el protocolo seguro WebSocket para realizar streaming y devolver resultados parciales. Siempre devuelve eventos adicionales. Es decir, el nuevo mensaje es aditivo para el anterior. El nuevo mensaje contiene nuevos eventos que no estaban en el mensaje anterior. El mensaje anterior debe mantenerse cuando se agrega el nuevo mensaje.
Punto de conexión y operación:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Estructura de carga de entrada:
- Cláusula de intervalo de búsqueda (obligatoria)
- Cláusula predicado (opcional)
- Cláusula Limit (obligatoria)
Mensaje de solicitud de ejemplo:
{ "headers" : { "Authorization":"Bearer <YOUR_AAD_OAUTH_TOKEN>", "x-ms-client-request-id" : "132gae-w343-41a1-2342-w23ta4532" }, "content": { "searchSpan": { "from": "2017-04-30T23:00:00.000Z", "to": "2017-05-01T00:00:00.000Z" }, "top": { "sort": [ { "input": { "builtInProperty": "$ts" }, "order": "Asc" } ], "count": 1000 } } }Nota:
- Actualmente no se admite la ordenación anidada (es decir, la ordenación por dos o más propiedades).
- Los eventos se pueden ordenar y limitar a la parte superior.
- La ordenación se admite en todos los tipos de propiedad. La ordenación se basa en operadores de comparación definidos para expresiones booleanas.
Mensaje de respuesta de ejemplo:
{ "headers": { "x-ms-request-id": "a325-a345-sy43-w332-a4qat36a2262" }, "content": { "events": [ { "schema": { "rid": 0, "$esn": "devicedata", "properties": [ { "name": "Id", "type": "String" }, { "name": "TemperatureControlLevel", "type": "Double" }, { "name": "Type", "type": "String" }, { "name": "UnitVersion", "type": "String" }, { "name": "Station", "type": "String" }, { "name": "ProductionLine", "type": "String" }, { "name": "Factory", "type": "String" }, { "name": "Timestamp", "type": "DateTime" } ] }, "$ts": "2017-04-30T23:00:00Z", "values": [ "82faa3c1-f11d-44f5-a1ca-e448f6123eee", 0.9835468282931982, "temp control rate", "1.1.7.0", "Station5", "Line1", "Factory2", "2017-04-30T23:00:00Z" ] }, { "schemaRid": 0, "$ts": "2017-04-30T23:00:00Z", "values": [ "acb2f926-62cc-4a88-9246-94a26ebcaee3", 0.8542095381579537, "temp control rate", "1.1.7.0", "Station2", "Line1", "Factory3", "2017-04-30T23:00:00Z" ] } ] }, "warnings": [], "percentCompleted": 100 }
Get Environment Aggregates API
La API Get Environment Aggregates agrupa los eventos por una propiedad especificada, ya que, opcionalmente, mide los valores de otras propiedades.
Nota:
Los límites del cubo admiten 10ⁿ, 2×10ⁿ o 5×10ⁿ valores para alinearse con y admitir mejor histogramas numéricos.
Punto de conexión y operación:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Estructura de carga de entrada:
- Cláusula de intervalo de búsqueda (obligatoria)
- Cláusula predicado (opcional)
- Cláusula Aggregates (obligatoria)
Ejemplo del cuerpo de solicitud:
{ "searchSpan": { "from": { "dateTime": "2019-12-30T00:00:00.000Z" }, "to": { "dateTime": "2019-12-31T23:00:00.000Z" } }, "predicateString": "PointValue.Double > 1000", "aggregates": [ { "dimension": { "uniqueValues": { "input": { "property": "iothub-connection-device-id", "type": "String" }, "take": 100 } }, "aggregate": { "dimension": { "dateHistogram": { "input": { "builtInProperty": "$ts" }, "breaks": { "size": "1h" } } }, "measures": [ { "min": { "input": { "property": "series.flowRate", "type": "Double" } } }, { "count": {} } ] } } ] }Cuerpo de respuesta de ejemplo:
{ "aggregates": [ { "dimension": [ "Test-Device-A11342" ], "aggregate": { "dimension": [ "2019-12-30T23:00:00Z", "2019-12-31T00:00:00Z" ], "measures": [ [ [ 0.319668575730514, 2678 ], [ 0.08442680357734211, 1238 ] ] ] } } ], "warnings": [] }Si no se especifica ninguna expresión de medida y la lista de eventos está vacía, la respuesta estará vacía.
Si hay medidas presentes, la respuesta contiene un único registro con un
nullvalor de dimensión, un0valor para count y unnullvalor para otros tipos de medidas.
Get Environment Aggregates Streamed API
Get Environment Aggregates Streamed API agrupa eventos por una propiedad especificada, ya que, opcionalmente, mide los valores de otras propiedades:
- Esta API usa el protocolo seguro WebSocket para el streaming y para devolver resultados parciales.
- Siempre devuelve un reemplazo (instantánea) de todos los valores.
- El cliente puede descartar los paquetes anteriores.
Nota:
Los límites del cubo admiten 10ⁿ, 2×10ⁿ o 5×10ⁿ valores para alinearse con y admitir mejor histogramas numéricos.
Punto de conexión y operación:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Estructura de carga de entrada:
- Cláusula de intervalo de búsqueda (obligatoria)
- Cláusula predicado (opcional)
- Cláusula Aggregates (obligatoria)
Mensaje de solicitud de ejemplo:
{ "headers":{ "Authorization":"Bearer <YOUR_AAD_OAUTH_TOKEN>" }, "content":{ "predicate":{ "predicateString":"" }, "searchSpan":{ "from":"2017-04-30T23:00:00.000Z", "to":"2017-05-01T00:00:00.000Z" }, "aggregates":[{ "dimension":{ "dateHistogram":{ "input":{ "builtInProperty":"$ts" }, "breaks":{ "size":"1m" } } }, "measures":[{ "count":{} }] }] } }Mensajes de respuesta de ejemplo:
{ "headers":{ "x-ms-request-id":"abc3243-23af-23ad-3224s-a32525age" }, "content":[ { "dimension":[ "2017-04-30T23:00:00Z", "2017-04-30T23:01:00Z", "2017-04-30T23:02:00Z", "2017-04-30T23:03:00Z", "2017-04-30T23:04:00Z" ], "measures":[ [ 722 ], [ 721 ], [ 722 ], [ 721 ], [ 722 ] ] } ], "warnings":[ ], "percentCompleted":100 }Si no se especifica ninguna expresión de medida y la lista de eventos está vacía, la respuesta estará vacía.
Si hay medidas presentes, la respuesta contiene un único registro con un
nullvalor de dimensión, un0valor para count y unnullvalor para otros tipos de medidas.
Límites
Los límites siguientes se aplican durante la ejecución de consultas para utilizar de forma equitativa los recursos entre varios entornos y usuarios:
| API aplicables | Nombre del límite | Valor límite | SKU afectadas | Notas |
|---|---|---|---|---|
| Todo | Tamaño máximo de la solicitud | 32 KB | S1, S2 | |
| Obtener disponibilidad del entorno, Obtener metadatos del entorno, Obtener eventos de entorno, Obtener agregados de entorno transmitidos | Número máximo de solicitudes simultáneas por entorno | 10 | S1, S2 | |
| Obtener eventos de entorno, Obtener agregados de entorno transmitidos | Tamaño máximo de respuesta | 16 MB | S1, S2 | |
| Obtener eventos de entorno, Obtener agregados de entorno transmitidos | Número máximo de referencias de propiedad únicas en predicado, incluidas las expresiones de cadena de predicado | 50 | S1, S2 | |
| Obtener eventos de entorno, Obtener agregados de entorno transmitidos | Número máximo de términos de búsqueda de texto completo sin referencia de propiedad en la cadena de predicado | 2 | S1, S2 | Ejemplo: HAS 'abc', 'abc' |
| Obtener eventos de entorno | Número máximo de eventos en respuesta | 10 000 | S1, S2 | |
| Obtención de agregados de entorno transmitidos | Número máximo de dimensiones | 5 | S1, S2 | |
| Obtención de agregados de entorno transmitidos | Cardinalidad total máxima en todas las dimensiones | 150 000 | S1, S2 | |
| Obtención de agregados de entorno transmitidos | Número máximo de medidas | 20 | S1, S2 |
Control y resolución de errores
Comportamiento de propiedad no encontrada
En el caso de las propiedades a las que se hace referencia en la consulta, ya sea como parte de predicados o parte de agregados (medidas), de forma predeterminada, la consulta intenta resolver la propiedad en el intervalo de búsqueda global del entorno. Si se encuentra la propiedad , la consulta se realiza correctamente. Si no se encuentra la propiedad , se produce un error en la consulta.
Sin embargo, puede modificar este comportamiento para tratar las propiedades como existentes, pero con null valores si no están presentes en el entorno. Para ello, establezca el encabezado x-ms-property-not-found-behavior de solicitud opcional con el valor UseNull.
Los valores posibles para el encabezado de solicitud son UseNull o ThrowError (valor predeterminado). Cuando se establece UseNull como valor, la consulta se realizará correctamente aunque las propiedades no existan y la respuesta contendrá advertencias que muestran las propiedades que no se encuentran.
Notificar propiedades sin resolver
Puede especificar referencias de propiedad para las expresiones de predicado, dimensión y medida. Si una propiedad con un nombre y tipo específicos no existe para un intervalo de búsqueda especificado, se intenta resolver una propiedad a lo largo de un intervalo de tiempo global.
En función del éxito de la resolución, se podría emitir la advertencia o el error siguientes:
- Si existe una propiedad en el entorno a lo largo de un intervalo de tiempo global, se resuelve correctamente y se emite una advertencia para notificarle que el valor de esta propiedad es
nullpara un intervalo de búsqueda determinado. - Si una propiedad no existe en el entorno, se emite un error y se produce un error en la ejecución de la consulta.
Respuestas de errores
Si se produce un error en la ejecución de la consulta, la carga de respuesta JSON contiene una respuesta de error con la siguiente estructura:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
Aquí, innerError es opcional. Además de los errores básicos, como una solicitud con formato incorrecto, se devuelven los siguientes errores:
| Código de estado HTTP | Código de error | Ejemplo de mensaje de error | Posibles códigos de error internos |
|---|---|---|---|
| 400 | InvalidApiVersion | No se admite la "versión de API "2016". Las versiones admitidas son "2016-12-12". | |
| 400 | InvalidInput | "No se puede analizar la cadena de predicado". | PredicateStringParseError |
| 400 | InvalidInput | "No se puede traducir la cadena de predicado". |
InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "No se admiten varios agregados". | |
| 400 | InvalidInput | "No se encontró la propiedad predicado". | PropertyNotFound |
| 400 | InvalidInput | "No se encontró la propiedad measure." | PropertyNotFound |
| 400 | InvalidInput | "No se encontró la propiedad Dimension." | PropertyNotFound |
| 400 | InvalidInput | "Número de medidas superadas." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Profundidad agregada superada." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "Límite total de cardinalidad superada." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "Falta la propiedad 'from'". | BreaksPropertyMissing |
| 400 | InvalidInput | "Falta la propiedad 'to'". | BreaksPropertyMissing |
| 400 | InvalidInput | "El tamaño de la solicitud ha superado el límite." | RequestSizeExceededLimit |
| 400 | InvalidInput | "El tamaño de respuesta ha superado el límite." | ResponseSizeExceededLimit |
| 400 | InvalidInput | "El número de eventos ha superado el límite." | EventCountExceededLimit |
| 400 | InvalidInput | "El número de referencias de propiedades superó el límite." | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | "Solo se permiten solicitudes de WebSocket en la ruta de acceso "agregados". | |
| 400 | InvalidUrl | "No se pudo analizar la dirección URL de solicitud '/a/b'". | |
| 408 | RequestTimeout | "Se agota el tiempo de espera de la solicitud después de "30" segundos". | |
| 503 | TooManyRequests | "Se superó el número de solicitudes simultáneas de '10' para el entorno '95880732-01b9-44ea-8d2d-4d764dfe1904'". | EnvRequestLimitExceeded |
Advertencias
Una respuesta de la API de consulta puede contener una lista de advertencias como "warnings" entrada en la raíz de la respuesta HTTP o el mensaje de respuesta de WebSocket. Actualmente se generan advertencias si no se encuentra la propiedad para un intervalo de búsqueda determinado, pero se encuentra en un entorno para el intervalo de tiempo global. También se genera cuando el encabezado x-ms-property-not-found-behavior se establece UseNull en y una propiedad a la que se hace referencia no existe incluso en el intervalo de búsqueda global.
Cada objeto de advertencia puede contener los siguientes campos:
| Nombre del campo | Tipo de campo | Notas |
|---|---|---|
| code | String | Uno de los códigos de advertencia predefinidos |
| message | String | Un mensaje de advertencia detallado |
| Destino | String | Ruta de acceso JSON separada por puntos a la entrada de carga de entrada JSON que provoca la advertencia |
| warningDetails | Diccionario | Opcional; detalles de advertencia adicionales (por ejemplo, la posición en la cadena de predicado) |
En el código siguiente se presentan ejemplos de advertencias para predicado, cadena de predicado dentro de predicado, dimensión y medida:
"warnings": [
{
"code": "PropertyNotFound",
"message": "Predicate property 'X' of type 'String' is not found in local search span.",
"target": "predicate.and[0].eq.left.property.name"
},
{
"code": "PropertyNotFound",
"message": "Predicate string property 'X' is not found in local search span.",
"target": "predicate.and[1].predicateString",
"warningDetails": {
"startPos": 1,
"endPos": 2,
"line": 1,
"col": 1
}
},
{
"code": "PropertyNotFound",
"message": "Dimension property 'X' of type 'String' is not found in local search span.",
"target": "aggregates.dimension.uniqueValues.input.property"
},
{
"code": "PropertyNotFound",
"message": "Measure property 'X' of type 'String' is not found in local search span.",
"target": "aggregates.aggregates.measures[0].min.input.property"
}
]
Consulte también
Para más información sobre el registro de aplicaciones y el modelo de programación de Azure Active Directory, consulte Azure Active Directory para desarrolladores.
Para obtener información sobre los parámetros de solicitud y autenticación, consulte Autenticación y autorización.
Entre las herramientas que ayudan a probar las solicitudes HTTP y las respuestas se incluyen:
- Fiddler. Este proxy de depuración web gratuito puede interceptar las solicitudes REST, por lo que puede diagnosticar los mensajes de solicitud y respuesta HTTP.
- JWT.io. Puede usar esta herramienta para volcar rápidamente las notificaciones en el token de portador y, a continuación, validar su contenido.
- Postman. Se trata de una herramienta gratuita de prueba de solicitudes y respuestas HTTP para depurar las API REST.
Para más información sobre Azure Time Series Insights Gen1, revise la documentación de Gen1.