API de Consulta do Azure Time Series Insights Gen1
Atenção
Este é um artigo da Gen1.
Este artigo descreve várias APIs de Consulta REST. As APIs REST são pontos finais de serviço que suportam conjuntos de operações HTTP (métodos), que lhe permitem consultar ambientes Azure Time Series Insights Gen1.
Importante
- Azure Time Series Insights Gen1 utiliza o Protocolo HTTPS para Obter Ambientes, Obter Disponibilidade do Ambiente, Obter Metadados, Obter Eventos de Ambiente e Obter APIs de Agregação de Ambiente.
- Azure Time Series Insights Gen1 utiliza o Protocolo WebSocket Secure (WSS) para obter APIs transmitidas em fluxo e obter agregações transmitidas em fluxo.
Obter API de Ambientes
A API Obter Ambientes devolve a lista de ambientes aos quais o autor da chamada está autorizado a aceder.
Ponto final e operação:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Corpo do pedido de exemplo: Não aplicável
Corpo da resposta de exemplo:
{ "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
O ambiente de propriedade de respostaFqdn é um nome de domínio exclusivo e completamente qualificado para o ambiente utilizado em pedidos de API de Consulta por ambiente.
Obter API de Disponibilidade do Ambiente
A API Obter Disponibilidade do Ambiente devolve a distribuição da contagem de eventos ao longo do carimbo de data/hora do evento $ts. A disponibilidade do ambiente é colocada em cache e o tempo de resposta não depende do número de eventos num ambiente.
Dica
A API Obter Disponibilidade do Ambiente pode ser utilizada para inicializar uma experiência de IU de front-end.
Ponto final e operação:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Corpo do pedido de exemplo: Não aplicável
Corpo da resposta de exemplo:
{ "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 } }É devolvido um objeto vazio para ambientes sem eventos.
Obter API de Metadados do Ambiente
A API Obter Metadados do Ambiente devolve metadados de ambiente para um determinado intervalo de pesquisa. Os metadados são devolvidos como um conjunto de referências de propriedades. Azure Time Series Insights Gen1 coloca em cache internamente e aproxima metadados e pode devolver mais propriedades que estão presentes nos eventos exatos no intervalo de pesquisa.
Ponto final e operação:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Estrutura de payload de entrada:
- Cláusula de span de pesquisa (obrigatório)
Corpo do pedido de exemplo:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Corpo da resposta de exemplo:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }É devolvida uma matriz vazia
propertiesquando o ambiente está vazio ou não existem eventos num intervalo de pesquisa.As propriedades incorporadas não são devolvidas na lista de propriedades.
Obter API de Eventos de Ambiente
A API Obter Eventos de Ambiente devolve uma lista de eventos não processados que correspondem ao intervalo de pesquisa e ao predicado.
Ponto final e operação:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Estrutura de payload de entrada:
- Cláusula de span de pesquisa (obrigatório)
- Cláusula predicado (opcional)
- Cláusula de limite (obrigatório)
Corpo do pedido de exemplo:
{ "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
- A ordenação aninhada (ou seja, a ordenação por duas ou mais propriedades) não é atualmente suportada.
- Os eventos podem ser ordenados e limitados à parte superior.
- A ordenação é suportada em todos os tipos de propriedade. A ordenação baseia-se em operadores de comparação definidos para expressões booleanas.
Corpo da resposta de exemplo:
{ "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] } ] }
Obter API em Fluxo de Eventos de Ambiente
A API Get Environment Events Streamed devolve uma lista de eventos não processados que correspondem ao intervalo de pesquisa e ao predicado.
Esta API utiliza o Protocolo Seguro WebSocket para fazer a transmissão em fluxo e devolver resultados parciais. Devolve sempre eventos adicionais. Ou seja, a nova mensagem é aditiva para a anterior. A nova mensagem contém novos eventos que não estavam na mensagem anterior. A mensagem anterior deve ser mantida quando a nova mensagem for adicionada.
Ponto final e operação:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Estrutura de payload de entrada:
- Cláusula de span de pesquisa (obrigatório)
- Cláusula predicado (opcional)
- Cláusula de limite (obrigatório)
Mensagem de pedido de exemplo:
{ "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
- A ordenação aninhada (ou seja, a ordenação por duas ou mais propriedades) não é atualmente suportada.
- Os eventos podem ser ordenados e limitados à parte superior.
- A ordenação é suportada em todos os tipos de propriedade. A ordenação baseia-se em operadores de comparação definidos para expressões booleanas.
Mensagem de resposta de exemplo:
{ "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 }
Obter API de Agregações de Ambiente
A API Get Environment Aggregates agrupa eventos por uma propriedade especificada, uma vez que, opcionalmente, mede os valores de outras propriedades.
Nota
Os limites do registo suportam valores de 10ⁿ, 2×10ⁿ ou 5×10ⁿ para alinhar e suportar melhor histogramas numéricos.
Ponto final e operação:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Estrutura de payload de entrada:
- Cláusula de span de pesquisa (obrigatório)
- Cláusula predicado (opcional)
- Cláusula agregadas (obrigatória)
Corpo do pedido de exemplo:
{ "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": {} } ] } } ] }Corpo da resposta de exemplo:
{ "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": [] }Se não forem especificadas expressões de medida e a lista de eventos estiver vazia, a resposta estará vazia.
Se existirem medidas, a resposta contém um único registo com um
nullvalor de dimensão, um0valor para contagem e umnullvalor para outros tipos de medidas.
Obter API Em Fluxo de Agregações de Ambiente
A API Get Environment Aggregates Streamed agrupa eventos por uma propriedade especificada, uma vez que, opcionalmente, mede os valores de outras propriedades:
- Esta API utiliza o Protocolo Seguro WebSocket para transmissão em fluxo e para devolver resultados parciais.
- Devolve sempre uma substituição (instantâneo) de todos os valores.
- Os pacotes anteriores podem ser eliminados pelo cliente.
Nota
Os limites do registo suportam valores de 10ⁿ, 2×10ⁿ ou 5×10ⁿ para alinhar e suportar melhor histogramas numéricos.
Ponto final e operação:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Estrutura de payload de entrada:
- Cláusula de span de pesquisa (obrigatório)
- Cláusula predicado (opcional)
- Cláusula agregadas (obrigatória)
Mensagem de pedido de exemplo:
{ "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":{} }] }] } }Mensagens de resposta de exemplo:
{ "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 }Se não forem especificadas expressões de medida e a lista de eventos estiver vazia, a resposta estará vazia.
Se existirem medidas, a resposta contém um único registo com um
nullvalor de dimensão, um0valor para contagem e umnullvalor para outros tipos de medidas.
Limites
Os seguintes limites são aplicados durante a execução de consultas para utilizar recursos de forma justa entre vários ambientes e utilizadores:
| APIs aplicáveis | Nome do limite | Valor de limite | SKUs afetados | Notas |
|---|---|---|---|---|
| Todos | Tamanho máximo do pedido | 32 KB | S1, S2 | |
| Obter Disponibilidade do Ambiente, Obter Metadados de Ambiente, Obter Eventos de Ambiente, Obter Agregados de Ambiente Transmitidos em Fluxo | Número máximo de pedidos simultâneos por ambiente | 10 | S1, S2 | |
| Obter Eventos de Ambiente, Obter Agregados de Ambiente Transmitidos em Fluxo | Tamanho máximo da resposta | 16 MB | S1, S2 | |
| Obter Eventos de Ambiente, Obter Agregados de Ambiente Transmitidos em Fluxo | Número máximo de referências de propriedade exclusivas no predicado, incluindo expressões de cadeia de carateres predicados | 50 | S1, S2 | |
| Obter Eventos de Ambiente, Obter Agregados de Ambiente Transmitidos em Fluxo | Termos de pesquisa de texto completo máximos sem referência de propriedade na cadeia de predicado | 2 | S1, S2 | Exemplo: HAS 'abc', 'abc' |
| Obter Eventos de Ambiente | Número máximo de eventos em resposta | 10,000 | S1, S2 | |
| Obter Agregados de Ambiente Transmitidos em Fluxo | Número máximo de dimensões | 5 | S1, S2 | |
| Obter Agregados de Ambiente Transmitidos em Fluxo | Cardinalidade total máxima em todas as dimensões | 150.000 | S1, S2 | |
| Obter Agregados de Ambiente Transmitidos em Fluxo | Número máximo de medidas | 20 | S1, S2 |
Processamento e resolução de erros
Comportamento da Propriedade Não Encontrada
Para as propriedades referenciadas na consulta, como parte de predicados ou parte de agregados (medidas), por predefinição, a consulta tenta resolver a propriedade no pesquisa global intervalo do ambiente. Se a propriedade for encontrada, a consulta será concluída com êxito. Se a propriedade não for encontrada, a consulta falhará.
No entanto, pode modificar este comportamento para tratar as propriedades como existentes, mas com null valores se não estiverem presentes no ambiente. Pode fazê-lo ao definir o cabeçalho x-ms-property-not-found-behavior de pedido opcional com o valor UseNull.
Os valores possíveis para o cabeçalho do pedido são UseNull ou ThrowError (predefinição). Quando definir UseNull como o valor, a consulta terá êxito mesmo que as propriedades não existam e a resposta conterá avisos que apresentam as propriedades que não foram encontradas.
Reportar propriedades não resolvidas
Pode especificar referências de propriedade para predicado, dimensão e expressões de medida. Se uma propriedade com um nome e tipo específicos não existir para um intervalo de pesquisa especificado, é efetuada uma tentativa de resolver uma propriedade durante um intervalo de tempo global.
Consoante o êxito da resolução, o seguinte aviso ou erro poderá ser emitido:
- Se existir uma propriedade no ambiente durante um período de tempo global, esta é resolvida adequadamente e é emitido um aviso para notificá-lo de que o valor desta propriedade é
nullpara um determinado período de pesquisa. - Se uma propriedade não existir no ambiente, será emitido um erro e a execução da consulta falhará.
Respostas a erros
Se a execução da consulta falhar, o payload de resposta JSON contém uma resposta de erro com a seguinte estrutura:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
Aqui, innerError é opcional. Além de erros básicos, como um pedido mal formado, são devolvidos os seguintes erros:
| Código de estado de HTTP | Código de erro | Exemplo de mensagem de erro | Possíveis códigos de erro internos |
|---|---|---|---|
| 400 | InvalidApiVersion | "A versão da API '2016' não é suportada. As versões suportadas são "2016-12-12"." | |
| 400 | InvalidInput | "Não é possível analisar a cadeia de predicado." | PredicateStringParseError |
| 400 | InvalidInput | "Não é possível traduzir a cadeia de carateres predicado." |
InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Não são suportados múltiplos agregados." | |
| 400 | InvalidInput | "Propriedade predicado não encontrada." | PropertyNotFound |
| 400 | InvalidInput | "Propriedade de medida não encontrada." | PropertyNotFound |
| 400 | InvalidInput | "Propriedade de dimensão não encontrada." | PropertyNotFound |
| 400 | InvalidInput | "O número de medidas excedeu o limite." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "A profundidade agregada excedeu o limite." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "A cardinalidade total excedeu o limite." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "A propriedade 'de' está em falta." | BreaksPropertyMissing |
| 400 | InvalidInput | "A propriedade 'a' está em falta." | BreaksPropertyMissing |
| 400 | InvalidInput | "O tamanho do pedido excedeu o limite." | RequestSizeExceededLimit |
| 400 | InvalidInput | "O tamanho da resposta excedeu o limite." | ResponseSizeExceededLimit |
| 400 | InvalidInput | "A contagem de eventos excedeu o limite." | EventCountExceededLimit |
| 400 | InvalidInput | "A contagem de referência de propriedades excedeu o limite." | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | "Apenas são permitidos pedidos WebSocket no caminho 'agregados'." | |
| 400 | InvalidUrl | "Não foi possível analisar o URL do pedido '/a/b'." | |
| 408 | RequestTimeout | "O pedido excedeu o tempo limite após "30" segundos."" | |
| 503 | TooManyRequests | "A contagem simultânea de pedidos de '10' foi excedida para o ambiente '95880732-01b9-44ea-8d2d-4d764dfe1904'." | EnvRequestLimitExceeded |
Avisos
Uma resposta da API de Consulta pode conter uma lista de avisos como "warnings" entrada na raiz da resposta HTTP ou da mensagem de resposta WebSocket. Atualmente, os avisos são gerados se a propriedade não for encontrada para um determinado intervalo de pesquisa, mas for encontrada num ambiente para o intervalo de tempo global. Também é gerado quando o cabeçalho x-ms-property-not-found-behavior está definido como UseNull e uma propriedade referenciada não existe mesmo no intervalo de pesquisa global.
Cada objeto de aviso pode conter os seguintes campos:
| Nome do campo | Tipo de campo | Notas |
|---|---|---|
| code | String | Um dos códigos de aviso predefinidos |
| mensagem | String | Uma mensagem de aviso detalhada |
| destino | String | Um caminho JSON separado por pontos para a entrada de payload de entrada JSON que causa o aviso |
| warningDetails | Dicionário | Opcional; detalhes de aviso adicionais (por exemplo, a posição na cadeia de predicado) |
O código seguinte apresenta exemplos de avisos para predicado, cadeia de predicado dentro do predicado, dimensão e 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"
}
]
Ver também
Para obter mais informações sobre o registo de aplicações e o modelo de programação do Azure Active Directory, veja Azure Active Directory para programadores.
Para saber mais sobre os parâmetros de pedido e autenticação, veja Autenticação e autorização.
As ferramentas que ajudam a testar pedidos e respostas HTTP incluem:
- Fiddler. Este proxy de depuração Web gratuito pode intercetar os seus pedidos REST, para que possa diagnosticar as mensagens de pedido e resposta HTTP.
- JWT.io. Pode utilizar esta ferramenta para capturar rapidamente as afirmações no token de portador e, em seguida, validar os respetivos conteúdos.
- Postman. Esta é uma ferramenta de teste de resposta e pedido HTTP gratuita para depurar APIs REST.
Saiba mais sobre Azure Time Series Insights Gen1 ao rever a documentação do Gen1.