Azure Time Series Insights Gen1 Reference Data API

Cikk
08/05/2023

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:

Tesz
Patch
Tulajdonságok törlése
Törlés
Lekérés

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.

Azure Time Series Insights Gen1 Reference Data API

Az API áttekintése

Referenciaadat-elemek elhelyezése

Javítási referenciaadat-elemek

Referenciaadat-elemek tulajdonságainak törlése

Referenciaadat-elemek törlése

Referenciaadat-elemek lekérése

Ellenőrzés és hibakezelés

Elemhibakódok

Referenciaadat-illesztés – példa

Csatlakozási szabályok és szemantika

Jelenlegi korlátok

Lásd még

További források