Azure Time Series Insights Gen1-fråge-API
Varning
Det här är en Gen1-artikel.
I den här artikeln beskrivs olika REST-fråge-API:er. REST-API:er är tjänstslutpunkter som stöder uppsättningar av HTTP-åtgärder (metoder), som gör att du kan fråga Azure Time Series Insights Gen1-miljöer.
Viktigt
- Azure Time Series Insights Gen1 använder HTTPS-protokollet för API:erna Hämta miljöer, Hämta miljötillgänglighet, Hämta metadata, Hämta miljöhändelser och Hämta miljöaggregeringar.
- Azure Time Series Insights Gen1 använder WSS-protokollet (WebSocket Secure) för API:erna Get Environment Events Streamed och Get Aggregates Streamed.
Hämta miljö-API
API:et Get Environments returnerar listan över miljöer som anroparen har behörighet att komma åt.
Slutpunkt och åtgärd:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Exempel på begärandetext: Ej tillämpligt
Exempel på svarstext:
{ "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" ] } ] }Anteckning
SvarsegenskapsmiljönFqdn är ett unikt, fullständigt kvalificerat domännamn för miljön som används i fråge-API-begäranden per miljö.
Hämta API för miljötillgänglighet
API:et För att hämta miljötillgänglighet returnerar fördelningen av antalet händelser över händelsetidsstämpeln $ts. Miljöns tillgänglighet cachelagras och svarstiden beror inte på antalet händelser i en miljö.
Tips
API:et För att hämta miljötillgänglighet kan användas för att initiera en gränssnittsupplevelse på klientsidan.
Slutpunkt och åtgärd:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Exempel på begärandetext: Ej tillämpligt
Exempel på svarstext:
{ "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 } }Ett tomt objekt returneras för miljöer utan händelser.
Hämta API för miljömetadata
API:et För att hämta miljömetadata returnerar miljömetadata för ett visst sökintervall. Metadata returneras som en uppsättning egenskapsreferenser. Azure Time Series Insights Gen1 cachelagrar och ungefärliger metadata internt och kan returnera fler egenskaper som finns i de exakta händelserna i sökintervallet.
Slutpunkt och åtgärd:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Struktur för indatanyttolast:
- Sökintervallsats (obligatorisk)
Exempel på begärandetext:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Exempel på svarstext:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }En tom
propertiesmatris returneras när miljön är tom eller om det inte finns några händelser i ett sökomfång.Inbyggda egenskaper returneras inte i listan över egenskaper.
Hämta API för miljöhändelser
API:et Hämta miljöhändelser returnerar en lista över råhändelser som matchar sökintervallet och predikatet.
Slutpunkt och åtgärd:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Struktur för indatanyttolast:
- Sökintervallsats (obligatorisk)
- Predikatsats (valfritt)
- Limit-sats (obligatorisk)
Exempel på begärandetext:
{ "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 } }Anteckning
- Kapslad sortering (d.v.s. sortering efter två eller flera egenskaper) stöds för närvarande inte.
- Händelser kan sorteras och begränsas till toppen.
- Sortering stöds för alla egenskapstyper. Sortering är beroende av jämförelseoperatorer som har definierats för booleska uttryck.
Exempel på svarstext:
{ "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] } ] }
Hämta streamat API för miljöhändelser
API:et Get Environment Events Streamed returnerar en lista över råhändelser som matchar sökintervallet och predikatet.
Det här API:et använder WebSocket Secure Protocol för att utföra strömning och returnera partiella resultat. Den returnerar alltid ytterligare händelser. Det nya meddelandet är alltså additivt till det föregående. Det nya meddelandet innehåller nya händelser som inte fanns i föregående meddelande. Föregående meddelande ska behållas när det nya meddelandet läggs till.
Slutpunkt och åtgärd:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Struktur för indatanyttolast:
- Sökintervallsats (obligatorisk)
- Predikatsats (valfritt)
- Limit-sats (obligatorisk)
Exempel på begärandemeddelande:
{ "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 } } }Anteckning
- Kapslad sortering (d.v.s. sortering efter två eller flera egenskaper) stöds för närvarande inte.
- Händelser kan sorteras och begränsas till toppen.
- Sortering stöds för alla egenskapstyper. Sortering är beroende av jämförelseoperatorer som har definierats för booleska uttryck.
Exempel på svarsmeddelande:
{ "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 }
Hämta API för miljöaggregeringar
API:et Get Environment Aggregates grupperar händelser efter en angiven egenskap eftersom det eventuellt mäter värdena för andra egenskaper.
Anteckning
Bucketgränser stöder värdena 10ⁿ, 2×10ⁿ eller 5×10ⁿ för att justera med och bättre stödja numeriska histogram.
Slutpunkt och åtgärd:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Struktur för indatanyttolast:
- Sökintervallsats (obligatorisk)
- Predikatsats (valfritt)
- Aggregat-sats (obligatorisk)
Exempel på begärandetext:
{ "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": {} } ] } } ] }Exempel på svarstext:
{ "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": [] }Om inga måttuttryck har angetts och listan över händelser är tom är svaret tomt.
Om mått finns innehåller svaret en enskild post med ett
nulldimensionsvärde, ett0värde för antal och ettnullvärde för andra typer av mått.
Hämta miljöaggregeringar strömmat API
Hämta miljöaggregeringar Strömmade API:et grupperar händelser efter en angiven egenskap eftersom den eventuellt mäter värdena för andra egenskaper:
- Det här API:et använder WebSocket Secure Protocol för strömning och för att returnera partiella resultat.
- Den returnerar alltid en ersättning (ögonblicksbild) av alla värden.
- Tidigare paket kan tas bort av klienten.
Anteckning
Bucketgränser stöder värdena 10ⁿ, 2×10ⁿ eller 5×10ⁿ för att justera med och bättre stödja numeriska histogram.
Slutpunkt och åtgärd:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Struktur för indatanyttolast:
- Sökintervallsats (obligatorisk)
- Predikatsats (valfritt)
- Aggregat-sats (obligatorisk)
Exempel på begärandemeddelande:
{ "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":{} }] }] } }Exempel på svarsmeddelanden:
{ "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 }Om inga måttuttryck har angetts och listan över händelser är tom är svaret tomt.
Om mått finns innehåller svaret en enskild post med ett
nulldimensionsvärde, ett0värde för antal och ettnullvärde för andra typer av mått.
Gränser
Följande gränser tillämpas under frågekörningen för att på ett rättvist sätt utnyttja resurser mellan flera miljöer och användare:
| Tillämpliga API:er | Gränsnamn | Gränsvärde | SKU:er som påverkas | Kommentarer |
|---|---|---|---|---|
| Alla | Maximal storlek på begäran | 32 kB | S1, S2 | |
| Hämta miljötillgänglighet, Hämta miljömetadata, Hämta miljöhändelser, Hämta miljöaggregeringar strömmade | Maximalt antal samtidiga begäranden per miljö | 10 | S1, S2 | |
| Hämta miljöhändelser, hämta miljöaggregeringar strömmade | Maximal svarsstorlek | 16 MB | S1, S2 | |
| Hämta miljöhändelser, hämta miljöaggregeringar strömmade | Maximalt antal unika egenskapsreferenser i predikat, inklusive predikatstränguttryck | 50 | S1, S2 | |
| Hämta miljöhändelser, hämta miljöaggregeringar strömmade | Maximalt antal söktermer i fulltext utan egenskapsreferens i predikatsträng | 2 | S1, S2 | Exempel: HAS 'abc', 'abc' |
| Hämta miljöhändelser | Maximalt antal händelser som svar | 10 000 | S1, S2 | |
| Hämta miljöaggregeringar strömmade | Maximalt antal dimensioner | 5 | S1, S2 | |
| Hämta miljöaggregeringar strömmade | Maximal total kardinalitet för alla dimensioner | 150 000 | S1, S2 | |
| Hämta miljöaggregeringar strömmade | Maximalt antal mått | 20 | S1, S2 |
Felhantering och lösning
Det gick inte att hitta egenskapen
För egenskaper som refereras i frågan, antingen som en del av predikat eller en del av aggregeringar (mått), försöker frågan som standard matcha egenskapen i global sökning området i miljön. Om egenskapen hittas lyckas frågan. Om egenskapen inte hittas misslyckas frågan.
Du kan dock ändra det här beteendet för att behandla egenskaper som befintliga men med null värden om de inte finns i miljön. Det gör du genom att ange det valfria begärandehuvudet x-ms-property-not-found-behavior med värdet UseNull.
Möjliga värden för begärandehuvudet är UseNull eller ThrowError (standard). När du anger UseNull som värde lyckas frågan även om egenskaperna inte finns och svaret innehåller varningar som visar de egenskaper som inte hittas.
Rapportera olösta egenskaper
Du kan ange egenskapsreferenser för predikat, dimension och måttuttryck. Om en egenskap med ett specifikt namn och en viss typ inte finns för ett angivet sökintervall görs ett försök att matcha en egenskap under ett globalt tidsintervall.
Beroende på hur bra lösningen lyckas kan följande varning eller fel genereras:
- Om en egenskap finns i miljön under ett globalt tidsintervall löses den på rätt sätt och en varning skickas för att meddela dig om att värdet för den här egenskapen är
nullför ett givet sökintervall. - Om det inte finns någon egenskap i miljön genereras ett fel och frågekörningen misslyckas.
Felsvar
Om frågekörningen misslyckas innehåller JSON-svarsnyttolasten ett felsvar med följande struktur:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
innerError Här är valfritt. Förutom grundläggande fel, till exempel en felaktig begäran, returneras följande fel:
| HTTP-statuskod | Felkod | Exempel på felmeddelande | Möjliga inre felkoder |
|---|---|---|---|
| 400 | InvalidApiVersion | "API-versionen '2016' stöds inte. Versioner som stöds är "2016-12-12"." | |
| 400 | InvalidInput | "Det går inte att parsa predikatsträngen." | PredicateStringParseError |
| 400 | InvalidInput | "Det går inte att översätta predikatsträngen." | InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Flera aggregeringar stöds inte." | |
| 400 | InvalidInput | "Predikategenskapen hittades inte." | PropertyNotFound |
| 400 | InvalidInput | "Det gick inte att hitta egenskapen Mått." | PropertyNotFound |
| 400 | InvalidInput | "Dimensionsegenskapen hittades inte." | PropertyNotFound |
| 400 | InvalidInput | "Antal åtgärder överskred gränsen." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Aggregerat djup överskred gränsen." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "Den totala kardinaliteten överskred gränsen." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "Egenskapen 'from' saknas." | BreaksPropertyMissing |
| 400 | InvalidInput | "Egenskapen 'till' saknas." | BreaksPropertyMissing |
| 400 | InvalidInput | "Begärandestorleken överskred gränsen." | RequestSizeExceededLimit |
| 400 | InvalidInput | "Svarsstorleken överskred gränsen." | ResponseSizeExceededLimit |
| 400 | InvalidInput | "Händelseantalet överskred gränsen." | EventCountExceededLimit |
| 400 | InvalidInput | "Antalet egenskapsreferenser överskred gränsen." | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | "Endast WebSocket-begäranden tillåts på sökvägen 'aggregates'." | |
| 400 | InvalidUrl | "Det gick inte att parsa begärande-URL:en '/a/b'." | |
| 408 | RequestTimeout | "Tidsgränsen för begäran översågs efter '30' sekund(s)." | |
| 503 | TooManyRequests | "Antalet samtidiga begäranden på '10' överskreds för miljön '95880732-01b9-44ea-8d2d-4d764dfe1904'." | EnvRequestLimitExceeded |
Varningar
Ett fråge-API-svar kan innehålla en lista med varningar som "warnings" en post i roten för HTTP-svaret eller WebSocket-svarsmeddelandet. För närvarande genereras varningar om egenskapen inte hittas för ett visst sökintervall, men hittas i en miljö för globalt tidsintervall. Det genereras också när huvudet x-ms-property-not-found-behavior är inställt på UseNull och en egenskap som refereras inte finns ens i global sökning spannet.
Varje varningsobjekt kan innehålla följande fält:
| Fältnamn | Fälttyp | Kommentarer |
|---|---|---|
| kod | Sträng | En av de fördefinierade varningskoderna |
| meddelande | Sträng | Ett detaljerat varningsmeddelande |
| Mål | Sträng | En punktavgränsad JSON-sökväg till JSON-indatanyttolasten som orsakar varningen |
| warningDetails | Ordlista | Valfri; ytterligare varningsinformation (till exempel positionen i predikatsträngen) |
Följande kod visar exempel på varningar för predikat, predikatsträng inom predikat, dimension och mått:
"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"
}
]
Se även
Mer information om programregistrering och Azure Active Directory-programmeringsmodellen finns i Azure Active Directory för utvecklare.
Mer information om parametrar för begäran och autentisering finns i Autentisering och auktorisering.
Verktyg som hjälper dig att testa HTTP-begäranden och svar är:
- Fiddler. Den här kostnadsfria webbfelsökningsproxyn kan fånga upp dina REST-begäranden så att du kan diagnostisera HTTP-begäran och svarsmeddelanden.
- JWT.io. Du kan använda det här verktyget för att snabbt dumpa anspråken i ägartoken och sedan verifiera innehållet.
- Postman. Det här är ett kostnadsfritt testverktyg för HTTP-begäran och svar för felsökning av REST-API:er.
Läs mer om Azure Time Series Insights Gen1 genom att läsa Gen1-dokumentationen.