Azure Time Series Insights Gen1-referensdata-API

Artikel
07/19/2023

Varning

Det här är en Gen1-artikel.

Den här artikeln beskriver Azure Time Series Insights Gen1-referens Datahantering API som används för att hantera objekt i en referensdatauppsättning. Det förutsätter att referensdatauppsättningen redan har skapats i miljön.

Referensdata innehåller tillverkare eller platsdata som ändras sällan. Referensdata används för att kontextualisera telemetridata och används för att jämföra telemetridata.

Tips

Information om hur du skapar en referensdatauppsättning finns i Så här skapar du en referensdatauppsättning.

Eftersom datauppsättningar är befintliga och fasta innehåller varje datapaket som skickas av en enhet identisk information. Därför skickas inte referensdata från enheter och du hanterar data med hjälp av API:et Referens Datahantering eller Azure Portal.

API-översikt

Api:et Reference Datahantering är ett batch-API.

Viktigt

Alla åtgärder mot det här API:et är HTTP POST-åtgärder.
Varje åtgärd accepterar JSON-objekt som nyttolast för begäran.
JSON-objekt för HTTP-begäran definierar ett enda egenskapsnamn som anger den åtgärd som ska köras av API:et.

Giltiga egenskapsnamn för JSON-begärandeåtgärden är:

Sätta
Patch
Ta bort egenskaper
Ta bort
Hämta

Viktigt

Egenskapsvärdet är en matris med referensdataobjekt som åtgärden måste tillämpas på.
Varje objekt bearbetas individuellt och ett fel med ett objekt förhindrar inte att de andra skrivs korrekt. Om din begäran till exempel har 100 objekt och ett objekt har ett fel skrivs 99 objekt och ett avvisas.
Referensdataobjekt efterfrågas med hjälp av deras fullständigt uppräknade nyckelegenskaper.

Anteckning

Alla följande JSON-brödtextexempel förutsätter en referensdatauppsättning med en enda egenskapsnyckel med namnet deviceId och typen String.

Placera referensdataobjekt

Infogar eller ersätter hela referensdataobjektet $.put[i] (det ^i:e objektet i matrisen med nyckeluppsättningen). Incheckningsenheten är $.put[i]. Åtgärden är idempotent.

Slutpunkt och åtgärd:

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

Exempel på begärandetext:

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

Svarsexempel:
```
{
  "put": [
    null,
    null
  ]
}
```

Korrigera referensdataobjekt

Uppdateringar och infogar specifika egenskaper för referensdataobjektet $.patch[i].

Slutpunkt och åtgärd:

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

Exempel på begärandetext:

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

Exempel på svarstext:

{
  "patch": [
    null,
    null
  ]
}

Ta bort egenskaper i referensdataobjekt

Tar bort de angivna egenskaperna från referensdataobjektet $.deleteproperties[i].

Slutpunkt och åtgärd:

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

Exempel på begärandetext:

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

Exempel på svarstext:

{
  "deleteProperties": [
    null
  ]
}

Ta bort referensdataobjekt

Tar bort hela referensdataobjektet som identifieras av nyckelegenskapsvärdena som anges i varje $.delete[i].

Slutpunkt och åtgärd:

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

Exempel på begärandetext:

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

Exempel på svarstext:
```
{
  "delete": [
    null
  ]
}
```

Hämta referensdataobjekt

Hämtar hela referensdataobjektet som identifieras av nyckelegenskapsvärdena som anges i varje $.get[i].

Slutpunkt och åtgärd:

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

Exempel på begärandetext:

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

Exempel på svarstext:

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

Verifiering och felhantering

Referens-Datahantering-API:et bearbetar varje objekt individuellt, och ett fel med ett objekt förhindrar inte att de andra skrivs korrekt. Om din begäran till exempel har 100 objekt och ett objekt har ett fel skrivs 99 objekt och ett avvisas.

Felkoder för objekt

Objektfelkoder inträffar i en lyckad JSON-svarstext som har HTTP-statuskoden 200.

InvalidInput: Nyckeln hittades inte.: Anger att det efterfrågade objektet inte kan hittas i referensdatauppsättningen.

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

