Azure Time Series Insights Gen1-query-API
Waarschuwing
Dit is een Gen1-artikel.
In dit artikel worden verschillende REST-query-API's beschreven. REST API's zijn service-eindpunten die sets HTTP-bewerkingen (methoden) ondersteunen, waarmee u query's kunt uitvoeren op Azure Time Series Insights Gen1-omgevingen.
Belangrijk
- Azure Time Series Insights Gen1 maakt gebruik van het HTTPS-protocol voor de API's Get Environments, Get Environment Availability, Get Metadata, Get Environment Events en Get Environment Aggregates.
- Azure Time Series Insights Gen1 maakt gebruik van het WSS-protocol (WebSocket Secure) voor de API's Gestreamde omgevingsgebeurtenissen ophalen en Gestreamde aggregaties ophalen.
Omgevingen-API ophalen
De API Omgevingen ophalen retourneert de lijst met omgevingen waartoe de aanroeper toegang heeft.
Eindpunt en bewerking:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Voorbeeld van aanvraagbody: Niet van toepassing
Voorbeeld van antwoordtekst:
{ "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" ] } ] }Notitie
De antwoordeigenschap environmentFqdn is een unieke, volledig gekwalificeerde domeinnaam voor de omgeving die wordt gebruikt in query-API-aanvragen per omgeving.
Api voor omgevings beschikbaarheid ophalen
De API Omgevings beschikbaarheid ophalen retourneert de distributie van het aantal gebeurtenissen over de tijdstempel van de gebeurtenis $ts. De beschikbaarheid van de omgeving wordt in de cache opgeslagen en de reactietijd is niet afhankelijk van het aantal gebeurtenissen in een omgeving.
Tip
De API Voor beschikbaarheid van de omgeving ophalen kan worden gebruikt om een front-endgebruikersinterface-ervaring te initialiseren.
Eindpunt en bewerking:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Voorbeeld van aanvraagbody: Niet van toepassing
Voorbeeld van antwoordtekst:
{ "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 } }Er wordt een leeg object geretourneerd voor omgevingen zonder gebeurtenissen.
Api voor omgevingsmetagegevens ophalen
De API Omgevingsmetagegevens ophalen retourneert metagegevens van de omgeving voor een bepaald zoekbereik. Metagegevens worden geretourneerd als een set eigenschapsverwijzingen. Azure Time Series Insights Gen1 intern metagegevens in de cache opslaat en benadert en mogelijk meer eigenschappen retourneert die aanwezig zijn in de exacte gebeurtenissen in het zoekbereik.
Eindpunt en bewerking:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Nettoladingsstructuur van invoer:
- Component zoekbereik (verplicht)
Voorbeeld van aanvraagbody:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Voorbeeld van antwoordtekst:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }Een lege
propertiesmatrix wordt geretourneerd wanneer de omgeving leeg is of er geen gebeurtenissen in een zoekbereik zijn.Ingebouwde eigenschappen worden niet geretourneerd in de lijst met eigenschappen.
Api voor omgevingsevenementen ophalen
De API Omgevingsgebeurtenissen ophalen retourneert een lijst met onbewerkte gebeurtenissen die overeenkomen met het zoekbereik en het predicaat.
Eindpunt en bewerking:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Nettoladingsstructuur van invoer:
- Component zoekbereik (verplicht)
- Predicaatcomponent (optioneel)
- Limit-component (verplicht)
Voorbeeld van aanvraagbody:
{ "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 } }Notitie
- Geneste sortering (sorteren op twee of meer eigenschappen) wordt momenteel niet ondersteund.
- Gebeurtenissen kunnen worden gesorteerd en beperkt tot de bovenkant.
- Sorteren wordt ondersteund voor alle eigenschapstypen. Sorteren is afhankelijk van vergelijkingsoperatoren die zijn gedefinieerd voor Boole-expressies.
Voorbeeld van antwoordtekst:
{ "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] } ] }
Gestreamde API voor omgevingsgebeurtenissen ophalen
De API Gestreamde omgevingsgebeurtenissen retourneert een lijst met onbewerkte gebeurtenissen die overeenkomen met het zoekbereik en het predicaat.
Deze API maakt gebruik van het WebSocket Secure Protocol om streaming uit te voeren en gedeeltelijke resultaten te retourneren. Er worden altijd extra gebeurtenissen geretourneerd. Dat wil dat het nieuwe bericht een aanvulling is op het vorige bericht. Het nieuwe bericht bevat nieuwe gebeurtenissen die niet in het vorige bericht voorkwamen. Het vorige bericht moet worden bewaard wanneer het nieuwe bericht wordt toegevoegd.
Eindpunt en bewerking:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Nettoladingsstructuur van invoer:
- Component zoekbereik (verplicht)
- Predicaatcomponent (optioneel)
- Limit-component (verplicht)
Voorbeeld van een aanvraagbericht:
{ "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 } } }Notitie
- Geneste sortering (sorteren op twee of meer eigenschappen) wordt momenteel niet ondersteund.
- Gebeurtenissen kunnen worden gesorteerd en beperkt tot de bovenkant.
- Sorteren wordt ondersteund voor alle eigenschapstypen. Sorteren is afhankelijk van vergelijkingsoperatoren die zijn gedefinieerd voor Boole-expressies.
Voorbeeld van antwoordbericht:
{ "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 }
Api voor omgevingsaggregaties ophalen
De API Omgeving aggregeren groepeert gebeurtenissen op een opgegeven eigenschap, omdat deze optioneel de waarden van andere eigenschappen meet.
Notitie
Bucketgrenzen ondersteunen waarden van 10ⁿ, 2×10ⁿ of 5×10ⁿ om uit te lijnen met numerieke histogrammen en deze beter te ondersteunen.
Eindpunt en bewerking:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Nettoladingsstructuur van invoer:
- Component zoekbereik (verplicht)
- Predicaatcomponent (optioneel)
- Component Aggregates (verplicht)
Voorbeeld van aanvraagbody:
{ "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": {} } ] } } ] }Voorbeeld van antwoordtekst:
{ "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": [] }Als er geen metingexpressies zijn opgegeven en de lijst met gebeurtenissen leeg is, is het antwoord leeg.
Als er metingen aanwezig zijn, bevat het antwoord één record met een
nulldimensiewaarde, een0waarde voor count en eennullwaarde voor andere soorten metingen.
Gestreamde API voor omgevingsaggregaties ophalen
De get environment aggregates streamed API groepeert gebeurtenissen op een opgegeven eigenschap, omdat deze optioneel de waarden van andere eigenschappen meet:
- Deze API maakt gebruik van het WebSocket Secure Protocol voor streaming en om gedeeltelijke resultaten te retourneren.
- Er wordt altijd een vervanging (momentopname) van alle waarden geretourneerd.
- Eerdere pakketten kunnen door de client worden verwijderd.
Notitie
Bucketgrenzen ondersteunen waarden van 10ⁿ, 2×10ⁿ of 5×10ⁿ om uit te lijnen met numerieke histogrammen en deze beter te ondersteunen.
Eindpunt en bewerking:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Nettoladingsstructuur van invoer:
- Component zoekbereik (verplicht)
- Predicaatcomponent (optioneel)
- Component Aggregates (verplicht)
Voorbeeld van een aanvraagbericht:
{ "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":{} }] }] } }Voorbeeld van antwoordberichten:
{ "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 }Als er geen metingexpressies zijn opgegeven en de lijst met gebeurtenissen leeg is, is het antwoord leeg.
Als er metingen aanwezig zijn, bevat het antwoord één record met een
nulldimensiewaarde, een0waarde voor count en eennullwaarde voor andere soorten metingen.
Limieten
De volgende limieten worden toegepast tijdens het uitvoeren van query's om resources redelijk te gebruiken tussen meerdere omgevingen en gebruikers:
| Toepasselijke API's | Naam van limiet | Limietwaarde | Betrokken SKU's | Notities |
|---|---|---|---|---|
| Alles | Maximale aanvraaggrootte | 32 kB | S1, S2 | |
| Beschikbaarheid van omgeving ophalen, omgevingsmetagegevens ophalen, omgevingsgebeurtenissen ophalen, gestreamde omgevingsaggregaties ophalen | Maximum aantal gelijktijdige aanvragen per omgeving | 10 | S1, S2 | |
| Omgevingsgebeurtenissen ophalen, gestreamde omgevingsaggregaties ophalen | Maximale antwoordgrootte | 16 MB | S1, S2 | |
| Omgevingsgebeurtenissen ophalen, gestreamde omgevingsaggregaties ophalen | Maximum aantal unieke eigenschapsverwijzingen in predicaat, inclusief predicaattekenreeksexpressies | 50 | S1, S2 | |
| Omgevingsgebeurtenissen ophalen, gestreamde omgevingsaggregaties ophalen | Maximum aantal zoektermen in volledige tekst zonder verwijzing naar eigenschappen in predicaattekenreeks | 2 | S1, S2 | Voorbeeld: HAS 'abc', 'abc' |
| Omgevingsevenementen ophalen | Maximum aantal gebeurtenissen in reactie | 10.000 | S1, S2 | |
| Gestreamde omgevingsaggregaties ophalen | Maximum aantal dimensies | 5 | S1, S2 | |
| Gestreamde omgevingsaggregaties ophalen | Maximale totale kardinaliteit voor alle dimensies | 150.000 | S1, S2 | |
| Gestreamde omgevingsaggregaties ophalen | Maximum aantal metingen | 20 | S1, S2 |
Foutafhandeling en oplossing
Eigenschap niet gevonden gedrag
Voor eigenschappen waarnaar wordt verwezen in de query, als onderdeel van predicaten of als onderdeel van aggregaties (metingen), probeert de query standaard de eigenschap op te lossen in de algemene zoekopdracht bereik van de omgeving. Als de eigenschap wordt gevonden, slaagt de query. Als de eigenschap niet wordt gevonden, mislukt de query.
U kunt dit gedrag echter wijzigen om eigenschappen te behandelen als bestaande, maar met null waarden als deze niet aanwezig zijn in de omgeving. U doet dit door de optionele aanvraagheader x-ms-property-not-found-behavior in te stellen met de waarde UseNull.
Mogelijke waarden voor de aanvraagheader zijn UseNull of ThrowError (standaard). Wanneer u instelt UseNull als de waarde, slaagt de query, ook al bestaan de eigenschappen niet en bevat het antwoord waarschuwingen waarin de eigenschappen worden weergegeven die niet zijn gevonden.
Niet-opgeloste eigenschappen rapporteren
U kunt eigenschapsverwijzingen opgeven voor predicaat-, dimensie- en meetexpressies. Als een eigenschap met een specifieke naam en type niet bestaat voor een opgegeven zoekbereik, wordt geprobeerd een eigenschap op te lossen gedurende een globale periode.
Afhankelijk van het succes van de oplossing kan de volgende waarschuwing of fout worden verzonden:
- Als een eigenschap in de omgeving bestaat gedurende een globale periode, wordt deze op de juiste manier opgelost en wordt er een waarschuwing verzonden om u te laten weten dat de waarde van deze eigenschap voor een bepaald zoekbereik is
null. - Als er geen eigenschap in de omgeving bestaat, wordt er een fout gegenereerd en mislukt de uitvoering van de query.
Foutreactiess
Als de uitvoering van de query mislukt, bevat de nettolading van het JSON-antwoord een foutbericht met de volgende structuur:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
innerError Hier is optioneel. Naast basisfouten, zoals een onjuiste aanvraag, worden de volgende fouten geretourneerd:
| HTTP-statuscode | Foutcode | Voorbeeld van foutbericht | Mogelijke interne foutcodes |
|---|---|---|---|
| 400 | InvalidApiVersion | 'API-versie '2016' wordt niet ondersteund. Ondersteunde versies zijn '2016-12-12'." | |
| 400 | InvalidInput | 'Kan predicaattekenreeks niet parseren.' | PredicateStringParseError |
| 400 | InvalidInput | 'Kan predicaattekenreeks niet vertalen'. | InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | 'Meerdere aggregaties worden niet ondersteund.' | |
| 400 | InvalidInput | "Predicaateigenschap niet gevonden." | PropertyNotFound |
| 400 | InvalidInput | "Meeteigenschap niet gevonden." | PropertyNotFound |
| 400 | InvalidInput | "Dimensie-eigenschap niet gevonden." | PropertyNotFound |
| 400 | InvalidInput | "Aantal metingen heeft de limiet overschreden." | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Aggregatiediepte heeft limiet overschreden." | AggregateDepthExceededLimit |
| 400 | InvalidInput | "Totale kardinaliteit heeft de limiet overschreden." | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "Eigenschap 'van' ontbreekt." | BreaksPropertyMissing |
| 400 | InvalidInput | "Eigenschap 'aan' ontbreekt." | BreaksPropertyMissing |
| 400 | InvalidInput | "Aanvraaggrootte heeft limiet overschreden." | RequestSizeExceededLimit |
| 400 | InvalidInput | "De limiet voor antwoordgrootte is overschreden." | ResponseSizeExceededLimit |
| 400 | InvalidInput | "Het aantal gebeurtenissen heeft de limiet overschreden." | EventCountExceededLimit |
| 400 | InvalidInput | "Aantal eigenschappenreferenties heeft limiet overschreden." | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | 'Alleen WebSocket-aanvragen zijn toegestaan op het pad 'aggregates'. | |
| 400 | InvalidUrl | "De aanvraag-URL '/a/b' kan niet worden geparseerd." | |
| 408 | RequestTimeout | "Time-out van aanvraag na '30' seconde(en)." | |
| 503 | TooManyRequests | "Het aantal gelijktijdige aanvragen van '10' is overschreden voor omgeving '95880732-01b9-44ea-8d2d-4d764dfe1904'." | EnvRequestLimitExceeded |
Waarschuwingen
Een Query-API-antwoord kan een lijst met waarschuwingen bevatten als "warnings" vermelding in de hoofdmap van het HTTP-antwoord of het WebSocket-antwoordbericht. Er worden momenteel waarschuwingen gegenereerd als de eigenschap niet wordt gevonden voor een bepaald zoekbereik, maar wel in een omgeving voor een globale periode. Deze wordt ook gegenereerd wanneer de header x-ms-property-not-found-behavior is ingesteld op UseNull en een eigenschap waarnaar wordt verwezen niet bestaat, zelfs niet in de algemene zoekopdracht reeks.
Elk waarschuwingsobject kan de volgende velden bevatten:
| Veldnaam | Veldtype | Notities |
|---|---|---|
| code | Tekenreeks | Een van de vooraf gedefinieerde waarschuwingscodes |
| bericht | Tekenreeks | Een gedetailleerd waarschuwingsbericht |
| Doel | Tekenreeks | Een door puntjes gescheiden JSON-pad naar de vermelding van de JSON-invoerpayload die de waarschuwing veroorzaakt |
| warningDetails | Woordenlijst | Optionele; aanvullende waarschuwingsdetails (bijvoorbeeld de positie in predicaattekenreeks) |
De volgende code bevat voorbeelden van waarschuwingen voor predicaat, predicaattekenreeks binnen predicaat, dimensie en meting:
"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"
}
]
Zie ook
Zie Azure Active Directory voor ontwikkelaars voor meer informatie over toepassingsregistratie en het Azure Active Directory-programmeermodel.
Zie Verificatie en autorisatie voor meer informatie over aanvraag- en verificatieparameters.
Hulpprogramma's die helpen bij het testen van HTTP-aanvragen en -antwoorden zijn onder andere:
- Fiddler. Deze gratis webopsporingsproxy kan uw REST-aanvragen onderscheppen, zodat u de HTTP-aanvraag- en antwoordberichten kunt diagnosticeren.
- JWT.io. U kunt dit hulpprogramma gebruiken om snel de claims in uw Bearer-token te dumpen en vervolgens de inhoud ervan te valideren.
- Postman. Dit is een gratis hulpprogramma voor het testen van HTTP-aanvragen en -antwoorden voor het opsporen van fouten in REST API's.
Meer informatie over Azure Time Series Insights Gen1 vindt u in de Gen1-documentatie.