Azure Time Series Insights Gen1-Abfrage-API
Achtung
Dies ist ein Artikel zu Azure Time Series Insights Gen1.
In diesem Artikel werden verschiedene REST-Abfrage-APIs beschrieben. REST-APIs sind Dienstendpunkte, die Sätze von HTTP-Vorgängen (Methoden) unterstützen, mit denen Sie Azure Time Series Insights Gen1-Umgebungen abfragen können.
Wichtig
- Azure Time Series Insights Gen1 verwendet das HTTPS-Protokoll für die APIs Get Environments, Get Environment Availability, Get Metadata, Get Environment Events und Get Environment Aggregates APIs.
- Azure Time Series Insights Gen1 verwendet das WebSocket Secure-Protokoll (WSS) für die APIs Get Environment Events Streamed (Get Environment Events Streamed) und Get Aggregate Streamed (Aggregate streamed).
Api zum Abrufen von Umgebungen
Die API zum Abrufen von Umgebungen gibt die Liste der Umgebungen zurück, für die der Aufrufer autorisiert ist.
Endpunkt und Vorgang:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Beispielanforderungstext: Nicht zutreffend
Beispielantworttext:
{ "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" ] } ] }Hinweis
Die Antworteigenschaft environmentFqdn ist ein eindeutiger, vollqualifizierter Domänenname für die Umgebung, die in Abfrage-API-Anforderungen pro Umgebung verwendet wird.
die „Umgebungsverfügbarkeit abrufen“-API,
Die API zum Abrufen der Umgebungsverfügbarkeit gibt die Verteilung der Ereignisanzahl über den Ereigniszeitstempel $ts zurück. Die Verfügbarkeit der Umgebung wird zwischengespeichert, und die Antwortzeit hängt nicht von der Anzahl der Ereignisse in einer Umgebung ab.
Tipp
Die API zum Abrufen der Verfügbarkeit von Umgebungen kann verwendet werden, um eine Front-End-Benutzeroberfläche zu initialisieren.
Endpunkt und Vorgang:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Beispielanforderungstext: Nicht zutreffend
Beispielantworttext:
{ "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 } }Für Umgebungen ohne Ereignisse wird ein leeres Objekt zurückgegeben.
Api zum Abrufen von Umgebungsmetadaten
Die API zum Abrufen von Umgebungsmetadaten gibt Umgebungsmetadaten für eine bestimmte Suchspanne zurück. Metadaten werden als Eine Reihe von Eigenschaftenverweise zurückgegeben. Azure Time Series Insights Gen1 speichert Metadaten intern zwischen und nähert sie an und gibt möglicherweise weitere Eigenschaften zurück, die in den genauen Ereignissen in der Suchspanne vorhanden sind.
Endpunkt und Vorgang:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Struktur der Eingabenutzlast:
- Search span-Klausel (obligatorisch)
Beispiel für Anforderungstext:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Beispielantworttext:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }Ein leeres
propertiesArray wird zurückgegeben, wenn die Umgebung leer ist oder keine Ereignisse in einer Suchspanne vorhanden sind.Integrierte Eigenschaften werden in der Liste der Eigenschaften nicht zurückgegeben.
API zum Abrufen von Umgebungsereignissen
Die API zum Abrufen von Umgebungsereignissen gibt eine Liste von Rohereignissen zurück, die der Suchspanne und dem Prädikat entsprechen.
Endpunkt und Vorgang:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Struktur der Eingabenutzlast:
- Search span-Klausel (obligatorisch)
- Prädikatklausel (optional)
- Limit-Klausel (obligatorisch)
Beispiel für Anforderungstext:
{ "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 } }Hinweis
- Die geschachtelte Sortierung (d. h. die Sortierung nach zwei oder mehr Eigenschaften) wird derzeit nicht unterstützt.
- Ereignisse können sortiert und auf den Anfang beschränkt werden.
- Die Sortierung wird für alle Eigenschaftentypen unterstützt. Die Sortierung basiert auf Vergleichsoperatoren, die für boolesche Ausdrücke definiert sind.
Beispielantworttext:
{ "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] } ] }
die „Gestreamte Umgebungsereignisse abrufen“-API,
Die GET Environment Events Streamed API gibt eine Liste von Rohereignissen zurück, die der Suchspanne und dem Prädikat entsprechen.
Diese API verwendet das WebSocket Secure Protocol, um Streaming zu durchführen und Teilergebnisse zurückzugeben. Es werden immer zusätzliche Ereignisse zurückgegeben. Das heißt, die neue Nachricht ist addiert zur vorherigen. Die neue Nachricht enthält neue Ereignisse, die nicht in der vorherigen Nachricht enthalten waren. Die vorherige Nachricht sollte beibehalten werden, wenn die neue Nachricht hinzugefügt wird.
Endpunkt und Vorgang:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Struktur der Eingabenutzlast:
- Search span-Klausel (obligatorisch)
- Prädikatklausel (optional)
- Limit-Klausel (obligatorisch)
Beispiel einer Anforderungsnachricht:
{ "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 } } }Hinweis
- Die geschachtelte Sortierung (d. h. die Sortierung nach zwei oder mehr Eigenschaften) wird derzeit nicht unterstützt.
- Ereignisse können sortiert und auf den Anfang beschränkt werden.
- Die Sortierung wird für alle Eigenschaftentypen unterstützt. Die Sortierung basiert auf Vergleichsoperatoren, die für boolesche Ausdrücke definiert sind.
Beispielantwortnachricht:
{ "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 }
die „Umgebungsaggregate abrufen“-API.
Die GET Environment Aggregates-API gruppiert Ereignisse nach einer angegebenen Eigenschaft, da sie optional die Werte anderer Eigenschaften misst.
Hinweis
Bucketgrenzen unterstützen 10ⁿ, 2×10ⁿ oder 5×10ⁿ Werte, um numerische Histogramme auszurichten und besser zu unterstützen.
Endpunkt und Vorgang:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Struktur der Eingabenutzlast:
- Search span-Klausel (obligatorisch)
- Prädikatklausel (optional)
- Aggregates-Klausel (obligatorisch)
Beispiel für Anforderungstext:
{ "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": {} } ] } } ] }Beispielantworttext:
{ "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": [] }Wenn keine Measureausdrücke angegeben werden und die Liste der Ereignisse leer ist, ist die Antwort leer.
Wenn Measures vorhanden sind, enthält die Antwort einen einzelnen Datensatz mit einem
nullDimensionswert, einen0Wert für die Anzahl und einennullWert für andere Arten von Measures.
die „Gestreamte Umgebungsaggregate abrufen“-API,
Die Get Environment Aggregates Streamed API gruppiert Ereignisse nach einer angegebenen Eigenschaft, da sie optional die Werte anderer Eigenschaften misst:
- Diese API verwendet das WebSocket Secure Protocol zum Streaming und zum Zurückgeben von Teilergebnissen.
- Er gibt immer eine Ersetzung (Momentaufnahme) aller Werte zurück.
- Vorherige Pakete können vom Client verworfen werden.
Hinweis
Bucketgrenzen unterstützen 10ⁿ, 2×10ⁿ oder 5×10ⁿ Werte, um numerische Histogramme auszurichten und besser zu unterstützen.
Endpunkt und Vorgang:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Struktur der Eingabenutzlast:
- Search span-Klausel (obligatorisch)
- Prädikatklausel (optional)
- Aggregates-Klausel (obligatorisch)
Beispiel einer Anforderungsnachricht:
{ "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":{} }] }] } }Beispielantwortnachrichten:
{ "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 }Wenn keine Measureausdrücke angegeben werden und die Liste der Ereignisse leer ist, ist die Antwort leer.
Wenn Measures vorhanden sind, enthält die Antwort einen einzelnen Datensatz mit einem
nullDimensionswert, einen0Wert für die Anzahl und einennullWert für andere Arten von Measures.
Grenzwerte
Die folgenden Grenzwerte werden während der Abfrageausführung angewendet, um Ressourcen in mehreren Umgebungen und Benutzern fair zu nutzen:
| Anwendbare APIs | Limitname | Grenzwert | Betroffene SKUs | Notizen |
|---|---|---|---|---|
| All | Maximale Anforderungsgröße | 32 KB | E1, E2 | |
| Abrufen der Umgebungsverfügbarkeit, Abrufen von Umgebungsmetadaten, Abrufen von Umgebungsereignissen, Streamen von Umgebungsaggregaten | Maximale Anzahl gleichzeitiger Anforderungen pro Umgebung | 10 | E1, E2 | |
| Abrufen von Umgebungsereignissen, Abrufen von Gestreamten Umgebungsaggregaten | Maximale Antwortgröße | 16 MB | E1, E2 | |
| Abrufen von Umgebungsereignissen, Abrufen von Gestreamten Umgebungsaggregaten | Maximale Anzahl eindeutiger Eigenschaftenverweise im Prädikat, einschließlich Prädikatzeichenfolgenausdrücken | 50 | E1, E2 | |
| Abrufen von Umgebungsereignissen, Abrufen von Gestreamten Umgebungsaggregaten | Max. Volltextsuchbegriffe ohne Eigenschaftsverweis in Prädikatzeichenfolge | 2 | E1, E2 | Beispiel: HAS 'abc', 'abc' |
| Abrufen von Umgebungsereignissen | Maximale Anzahl von Ereignissen als Antwort | 10.000 | E1, E2 | |
| Abrufen von Gestreamten Umgebungsaggregaten | Maximale Anzahl von Dimensionen | 5 | E1, E2 | |
| Abrufen von Gestreamten Umgebungsaggregaten | Maximale Gesamtkardinalität über alle Dimensionen hinweg | 150.000 | E1, E2 | |
| Abrufen von Gestreamten Umgebungsaggregaten | Maximale Anzahl von Measures | 20 | E1, E2 |
Fehlerbehandlung und -lösung
Verhalten der Eigenschaft nicht gefunden
Bei Eigenschaften, auf die in der Abfrage verwiesen wird, entweder als Teil von Prädikaten oder als Teil von Aggregaten (Measures), versucht die Abfrage standardmäßig, die -Eigenschaft in der globale Suche-Spanne der Umgebung aufzulösen. Wenn die -Eigenschaft gefunden wird, ist die Abfrage erfolgreich. Wenn die Eigenschaft nicht gefunden wird, schlägt die Abfrage fehl.
Sie können dieses Verhalten jedoch ändern, um Eigenschaften als vorhanden zu behandeln, aber mit null Werten, wenn sie nicht in der Umgebung vorhanden sind. Dazu legen Sie den optionalen Anforderungsheader x-ms-property-not-found-behavior auf den Wert UseNullfest.
Mögliche Werte für den Anforderungsheader sind UseNull oder ThrowError (Standard). Wenn Sie als Wert festlegen UseNull , ist die Abfrage erfolgreich, obwohl die Eigenschaften nicht vorhanden sind, und die Antwort enthält Warnungen, die die eigenschaften anzeigen, die nicht gefunden wurden.
Melden nicht aufgelöster Eigenschaften
Sie können Eigenschaftenverweise für Prädikat-, Dimensions- und Measureausdrücke angeben. Wenn eine Eigenschaft mit einem bestimmten Namen und Typ für eine angegebene Suchspanne nicht vorhanden ist, wird versucht, eine Eigenschaft über einen globalen Zeitraum aufzulösen.
Je nach Erfolg der Lösung kann die folgende Warnung oder der folgende Fehler ausgegeben werden:
- Wenn eine Eigenschaft in der Umgebung über einen globalen Zeitraum vorhanden ist, wird sie entsprechend aufgelöst, und es wird eine Warnung ausgegeben, um Sie darüber zu informieren, dass der Wert dieser Eigenschaft für eine bestimmte Suchspanne gilt
null. - Wenn in der Umgebung keine Eigenschaft vorhanden ist, wird ein Fehler ausgegeben, und die Abfrageausführung schlägt fehl.
Fehlercodes
Wenn bei der Abfrageausführung ein Fehler auftritt, enthält die JSON-Antwortnutzlast eine Fehlerantwort mit der folgenden Struktur:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
innerError Hier ist optional. Zusätzlich zu grundlegenden Fehlern, z. B. einer falsch formatierten Anforderung, werden die folgenden Fehler zurückgegeben:
| HTTP-Statuscode | Fehlercode | Beispiel einer Fehlermeldung | Mögliche interne Fehlercodes |
|---|---|---|---|
| 400 | InvalidApiVersion | "DIE API-Version '2016' wird nicht unterstützt. Unterstützte Versionen sind '2016-12-12'." | |
| 400 | InvalidInput | "Prädikatzeichenfolge kann nicht analysiert werden." | PredicateStringParseError |
| 400 | InvalidInput | "Prädikatzeichenfolge kann nicht übersetzt werden." | InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Mehrere Aggregate werden nicht unterstützt." | |
| 400 | InvalidInput | "Prädikateigenschaft nicht gefunden." | PropertyNotFound |
| 400 | InvalidInput | "Measure-Eigenschaft nicht gefunden." | PropertyNotFound |
| 400 | InvalidInput | "Dimensionseigenschaft nicht gefunden." | PropertyNotFound |
| 400 | InvalidInput | "Die Anzahl der Maßnahmen hat den Grenzwert überschritten." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Der Grenzwert für die Aggregattiefe wurde überschritten." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "Der Grenzwert für die Gesamtkardinalität wurde überschritten." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "Eigenschaft 'from' fehlt." | BreaksPropertyMissing |
| 400 | InvalidInput | "Eigenschaft 'to' fehlt." | BreaksPropertyMissing |
| 400 | InvalidInput | "Die Anforderungsgröße hat den Grenzwert überschritten." | RequestSizeExceededLimit |
| 400 | InvalidInput | "Die Antwortgröße hat den Grenzwert überschritten." | ResponseSizeExceededLimit |
| 400 | InvalidInput | "Die Ereignisanzahl hat den Grenzwert überschritten." | EventCountExceededLimit |
| 400 | InvalidInput | "Die Anzahl der Eigenschaftsverweis hat den Grenzwert überschritten." | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | "Nur WebSocket-Anforderungen sind für den Pfad 'Aggregate' zulässig." | |
| 400 | InvalidUrl | "Die Anforderungs-URL '/a/b' konnte nicht analysiert werden." | |
| 408 | RequestTimeout | "Timeout der Anforderung nach '30' Sekunden." | |
| 503 | TooManyRequests | "Anzahl gleichzeitiger Anforderungen von '10' wurde für die Umgebung '95880732-01b9-44ea-8d2d-4d764dfe1904' überschritten." | EnvRequestLimitExceeded |
Warnungen
Eine Abfrage-API-Antwort kann eine Liste von Warnungen als "warnings" Eintrag unter dem Stamm der HTTP-Antwort oder WebSocket-Antwortnachricht enthalten. Derzeit werden Warnungen generiert, wenn die Eigenschaft für eine bestimmte Suchspanne nicht gefunden wird, aber in einer Umgebung für einen globalen Zeitraum gefunden wird. Sie wird auch generiert, wenn der Header x-ms-property-not-found-behavior auf UseNull festgelegt ist und eine Eigenschaft, auf die verwiesen wird, selbst in der globale Suche Spanne nicht vorhanden ist.
Jedes Warnungsobjekt kann die folgenden Felder enthalten:
| Feldname | Feldtyp | Notizen |
|---|---|---|
| code | String | Einer der vordefinierten Warnungscodes |
| Nachricht | String | Eine ausführliche Warnmeldung |
| Ziel | String | Ein punkttrennlicher JSON-Pfad zum JSON-Eingabenutzlasteintrag, der die Warnung verursacht |
| warningDetails | Wörterbuch | Optional; zusätzliche Warnungsdetails (z. B. die Position in der Prädikatzeichenfolge) |
Der folgende Code enthält Beispiele für Warnungen für Prädikat, Prädikatzeichenfolge in Prädikat, Dimension und Measure:
"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"
}
]
Weitere Informationen
Weitere Informationen zur Anwendungsregistrierung und zum Azure Active Directory-Programmiermodell finden Sie unter Azure Active Directory für Entwickler.
Informationen zu Anforderungs- und Authentifizierungsparametern finden Sie unter Authentifizierung und Autorisierung.
Zu den Tools, die beim Testen von HTTP-Anforderungen und -Antworten helfen, gehören:
- Fiddler. Dieser kostenlose Webdebugproxy kann Ihre REST-Anforderungen abfangen, sodass Sie die HTTP-Anforderung und -Antwortnachrichten diagnostizieren können.
- JWT.io. Sie können dieses Tool verwenden, um die Ansprüche in Ihrem Bearertoken schnell abzuspeichern und dann deren Inhalt zu überprüfen.
- Postman. Dies ist ein kostenloses HTTP-Anforderungs- und Antworttesttool zum Debuggen von REST-APIs.
Weitere Informationen zu Azure Time Series Insights Gen1 finden Sie in der Gen1-Dokumentation.