interfejs API danych referencyjnych usługi Azure Time Series Insights Gen1

Artykuł
08/05/2023

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:

Umieścić
Patch
Usuń właściwości
Usuwanie
Get

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.

Udostępnij za pośrednictwem

interfejs API danych referencyjnych usługi Azure Time Series Insights Gen1

Przegląd interfejsu API

Umieszczanie elementów danych referencyjnych

Elementy danych referencyjnych poprawek

Usuwanie właściwości w elementach danych referencyjnych

Usuwanie elementów danych referencyjnych

Pobieranie elementów danych referencyjnych

Walidacja i obsługa błędów

Kody błędów elementu

Przykład dołączania danych referencyjnych

Dołączanie reguł i semantyki

Bieżące limity

Zobacz też

Dodatkowe zasoby