Rozhraní API referenčních dat Azure Time Series Insights Gen1

Upozornění

Toto je článek Gen1.

Tento článek popisuje rozhraní API pro správu referenčních dat Azure Time Series Insights Gen1, které se používá ke správě položek v referenční datové sadě. Předpokládá, že referenční datová sada již byla vytvořena v prostředí.

Referenční údaje zahrnují údaje o výrobci nebo poloze, které se mění zřídka. Referenční data se používají ke kontextualizaci telemetrických dat a slouží k porovnání telemetrických dat.

Tip

Chcete-li vytvořit referenční datovou sadu, přečtěte si téma Jak vytvořit referenční datovou sadu.

Vzhledem k tomu, že datové sady existují již dříve a jsou pevné, každý datový paket odeslaný zařízením by obsahoval identické informace. V důsledku toho se referenční data neodesílají ze zařízení a data spravujete pomocí rozhraní API pro správu referenčních dat nebo webu Azure Portal.

Přehled rozhraní API

Rozhraní API pro správu referenčních dat je dávkové rozhraní API.

Důležité

Všechny operace s tímto rozhraním API jsou operace HTTP POST.
Každá operace přijímá objekty JSON jako datovou část požadavku.
Objekty JSON požadavku HTTP-request definují jeden název vlastnosti, který určuje operaci, která má být provedena rozhraním API.

Platné názvy vlastností operace požadavku JSON jsou:

Dát
Patch
Odstranit vlastnosti
Vymazat
Získat

Důležité

Hodnota vlastnosti je pole položek referenčních dat, na které musí být operace použita.
Každá položka je zpracována samostatně a chyba u jedné položky nezabrání úspěšnému zápisu ostatních. Pokud má například váš požadavek 100 položek a jedna položka obsahuje chybu, zapíše se 99 položek a jedna se zamítne.
Položky referenčních dat jsou dotazovány pomocí jejich plně vyjmenovaných klíčových vlastností.

Poznámka:

Všechny následující příklady těla JSON předpokládají referenční datovou sadu s jedním klíčem vlastnosti s názvem deviceId a typem String.

Vložte položky referenčních dat

Vloží nebo nahradí celou položku $.put[i] referenčních dat (^i-tou položku v poli s vložením klíče). Jednotkou commit je $.put[i]. Operace je idempotentní.

Koncové body a provoz:

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Příklad textu požadavku:

{
  "put": [{
    "deviceId": "Fan1",
    "color": "Red",
    "maxSpeed": 5
  },
  {
    "deviceId": "Fan2",
    "color": "White",
    "floor": 2
  }]
}

Příklad odpovědi:
```
{
  "put": [
    null,
    null
  ]
}
```

Datové položky odkazu na opravu

Aktualizuje a vloží specifické vlastnosti pro položku $.patch[i]referenčních dat.

Koncové body a provoz:

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Příklad textu požadavku:

{
  "patch": [
    {
      "deviceId": "Fan1",
      "maxSpeed": 108
    },
    {
      "deviceId": "Fan2",
      "floor": 18
    }
  ]
}

Příklad textu odpovědi:

{
  "patch": [
    null,
    null
  ]
}

Odstranění vlastností v referenčních datových položkách

Odstraní zadané vlastnosti z položky $.deleteproperties[i]referenčních dat.

Koncové body a provoz:

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Příklad textu požadavku:

{
  "deleteProperties":[
    {
      "key":{
        "deviceId":"Fan2"
      },
      "properties":[
        "floor"
      ]
    }
  ]
}

Příklad textu odpovědi:

{
  "deleteProperties": [
    null
  ]
}

Odstranění položek referenčních dat

Odstraní celou položku referenčních dat, která je identifikována hodnotami vlastností klíče zadanými v každém $.delete[i]souboru .

Koncové body a provoz:

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Příklad textu požadavku:

{
  "delete": [{
    "deviceId": "Fan1"
  }]
}

Příklad textu odpovědi:
```
{
  "delete": [
    null
  ]
}
```

Získání položek referenčních dat

Získá celou položku referenčních dat, která je identifikována hodnotami vlastností klíče zadanými v každém z nich $.get[i].

Koncové body a provoz:

POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12

Příklad textu požadavku:

{
  "get": [{
    "deviceId": "Fan1"
  },
  {
    "deviceId": "Fan2"
  }]
}

Příklad textu odpovědi:

{
  "get": [
    {
      "code": "InvalidInput",
      "message": "Key not found.",
      "target": null,
      "details": null,
      "innerError": null
    },
    {
      "id": "Fan2",
      "floor": 18
    }
  ]
}

Validace a zpracování chyb

Rozhraní API pro správu referenčních dat zpracovává každou položku jednotlivě a chyba u jedné položky nezabrání úspěšnému zápisu ostatních. Pokud má například váš požadavek 100 položek a jedna položka obsahuje chybu, zapíše se 99 položek a jedna se zamítne.

Kódy chyb položky

Kódy chyb položek se vyskytují v těle úspěšné odpovědi JSON, která má stavový kód HTTP 200.

InvalidInput: Klíč nebyl nalezen.: Označuje, že dotazovaná položka nebyla nalezena v referenční datové sadě.

{
  "code": "InvalidInput",
  "message": "Key not found.",
  "target": null,
  "details": null,
  "innerError": null
}

