rozhraní API pro dotazy Azure Time Series Insights Gen1
Upozornění
Toto je článek Gen1.
Tento článek popisuje různá rozhraní REST Query API. ROZHRANÍ REST API jsou koncové body služby, které podporují sady operací HTTP (metod), které umožňují dotazovat Azure Time Series Insights prostředí Gen1.
Důležité
- Azure Time Series Insights Gen1 používá protokol HTTPS pro rozhraní API Get Environment, Get Environment Availability, Get Metadata, Get Environment Events a Get Environment Aggregates.
- Azure Time Series Insights Gen1 používá protokol WSS (WebSocket Secure) pro rozhraní API get environment events streamed a Get Aggregates Streamed.
Rozhraní API pro získání prostředí
Rozhraní API Get Environment vrátí seznam prostředí, ke kterým má volající oprávnění k přístupu.
Koncový bod a operace:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Příklad textu požadavku: Nepoužitelné
Příklad textu odpovědi:
{ "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" ] } ] }Poznámka
Vlastnost odpovědi environmentFqdn je jedinečný plně kvalifikovaný název domény pro prostředí, který se používá v požadavcích rozhraní API pro dotazy na jednotlivá prostředí.
Získat rozhraní API pro dostupnost prostředí
Rozhraní API Pro získání dostupnosti prostředí vrátí rozdělení počtu událostí podle časového razítka události $ts. Dostupnost prostředí se ukládá do mezipaměti a doba odezvy nezávisí na počtu událostí v prostředí.
Tip
Rozhraní API pro dostupnost prostředí Get můžete použít k inicializaci prostředí front-end uživatelského rozhraní.
Koncový bod a operace:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Příklad textu požadavku: Nepoužitelné
Příklad textu odpovědi:
{ "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 } }Pro prostředí bez událostí se vrátí prázdný objekt.
Získání rozhraní API metadat prostředí
Rozhraní API Get Environment Metadata (Získat metadata prostředí) vrací metadata prostředí pro daný rozsah hledání. Metadata se vrátí jako sada odkazů na vlastnosti. Azure Time Series Insights Gen1 interně ukládá do mezipaměti a přibližuje metadata a může vracet více vlastností, které jsou přítomné v přesných událostech v rozsahu hledání.
Koncový bod a operace:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Struktura vstupní datové části:
- Klauzule Search span (povinné)
Příklad textu požadavku:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Příklad textu odpovědi:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }Prázdné
propertiespole je vráceno, pokud je prostředí prázdné nebo neexistují žádné události v rozsahu hledání.Předdefinované vlastnosti nejsou v seznamu vlastností vráceny.
Rozhraní API pro získání událostí prostředí
Rozhraní API Pro získání událostí prostředí vrátí seznam nezpracovaných událostí, které odpovídají rozsahu hledání a predikátu.
Koncový bod a operace:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Struktura vstupní datové části:
- Klauzule Search span (povinné)
- Predikát – klauzule (volitelné)
- Klauzule Limit (povinná)
Příklad textu požadavku:
{ "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 } }Poznámka
- Vnořené řazení (tj. řazení podle dvou nebo více vlastností) se v současné době nepodporuje.
- Události se dají seřadit a omezit na začátek.
- Řazení se podporuje u všech typů vlastností. Řazení závisí na relačních operátorech definovaných pro logické výrazy.
Příklad textu odpovědi:
{ "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] } ] }
Rozhraní API pro streamování událostí prostředí
Rozhraní API Get Environment Events Streamed vrátí seznam nezpracovaných událostí, které odpovídají rozsahu hledání a predikátu.
Toto rozhraní API používá protokol WebSocket Secure Protocol k streamování a vrácení částečných výsledků. Vždy vrací další události. To znamená, že nová zpráva je přidána k předchozí zprávě. Nová zpráva obsahuje nové události, které nebyly v předchozí zprávě. Předchozí zpráva by měla být při přidání nové zprávy zachována.
Koncový bod a operace:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Struktura vstupní datové části:
- Klauzule Search span (povinné)
- Predikát – klauzule (volitelné)
- Klauzule Limit (povinná)
Příklad zprávy požadavku:
{ "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 } } }Poznámka
- Vnořené řazení (tj. řazení podle dvou nebo více vlastností) se v současné době nepodporuje.
- Události se dají seřadit a omezit na začátek.
- Řazení se podporuje u všech typů vlastností. Řazení závisí na relačních operátorech definovaných pro logické výrazy.
Příklad zprávy odpovědi:
{ "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 }
Získat rozhraní API pro agregace prostředí
Rozhraní API Get Environment agreguje seskupuje události podle zadané vlastnosti, protože volitelně měří hodnoty jiných vlastností.
Poznámka
Hranice kbelíků podporují hodnoty 10ⁿ, 2×10ⁿ nebo 5×10ⁿ pro zarovnání a lepší podporu číselných histogramů.
Koncový bod a operace:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Struktura vstupní datové části:
- Klauzule Search span (povinné)
- Predikát – klauzule (volitelné)
- Klauzule Aggregates (povinná)
Příklad textu požadavku:
{ "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říklad textu odpovědi:
{ "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": [] }Pokud nejsou zadány žádné výrazy míry a seznam událostí je prázdný, odpověď bude prázdná.
Pokud jsou k dispozici míry, odpověď obsahuje jeden záznam s
nullhodnotou dimenze,0hodnotu pro počet anullhodnotu pro jiné druhy měr.
Rozhraní API pro agregaci prostředí
Funkce Get Environment agreguje streamované rozhraní API seskupuje události podle zadané vlastnosti, protože volitelně měří hodnoty jiných vlastností:
- Toto rozhraní API používá k streamování a vrácení částečných výsledků protokol WebSocket Secure Protocol.
- Vždy vrátí nahrazení (snímek) všech hodnot.
- Předchozí pakety může klient zahodit.
Poznámka
Hranice kbelíků podporují hodnoty 10ⁿ, 2×10ⁿ nebo 5×10ⁿ pro zarovnání a lepší podporu číselných histogramů.
Koncový bod a operace:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Struktura vstupní datové části:
- Klauzule Search span (povinné)
- Predikát – klauzule (volitelné)
- Klauzule Aggregates (povinná)
Příklad zprávy požadavku:
{ "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":{} }] }] } }Ukázkové zprávy odpovědi:
{ "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 }Pokud nejsou zadány žádné výrazy míry a seznam událostí je prázdný, odpověď bude prázdná.
Pokud jsou k dispozici míry, odpověď obsahuje jeden záznam s
nullhodnotou dimenze,0hodnotu pro počet anullhodnotu pro jiné druhy měr.
Omezení
Při provádění dotazů se použijí následující omezení, aby bylo možné využívat prostředky mezi více prostředími a uživateli:
| Příslušná rozhraní API | Název limitu | Limitní hodnota | Ovlivněné skladové položky | Poznámky |
|---|---|---|---|---|
| Vše | Maximální velikost požadavku | 32 kB | S1, S2 | |
| Získání dostupnosti prostředí, získání metadat prostředí, získání událostí prostředí, streamování agregací prostředí | Maximální počet souběžných požadavků na prostředí | 10 | S1, S2 | |
| Získání událostí prostředí, streamování agregací prostředí | Maximální velikost odpovědi | 16 MB | S1, S2 | |
| Získání událostí prostředí, streamování agregací prostředí | Maximální počet jedinečných odkazů na vlastnosti v predikátu, včetně řetězcových výrazů predikátu | 50 | S1, S2 | |
| Získání událostí prostředí, streamování agregací prostředí | Maximální počet fulltextových hledaných termínů bez odkazu na vlastnost v řetězci predikátu | 2 | S1, S2 | Příklad: HAS 'abc', 'abc' |
| Získání událostí prostředí | Maximální počet událostí v odpovědi | 10 000 | S1, S2 | |
| Získání agregací prostředí streamovaných | Maximální počet dimenzí | 5 | S1, S2 | |
| Získání agregací prostředí streamovaných | Maximální celková kardinalita napříč všemi dimenzemi | 150 000 | S1, S2 | |
| Získání agregací prostředí streamovaných | Maximální počet měr | 20 | S1, S2 |
Zpracování a řešení chyb
Chování vlastnosti nenalezena
U vlastností odkazovaných v dotazu, ať už jako součást predikátů nebo součástí agregací (měr), se dotaz ve výchozím nastavení pokusí přeložit vlastnost v globální vyhledávání rozsahu prostředí. Pokud se vlastnost najde, dotaz bude úspěšný. Pokud se vlastnost nenajde, dotaz selže.
Toto chování však můžete upravit tak, aby vlastnosti byly považovány za existující, ale s null hodnotami, pokud se v prostředí nenacházejí. Provedete to nastavením volitelné hlavičky x-ms-property-not-found-behavior požadavku na hodnotu UseNull.
Možné hodnoty pro hlavičku požadavku jsou UseNull nebo ThrowError (výchozí). Když nastavíte UseNull jako hodnotu, dotaz bude úspěšný, i když vlastnosti neexistují, a odpověď bude obsahovat upozornění, která zobrazí vlastnosti, které nebyly nalezeny.
Nevyřešené vlastnosti sestavy
Odkazy na vlastnosti můžete zadat pro výrazy predikátu, dimenze a míry. Pokud vlastnost s konkrétním názvem a typem pro zadaný rozsah hledání neexistuje, pokusí se přeložit vlastnost v globálním časovém rozsahu.
V závislosti na úspěchu řešení se může zobrazit následující upozornění nebo chyba:
- Pokud v prostředí existuje vlastnost v globálním časovém intervalu, je správně vyřešena a vygeneruje se upozornění s upozorněním, že hodnota této vlastnosti odpovídá
nulldanému rozsahu hledání. - Pokud vlastnost v prostředí neexistuje, vygeneruje se chyba a provádění dotazu se nezdaří.
Chybové odpovědi
Pokud se provádění dotazu nezdaří, datová část odpovědi JSON obsahuje chybovou odpověď s následující strukturou:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
innerError Tady je nepovinný argument. Kromě základních chyb, jako je například poškozený požadavek, se vrátí následující chyby:
| Stavový kód HTTP | Kód chyby | Příklad chybové zprávy | Možné vnitřní kódy chyb |
|---|---|---|---|
| 400 | InvalidApiVersion | Verze rozhraní API 2016 se nepodporuje. Podporované verze jsou '2016-12-12'." | |
| 400 | InvalidInput | "Nelze analyzovat predikátový řetězec." | PredicateStringParseError |
| 400 | InvalidInput | "Nelze přeložit řetězec predikátu." |
InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Více agregací není podporováno." | |
| 400 | InvalidInput | "Vlastnost predikátu nebyla nalezena." | PropertyNotFound |
| 400 | InvalidInput | "Vlastnost míry nebyla nalezena." | PropertyNotFound |
| 400 | InvalidInput | "Vlastnost dimenze nebyla nalezena." | PropertyNotFound |
| 400 | InvalidInput | Počet měr překročil limit. | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Agregační hloubka překročila limit." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "Celková kardinalita překročila limit." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "Vlastnost 'from' chybí." | BreaksPropertyMissing |
| 400 | InvalidInput | "Vlastnost 'to' chybí." | BreaksPropertyMissing |
| 400 | InvalidInput | "Velikost požadavku překročila limit." | RequestSizeExceededLimit |
| 400 | InvalidInput | "Velikost odpovědi překročila limit." | ResponseSizeExceededLimit |
| 400 | InvalidInput | Počet událostí překročil limit. | EventCountExceededLimit |
| 400 | InvalidInput | Počet odkazů na vlastnost překročil limit. | PropertyReferenceCountExceededLimit |
| 400 | Neplatnýmethod | "Na cestě agregace jsou povoleny pouze požadavky Protokolu WebSocket." | |
| 400 | Neplatná adresa | "Adresu URL požadavku /a/b nelze analyzovat." | |
| 408 | RequestTimeout | "Časový limit požadavku vypršel po 30 sekundách." | |
| 503 | TooManyRequests | Počet souběžných požadavků 10 byl překročen pro prostředí 95880732-01b9-44ea-8d2d-4d764dfe1904. | EnvRequestLimitExceeded |
Upozornění
Odpověď rozhraní API pro dotazy může obsahovat seznam upozornění jako "warnings" položku v kořenovém adresáři odpovědi HTTP nebo zprávy odpovědi WebSocket. V současné době se vygenerují upozornění, pokud se vlastnost nenajde pro daný rozsah hledání, ale je nalezena v prostředí pro globální časový rozsah. Vygeneruje se také v případě, že je hlavička x-ms-property-not-found-behavior nastavena na UseNull a odkazovaná vlastnost neexistuje ani v rozsahu globální vyhledávání.
Každý objekt upozornění může obsahovat následující pole:
| Název pole | Typ pole | Poznámky |
|---|---|---|
| kód | Řetězec | Jeden z předdefinovaných kódů upozornění |
| message | Řetězec | Podrobná zpráva s upozorněním |
| Cíl | Řetězec | Cesta JSON oddělená tečkami k vstupní datové části JSON, která způsobuje upozornění |
| warningDetails | Slovník | Volitelné; další podrobnosti upozornění (například pozice v řetězci predikátu) |
Následující kód obsahuje příklady upozornění pro predikát, řetězec predikátu v rámci predikátu, dimenze a míry:
"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"
}
]
Viz také
Další informace o registraci aplikací a programovacím modelu Azure Active Directory najdete v tématu Azure Active Directory pro vývojáře.
Další informace o parametrech požadavků a ověřování najdete v tématu Ověřování a autorizace.
Mezi nástroje, které pomáhají s testováním požadavků a odpovědí HTTP, patří:
- Fiddleři. Tento bezplatný webový ladicí proxy server může zachycovat vaše požadavky REST, abyste mohli diagnostikovat požadavky HTTP a zprávy odpovědí.
- JWT.io. Tento nástroj můžete použít k rychlému výpisu deklarací identity v nosným tokenu a následnému ověření jejich obsahu.
- Postman. Toto je bezplatný nástroj pro testování požadavků HTTP a odpovědí pro ladění rozhraní REST API.
Další informace o Azure Time Series Insights Gen1 najdete v dokumentaci k Gen1.