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

Článek
07/19/2023

Upozornění

Toto je článek Gen1.

Tento článek popisuje referenční Správa dat rozhraní API 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 už byla v prostředí vytvořená.

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

Tip

Pokud chcete vytvořit referenční datovou sadu, přečtěte si téma Vytvoření referenční datové sady.

Vzhledem k tomu, že datové sady už existují a jsou pevné, každý datový paket odeslaný zařízením by obsahoval stejné informace. V důsledku toho se referenční data neodesílají ze zařízení a vy je spravujete pomocí rozhraní API Správa dat reference nebo Azure Portal.

Přehled rozhraní API

Referenční Správa dat API 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 definují jeden název vlastnosti, který určuje operaci, kterou má rozhraní API provést.

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

Dát
Patch
Odstranění vlastností
Odstranit
Získat

Důležité

Hodnota vlastnosti je pole položek referenčních dat, na které se musí operace použít.
Každá položka se zpracovává zvlášť a chyba u jedné položky nezabrání úspěšnému zápisu ostatních položek. Pokud například váš požadavek obsahuje 100 položek a jedna položka obsahuje chybu, zapíše se 99 položek a jedna se zamítne.
Dotazy na položky referenčních dat se dotazují pomocí jejich plně vyčíslené klíčové vlastnosti.

Poznámka

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

Vložení položek referenčních dat

Vloží nebo nahradí celou položku $.put[i] referenčních dat ( i^. položku v poli pomocí klíče put). Jednotka potvrzení je $.put[i]. Operace je idempotentní.

Koncový bod a operace:

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
  ]
}
```

Oprava položek referenčních dat

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

Koncový bod a operace:

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 položkách referenčních dat

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

Koncový bod a operace:

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
  ]
}

Odstranit položky referenčních dat

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

Koncový bod a operace:

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 vlastnosti klíče zadanými v každé $.get[i].

Koncový bod a operace:

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
    }
  ]
}

Ověřování a zpracování chyb

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

Kódy chyb položek

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

InvalidInput: Klíč se nenašel.: Označuje, že dotazovanou položku nelze najít 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 vlastnost, která není klíč.: Určuje, že položky dotazu textu požadavku JSON by neměly obsahovat žádné vlastnosti, které nejsou klíčovými vlastnostmi (tj. vlastnosti zadané ve schématu sady odkazů). Klíčové vlastnosti najdete v 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.: Určuje, že položky dotazu v textu požadavku JSON by měly obsahovat všechny klíčové vlastnosti (tj. vlastnosti, které jsou zadané ve schématu referenční sady). Klíčové vlastnosti najdete v 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"
  }
]

Představte si položku referenčních dat, která je nastavená s názvem contoso a klíčem deviceId typu String a která má následující strukturu:

deviceId	color	Maxspeed	Podlaze
Vějíř1	Red	5
Vějíř2	White		2

Když modul příchozího přenosu dat Azure Time Series Insights Gen1 zpracuje dvě události ve zprávě centra událostí, spojí se 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 připojování referenčních dat dodržujte následující omezení:

Při porovnávání názvů klíčů se rozlišují velká a malá písmena.
Při porovnávání hodnot klíčů se u vlastností řetězce rozlišují malá a velká písmena.

Pro 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 zadat svůj vlastní seznam vlastností, které nejsou klíčové.
Pro jakékoli dvě referenční datové sady A a B se vlastnosti, které nejsou klíč, nesmí protínnout.
Referenční datové sady se připojují přímo pouze k událostem, nikdy k jiným odkazovaným datovým sadám (a pak k událostem). Pokud chcete spojit položku referenčních dat s událostí, musí být v události přítomny všechny klíčové vlastnosti, které se používají v položce referenčních dat. Klíčové vlastnosti by také neměly pocházet z jiných než klíčových vlastností, které jsou připojeny k události prostřednictvím některé 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 řazení se nezohlední.

Aktuální limity

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

Název limitu	Hodnota limitu	Ovlivněné skladové položky	Poznámky
Počet vlastností klíče	3	S1, S2	Na referenční datovou sadu; Azure Resource Manager a pouze 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
Maximální počet transakcí s referenčními daty	120/600 (S1/S2)	S1, S2	Za hodinu
Maximální počet referenčních datových položek	1 000	S1, S2	Na transakci
Maximální velikost položky referenčních dat	8 192 kB	S1, S2	Na transakci

Viz také

Další informace o registraci aplikací 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ří:

Fiddleři. Tento bezplatný webový ladicí proxy server může zachycovat vaše požadavky REST, abyste mohli diagnostikovat požadavky HTTP a zprávy odpovědí.
JWT.io. Tento nástroj můžete použít k rychlému výpisu deklarací identity v nosným tokenu a následnému ověření jejich obsahu.
Postman. Toto je bezplatný nástroj pro testování požadavků HTTP a odpovědí pro ladění rozhraní REST API.

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

Sdílet prostřednictvím

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

Přehled rozhraní API

Vložení položek referenčních dat

Oprava položek referenčních dat

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

Odstranit položky referenčních dat

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

Ověřování a zpracování chyb

Kódy chyb položek

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

Pravidla spojení a sémantika

Aktuální limity

Viz také

Další materiály