InvalidInput: Klíč datové části by neměl obsahovat žádnou jinou než klíčovou vlastnost.: Označuje, že položky dotazu na text požadavku JSON by neměly obsahovat žádné vlastnosti, které nejsou klíčovými vlastnostmi (tj. vlastnostmi, které jsou určeny ve schématu referenční sady). Klíčové vlastnosti najdete na webu Azure Portal.
```
{
  "code": "InvalidInput",
  "message": "Payload key should not contain any non-key property.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput: Položka datové části by měla obsahovat všechny klíčové vlastnosti.: Označuje, že položky dotazu na text požadavku JSON by měly obsahovat všechny klíčové vlastnosti (tj. vlastnosti, které jsou specifikovány ve schématu referenční sady). Klíčové vlastnosti najdete na webu Azure Portal.
```
{
  "code": "InvalidInput",
  "message": "Payload item should contain all key properties.",
  "target": null,
  "details": null,
  "innerError": null
}
```

Příklad spojení referenčních dat

Představte si zprávu centra událostí, která má následující strukturu:

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z"
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z"
  }
]

Vezměte v úvahu položku referenčních dat, která je nastavena pomocí názvu contoso a klíče deviceId typu String a která má následující strukturu:

identifikátor zařízení	barva	maximální rychlost	podlaha
Ventilátor1	Červený	5
Ventilátor2	Bílý		2

Když jsou dvě události ve zprávě centra událostí zpracovány modulem příchozího přenosu dat Azure Time Series Insights Gen1, jsou spojeny se správnou položkou referenčních dat. Výstup událostí má následující strukturu:

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"Red",
    "maxSpeed":5
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"White",
    "floor":2
  }
]

Pravidla spojení a sémantika

Při spojování referenčních dat dodržujte následující omezení:

Porovnávání názvů klíčů rozlišuje velká a malá písmena.
Porovnání hodnot klíče rozlišuje velká a malá písmena u vlastností řetězce.

U prostředí s více než jednou referenční datovou sadou se během spojení vynucují tři další omezení:

Každá položka v referenční datové sadě může určovat svůj vlastní seznam neklíčových vlastností.
U jakýchkoli dvou referenčních datových sad A a B se nesmí protínat neklíčové vlastnosti.
Referenční datové sady jsou přímo připojeny pouze k událostem, nikdy k jiným odkazovaným datovým sadám (a poté k událostem). Chcete-li připojit položku referenčních dat k události, musí být v události přítomny všechny klíčové vlastnosti, které jsou použity v položce referenčních dat. Klíčové vlastnosti by také neměly pocházet z neklíčových vlastností, které jsou připojeny k události prostřednictvím jiné položky referenčních dat.

Vzhledem k těmto omezením může modul spojení použít spojení v libovolném pořadí pro danou událost. Hierarchie a uspořádání nejsou brány v úvahu.

Aktuální limity

Do každého prostředí Azure Time Series Insights Gen1 můžete přidat až dvě referenční datové sady. Další omezení spojená s referenčními daty Azure Time Series Insights Gen1 jsou uvedená v následující tabulce:

Název limitu	Hodnota limitu	Ovlivněné SKU	Poznámky
Počet vlastností klíčů	3	S1, S2	Na referenční datovou sadu; Pouze Azure Resource Manager a Azure Portal
Velikost vlastnosti klíče	1 kB	S1, S2	Na referenční datovou sadu
Počet položek referenčních dat	2 000/20 000 (S1/S2)	S1, S2	Na jednotku; například 4 jednotky S1 SKU = 8 000 položek (4 x 2 000)
Maximální počet souběžných transakcí	2/10 (S1/S2)	S1, S2
Max. počet transakcí s referenčními daty	120/600 (S1/S2)	S1, S2	Za hodinu
Maximální počet položek referenčních dat	1 000	S1, S2	Za transakci
Maximální velikost položky referenčních dat	8 192 KB	S1, S2	Za transakci

Viz také

Další informace o registraci aplikace a programovacím modelu Azure Active Directory najdete v tématu Azure Active Directory pro vývojáře.

Další informace o parametrech požadavků a ověřování najdete v tématu Ověřování a autorizace.

Mezi nástroje, které pomáhají s testováním požadavků a odpovědí HTTP, patří:

Šumař. Tento bezplatný proxy server pro ladění webu dokáže zachytit vaše požadavky REST, takže můžete diagnostikovat zprávy požadavků a odpovědí HTTP.
JWT.io. Tento nástroj můžete použít k rychlému výpisu deklarací identity ve vašem nosném tokenu a následnému ověření jejich obsahu.
Pošťák. Jedná se o bezplatný nástroj pro testování požadavků a odpovědí HTTP pro ladění rozhraní REST API.

Další informace o Azure Time Series Insights Gen1 najdete v dokumentaci ke Gen1.

Last updated on 2025-08-12

Sdílet prostřednictvím

Rozhraní API referenčních dat Azure Time Series Insights Gen1

Přehled rozhraní API

Vložte položky referenčních dat

Datové položky odkazu na opravu

Odstranění vlastností v referenčních datových položkách

Odstranění položek referenčních dat

Získání položek referenčních dat

Validace a zpracování chyb

Kódy chyb položky

Příklad spojení referenčních dat

Pravidla spojení a sémantika

Aktuální limity

Viz také

Další materiály