API query Azure Time Series Insights Gen1
Attenzione
È un articolo di Gen1.
Questo articolo descrive varie API di query REST. Le API REST sono endpoint di servizio che supportano set di operazioni HTTP (metodi), che consentono di eseguire query su ambienti Azure Time Series Insights Gen1.
Importante
- Azure Time Series Insights Gen1 usa il protocollo HTTPS per gli ambienti Get, Ottenere la disponibilità dell'ambiente, ottenere metadati, ottenere eventi di ambiente e ottenere le API di aggregazioni dell'ambiente.
- Azure Time Series Insights Gen1 usa il protocollo WebSocket Secure (WSS) per le API Get Environment Events Streamed e Get Aggregates Streamed.
Ottenere l'API ambienti
L'API Get Environment restituisce l'elenco di ambienti autorizzati dal chiamante ad accedere.
Endpoint e operazione:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Corpo della richiesta di esempio: non applicabile
Corpo della risposta di esempio:
{ "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
L'ambiente della proprietà responseFqdn è un nome di dominio univoco completo per l'ambiente usato nelle richieste api query per ambiente.
Ottenere l'API di disponibilità dell'ambiente
L'API Get Environment Availability restituisce la distribuzione del conteggio degli eventi nel timestamp dell'evento $ts. La disponibilità dell'ambiente viene memorizzata nella cache e il tempo di risposta non dipende dal numero di eventi in un ambiente.
Suggerimento
L'API Get Environment Availability può essere usata per inizializzare un'esperienza dell'interfaccia utente front-end.
Endpoint e operazione:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Corpo della richiesta di esempio: non applicabile
Corpo della risposta di esempio:
{ "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 } }Viene restituito un oggetto vuoto per gli ambienti senza eventi.
Ottenere l'API metadati dell'ambiente
L'API Recupera metadati dell'ambiente restituisce i metadati dell'ambiente per un determinato intervallo di ricerca. I metadati vengono restituiti come set di riferimenti alle proprietà. Azure Time Series Insights cache interne di Gen1 e metadati approssimativi e possono restituire più proprietà presenti negli eventi esatti nell'intervallo di ricerca.
Endpoint e operazione:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Struttura del payload di input:
- Clausola di intervallo di ricerca (obbligatoria)
Corpo della richiesta di esempio:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Corpo della risposta di esempio:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }Viene restituita una matrice vuota quando l'ambiente è vuoto
propertieso non sono presenti eventi in un intervallo di ricerca.Le proprietà predefinite non vengono restituite nell'elenco delle proprietà.
Ottenere l'API Eventi di ambiente
L'API Get Environment Events restituisce un elenco di eventi non elaborati che corrispondono all'intervallo di ricerca e al predicato.
Endpoint e operazione:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Struttura del payload di input:
- Clausola di intervallo di ricerca (obbligatoria)
- Clausola predicato (facoltativo)
- Clausola limite (obbligatoria)
Corpo della richiesta di esempio:
{ "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
- L'ordinamento annidato (ovvero l'ordinamento in base a due o più proprietà) non è attualmente supportato.
- Gli eventi possono essere ordinati e limitati all'inizio.
- L'ordinamento è supportato in tutti i tipi di proprietà. L'ordinamento si basa sugli operatori di confronto definiti per le espressioni booleane.
Corpo della risposta di esempio:
{ "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] } ] }
Ottenere l'API streamed degli eventi di ambiente
L'API Get Environment Events Streamed restituisce un elenco di eventi non elaborati che corrispondono all'intervallo di ricerca e al predicato.
Questa API usa webSocket Secure Protocol per eseguire lo streaming e restituire risultati parziali. Restituisce sempre eventi aggiuntivi. Vale a dire, il nuovo messaggio è aggiuntivo a quello precedente. Il nuovo messaggio contiene nuovi eventi che non erano presenti nel messaggio precedente. Il messaggio precedente deve essere mantenuto quando viene aggiunto il nuovo messaggio.
Endpoint e operazione:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Struttura del payload di input:
- Clausola di intervallo di ricerca (obbligatoria)
- Clausola predicato (facoltativo)
- Clausola limite (obbligatoria)
Messaggio di richiesta di esempio:
{ "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
- L'ordinamento annidato (ovvero l'ordinamento in base a due o più proprietà) non è attualmente supportato.
- Gli eventi possono essere ordinati e limitati all'inizio.
- L'ordinamento è supportato in tutti i tipi di proprietà. L'ordinamento si basa sugli operatori di confronto definiti per le espressioni booleane.
Messaggio di risposta di esempio:
{ "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 }
Ottenere l'API Aggregazioni dell'ambiente
Gli eventi Get Environment Aggregates API groups di una proprietà specificata misurano facoltativamente i valori di altre proprietà.
Nota
I limiti del bucket supportano 10ⁿ, 2×10ⁿ o 5×10ⁿ valori per allinearsi e supportare meglio gli istogrammi numerici.
Endpoint e operazione:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Struttura del payload di input:
- Clausola di intervallo di ricerca (obbligatoria)
- Clausola predicato (facoltativo)
- Clausola Aggregates (obbligatoria)
Corpo della richiesta di esempio:
{ "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 della risposta di esempio:
{ "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 non vengono specificate espressioni di misura e l'elenco di eventi è vuoto, la risposta sarà vuota.
Se sono presenti misure, la risposta contiene un singolo record con un
nullvalore di dimensione, un0valore per il conteggio e unnullvalore per altri tipi di misure.
Ottenere l'API streamed di aggregazioni dell'ambiente
Gli eventi Get Environment Aggregates Streamed API groups by a specificato property as facoltativamente misurano i valori di altre proprietà:
- Questa API usa webSocket Secure Protocol per lo streaming e restituisce risultati parziali.
- Restituisce sempre una sostituzione (snapshot) di tutti i valori.
- I pacchetti precedenti possono essere rimossi dal client.
Nota
I limiti del bucket supportano 10ⁿ, 2×10ⁿ o 5×10ⁿ valori per allinearsi e supportare meglio gli istogrammi numerici.
Endpoint e operazione:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Struttura del payload di input:
- Clausola di intervallo di ricerca (obbligatoria)
- Clausola predicato (facoltativo)
- Clausola Aggregates (obbligatoria)
Messaggio di richiesta di esempio:
{ "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":{} }] }] } }Messaggi di risposta di esempio:
{ "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 non vengono specificate espressioni di misura e l'elenco di eventi è vuoto, la risposta sarà vuota.
Se sono presenti misure, la risposta contiene un singolo record con un
nullvalore di dimensione, un0valore per il conteggio e unnullvalore per altri tipi di misure.
Limiti
Durante l'esecuzione delle query vengono applicati i limiti seguenti per usare equamente le risorse tra più ambienti e utenti:
| API applicabili | Nome limite | Valore limite | SKU interessati | Note |
|---|---|---|---|---|
| Tutti | Dimensioni massime richieste | 32 KB | S1, S2 | |
| Ottenere la disponibilità dell'ambiente, ottenere i metadati dell'ambiente, ottenere gli eventi dell'ambiente, ottenere gli aggregati dell'ambiente trasmessi | Numero massimo di richieste simultanee per ambiente | 10 | S1, S2 | |
| Ottenere gli eventi dell'ambiente, ottenere le aggregazioni dell'ambiente in streaming | Dimensioni massime della risposta | 16 MB | S1, S2 | |
| Ottenere gli eventi dell'ambiente, ottenere le aggregazioni dell'ambiente in streaming | Numero massimo di riferimenti di proprietà univoci nel predicato, incluse le espressioni stringa del predicato | 50 | S1, S2 | |
| Ottenere gli eventi dell'ambiente, ottenere le aggregazioni dell'ambiente in streaming | Numero massimo di termini di ricerca full-text senza riferimenti alle proprietà nella stringa del predicato | 2 | S1, S2 | Esempio: HAS 'abc', 'abc' |
| Ottenere gli eventi dell'ambiente | Numero massimo di eventi in risposta | 10,000 | S1, S2 | |
| Ottenere le aggregazioni dell'ambiente in streaming | Numero massimo di dimensioni | 5 | S1, S2 | |
| Ottenere le aggregazioni dell'ambiente in streaming | Cardinalità totale massima in tutte le dimensioni | 150.000 | S1, S2 | |
| Ottenere le aggregazioni dell'ambiente in streaming | Numero massimo di misure | 20 | S1, S2 |
Gestione e risoluzione degli errori
Comportamento proprietà non trovato
Per le proprietà a cui si fa riferimento nella query, come parte dei predicati o parte delle aggregazioni (misure), per impostazione predefinita, la query tenta di risolvere la proprietà nell'intervallo di ricerca globale dell'ambiente. Se la proprietà viene trovata, la query ha esito positivo. Se la proprietà non viene trovata, la query ha esito negativo.
Tuttavia, è possibile modificare questo comportamento per considerare le proprietà come esistenti, ma con null valori se non sono presenti nell'ambiente. A tale scopo, impostare l'intestazione x-ms-property-not-found-behavior della richiesta facoltativa con il valore UseNull.
I valori possibili per l'intestazione della richiesta sono UseNull o ThrowError (impostazione predefinita). Quando si imposta UseNull come valore, la query avrà esito positivo anche se le proprietà non esistono e la risposta conterrà avvisi che visualizzano le proprietà non trovate.
Proprietà non risolte del report
È possibile specificare riferimenti alle proprietà per le espressioni di predicato, dimensione e misura. Se non esiste una proprietà con un nome e un tipo specifico per un intervallo di ricerca specificato, viene effettuato un tentativo di risolvere una proprietà in un intervallo di tempo globale.
A seconda dell'esito positivo della risoluzione, potrebbe essere generato l'avviso o l'errore seguente:
- Se nell'ambiente esiste una proprietà in un intervallo di tempo globale, viene risolta in modo appropriato e viene generato un avviso per notificare che il valore di questa proprietà è
nullrelativo a un intervallo di ricerca specificato. - Se non esiste una proprietà nell'ambiente, viene generato un errore e l'esecuzione della query ha esito negativo.
Risposte agli errori
Se l'esecuzione della query ha esito negativo, il payload della risposta JSON contiene una risposta di errore con la struttura seguente:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
In questo caso, innerError è facoltativo. Oltre agli errori di base, ad esempio una richiesta in formato non valido, vengono restituiti gli errori seguenti:
| Codice di stato HTTP | Codice di errore | Esempio di messaggio di errore | Codici di errore interni possibili |
|---|---|---|---|
| 400 | InvalidApiVersion | "La versione API '2016' non è supportata. Le versioni supportate sono '2016-12-12'." | |
| 400 | InvalidInput | "Impossibile analizzare la stringa del predicato". | PredicateStringParseError |
| 400 | InvalidInput | "Impossibile tradurre la stringa del predicato". |
InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Non sono supportate più aggregazioni". | |
| 400 | InvalidInput | "Proprietà predicato non trovata". | PropertyNotFound |
| 400 | InvalidInput | "Impossibile trovare la proprietà measure". | PropertyNotFound |
| 400 | InvalidInput | "Impossibile trovare la proprietà dimension". | PropertyNotFound |
| 400 | InvalidInput | "Il numero di misure ha superato il limite." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "La profondità aggregata ha superato il limite." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "La cardinalità totale ha superato il limite." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "Proprietà 'from' mancante". | BreaksPropertyMissing |
| 400 | InvalidInput | "La proprietà 'to' è mancante." | BreaksPropertyMissing |
| 400 | InvalidInput | "Le dimensioni della richiesta hanno superato il limite". | RequestSizeExceededLimit |
| 400 | InvalidInput | "Le dimensioni della risposta hanno superato il limite". | ResponseSizeExceededLimit |
| 400 | InvalidInput | "Numero di eventi superato il limite". | EventCountExceededLimit |
| 400 | InvalidInput | "Numero di riferimenti delle proprietà superato il limite". | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | "Solo le richieste WebSocket sono consentite nel percorso "aggregazioni". | |
| 400 | InvalidUrl | "Impossibile analizzare l'URL della richiesta '/a/b'". | |
| 408 | RequestTimeout | "Timeout della richiesta dopo i secondi '30'". | |
| 503 | TooManyRequests | "Numero di richieste simultanee di '10' superato per l'ambiente '95880732-01b9-44ea-8d2d-4d764dfe1904'". | EnvRequestLimitExceeded |
Avvisi
Una risposta API query può contenere un elenco di avvisi come "warnings" voce nella radice della risposta HTTP o del messaggio di risposta WebSocket. Attualmente vengono generati avvisi se la proprietà non viene trovata per un determinato intervallo di ricerca, ma viene trovato in un ambiente per l'intervallo di tempo globale. Viene generato anche quando l'intestazione x-ms-property-not-found-behavior è impostata su UseNull e una proprietà a cui viene fatto riferimento non esiste nemmeno nell'intervallo di ricerca globale.
Ogni oggetto avviso può contenere i campi seguenti:
| Nome del campo | Tipo di campo | Note |
|---|---|---|
| code | Stringa | Uno dei codici di avviso predefiniti |
| message | Stringa | Messaggio di avviso dettagliato |
| target | Stringa | Percorso JSON delimitato da punti alla voce del payload di input JSON che causa l'avviso |
| warningDetails | Dizionario | Opzionale; dettagli di avviso aggiuntivi (ad esempio, la posizione nella stringa di predicato) |
Il codice seguente presenta esempi di avvisi per predicato, stringa predicato all'interno di predicato, dimensione e misura:
"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"
}
]
Vedi anche
Per altre informazioni sulla registrazione dell'applicazione e sul modello di programmazione di Azure Active Directory, vedere Azure Active Directory per gli sviluppatori.
Per informazioni sui parametri di richiesta e autenticazione, vedere Autenticazione e autorizzazione.
Gli strumenti che consentono di testare le richieste e le risposte HTTP includono:
- Fiddler. Questo proxy di debug Web gratuito può intercettare le richieste REST, in modo da poter diagnosticare i messaggi di richiesta e risposta HTTP.
- JWT.io. È possibile usare questo strumento per eseguire rapidamente il dump delle attestazioni nel token di connessione e quindi convalidarne il contenuto.
- Postman. Si tratta di uno strumento gratuito di test di richiesta HTTP e risposta per il debug delle API REST.
Altre informazioni su Azure Time Series Insights Gen1 esaminando la documentazione di Gen1.