InvalidInput: Nyttolastnyckeln får inte innehålla någon icke-nyckelegenskap.: Anger att frågeobjekt för JSON-begärandetexten inte ska innehålla några egenskaper som inte är viktiga egenskaper (dvs. egenskaper som anges i referensuppsättningsschemat). Viktiga egenskaper finns i Azure Portal.
```
{
  "code": "InvalidInput",
  "message": "Payload key should not contain any non-key property.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput: Nyttolastobjektet ska innehålla alla nyckelegenskaper.: Anger att frågeobjekt för JSON-begärandetexten ska innehålla alla nyckelegenskaper (det vill ex. egenskaper som anges i referensuppsättningsschemat). Viktiga egenskaper finns i Azure Portal.
```
{
  "code": "InvalidInput",
  "message": "Payload item should contain all key properties.",
  "target": null,
  "details": null,
  "innerError": null
}
```

Exempel på referensdataanslutning

Överväg ett händelsehubbmeddelande som har följande struktur:

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

Överväg ett referensdataobjekt som har angetts med namnet contoso och nyckeln deviceId av typen Sträng och som har följande struktur:

deviceId	color	Maxomdr	Golvet
Fan1	Red	5
Fan2	Vit		2

När de två händelserna i händelsehubben bearbetas av Azure Time Series Insights Gen1-ingressmotorn är de kopplade till rätt referensdataobjekt. Händelseutdata har följande 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
  }
]

Kopplingsregler och semantik

När du ansluter till referensdata följer du följande begränsningar:

Jämförelse av nyckelnamn är skiftlägeskänsligt.
Jämförelse av nyckelvärde är skiftlägeskänsligt för strängegenskaper.

För miljöer med mer än en referensdatauppsättning tillämpas ytterligare tre begränsningar under kopplingar:

Varje objekt i en referensdatauppsättning kan ange en egen lista över icke-nyckelegenskaper.
För två referensdatauppsättningar A och B får icke-nyckelegenskaper inte korsa varandra.
Referensdatauppsättningar kopplas direkt endast till händelser, aldrig till andra refererade datauppsättningar (och sedan till händelser). Om du vill koppla ett referensdataobjekt till en händelse måste alla nyckelegenskaper som används i referensdataobjektet finnas i händelsen. Dessutom bör nyckelegenskaperna inte komma från de icke-nyckelegenskaper som är kopplade till en händelse via något annat referensdataobjekt.

Med tanke på dessa begränsningar kan kopplingsmotorn tillämpa kopplingen i valfri ordning för en viss händelse. Hierarki och ordning beaktas inte.

Aktuella gränser

Du kan lägga till upp till två referensdatauppsättningar per Azure Time Series Insights Gen1-miljö. Ytterligare begränsningar som är associerade med Azure Time Series Insights Gen1-referensdata visas i följande tabell:

Gränsnamn	Gränsvärde	SKU:er som påverkas	Kommentarer
Antal nyckelegenskaper	3	S1, S2	Per referensdatauppsättning; Endast Azure Resource Manager och Azure Portal
Nyckelegenskapens storlek	1 kB	S1, S2	Datauppsättning per referens
Antal referensdataobjekt	2 000/20 000 (S1/S2)	S1, S2	Per enhet; till exempel 4 enhets-S1 SKU = 8 000 objekt (4 x 2 000)
Maximalt antal samtidiga transaktioner	2/10 (S1/S2)	S1, S2
Maximalt antal referensdatatransaktioner	120/600 (S1/S2)	S1, S2	Per timme
Maximalt antal referensdataobjekt	1 000	S1, S2	Per transaktion
Maximal storlek på referensdataobjekt	8 192 kB	S1, S2	Per transaktion

Se även

Mer information om programregistrering och Azure Active Directory-programmeringsmodellen finns i Azure Active Directory för utvecklare.

Mer information om parametrar för begäran och autentisering finns i Autentisering och auktorisering.

Verktyg som hjälper dig att testa HTTP-begäranden och svar är:

Fiddler. Den här kostnadsfria webbfelsökningsproxyn kan fånga upp dina REST-begäranden, så att du kan diagnostisera HTTP-begäranden och svarsmeddelanden.
JWT.io. Du kan använda det här verktyget för att snabbt dumpa anspråken i ägartoken och sedan verifiera innehållet.
Postman. Det här är ett kostnadsfritt testverktyg för HTTP-begäran och svar för felsökning av REST-API:er.

Läs mer om Azure Time Series Insights Gen1 i Gen1-dokumentationen.

Azure Time Series Insights Gen1-referensdata-API

API-översikt

Placera referensdataobjekt

Korrigera referensdataobjekt

Ta bort egenskaper i referensdataobjekt

Ta bort referensdataobjekt

Hämta referensdataobjekt

Verifiering och felhantering

Felkoder för objekt

Exempel på referensdataanslutning

Kopplingsregler och semantik

Aktuella gränser

Se även

Ytterligare resurser