interfejs API danych referencyjnych usługi Azure Time Series Insights Gen1
Przestroga
Jest to artykuł gen1.
W tym artykule opisano interfejs API Zarządzanie danymi Azure Time Series Insights Gen1, który służy do zarządzania elementami w zestawie danych referencyjnych. Przyjęto założenie, że zestaw danych referencyjnych został już utworzony w środowisku.
Dane referencyjne obejmują dane producenta lub lokalizacji, które zmieniają się rzadko. Dane referencyjne służą do kontekstualizowania danych telemetrycznych i służą do porównywania danych telemetrycznych.
Porada
- Aby utworzyć zestaw danych referencyjnych, zobacz Jak utworzyć zestaw danych referencyjnych.
Ponieważ zestawy danych są wstępnie istniejące i stałe, każdy pakiet danych wysyłany przez urządzenie będzie zawierać identyczne informacje. W związku z tym dane referencyjne nie są wysyłane z urządzeń i zarządzasz danymi przy użyciu interfejsu API Zarządzanie danymi odwołania lub Azure Portal.
Przegląd interfejsu API
Interfejs API Zarządzanie danymi odwołania to interfejs API wsadowy.
Ważne
- Wszystkie operacje na tym interfejsie API to operacje HTTP POST.
- Każda operacja akceptuje obiekty JSON jako ładunek żądania.
- Obiekty JSON żądania HTTP definiują pojedynczą nazwę właściwości, która określa operację do wykonania przez interfejs API.
Prawidłowe nazwy właściwości operacji żądania JSON to:
Ważne
- Wartość właściwości to tablica elementów danych referencyjnych, nad którymi należy zastosować operację.
- Każdy element jest przetwarzany indywidualnie, a błąd z jednym elementem nie uniemożliwia pomyślnego zapisania innych elementów. Jeśli na przykład żądanie zawiera 100 elementów, a jeden element zawiera błąd, 99 elementów jest zapisywanych i jeden jest odrzucany.
- Elementy danych referencyjnych są odpytywane przy użyciu ich w pełni wyliczonych właściwości klucza.
Uwaga
Wszystkie poniższe przykłady treści JSON zakładają zestaw danych referencyjnych z pojedynczym kluczem właściwości o nazwie deviceId i wpisz Ciąg.
Umieszczanie elementów danych referencyjnych
Wstawia lub zastępuje cały element $.put[i]
danych referencyjnych (element i w tablicy umieścić klucz). Jednostka zatwierdzenia to $.put[i].
Operacja jest idempotentna.
Punkt końcowy i operacja:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
Przykład treści żądania:
{ "put": [{ "deviceId": "Fan1", "color": "Red", "maxSpeed": 5 }, { "deviceId": "Fan2", "color": "White", "floor": 2 }] }
Przykładowa odpowiedź:
{ "put": [ null, null ] }
Elementy danych referencyjnych poprawek
Aktualizacje i wstawia określone właściwości elementu danych $.patch[i]
referencyjnych .
Punkt końcowy i operacja:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
Przykład treści żądania:
{ "patch": [ { "deviceId": "Fan1", "maxSpeed": 108 }, { "deviceId": "Fan2", "floor": 18 } ] }
Przykład treści odpowiedzi:
{ "patch": [ null, null ] }
Usuwanie właściwości w elementach danych referencyjnych
Usuwa określone właściwości z elementu $.deleteproperties[i]
danych referencyjnych .
Punkt końcowy i operacja:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
Przykład treści żądania:
{ "deleteProperties":[ { "key":{ "deviceId":"Fan2" }, "properties":[ "floor" ] } ] }
Przykład treści odpowiedzi:
{ "deleteProperties": [ null ] }
Usuwanie elementów danych referencyjnych
Usuwa cały element danych referencyjnych identyfikowany przez wartości właściwości klucza określone w każdym elemencie $.delete[i]
.
Punkt końcowy i operacja:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
Przykład treści żądania:
{ "delete": [{ "deviceId": "Fan1" }] }
Przykład treści odpowiedzi:
{ "delete": [ null ] }
Pobieranie elementów danych referencyjnych
Pobiera cały element danych referencyjnych identyfikowany przez wartości właściwości klucza określone w każdym elemencie $.get[i]
.
Punkt końcowy i operacja:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
Przykład treści żądania:
{ "get": [{ "deviceId": "Fan1" }, { "deviceId": "Fan2" }] }
Przykład treści odpowiedzi:
{ "get": [ { "code": "InvalidInput", "message": "Key not found.", "target": null, "details": null, "innerError": null }, { "id": "Fan2", "floor": 18 } ] }
Walidacja i obsługa błędów
Interfejs API Zarządzanie danymi odwołania przetwarza poszczególne elementy indywidualnie, a błąd z jednym elementem nie uniemożliwia pomyślnego zapisania innych elementów. Jeśli na przykład żądanie zawiera 100 elementów, a jeden element zawiera błąd, 99 elementów jest zapisywanych i jeden jest odrzucany.
Kody błędów elementu
Kody błędów elementu występują w pomyślnej treści odpowiedzi JSON, która ma kod stanu HTTP 200.
InvalidInput: Nie znaleziono klucza.: wskazuje, że nie można odnaleźć elementu zapytanego w zestawie danych referencyjnym.
{ "code": "InvalidInput", "message": "Key not found.", "target": null, "details": null, "innerError": null }
InvalidInput: Klucz ładunku nie powinien zawierać żadnej właściwości innej niż klucz.: Wskazuje, że elementy kwerendy treści żądania JSON nie powinny zawierać żadnych właściwości, które nie są właściwościami klucza (czyli właściwości określone w schemacie zestawu odwołań). Właściwości klucza można znaleźć w Azure Portal.
{ "code": "InvalidInput", "message": "Payload key should not contain any non-key property.", "target": null, "details": null, "innerError": null }
InvalidInput: Element ładunku powinien zawierać wszystkie właściwości klucza.: Wskazuje, że elementy zapytania treści żądania JSON powinny zawierać wszystkie właściwości klucza (czyli właściwości określone w schemacie zestawu odwołań). Właściwości klucza można znaleźć w Azure Portal.
{ "code": "InvalidInput", "message": "Payload item should contain all key properties.", "target": null, "details": null, "innerError": null }
Przykład dołączania danych referencyjnych
Rozważ komunikat centrum zdarzeń, który ma następującą strukturę:
[
{
"deviceId":"Fan1",
"timestamp":"1/5/2015T00:10:30Z"
},
{
"deviceId":"Fan2",
"timestamp":"1/5/2015T00:10:30Z"
}
]
Rozważ element danych referencyjnych ustawiony z nazwą contoso
i kluczem deviceId typu String, który ma następującą strukturę:
deviceId | color | Maxspeed | Podłogi |
---|---|---|---|
Wentylator1 | Red (Czerwony) | 5 | |
Wentylator2 | Biały | 2 |
Gdy dwa zdarzenia w komunikacie centrum zdarzeń są przetwarzane przez aparat ruchu przychodzącego Azure Time Series Insights Gen1, są one połączone z poprawnym elementem danych referencyjnych. Dane wyjściowe zdarzeń mają następującą strukturę:
[
{
"deviceId":"Fan1",
"timestamp":"1/5/2015T00:10:30Z",
"color":"Red",
"maxSpeed":5
},
{
"deviceId":"Fan2",
"timestamp":"1/5/2015T00:10:30Z",
"color":"White",
"floor":2
}
]
Dołączanie reguł i semantyki
Podczas dołączania do danych referencyjnych należy przestrzegać następujących ograniczeń:
- Porównanie nazw kluczy jest uwzględniane w wielkości liter.
- Porównanie wartości klucza jest uwzględniane w przypadku właściwości ciągu.
W przypadku środowisk z więcej niż jednym zestawem danych referencyjnych trzy dalsze ograniczenia są wymuszane podczas sprzężeń:
- Każdy element w zestawie danych referencyjnych może określać własną listę właściwości innych niż klucz.
- W przypadku dwóch zestawów danych referencyjnych A i B właściwości inne niż kluczowe nie mogą przecinać się.
- Zestawy danych referencyjnych są dołączane bezpośrednio tylko do zdarzeń, nigdy nie do innych zestawów danych, do których odwołuje się odwołanie (a następnie do zdarzeń). Aby dołączyć element danych referencyjnych do zdarzenia, wszystkie kluczowe właściwości używane w elemencie danych referencyjnych muszą być obecne w zdarzeniu. Ponadto właściwości klucza nie powinny pochodzić z właściwości innych niż klucz, które są przyłączone do zdarzenia za pośrednictwem innego elementu danych referencyjnych.
Biorąc pod uwagę te ograniczenia, aparat sprzężenia może zastosować sprzężenia w dowolnej kolejności dla danego zdarzenia. Hierarchia i kolejność nie są brane pod uwagę.
Bieżące limity
W środowisku Azure Time Series Insights Gen1 można dodać maksymalnie dwa zestawy danych referencyjnych. Dodatkowe ograniczenia skojarzone z danymi referencyjnymi Azure Time Series Insights Gen1 są wymienione w poniższej tabeli:
Nazwa limitu | Wartość limitu | Jednostki SKU, których dotyczy problem | Uwagi |
---|---|---|---|
Liczba właściwości klucza | 3 | S1, S2 | Na zestaw danych referencyjnych; Usługa Azure Resource Manager i tylko Azure Portal |
Rozmiar właściwości klucza | 1 KB | S1, S2 | Na zestaw danych referencyjnych |
Liczba elementów danych referencyjnych | 2000/20 000 (S1/S2) | S1, S2 | Na jednostkę; na przykład 4 jednostka SKU S1 = 8000 elementów (4 x 2000) |
Maksymalna liczba współbieżnych transakcji | 2/10 (S1/S2) | S1, S2 | |
Maksymalna liczba transakcji danych referencyjnych | 120/600 (S1/S2) | S1, S2 | Godzinę |
Maksymalna liczba elementów danych referencyjnych | 1000 | S1, S2 | Na transakcję |
Maksymalny rozmiar elementu danych referencyjnych | 8192 KB | S1, S2 | Na transakcję |
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 pomagają w testowaniu żą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 Azure Time Series Insights Gen1, przeglądając dokumentację usługi Gen1.