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

W tym artykule opisano interfejs API zarządzania danymi referencyjnymi usługi Azure Time Series Insights Gen1, który służy do zarządzania elementami w zestawie danych referencyjnych. Przyjęto założenie, że referencyjny zestaw danych został już utworzony w środowisku.

Dane referencyjne obejmują dane producenta lub lokalizacji, które rzadko się zmieniają. Dane referencyjne służą do kontekstualizacji danych telemetrycznych i służą do porównywania danych telemetrycznych.

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ń, a danymi można zarządzać przy użyciu interfejsu API zarządzania danymi referencyjnymi lub Azure Portal.

Przegląd interfejsu API

Interfejs API zarządzania danymi referencyjnymi jest interfejsem API wsadowym.

Prawidłowe nazwy właściwości operacji żądania JSON to:

• Kłaść
• Aktualizacja
• Usuwanie właściwości
• Delete
• Pobierz

Umieszczanie elementów danych referencyjnych

Wstawia lub zamienia cały element $.put[i] danych referencyjnych (^i-ty element w tablicy z kluczem put). Jednostką commita jest $.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

Aktualizuje i wstawia określone właściwości elementu danych $.patch[i]odniesienia.

• 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 odniesienia.

• 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, który jest identyfikowany przez wartości właściwości klucza określone w każdym $.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, który jest identyfikowany przez wartości właściwości klucza określone w każdym $.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ądzania danymi referencyjnymi przetwarza każdy element indywidualnie, a błąd z jednym elementem nie uniemożliwia pomyślnego zapisania pozostałych. Na przykład, jeśli żądanie zawiera 100 elementów, a jeden element zawiera błąd, 99 elementów jest zapisywanych i jeden jest odrzucany.

Kody błędów przedmiotów

Kody błędów elementów 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 zapytania w zestawie danych referencyjnych.

  {
    "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 zapytania 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ściami określonymi w schemacie zestawu odwołań). Kluczowe właściwości 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ń). Kluczowe właściwości można znaleźć w Azure Portal.

  {
    "code": "InvalidInput",
    "message": "Payload item should contain all key properties.",
    "target": null,
    "details": null,
    "innerError": null
  }
  

Przykład sprzężenia danych referencyjnych

Rozważmy 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żmy element danych referencyjnych, który jest ustawiony z nazwą contoso i kluczem deviceId typu String i który ma następującą strukturę:

Gdy dwa zdarzenia w komunikacie centrum zdarzeń są przetwarzane przez aparat ruchu przychodzącego Azure Time Series Insights Gen1, są one sprzężone 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
  }
]

Reguły i semantyka sprzężenia

Podczas łączenia danych referencyjnych należy przestrzegać następujących ograniczeń:

• W porównaniu nazw kluczy rozróżniana jest wielkość liter.
• W porównaniu wartości klucza jest rozróżniana wielkość liter w przypadku właściwości ciągu.

W przypadku środowisk z więcej niż jednym zestawem danych referencyjnych podczas sprzężeń są wymuszane trzy dodatkowe ograniczenia:

• Każdy element w zestawie danych referencyjnych może określać własną listę właściwości niebędących kluczami.
• W przypadku dowolnych dwóch zestawów danych referencyjnych A i B właściwości niebędące kluczem nie mogą się przecinać.
• Zestawy danych odwołań są sprzężone bezpośrednio tylko ze zdarzeniami, nigdy z innymi przywoływanymi zestawami danych (a następnie ze zdarzeniami). Aby połączyć element danych referencyjnych ze zdarzeniem, wszystkie kluczowe właściwości, które są 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ż klucze, które są sprzężone ze zdarzeniem za pomocą innego elementu danych referencyjnych.

Biorąc pod uwagę te ograniczenia, silnik sprzężenia może zastosować sprzężenie w dowolnej kolejności dla danego zdarzenia. Hierarchia i kolejność nie są brane pod uwagę.

Bieżące limity

Możesz dodać maksymalnie dwa zestawy danych referencyjnych na środowisko Azure Time Series Insights Gen1. Dodatkowe ograniczenia związane z danymi referencyjnymi usługi Azure Time Series Insights Gen1 są wymienione w poniższej tabeli:

Zobacz także

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ą:

• Skrzypek. Ten bezpłatny serwer proxy do debugowania sieci Web może przechwytywać żądania REST, dzięki czemu można zdiagnozować komunikaty żądań i odpowiedzi HTTP.
• JWT.io. Za pomocą tego narzędzia można szybko zrzucić oświadczenia w tokenie okaziciela, a następnie zweryfikować ich zawartość.
• Listonosz. Jest to bezpłatne narzędzie do testowania żądań i odpowiedzi HTTP do debugowania interfejsów API REST.

Dowiedz się więcej o usłudze Azure Time Series Insights Gen1, przeglądając dokumentację Gen1.