API för Azure Time Series Insights Gen1-referensdata

I den här artikeln beskrivs Azure Time Series Insights Gen1 API för hantering av referensdata 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 omfattar tillverkar- eller platsdata som ändras sällan. Referensdata används för att kontextualisera telemetridata och används för att jämföra telemetridata.

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

API-översikt

API:et för hantering av referensdata är ett batch-API.

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

• Ställa
• Patch
• Ta bort egenskaper
• Ta bort
• Hämta

Placera referensdataobjekt

Infogar eller ersätter hela referensdataobjektet $.put[i] (det i^:te objektet i matrisen med nyckeln placera). Enheten för incheckning ä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
    ]
  }
  

Referensdataobjekt för korrigering

Uppdaterar 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 de nyckelegenskapsvärden 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 de nyckelegenskapsvärden 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
      }
    ]
  }
  

Validering och felhantering

API:et för hantering av referensdata bearbetar varje objekt individuellt, och ett fel med ett objekt hindrar inte de andra från att skrivas. 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 uppstår 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 får innehålla några egenskaper som inte är nyckelegenskaper (d.v.s. 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 säga 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å koppling av referensdata

Ö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 String och som har följande struktur:

När de två händelserna i händelsehubbmeddelandet bearbetas av Azure Time Series Insights Gen1-ingressmotorn ansluts de 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 kopplar referensdata ska du följa 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 endast direkt 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. Nyckelegenskaperna bör inte heller 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:

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:

• Spelman. Den här kostnadsfria webbfelsökningsproxyn kan fånga upp dina REST-begäranden, så att du kan diagnostisera HTTP-begäran och svarsmeddelanden.
• JWT.io. Du kan använda det här verktyget för att snabbt dumpa anspråken i din ägartoken och sedan verifiera deras innehåll.
• Brevbärare. 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.