Azure Time Series Insights Gen1 Query API
Figyelemfelhívás
Ez egy Gen1-cikk.
Ez a cikk különböző REST Query API-kat ismertet. A REST API-k olyan szolgáltatásvégpontok, amelyek támogatják a HTTP-műveletek (metódusok) készleteit, amelyek lehetővé teszik Azure Time Series Insights Gen1-környezetek lekérdezését.
Fontos
- Azure Time Series Insights Gen1 a HTTPS Protokollt használja a Környezetek lekérése, a Környezet rendelkezésre állásának lekérése, a Metaadatok lekérése, a Környezeti események lekérése és a Környezeti összesítések lekérése API-khoz.
- Azure Time Series Insights Gen1 a WebSocket Secure (WSS) protokollt használja a Streamelt környezeti események lekérése és az Összesítések lekérése streamelt API-khoz.
Környezetek API lekérése
A Környezetek lekérése API visszaadja azoknak a környezeteknek a listáját, amelyek eléréséhez a hívó jogosult.
Végpont és művelet:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Példakérés törzsére: Nem alkalmazható
Példa válasz törzse:
{ "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" ] } ] }Megjegyzés
A environmentFqdn választulajdonság egy egyedi, teljes tartománynév ahhoz a környezethez, amelyet a környezetenkénti lekérdezési API-kérésekben használnak.
Környezeti rendelkezésre állási API lekérése
A Get Environment Availability API az eseményszám eloszlását adja vissza az esemény időbélyeg -$ts. A környezet rendelkezésre állása gyorsítótárazva van, és a válaszidő nem függ a környezetben lévő események számától.
Tipp
A Get Environment Availability API használható az előtérbeli felhasználói felület inicializálására.
Végpont és művelet:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Példakérés törzsére: Nem alkalmazható
Példa válasz törzse:
{ "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 } }A program egy üres objektumot ad vissza az események nélküli környezetekhez.
Környezeti metaadatok API lekérése
A Környezet metaadatainak lekérése API egy adott keresési tartomány környezeti metaadatait adja vissza. A metaadatok tulajdonsághivatkozások halmazaként lesznek visszaadva. Azure Time Series Insights Gen1 belsőleg gyorsítótárazza és hozzávetőlegesen megjeleníti a metaadatokat, és további tulajdonságokat adhat vissza, amelyek a keresési tartomány pontos eseményeiben szerepelnek.
Végpont és művelet:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Bemeneti hasznos adatstruktúra:
- Keresési span záradék (kötelező)
Példakérés törzsére:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Példa válasz törzse:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }A rendszer üres
propertiestömböt ad vissza, ha a környezet üres, vagy nincsenek események a keresési tartományon belül.A beépített tulajdonságok nem jelennek meg a tulajdonságok listájában.
Környezeti események API lekérése
A Get Environment Events API a keresési tartománynak és a predikátumnak megfelelő nyers események listáját adja vissza.
Végpont és művelet:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Bemeneti hasznos adatstruktúra:
- Keresési span záradék (kötelező)
- Predikátum záradék (nem kötelező)
- Korlát záradék (kötelező)
Példakérés törzsére:
{ "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 } }Megjegyzés
- A beágyazott rendezés (azaz két vagy több tulajdonság szerinti rendezés) jelenleg nem támogatott.
- Az események felülre rendezhetők és korlátozhatók.
- A rendezés minden tulajdonságtípus esetében támogatott. A rendezés logikai kifejezésekhez definiált összehasonlító operátorokra támaszkodik.
Példa válasz törzse:
{ "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] } ] }
Környezeti események streamelt API lekérése
A Környezeti események lekérése streamelt API a keresési tartománynak és a predikátumnak megfelelő nyers események listáját adja vissza.
Ez az API a WebSocket Secure Protocol használatával végez streamelést, és részleges eredményeket ad vissza. Mindig további eseményeket ad vissza. Vagyis az új üzenet adalék az előzőhöz. Az új üzenet olyan új eseményeket tartalmaz, amelyek nem voltak az előző üzenetben. Az előző üzenetet meg kell őrizni az új üzenet hozzáadásakor.
Végpont és művelet:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Bemeneti hasznos adatstruktúra:
- Keresési span záradék (kötelező)
- Predikátum záradék (nem kötelező)
- Korlát záradék (kötelező)
Példakérési üzenetre:
{ "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 } } }Megjegyzés
- A beágyazott rendezés (azaz két vagy több tulajdonság szerinti rendezés) jelenleg nem támogatott.
- Az események felülre rendezhetők és korlátozhatók.
- A rendezés minden tulajdonságtípus esetében támogatott. A rendezés logikai kifejezésekhez definiált összehasonlító operátorokra támaszkodik.
Példa válaszüzenet:
{ "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 }
Környezeti összesítések API lekérése
A Get Environment Aggregates API egy megadott tulajdonság alapján csoportosítja az eseményeket, mivel opcionálisan más tulajdonságok értékeit méri.
Megjegyzés
A gyűjtőhatárok támogatják a 10ⁿ, a 2×10ⁿ vagy az 5×10ⁿ értékeket a numerikus hisztogramokhoz való igazításhoz és jobb támogatáshoz.
Végpont és művelet:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Bemeneti hasznos adatstruktúra:
- Keresési span záradék (kötelező)
- Predikátum záradék (nem kötelező)
- Összesítési záradék (kötelező)
Példakérés törzsére:
{ "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": {} } ] } } ] }Példa válasz törzse:
{ "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": [] }Ha nincs megadva mértékkifejezés, és az események listája üres, a válasz üres lesz.
Ha mértékek vannak jelen, a válasz egyetlen rekordot tartalmaz dimenzióértékkel
null, a0darabszám értékét és másnulltípusú mértékek értékét.
Környezeti összesítések streamelt API lekérése
A Get Environment Aggregates Streamed API egy megadott tulajdonság alapján csoportosítja az eseményeket, mivel opcionálisan más tulajdonságok értékeit is méri:
- Ez az API a WebSocket Secure Protocol protokollt használja a streameléshez, és részleges eredményeket ad vissza.
- Mindig az összes érték pótlását (pillanatképét) adja vissza.
- Az ügyfél elvetheti a korábbi csomagokat.
Megjegyzés
A gyűjtőhatárok támogatják a 10ⁿ, a 2×10ⁿ vagy az 5×10ⁿ értékeket a numerikus hisztogramokhoz való igazításhoz és jobb támogatáshoz.
Végpont és művelet:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Bemeneti hasznos adatstruktúra:
- Keresési span záradék (kötelező)
- Predikátum záradék (nem kötelező)
- Összesítési záradék (kötelező)
Példakérési üzenetre:
{ "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":{} }] }] } }Példa válaszüzenetek:
{ "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 }Ha nincs megadva mértékkifejezés, és az események listája üres, a válasz üres lesz.
Ha mértékek vannak jelen, a válasz egyetlen rekordot tartalmaz dimenzióértékkel
null, a0darabszám értékét és másnulltípusú mértékek értékét.
Korlátok
A lekérdezés végrehajtása során a következő korlátok vonatkoznak az erőforrások több környezet és felhasználó közötti igazságos használatára:
| Alkalmazható API-k | Korlát neve | Korlátérték | Érintett termékváltozatok | Jegyzetek |
|---|---|---|---|---|
| Mind | Kérelem maximális mérete | 32 kB | S1, S2 | |
| Környezet rendelkezésre állásának lekérése, Környezeti metaadatok lekérése, Környezeti események lekérése, Környezeti összesítések lekérése streamelve | Egyidejű kérések maximális száma környezetenként | 10 | S1, S2 | |
| Környezeti események lekérése, Környezeti aggregátumok lekérése streamelve | Maximális válaszméret | 16 MB | S1, S2 | |
| Környezeti események lekérése, Környezeti aggregátumok lekérése streamelve | A predikátumban található egyedi tulajdonsághivatkozások maximális száma, beleértve a predikátumi sztringkifejezéseket is | 50 | S1, S2 | |
| Környezeti események lekérése, Környezeti aggregátumok lekérése streamelve | Teljes szöveges keresési kifejezések maximális száma tulajdonsághivatkozás nélkül a predikátumi sztringben | 2 | S1, S2 | Példa: HAS 'abc', 'abc' |
| Környezeti események lekérése | Válaszban szereplő események maximális száma | 10,000 | S1, S2 | |
| Környezeti aggregátumok streamelt állapotának lekérése | Méretek maximális száma | 5 | S1, S2 | |
| Környezeti aggregátumok streamelt állapotának lekérése | Teljes számosság maximális száma az összes dimenzióban | 150 000 | S1, S2 | |
| Környezeti aggregátumok streamelt állapotának lekérése | Mértékek maximális száma | 20 | S1, S2 |
Hibakezelés és megoldás
A tulajdonság nem található viselkedése
A lekérdezésben hivatkozott tulajdonságok esetében, akár predikátumok részeként, akár az összesítések (mértékek) részeként, a lekérdezés alapértelmezés szerint megpróbálja feloldani a tulajdonságot a környezet globális keresés tartományában. Ha a tulajdonság megtalálható, a lekérdezés sikeres lesz. Ha a tulajdonság nem található, a lekérdezés meghiúsul.
Ezt a viselkedést azonban módosíthatja úgy, hogy meglévőként, de értékekkel null kezelje a tulajdonságokat, ha azok nincsenek jelen a környezetben. Ehhez állítsa be az opcionális kérelemfejlécet x-ms-property-not-found-behavior a következő értékre UseNull: .
A kérelem fejlécének UseNull lehetséges értékei a vagy ThrowError (alapértelmezett). Ha értékként van beállítva UseNull , a lekérdezés akkor is sikeres lesz, ha a tulajdonságok nem léteznek, és a válasz figyelmeztetéseket tartalmaz, amelyek a nem található tulajdonságokat jelenítik meg.
Megoldatlan tulajdonságok jelentése
Megadhatja a predikátumok, dimenziók és mértékkifejezések tulajdonsághivatkozásait. Ha egy adott névvel és típussal rendelkező tulajdonság nem létezik egy adott keresési tartományhoz, a rendszer megkísérel feloldani egy tulajdonságot egy globális időtartamon keresztül.
A megoldás sikerességétől függően a következő figyelmeztetés vagy hiba jelenhet meg:
- Ha egy tulajdonság globális időtartományon keresztül létezik a környezetben, a rendszer megfelelően feloldja azt, és egy figyelmeztetés jelenik meg, amely tájékoztatja arról, hogy a tulajdonság értéke egy adott keresési tartományra vonatkozik
null. - Ha egy tulajdonság nem létezik a környezetben, hibaüzenet jelenik meg, és a lekérdezés végrehajtása meghiúsul.
Hibaválaszok
Ha a lekérdezés végrehajtása sikertelen, a JSON-válasz hasznos adata a következő struktúrával rendelkező hibaválaszt tartalmaz:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
innerError Itt nem kötelező megadni. Az alapszintű hibák, például a hibásan formázott kérések mellett a következő hibák jelennek meg:
| HTTP-állapotkód | Hibakód | Példa egy hibaüzenetre | Lehetséges belső hibakódok |
|---|---|---|---|
| 400 | InvalidApiVersion | "Az API 2016-os verziója nem támogatott. A támogatott verziók a következők: "2016-12-12". | |
| 400 | InvalidInput | "Nem lehet elemezni a predikátumi sztringet." | PredicateStringParseError |
| 400 | InvalidInput | "Nem lehet lefordítani a predikátumi sztringet." | InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Több összesítés nem támogatott." | |
| 400 | InvalidInput | "A predikátum tulajdonság nem található." | PropertyNotFound |
| 400 | InvalidInput | "A Mérték tulajdonság nem található." | PropertyNotFound |
| 400 | InvalidInput | "A dimenziótulajdonság nem található." | PropertyNotFound |
| 400 | InvalidInput | "A mértékek száma túllépte a korlátot." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Az összesített mélység túllépte a korlátot." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "A teljes számosság túllépte a korlátot." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "A(z) "from" tulajdonság hiányzik." | BreaksPropertyMissing |
| 400 | InvalidInput | "Hiányzik a "to" tulajdonság." | BreaksPropertyMissing |
| 400 | InvalidInput | "A kérelem mérete túllépte a korlátot." | RequestSizeExceededLimit |
| 400 | InvalidInput | "A válasz mérete túllépte a korlátot." | ResponseSizeExceededLimit |
| 400 | InvalidInput | "Az eseményszám túllépte a korlátot." | EventCountExceededLimit |
| 400 | InvalidInput | "A tulajdonsághivatkozások száma túllépte a korlátot." | PropertyReferenceCountExceededLimit |
| 400 | Érvénytelenmethod | "Csak a WebSocket-kérelmek engedélyezettek az összesítések útvonalán." | |
| 400 | InvalidUrl | "A kérelem URL-címe (/a/b) nem elemezhető." | |
| 408 | RequestTimeout | "A kérés a 30 másodperc(ek) után időtúllépést jelent." | |
| 503 | TooManyRequests | "A "95880732-01b9-44ea-8d2d-4d764dfe1904" környezetben a "10" egyidejű kérelemszám túllépve." | EnvRequestLimitExceeded |
Figyelmeztetések
A Lekérdezési API-válasz tartalmazhat figyelmeztetések listáját bejegyzésként "warnings" a HTTP-válasz vagy a WebSocket válaszüzenet gyökerében. Jelenleg figyelmeztetések jönnek létre, ha a tulajdonság nem található egy adott keresési tartományhoz, de globális időtartományra vonatkozó környezetben található. Akkor is létrejön, ha a fejléc x-ms-property-not-found-behaviorUseNull értéke, és a hivatkozott tulajdonság még a globális keresés spanban sem létezik.
Minden figyelmeztető objektum a következő mezőket tartalmazhatja:
| Mező neve | Mező típusa | Jegyzetek |
|---|---|---|
| code | Sztring | Az egyik előre definiált figyelmeztető kód |
| üzenet | Sztring | Részletes figyelmeztető üzenet |
| Cél | Sztring | A JSON bemeneti hasznos adatbevitelének ponttól elválasztott JSON-elérési útja, amely a figyelmeztetést okozza |
| warningDetails | Szótár | Választható; további figyelmeztetési adatok (például a predikátumi sztring pozíciója) |
Az alábbi kód példákat mutat be a predikátumra, a predikátumon belüli predikátumi sztringre, a dimenzióra és a mértékre vonatkozó figyelmeztetésekre:
"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"
}
]
Lásd még
További információ az alkalmazásregisztrációról és az Azure Active Directory programozási modellről: Azure Active Directory fejlesztőknek.
A kérelem- és hitelesítési paraméterekkel kapcsolatos további információkért lásd: Hitelesítés és engedélyezés.
A HTTP-kérések és -válaszok tesztelését segítő eszközök a következők:
- Fiddler. Ez az ingyenes webes hibakeresési proxy elfoghatja a REST-kéréseket, így diagnosztizálhatja a HTTP-kéréseket és a válaszüzeneteket.
- JWT.io. Ezzel az eszközzel gyorsan lerakhatja a jogcímeket a tulajdonosi jogkivonatban, majd ellenőrizheti azok tartalmát.
- Postás. Ez egy ingyenes HTTP-kérés- és választesztelési eszköz a REST API-k hibakereséséhez.
Az 1. generációs Azure Time Series Insights a Gen1 dokumentációjának áttekintésével talál további információt.