interfejs API zapytań usługi Azure Time Series Insights Gen1
Przestroga
Jest to artykuł gen1.
W tym artykule opisano różne interfejsy API zapytań REST. Interfejsy API REST to punkty końcowe usługi, które obsługują zestawy operacji HTTP (metod), które umożliwiają wykonywanie zapytań w środowiskach Azure Time Series Insights Gen1.
Ważne
- Azure Time Series Insights Gen1 używa protokołu HTTPS dla środowisk pobierania, uzyskiwania dostępności środowiska, pobierania metadanych, pobierania zdarzeń środowiska i interfejsów API agregacji środowiska.
- Azure Time Series Insights Gen1 używa protokołu WebSocket Secure (WSS) dla strumieniowych zdarzeń środowiska ipobierania zagregowanych interfejsów API przesyłanych strumieniowo.
Uzyskiwanie interfejsu API środowisk
Interfejs API Get Environments zwraca listę środowisk, do których obiekt wywołujący ma uprawnienia dostępu.
Punkt końcowy i operacja:
GET https://api.timeseries.azure.com/environments?api-version=2016-12-12Przykładowa treść żądania: Nie dotyczy
Przykładowa treść odpowiedzi:
{ "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" ] } ] }Uwaga
Środowisko właściwości odpowiedziFqdn jest unikatową, w pełni kwalifikowaną nazwą domeny dla środowiska używanego w żądaniach interfejsu API zapytań dla środowiska.
Uzyskiwanie interfejsu API dostępności środowiska
Interfejs API pobierania dostępności środowiska zwraca rozkład liczby zdarzeń w $ts sygnatury czasowej zdarzenia. Dostępność środowiska jest buforowana, a czas odpowiedzi nie zależy od liczby zdarzeń w środowisku.
Porada
Interfejs API uzyskiwania dostępności środowiska może służyć do inicjowania środowiska interfejsu użytkownika frontonu.
Punkt końcowy i operacja:
GET https://<environmentFqdn>/availability?api-version=2016-12-12Przykładowa treść żądania: Nie dotyczy
Przykładowa treść odpowiedzi:
{ "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 } }Pusty obiekt jest zwracany dla środowisk bez zdarzeń.
Uzyskiwanie interfejsu API metadanych środowiska
Interfejs API pobierania metadanych środowiska zwraca metadane środowiska dla danego zakresu wyszukiwania. Metadane są zwracane jako zestaw odwołań do właściwości. Azure Time Series Insights Gen1 wewnętrznie buforuje i przybliżone metadane i może zwracać więcej właściwości, które są obecne w dokładnych zdarzeniach w zakresie wyszukiwania.
Punkt końcowy i operacja:
POST https://<environmentFqdn>/metadata?api-version=2016-12-12Struktura ładunku wejściowego:
- Klauzula search span (obowiązkowa)
Przykładowa treść żądania:
{ "searchSpan": { "from": {"dateTime":"2016-08-01T00:00:00.000Z"}, "to": {"dateTime":"2016-08-31T00:00:00.000Z"} } }Przykładowa treść odpowiedzi:
{ "properties": [ { "name": "sensorId", "type": "String" }, { "name": "sensorValue", "type": "Double" }, { "name": "iothub-connection-device-id", "type": "String" } ] }Pusta
propertiestablica jest zwracana, gdy środowisko jest puste lub nie ma żadnych zdarzeń w zakresie wyszukiwania.Właściwości wbudowane nie są zwracane na liście właściwości.
Uzyskiwanie interfejsu API zdarzeń środowiska
Interfejs API zdarzeń get environment zwraca listę nieprzetworzonych zdarzeń pasujących do zakresu wyszukiwania i predykatu.
Punkt końcowy i operacja:
POST https://<environmentFqdn>/events?api-version=<apiVersion>Struktura ładunku wejściowego:
- Klauzula search span (obowiązkowa)
- Klauzula predykatu (opcjonalnie)
- Klauzula limitu (obowiązkowa)
Przykładowa treść żądania:
{ "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 } }Uwaga
- Sortowanie zagnieżdżone (czyli sortowanie według co najmniej dwóch właściwości) nie jest obecnie obsługiwane.
- Zdarzenia można sortować i ograniczać do góry.
- Sortowanie jest obsługiwane we wszystkich typach właściwości. Sortowanie opiera się na operatorach porównania zdefiniowanych dla wyrażeń logicznych.
Przykładowa treść odpowiedzi:
{ "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] } ] }
Pobieranie strumieniowego interfejsu API zdarzeń środowiska
Interfejs API strumienia zdarzeń środowiska zwraca listę nieprzetworzonych zdarzeń pasujących do zakresu wyszukiwania i predykatu.
Ten interfejs API używa protokołu Secure Protocol protokołu WebSocket do przesyłania strumieniowego i zwracania częściowych wyników. Zawsze zwraca dodatkowe zdarzenia. Oznacza to, że nowy komunikat jest dodany do poprzedniego. Nowy komunikat zawiera nowe zdarzenia, które nie były w poprzednim komunikacie. Poprzedni komunikat powinien być zachowany po dodaniu nowego komunikatu.
Punkt końcowy i operacja:
GET wss://<environmentFqdn>/events?api-version=<apiVersion>Struktura ładunku wejściowego:
- Klauzula search span (obowiązkowa)
- Klauzula predykatu (opcjonalnie)
- Klauzula limitu (obowiązkowa)
Przykładowy komunikat żądania:
{ "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 } } }Uwaga
- Sortowanie zagnieżdżone (czyli sortowanie według co najmniej dwóch właściwości) nie jest obecnie obsługiwane.
- Zdarzenia można sortować i ograniczać do góry.
- Sortowanie jest obsługiwane we wszystkich typach właściwości. Sortowanie opiera się na operatorach porównania zdefiniowanych dla wyrażeń logicznych.
Przykładowy komunikat odpowiedzi:
{ "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 }
Uzyskiwanie interfejsu API agregacji środowiska
Interfejs API Get Environment Agreguje zdarzenia według określonej właściwości, ponieważ opcjonalnie mierzy wartości innych właściwości.
Uwaga
Granice zasobnika obsługują wartości 10ⁿ, 2×10ⁿ lub 5×10ⁿ w celu wyrównania i lepszego obsługi histogramów liczbowych.
Punkt końcowy i operacja:
POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>Struktura ładunku wejściowego:
- Klauzula search span (obowiązkowa)
- Klauzula predykatu (opcjonalnie)
- Klauzula Agregacje (obowiązkowe)
Przykładowa treść żądania:
{ "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": {} } ] } } ] }Przykładowa treść odpowiedzi:
{ "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": [] }Jeśli nie określono wyrażeń miar, a lista zdarzeń jest pusta, odpowiedź będzie pusta.
Jeśli miary są obecne, odpowiedź zawiera pojedynczy rekord z wartością
nullwymiaru,0wartością dla liczby i wartościąnullinnych rodzajów miar.
Pobieranie interfejsu API strumienia agregacji środowiska
Funkcja Get Environment Agreguje strumieniowe zdarzenia interfejsu API grupuje zdarzenia według określonej właściwości, ponieważ opcjonalnie mierzy wartości innych właściwości:
- Ten interfejs API używa protokołu Secure Protocol protokołu WebSocket do przesyłania strumieniowego i zwracania częściowych wyników.
- Zawsze zwraca ona zamianę (migawkę) wszystkich wartości.
- Poprzednie pakiety można odrzucić przez klienta.
Uwaga
Granice zasobnika obsługują wartości 10ⁿ, 2×10ⁿ lub 5×10ⁿ w celu wyrównania i lepszego obsługi histogramów liczbowych.
Punkt końcowy i operacja:
GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>Struktura ładunku wejściowego:
- Klauzula search span (obowiązkowa)
- Klauzula predykatu (opcjonalnie)
- Klauzula Agregacje (obowiązkowe)
Przykładowy komunikat żądania:
{ "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":{} }] }] } }Przykładowe komunikaty odpowiedzi:
{ "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 }Jeśli nie określono wyrażeń miar, a lista zdarzeń jest pusta, odpowiedź będzie pusta.
Jeśli miary są obecne, odpowiedź zawiera pojedynczy rekord z wartością
nullwymiaru,0wartością dla liczby i wartościąnullinnych rodzajów miar.
Limity
Podczas wykonywania zapytania są stosowane następujące limity, aby sprawiedliwie korzystać z zasobów w wielu środowiskach i użytkownikach:
| Odpowiednie interfejsy API | Nazwa limitu | Wartość limitu | Jednostki SKU, których dotyczy problem | Uwagi |
|---|---|---|---|---|
| Wszystko | Maksymalny rozmiar żądania | 32 KB | S1, S2 | |
| Uzyskiwanie dostępności środowiska, pobieranie metadanych środowiska, pobieranie zdarzeń środowiska, pobieranie zagregowanych zagregowanych środowisk | Maksymalna liczba współbieżnych żądań na środowisko | 10 | S1, S2 | |
| Pobieranie zdarzeń środowiska, pobieranie zagregowanych zagregowanych środowisk | Maksymalny rozmiar odpowiedzi | 16 MB | S1, S2 | |
| Pobieranie zdarzeń środowiska, pobieranie zagregowanych zagregowanych środowisk | Maksymalna liczba unikatowych odwołań do właściwości w predykacie, w tym wyrażeń ciągu predykatu | 50 | S1, S2 | |
| Pobieranie zdarzeń środowiska, pobieranie zagregowanych zagregowanych środowisk | Maksymalna liczba terminów wyszukiwania pełnotekstowego bez odwołania do właściwości w ciągu predykatu | 2 | S1, S2 | Przykład: HAS 'abc', 'abc' |
| Pobieranie zdarzeń środowiska | Maksymalna liczba zdarzeń w odpowiedzi | 10 000 | S1, S2 | |
| Pobieranie zagregowanych zagregowanych środowisk | Maksymalna liczba wymiarów | 5 | S1, S2 | |
| Pobieranie zagregowanych zagregowanych środowisk | Maksymalna całkowita kardynalność we wszystkich wymiarach | 150 000 | S1, S2 | |
| Pobieranie zagregowanych zagregowanych środowisk | Maksymalna liczba miar | 20 | S1, S2 |
Obsługa błędów i ich rozwiązywanie
Zachowanie nieznajdowania właściwości
W przypadku właściwości, do których odwołuje się zapytanie, jako część predykatów lub części agregacji (miar), domyślnie zapytanie próbuje rozpoznać właściwość w wyszukiwanie globalne zakresie środowiska. Jeśli właściwość zostanie znaleziona, zapytanie zakończy się pomyślnie. Jeśli właściwość nie zostanie znaleziona, zapytanie zakończy się niepowodzeniem.
Można jednak zmodyfikować to zachowanie, aby traktować właściwości jako istniejące, ale z wartościami null , jeśli nie są obecne w środowisku. W tym celu należy ustawić opcjonalny nagłówek x-ms-property-not-found-behavior żądania z wartością UseNull.
Możliwe wartości nagłówka żądania to UseNull lub ThrowError (wartość domyślna). Jeśli ustawisz UseNull wartość jako wartość, zapytanie zakończy się pomyślnie, mimo że właściwości nie istnieją, a odpowiedź będzie zawierać ostrzeżenia, które wyświetlają nieznajdujące się właściwości.
Zgłaszanie nierozwiązanych właściwości
Można określić odwołania do właściwości dla wyrażeń predykatu, wymiaru i miary. Jeśli właściwość o określonej nazwie i typie nie istnieje dla określonego zakresu wyszukiwania, zostanie podjęta próba rozpoznania właściwości w globalnym przedziale czasu.
W zależności od powodzenia rozwiązania może być emitowane następujące ostrzeżenie lub błąd:
- Jeśli właściwość istnieje w środowisku w globalnym przedziale czasu, zostanie ona odpowiednio rozwiązana i zostanie wyświetlone ostrzeżenie informujące o tym, że wartość tej właściwości dotyczy
nulldanego zakresu wyszukiwania. - Jeśli właściwość nie istnieje w środowisku, jest emitowany błąd i wykonywanie zapytania kończy się niepowodzeniem.
Odpowiedzi na błędy
Jeśli wykonanie zapytania zakończy się niepowodzeniem, ładunek odpowiedzi JSON zawiera odpowiedź o błędzie z następującą strukturą:
{
"error" : {
"code" : "...",
"message" : "...",
"innerError" : {
"code" : "...",
"message" : "...",
}
}
}
innerError W tym miejscu jest to opcjonalne. Oprócz podstawowych błędów, takich jak źle sformułowane żądanie, zwracane są następujące błędy:
| Kod stanu HTTP | Kod błędu | Przykład komunikatu o błędzie | Możliwe kody błędów wewnętrznych |
|---|---|---|---|
| 400 | InvalidApiVersion | "Wersja interfejsu API "2016" nie jest obsługiwana. Obsługiwane wersje to "2016-12-12". | |
| 400 | InvalidInput | "Nie można przeanalizować ciągu predykatu." | PredicateStringParseError |
| 400 | InvalidInput | "Nie można przetłumaczyć ciągu predykatu". |
InvalidTypes, LimitExceeded, MissingOperand, InvalidPropertyType, InvalidLiteral, PropertyNotFound |
| 400 | InvalidInput | "Wiele agregacji nie jest obsługiwanych". | |
| 400 | InvalidInput | "Nie znaleziono właściwości predykatu". | PropertyNotFound |
| 400 | InvalidInput | "Nie znaleziono właściwości miary". | PropertyNotFound |
| 400 | InvalidInput | "Nie znaleziono właściwości wymiaru". | PropertyNotFound |
| 400 | InvalidInput | "Liczba miar przekroczyła limit". | NumberOfMeasuresExceededLimit |
| 400 | InvalidInput | "Przekroczono limit głębokości agregacji". | AggregateDepthExceededLimit |
| 400 | InvalidInput | "Przekroczono limit kardynalności całkowitej". | TotalCardinalityExceededLimit |
| 400 | InvalidInput | "Brak właściwości 'from'". | BreaksPropertyMissing |
| 400 | InvalidInput | "Brak właściwości "to". | BreaksPropertyMissing |
| 400 | InvalidInput | "Przekroczono limit rozmiaru żądania". | RequestSizeExceededLimit |
| 400 | InvalidInput | "Przekroczono limit rozmiaru odpowiedzi". | ResponseSizeExceededLimit |
| 400 | InvalidInput | "Przekroczono limit liczby zdarzeń". | EventCountExceededLimit |
| 400 | InvalidInput | "Przekroczono limit liczby odwołań do właściwości". | PropertyReferenceCountExceededLimit |
| 400 | InvalidMethod | "Tylko żądania protokołu WebSocket są dozwolone w ścieżce "agregacje". | |
| 400 | InvalidUrl | "Nie można przeanalizować adresu URL żądania "/a/b". | |
| 408 | RequestTimeout | "Upłynął limit czasu żądania po 30 sekundach"." | |
| 503 | TooManyRequests | "Liczba żądań współbieżnych "10" została przekroczona dla środowiska "95880732-01b9-44ea-8d2d-4d764dfe1904". | EnvRequestLimitExceeded |
Ostrzeżenia
Odpowiedź interfejsu API zapytań może zawierać listę ostrzeżeń jako "warnings" wpis w katalogu głównym odpowiedzi HTTP lub komunikatu odpowiedzi protokołu WebSocket. Obecnie ostrzeżenia są generowane, jeśli właściwość nie zostanie znaleziona dla danego zakresu wyszukiwania, ale znajduje się w środowisku dla globalnego przedziału czasu. Jest on również generowany, gdy nagłówek x-ms-property-not-found-behavior jest ustawiony na UseNull i właściwość, do którego odwołuje się odwołanie, nie istnieje nawet w zakresie wyszukiwanie globalne.
Każdy obiekt ostrzegawczy może zawierać następujące pola:
| Nazwa pola | Typ pola | Uwagi |
|---|---|---|
| kod | Ciąg | Jeden ze wstępnie zdefiniowanych kodów ostrzeżeń |
| message | Ciąg | Szczegółowy komunikat ostrzegawczy |
| Docelowego | Ciąg | Ścieżka JSON rozdzielona kropką do wpisu ładunku wejściowego JSON powodująca ostrzeżenie |
| warningDetails | Słownik | Opcjonalne; dodatkowe szczegóły ostrzeżenia (na przykład pozycja w ciągu predykatu) |
Poniższy kod przedstawia przykłady ostrzeżeń dotyczących predykatu, ciągu predykatu w predykacie, wymiarze i mierze:
"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"
}
]
Zobacz też
Aby uzyskać więcej informacji na temat rejestracji aplikacji i modelu programowania usługi Azure Active Directory, zobacz Azure Active Directory dla deweloperów.
Aby dowiedzieć się więcej o parametrach żądania i uwierzytelniania, zobacz Uwierzytelnianie i autoryzacja.
Narzędzia, które ułatwiają testowanie żądań i odpowiedzi HTTP, obejmują:
- Fiddler. Ten bezpłatny internetowy serwer proxy debugowania może przechwytywać żądania REST, dzięki czemu można zdiagnozować żądania HTTP i komunikaty odpowiedzi.
- JWT.io. Za pomocą tego narzędzia można szybko zrzucić oświadczenia w tokenie elementu nośnego, a następnie zweryfikować ich zawartość.
- Postman. Jest to bezpłatne narzędzie do testowania żądań HTTP i odpowiedzi na potrzeby debugowania interfejsów API REST.
Dowiedz się więcej o usłudze Azure Time Series Insights Gen1, przeglądając dokumentację usługi Gen1.