Azure Time Series Insights Gen1 Reference Data API
Figyelemfelhívás
Ez egy Gen1-cikk.
Ez a cikk az 1. generációs Azure Time Series Insights referencia-adatkezelés API-t ismerteti, amely egy referenciaadatkészlet elemeinek kezelésére szolgál. Feltételezi, hogy a referenciaadatkészlet már létrejött a környezetben.
A referenciaadatok közé tartoznak a ritkán változó gyártó- vagy helyadatok. A referenciaadatok a telemetriai adatok környezetfüggőségére szolgálnak, és a telemetriai adatok összehasonlítására szolgálnak.
Tipp
- Referenciaadatkészlet létrehozásához lásd: Referenciaadatkészlet létrehozása.
Mivel az adathalmazok már léteznek és javítva vannak, az eszköz által küldött adatcsomagok azonos információkat tartalmaznak. Következésképpen a rendszer nem küld referenciaadatokat az eszközökről, és a Referencia adatkezelés API vagy a Azure Portal használatával kezeli az adatokat.
Az API áttekintése
A Referencia adatkezelés API egy batch API.
Fontos
- Az API-val végzett összes művelet HTTP POST-műveletek.
- Minden művelet fogadja el a JSON-objektumokat a kérelem hasznos adataként.
- A HTTP-request JSON-objektumok egyetlen tulajdonságnevet határoznak meg, amely meghatározza az API által végrehajtandó műveletet.
A JSON-kérelemművelet érvényes tulajdonságnevei a következők:
Fontos
- A tulajdonságérték olyan referenciaadat-elemek tömbje, amelyre a műveletet alkalmazni kell.
- A rendszer minden elemet egyenként dolgoz fel, és az egyik elemet tartalmazó hiba nem akadályozza meg a többi elem sikeres írását. Ha például a kérés 100 elemet tartalmaz, és egy elem hibát jelez, a rendszer 99 elemet ír, egyet pedig elutasít.
- A referenciaadat-elemek lekérdezhetők a teljes számbavételű kulcstulajdonságokkal.
Megjegyzés
Az alábbi JSON-példatörzsek mindegyike feltételezi, hogy egy referenciaadatkészlet egy deviceId nevű tulajdonságkulcsot tartalmaz, és írja be a Sztring kifejezést.
Referenciaadat-elemek elhelyezése
Beszúrja vagy lecseréli a teljes referenciaadat-elemet $.put[i]
(a tömb i. elemét a kulccsal). A véglegesítési egység az $.put[i].
Idempotens művelet.
Végpont és művelet:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
Példa kérelemtörzsre:
{ "put": [{ "deviceId": "Fan1", "color": "Red", "maxSpeed": 5 }, { "deviceId": "Fan2", "color": "White", "floor": 2 }] }
Példa a válaszra:
{ "put": [ null, null ] }
Javítási referenciaadat-elemek
Frissítések és beszúrja a referenciaadat-elem $.patch[i]
adott tulajdonságait.
Végpont és művelet:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
Példa kérelemtörzsre:
{ "patch": [ { "deviceId": "Fan1", "maxSpeed": 108 }, { "deviceId": "Fan2", "floor": 18 } ] }
Példa választörzsre:
{ "patch": [ null, null ] }
Referenciaadat-elemek tulajdonságainak törlése
Törli a megadott tulajdonságokat a referenciaadatelemből $.deleteproperties[i]
.
Végpont és művelet:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
Példa kérelemtörzsre:
{ "deleteProperties":[ { "key":{ "deviceId":"Fan2" }, "properties":[ "floor" ] } ] }
Példa választörzsre:
{ "deleteProperties": [ null ] }
Referenciaadat-elemek törlése
Törli az egyes $.delete[i]
kulcstulajdonságok által azonosított teljes referenciaadat-elemet.
Végpont és művelet:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
Példa kérelemtörzsre:
{ "delete": [{ "deviceId": "Fan1" }] }
Példa választörzsre:
{ "delete": [ null ] }
Referenciaadat-elemek lekérése
Lekéri az egyes $.get[i]
kulcstulajdonságok által azonosított teljes referenciaadat-elemet.
Végpont és művelet:
POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
Példa kérelemtörzsre:
{ "get": [{ "deviceId": "Fan1" }, { "deviceId": "Fan2" }] }
Példa választörzsre:
{ "get": [ { "code": "InvalidInput", "message": "Key not found.", "target": null, "details": null, "innerError": null }, { "id": "Fan2", "floor": 18 } ] }
Ellenőrzés és hibakezelés
A Referencia adatkezelés API egyenként dolgozza fel az egyes elemeket, és az egyik elem hibája nem akadályozza meg a többi elem sikeres írását. Ha például a kérés 100 elemet tartalmaz, és egy elem hibát jelez, a rendszer 99 elemet ír, egyet pedig elutasít.
Elemhibakódok
Az elemhibakódok egy sikeres JSON-választörzsben fordulnak elő, amely a 200-ás HTTP-állapotkóddal rendelkezik.
InvalidInput: A kulcs nem található.: Azt jelzi, hogy a lekérdezett elem nem található a referenciaadatkészletben.
{ "code": "InvalidInput", "message": "Key not found.", "target": null, "details": null, "innerError": null }
InvalidInput: A hasznos adatkulcs nem tartalmazhat kulcs nélküli tulajdonságot.: Azt jelzi, hogy a JSON-kérelem törzsének lekérdezési elemei nem tartalmazhatnak olyan tulajdonságokat, amelyek nem kulcstulajdonságok (azaz a referenciakészlet sémájában megadott tulajdonságok). A kulcstulajdonságok a Azure Portal találhatók.
{ "code": "InvalidInput", "message": "Payload key should not contain any non-key property.", "target": null, "details": null, "innerError": null }
InvalidInput: A hasznos adatelemnek tartalmaznia kell az összes kulcstulajdonságt.: Azt jelzi, hogy a JSON-kérelem törzsének lekérdezési elemeinek tartalmazniuk kell az összes kulcstulajdonságt (azaz a referenciakészlet sémájában megadott tulajdonságokat). A kulcstulajdonságok Azure Portal találhatók.
{ "code": "InvalidInput", "message": "Payload item should contain all key properties.", "target": null, "details": null, "innerError": null }
Referenciaadat-illesztés – példa
Fontolja meg a következő struktúrával rendelkező eseményközpont-üzenet létrehozását:
[
{
"deviceId":"Fan1",
"timestamp":"1/5/2015T00:10:30Z"
},
{
"deviceId":"Fan2",
"timestamp":"1/5/2015T00:10:30Z"
}
]
Fontolja meg egy olyan referenciaadat-elemet, amely a Sztring típusú névvel contoso
és kulcseszköz-azonosítóval van beállítva, és amelynek struktúrája a következő:
deviceId | szín | Maxspeed | Padló |
---|---|---|---|
Ventilátor1 | Piros | 5 | |
Ventilátor2 | Fehér | 2 |
Amikor az eseményközpont üzenetében szereplő két eseményt Azure Time Series Insights Gen1 bemeneti motor dolgozza fel, a rendszer a megfelelő referenciaadat-elemhez csatlakozik. Az események kimenete a következő struktúrával rendelkezik:
[
{
"deviceId":"Fan1",
"timestamp":"1/5/2015T00:10:30Z",
"color":"Red",
"maxSpeed":5
},
{
"deviceId":"Fan2",
"timestamp":"1/5/2015T00:10:30Z",
"color":"White",
"floor":2
}
]
Csatlakozási szabályok és szemantika
Referenciaadatok összekapcsolásakor tartsa be az alábbi korlátozásokat:
- A kulcsnevek összehasonlítása megkülönbözteti a kis- és nagybetűk megkülönböztetettségét.
- A kulcsértékek összehasonlítása megkülönbözteti a sztringtulajdonságok kis- és nagybetűinek megkülönböztetett értékeit.
Egynél több referenciaadatkészlettel rendelkező környezetek esetén a rendszer három további korlátozást kényszerít ki az illesztések során:
- A referenciaadatkészlet minden eleme megadhatja a nem kulcstulajdonságok saját listáját.
- Az A és a B referenciaadatkészletek esetében a nem kulcstulajdonságok nem metszenek.
- A referenciaadatkészletek közvetlenül csak az eseményekhez vannak csatlakoztatva, soha nem más hivatkozott adathalmazokhoz (majd eseményekhez). Ha egy referenciaadat-elemet egy eseményhez szeretne csatlakoztatni, a referenciaadat-elemben használt összes kulcstulajdonságnak szerepelnie kell az eseményben. Emellett a kulcstulajdonságok nem származnak az eseményhez más referenciaadat-elemen keresztül csatlakoztatott nem kulcstulajdonságokból.
Ezekre a korlátozásokra tekintettel az illesztési motor bármilyen sorrendben alkalmazhatja az illesztéseket egy adott eseményre. A hierarchia és a rendezés nem számít.
Jelenlegi korlátok
Gen1-környezet Azure Time Series Insights enként legfeljebb két referenciaadatkészletet adhat hozzá. A Azure Time Series Insights Gen1 referenciaadatokhoz kapcsolódó további korlátozások az alábbi táblázatban találhatók:
Korlát neve | Korlátérték | Érintett termékváltozatok | Jegyzetek |
---|---|---|---|
Kulcstulajdonságok száma | 3 | S1, S2 | Referenciaadatkészletenként; Azure Resource Manager és csak az Azure Portal |
Kulcstulajdonság mérete | 1 KB | S1, S2 | Referenciaadatkészletenként |
Referenciaadat-elemek száma | 2 000/20 000 (S1/S2) | S1, S2 | Egységnyi; például 4 egység S1 termékváltozat = 8000 elem (4 x 2000) |
Egyidejű tranzakciók maximális kihasználása | 2/10 (S1/S2) | S1, S2 | |
Referencia-adattranzakciók maximális kihasználása | 120/600 (S1/S2) | S1, S2 | Óránként |
Referenciaadatok maximális száma | 1,000 | S1, S2 | Tranzakciónként |
Referenciaadat-elem maximális mérete | 8,192 KB | S1, S2 | Tranzakciónként |
Lásd még
További információ az alkalmazásregisztrációról és az Azure Active Directory programozási modellről: Azure Active Directory fejlesztőknek.
A kérelem- és hitelesítési paraméterekkel kapcsolatos további információkért lásd: Hitelesítés és engedélyezés.
A HTTP-kérések és -válaszok tesztelését segítő eszközök a következők:
- Fiddler. Ez az ingyenes webes hibakeresési proxy elfoghatja a REST-kéréseket, így diagnosztizálhatja a HTTP-kéréseket és a válaszüzeneteket.
- JWT.io. Ezzel az eszközzel gyorsan lerakhatja a jogcímeket a tulajdonosi jogkivonatban, majd ellenőrizheti azok tartalmát.
- Postás. Ez egy ingyenes HTTP-kérés- és választesztelési eszköz a REST API-k hibakereséséhez.
Az 1. generációs Azure Time Series Insights a Gen1 dokumentációjának áttekintésével talál további információt.