Azure Time Series Insights Gen1-referentiegegevens-API

Artikel
08/05/2023

Waarschuwing

Dit is een Gen1-artikel.

In dit artikel wordt de Azure Time Series Insights Gen1 Reference Gegevensbeheer API beschreven die wordt gebruikt voor het beheren van items in een referentiegegevensset. Hierbij wordt ervan uitgegaan dat de referentiegegevensset al in de omgeving is gemaakt.

Referentiegegevens omvatten fabrikant- of locatiegegevens die niet vaak worden gewijzigd. Referentiegegevens worden gebruikt om telemetriegegevens te contextualiseren en dienen om telemetriegegevens te vergelijken.

Tip

Zie Een referentiegegevensset maken voor informatie over het maken van een referentiegegevensset.

Omdat gegevenssets al bestaan en vaststaan, zou elk gegevenspakket dat door een apparaat wordt verzonden, identieke informatie bevatten. Daarom worden referentiegegevens niet verzonden vanaf apparaten en beheert u de gegevens met behulp van de Verwijzings-Gegevensbeheer-API of de Azure Portal.

API-overzicht

De Reference Gegevensbeheer-API is een batch-API.

Belangrijk

Alle bewerkingen met deze API zijn HTTP POST-bewerkingen.
Elke bewerking accepteert JSON-objecten als de nettolading van de aanvraag.
JSON-objecten met HTTP-aanvragen definiëren één eigenschapsnaam die de bewerking aangeeft die door de API moet worden uitgevoerd.

Geldige JSON-aanvraagbewerkingseigenschapsnamen zijn:

Zet
Patch
Eigenschappen verwijderen
Verwijderen
Ophalen

Belangrijk

De eigenschapswaarde is een matrix van referentiegegevensitems waarop de bewerking moet worden toegepast.
Elk item wordt afzonderlijk verwerkt en een fout met het ene item verhindert niet dat de andere items correct worden geschreven. Als uw aanvraag bijvoorbeeld 100 items bevat en één item een fout heeft, worden er 99 items geschreven en één item geweigerd.
Referentiegegevensitems worden opgevraagd met behulp van hun volledig opgesomde sleuteleigenschappen.

Notitie

In alle volgende voorbeelden van de JSON-hoofdtekst wordt uitgegaan van een referentiegegevensset met één eigenschapssleutel met de naam deviceId en het type String.

Referentiegegevensitems plaatsen

Hiermee wordt het hele verwijzingsgegevensitem $.put[i] ingevoegd of vervangen (het i^th item in de matrix door de toets put). De eenheid van doorvoer is $.put[i]. De bewerking is idempotent.

Eindpunt en bewerking:

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

Voorbeeld van aanvraagbody:

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

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

Patchreferentiegegevensitems

Updates en voegt specifieke eigenschappen in voor het referentiegegevensitem $.patch[i].

Eindpunt en bewerking:

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

Voorbeeld van aanvraagbody:

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

Voorbeeld van antwoordtekst:

{
  "patch": [
    null,
    null
  ]
}

Eigenschappen in verwijzingsgegevensitems verwijderen

Hiermee verwijdert u de opgegeven eigenschappen uit het verwijzingsgegevensitem $.deleteproperties[i].

Eindpunt en bewerking:

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

Voorbeeld van aanvraagbody:

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

Voorbeeld van antwoordtekst:

{
  "deleteProperties": [
    null
  ]
}

Verwijzingsgegevensitems verwijderen

Hiermee verwijdert u het volledige referentiegegevensitem dat wordt geïdentificeerd door de sleuteleigenschapswaarden die zijn opgegeven in elke $.delete[i].

Eindpunt en bewerking:

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

Voorbeeld van aanvraagbody:

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

Voorbeeld van antwoordtekst:
```
{
  "delete": [
    null
  ]
}
```

Referentiegegevensitems ophalen

Hiermee haalt u het volledige referentiegegevensitem op dat wordt geïdentificeerd door de sleuteleigenschapswaarden die zijn opgegeven in elke $.get[i].

Eindpunt en bewerking:

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

Voorbeeld van aanvraagbody:

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

Voorbeeld van antwoordtekst:

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

Validatie en foutafhandeling

De Api voor verwijzing Gegevensbeheer verwerkt elk item afzonderlijk en een fout met het ene item verhindert niet dat de andere items met succes worden geschreven. Als uw aanvraag bijvoorbeeld 100 items bevat en één item een fout heeft, worden er 99 items geschreven en één item geweigerd.

Foutcodes voor items

Itemfoutcodes treden op in een geslaagde JSON-antwoordtekst met de HTTP-statuscode 200.

