API de Consulta do Azure Time Series Insights Gen1
Cuidado
Esse é um artigo do Gen1.
Este artigo descreve várias APIs de Consulta REST. APIs REST são pontos de extremidade de serviço que dão suporte a conjuntos de operações HTTP (métodos), que permitem consultar ambientes Azure Time Series Insights Gen1.
Importante
- Azure Time Series Insights Gen1 usa o protocolo HTTPS para obter ambientes, obter disponibilidade do ambiente, obter metadados, obter eventos de ambiente e obter apis de agregações de ambiente.
- Azure Time Series Insights Gen1 usa o protocolo WSS (WebSocket Secure) para obter eventos de ambiente transmitidos e obter agregações apIs transmitidas.
Obter API de Ambientes
A API Obter Ambientes retorna a lista de ambientes que o chamador está autorizado a acessar.
Ponto de extremidade e operação:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Corpo da solicitação 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" ] } ] }Observação
O ambiente da propriedade de respostaFqdn é um nome de domínio exclusivo e totalmente qualificado para o ambiente usado em solicitações de API de Consulta por ambiente.
Obter a API de Disponibilidade de Ambiente
A API Obter Disponibilidade do Ambiente retorna a distribuição da contagem de eventos sobre o carimbo de data /hora do evento $ts. A disponibilidade do ambiente é armazenada em cache e o tempo de resposta não depende do número de eventos em um ambiente.
Dica
A API Obter Disponibilidade do Ambiente pode ser usada para inicializar uma experiência de interface do usuário de front-end.
Ponto de extremidade e operação:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Corpo da solicitação 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 } }Um objeto vazio é retornado para ambientes sem eventos.
Obter API de Metadados de Ambiente
A API Obter Metadados de Ambiente retorna metadados de ambiente para um determinado intervalo de pesquisa. Os metadados são retornados como um conjunto de referências de propriedade. Azure Time Series Insights Gen1 armazena em cache internamente e aproxima metadados e pode retornar mais propriedades presentes nos eventos exatos no intervalo de pesquisa.
Ponto de extremidade e operação:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Estrutura de conteúdo de entrada:
- Cláusula de intervalo de pesquisa (obrigatória)
Exemplo de corpo de solicitação:
{ "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" } ] }Uma matriz vazia
propertiesé retornada quando o ambiente está vazio ou não há eventos em um intervalo de pesquisa.As propriedades internas não são retornadas na lista de propriedades.
Obter API de Eventos de Ambiente
A API Obter Eventos de Ambiente retorna uma lista de eventos brutos que correspondem ao intervalo de pesquisa e predicado.
Ponto de extremidade e operação:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Estrutura de conteúdo de entrada:
- Cláusula de intervalo de pesquisa (obrigatória)
- Cláusula Predicate (opcional)
- Cláusula Limit (obrigatória)
Exemplo de corpo de solicitação:
{ "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 } }Observação
- Atualmente, não há suporte para classificação aninhada (ou seja, classificação por duas ou mais propriedades).
- Os eventos podem ser classificados e limitados à parte superior.
- Há suporte para classificação em todos os tipos de propriedade. A classificação depende de operadores de comparação definidos para expressões boolianas.
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 de Fluxo de Eventos de Ambiente
A API Get Environment Events Streamed retorna uma lista de eventos brutos que correspondem ao intervalo de pesquisa e predicado.
Essa API usa o Protocolo Seguro WebSocket para fazer streaming e retornar resultados parciais. Ele sempre retorna eventos adicionais. Ou seja, a nova mensagem é aditiva à 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 é adicionada.
Ponto de extremidade e operação:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Estrutura de conteúdo de entrada:
- Cláusula de intervalo de pesquisa (obrigatória)
- Cláusula Predicate (opcional)
- Cláusula Limit (obrigatória)
Exemplo de mensagem de solicitação:
{ "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 } } }Observação
- Atualmente, não há suporte para classificação aninhada (ou seja, classificação por duas ou mais propriedades).
- Os eventos podem ser classificados e limitados à parte superior.
- Há suporte para classificação em todos os tipos de propriedade. A classificação depende de operadores de comparação definidos para expressões boolianas.
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 Agregados de Ambiente
A API Obter Agregações de Ambiente agrupa eventos por uma propriedade especificada, pois, opcionalmente, mede os valores de outras propriedades.
Observação
Os limites de bucket dão suporte a valores 10ⁿ, 2×10ⁿ ou 5×10ⁿ para se alinhar e dar melhor suporte a histogramas numéricos.
Ponto de extremidade e operação:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Estrutura de conteúdo de entrada:
- Cláusula de intervalo de pesquisa (obrigatória)
- Cláusula Predicate (opcional)
- Cláusula Aggregates (obrigatória)
Exemplo de corpo de solicitação:
{ "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 nenhuma expressão de medida for especificada e a lista de eventos estiver vazia, a resposta estará vazia.
Se as medidas estiverem presentes, a resposta conterá um único registro com um
nullvalor de dimensão, um0valor para contagem e umnullvalor para outros tipos de medidas.
Obter API Transmitida de Agregações de Ambiente
A API Get Environment Aggregates Streamed agrupa eventos por uma propriedade especificada, pois, opcionalmente, mede os valores de outras propriedades:
- Essa API usa o Protocolo Seguro WebSocket para streaming e para retornar resultados parciais.
- Ele sempre retorna uma substituição (instantâneo) de todos os valores.
- Os pacotes anteriores podem ser descartados pelo cliente.
Observação
Os limites de bucket dão suporte a valores 10ⁿ, 2×10ⁿ ou 5×10ⁿ para se alinhar e dar melhor suporte a histogramas numéricos.
Ponto de extremidade e operação:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Estrutura de conteúdo de entrada:
- Cláusula de intervalo de pesquisa (obrigatória)
- Cláusula Predicate (opcional)
- Cláusula Aggregates (obrigatória)
Exemplo de mensagem de solicitação:
{ "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 nenhuma expressão de medida for especificada e a lista de eventos estiver vazia, a resposta estará vazia.
Se as medidas estiverem presentes, a resposta conterá um único registro 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 da consulta para utilizar recursos de forma justa entre vários ambientes e usuários:
| APIs aplicáveis | Nome do limite | Valor limite | SKUs afetadas | Observações |
|---|---|---|---|---|
| Tudo | Tamanho máximo da solicitação | 32 KB | S1, S2 | |
| Obter disponibilidade de ambiente, obter metadados de ambiente, obter eventos de ambiente, obter agregações de ambiente transmitidas | Número máximo de solicitações simultâneas por ambiente | 10 | S1, S2 | |
| Obter eventos de ambiente, obter agregações de ambiente transmitidas | Tamanho máximo da resposta | 16 MB | S1, S2 | |
| Obter eventos de ambiente, obter agregações de ambiente transmitidas | Número máximo de referências de propriedade exclusivas no predicado, incluindo expressões de cadeia de caracteres de predicado | 50 | S1, S2 | |
| Obter eventos de ambiente, obter agregações de ambiente transmitidas | Máximo de termos de pesquisa de texto completo sem referência de propriedade na cadeia de caracteres 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 agregações de ambiente transmitidas | Número máximo de dimensões | 5 | S1, S2 | |
| Obter agregações de ambiente transmitidas | Cardinalidade total máxima em todas as dimensões | 150.000 | S1, S2 | |
| Obter agregações de ambiente transmitidas | Número máximo de medidas | 20 | S1, S2 |
Tratamento e resolução de erros
Comportamento de Propriedade Não Encontrada
Para propriedades referenciadas na consulta, como parte de predicados ou parte de agregações (medidas), por padrão, a consulta tenta resolve a propriedade no intervalo de pesquisa global do ambiente. Se a propriedade for encontrada, a consulta terá êxito. Se a propriedade não for encontrada, a consulta falhará.
No entanto, você pode modificar esse comportamento para tratar as propriedades como existentes, mas com null valores se elas não estiverem presentes no ambiente. Faça isso definindo o cabeçalho x-ms-property-not-found-behavior de solicitação opcional com o valor UseNull.
Os valores possíveis para o cabeçalho de solicitação são UseNull ou ThrowError (padrão). Quando você definir UseNull como o valor, a consulta terá êxito mesmo que as propriedades não existam e a resposta conterá avisos que exibem as propriedades que não foram encontradas.
Relatar propriedades não resolvidas
Você pode especificar referências de propriedade para predicado, dimensão e expressões de medida. Se uma propriedade com um nome e um tipo específicos não existir para um intervalo de pesquisa especificado, será feita uma tentativa de resolve uma propriedade em um período de tempo global.
Dependendo do sucesso da resolução, o seguinte aviso ou erro pode ser emitido:
- Se houver uma propriedade no ambiente em um período de tempo global, ela será resolvida adequadamente e um aviso será emitido para notificá-lo de que o valor dessa propriedade é
nullpara um determinado intervalo de pesquisa. - Se uma propriedade não existir no ambiente, um erro será emitido e a execução da consulta falhará.
Respostas de erro
Se a execução da consulta falhar, o conteúdo da resposta JSON conterá uma resposta de erro com a seguinte estrutura:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
Aqui, innerError é opcional. Além de erros básicos, como uma solicitação malformada, os seguintes erros são retornados:
| Código de status HTTP | Código do erro | Exemplo de mensagem de erro | Possíveis códigos de erro interno |
|---|---|---|---|
| 400 | InvalidApiVersion | "Não há suporte para a versão da API '2016'. As versões com suporte são '2016-12-12'." | |
| 400 | InvalidInput | "Não é possível analisar a cadeia de caracteres de predicado." | PredicateStringParseError |
| 400 | InvalidInput | "Não é possível traduzir a cadeia de caracteres de predicado." | InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Não há suporte para várias agregações." | |
| 400 | InvalidInput | "Propriedade predicado não encontrada." | PropertyNotFound |
| 400 | InvalidInput | "Propriedade measure não encontrada." | PropertyNotFound |
| 400 | InvalidInput | "Propriedade dimension não encontrada." | PropertyNotFound |
| 400 | InvalidInput | "O número de medidas excedeu o limite." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Profundidade de agregação excedeu o limite." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "A cardinalidade total excedeu o limite." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "A propriedade 'from' está ausente." | BreaksPropertyMissing |
| 400 | InvalidInput | "A propriedade 'to' está ausente." | BreaksPropertyMissing |
| 400 | InvalidInput | "O tamanho da solicitação 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 propriedade excedeu o limite." | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | "Somente solicitações WebSocket são permitidas no caminho 'aggregates'." | |
| 400 | InvalidUrl | "A URL de solicitação '/a/b' não pôde ser analisada." | |
| 408 | RequestTimeout | "A solicitação atingiu o tempo limite após '30' segundo(s)." | |
| 503 | TooManyRequests | "Contagem de solicitações simultâneas de '10' excedida para o ambiente '95880732-01b9-44ea-8d2d-4d764dfe1904'." | EnvRequestLimitExceeded |
Warnings
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 período de pesquisa, mas for encontrada em um ambiente para intervalo de tempo global. Ele também é gerado quando o cabeçalho x-ms-property-not-found-behavior é definido UseNull como 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 | Observações |
|---|---|---|
| code | Cadeia de caracteres | Um dos códigos de aviso predefinidos |
| message | Cadeia de caracteres | Uma mensagem de aviso detalhada |
| destino | Cadeia de caracteres | Um caminho JSON separado por ponto para a entrada de conteúdo de entrada JSON causando o aviso |
| warningDetails | Dicionário | Opcional; detalhes de aviso adicionais (por exemplo, a posição na cadeia de caracteres de predicado) |
O código a seguir apresenta exemplos de avisos para predicado, cadeia de caracteres de predicado dentro de 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"
}
]
Confira também
Para obter mais informações sobre o registro de aplicativos e o modelo de programação do Azure Active Directory, consulte Azure Active Directory para desenvolvedores.
Para saber mais sobre os parâmetros de solicitação e autenticação, consulte Autenticação e autorização.
As ferramentas que ajudam a testar solicitações e respostas HTTP incluem:
- Fiddler. Esse proxy de depuração da Web gratuito pode interceptar suas solicitações REST, para que você possa diagnosticar as mensagens de solicitação e resposta HTTP.
- JWT.io. Você pode usar essa ferramenta para despejar rapidamente as declarações em seu token de portador e, em seguida, validar seu conteúdo.
- O Postman. Essa é uma ferramenta gratuita de teste de resposta e solicitação HTTP para depuração de APIs REST.
Saiba mais sobre Azure Time Series Insights Gen1 examinando a documentação do Gen1.