InvalidInput: Sleutel niet gevonden.: geeft aan dat het opgevraagde item niet kan worden gevonden in de referentiegegevensset.
```
{
  "code": "InvalidInput",
  "message": "Key not found.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput: Payload-sleutel mag geen niet-sleuteleigenschap bevatten.: geeft aan dat queryitems van de JSON-aanvraagbody geen eigenschappen mogen bevatten die geen sleuteleigenschappen zijn (dat wil dus eigenschappen die zijn opgegeven in het schema van de referentieset). Sleuteleigenschappen vindt u in de Azure Portal.
```
{
  "code": "InvalidInput",
  "message": "Payload key should not contain any non-key property.",
  "target": null,
  "details": null,
  "innerError": null
}
```
InvalidInput: Payload-item moet alle sleuteleigenschappen bevatten.: geeft aan dat query-items van de JSON-aanvraagbody alle sleuteleigenschappen moeten bevatten (dat wil gezegd eigenschappen die zijn opgegeven in het schema van de referentieset). Sleuteleigenschappen vindt u in Azure Portal.
```
{
  "code": "InvalidInput",
  "message": "Payload item should contain all key properties.",
  "target": null,
  "details": null,
  "innerError": null
}
```

Voorbeeld van referentiegegevenskoppeling

Overweeg een Event Hub-bericht met de volgende structuur:

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

Overweeg een verwijzingsgegevensitem dat is ingesteld met de naam contoso en sleutel deviceId van het type String en dat de volgende structuur heeft:

deviceId	color	maxSpeed	Verdieping
Ventilator1	Red	5
Ventilator2	Wit		2

Wanneer de twee gebeurtenissen in het Event Hub-bericht worden verwerkt door Azure Time Series Insights Gen1-ingangsengine, worden ze gekoppeld aan het juiste referentiegegevensitem. De gebeurtenisuitvoer heeft de volgende structuur:

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"Red",
    "maxSpeed":5
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"White",
    "floor":2
  }
]

Regels en semantiek voor samenvoegen

Wanneer u referentiegegevens samenvoegt, moet u voldoen aan de volgende beperkingen:

Vergelijking van sleutelnamen is hoofdlettergevoelig.
Sleutelwaardevergelijking is hoofdlettergevoelig voor tekenreekseigenschappen.

Voor omgevingen met meer dan één referentiegegevensset worden drie andere beperkingen afgedwongen tijdens joins:

Elk item in een referentiegegevensset kan een eigen lijst met niet-sleuteleigenschappen opgeven.
Voor twee referentiegegevenssets A en B mogen niet-sleuteleigenschappen elkaar niet snijden.
Referentiegegevenssets worden alleen rechtstreeks aan gebeurtenissen gekoppeld, nooit aan andere gegevenssets waarnaar wordt verwezen (en vervolgens aan gebeurtenissen). Als u een verwijzingsgegevensitem wilt toevoegen aan een gebeurtenis, moeten alle sleuteleigenschappen die worden gebruikt in het verwijzingsgegevensitem aanwezig zijn in de gebeurtenis. De sleuteleigenschappen mogen ook niet afkomstig zijn van de niet-sleuteleigenschappen die via een ander verwijzingsgegevensitem aan een gebeurtenis zijn gekoppeld.

Gezien deze beperkingen kan de join-engine de join in elke volgorde toepassen voor een bepaalde gebeurtenis. Hiërarchie en volgorde worden niet in aanmerking genomen.

Huidige limieten

U kunt maximaal twee referentiegegevenssets per Azure Time Series Insights Gen1-omgeving toevoegen. Aanvullende beperkingen die zijn gekoppeld aan Azure Time Series Insights Gen1-referentiegegevens worden weergegeven in de volgende tabel:

Naam van limiet	Limietwaarde	Betrokken SKU's	Notities
Aantal sleuteleigenschappen	3	S1, S2	Per referentiegegevensset; Alleen Azure Resource Manager en de Azure Portal
Grootte van sleuteleigenschap	1 kB	S1, S2	Per referentiegegevensset
Aantal referentiegegevensitems	2.000/20.000 (S1/S2)	S1, S2	Per eenheid; bijvoorbeeld: 4 eenheid S1 SKU = 8.000 items (4 x 2.000)
Maximum aantal gelijktijdige transacties	2/10 (S1/S2)	S1, S2
Maximum aantal referentiegegevenstransacties	120/600 (S1/S2)	S1, S2	Per uur
Maximumaantal referentiegegevensitems	1000	S1, S2	Per transactie
Maximale grootte van verwijzingsgegevensitems	8.192 KB	S1, S2	Per transactie

Zie ook

Zie Azure Active Directory voor ontwikkelaars voor meer informatie over toepassingsregistratie en het Azure Active Directory-programmeermodel.

Zie Verificatie en autorisatie voor meer informatie over aanvraag - en verificatieparameters.

Hulpprogramma's die helpen bij het testen van HTTP-aanvragen en -antwoorden zijn onder andere:

Fiddler. Met deze gratis webopsporingsproxy kunt u uw REST-aanvragen onderscheppen, zodat u de HTTP-aanvraag- en antwoordberichten kunt diagnosticeren.
JWT.io. U kunt dit hulpprogramma gebruiken om snel de claims in uw Bearer-token te dumpen en vervolgens de inhoud ervan te valideren.
Postman. Dit is een gratis hulpprogramma voor het testen van HTTP-aanvragen en -antwoorden voor het opsporen van fouten in REST API's.

Meer informatie over Azure Time Series Insights Gen1 vindt u in de Gen1-documentatie.

Delen via

Azure Time Series Insights Gen1-referentiegegevens-API

API-overzicht

Referentiegegevensitems plaatsen

Patchreferentiegegevensitems

Eigenschappen in verwijzingsgegevensitems verwijderen

Verwijzingsgegevensitems verwijderen

Referentiegegevensitems ophalen

Validatie en foutafhandeling

Foutcodes voor items

Voorbeeld van referentiegegevenskoppeling

Regels en semantiek voor samenvoegen

Huidige limieten

Zie ook

Aanvullende resources