Azure Time Series Insights Gen1 Reference Data-API

Waarschuwing

Dit is een Gen1-artikel.

In dit artikel wordt de Azure Time Series Insights Gen1 Reference Data Management-API beschreven die wordt gebruikt voor het beheren van items in een referentiegegevensset. Er wordt van uitgegaan dat de referentiedataset 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.

Aanbeveling

Omdat gegevenssets al bestaan en vast liggen, bevat elk gegevenspakket dat door een apparaat wordt verzonden identieke informatie. Referentiegegevens worden dus niet verzonden vanaf apparaten en u beheert de gegevens met behulp van de Reference Data Management-API of de Azure Portal.

API-overzicht

De API voor het beheer van referentiegegevens is een batch-API.

Belangrijk

  • Alle bewerkingen op deze API zijn HTTP POST-bewerkingen.
  • Bij elke bewerking worden JSON-objecten geaccepteerd als de nettolading van de aanvraag.
  • HTTP-request JSON-objecten definiëren een enkele eigenschapsnaam die de bewerking aangeeft die door de API moet worden uitgevoerd.

De namen van geldige JSON-bewerkingen zijn:

Belangrijk

  • De eigenschapswaarde is een matrix met verwijzingsgegevensitems waarop de bewerking moet worden toegepast.
  • Elk item wordt afzonderlijk verwerkt en een fout bij het ene item voorkomt niet dat de andere items met succes worden geschreven. Als uw aanvraag bijvoorbeeld 100 artikelen bevat en één artikel een fout bevat, worden 99 artikelen geschreven en wordt één artikel afgewezen.
  • Referentiegegevensitems worden opgevraagd met behulp van hun volledig opgesomde sleuteleigenschappen.

Opmerking

Alle volgende JSON-bodyvoorbeelden gaan uit van een referentiegegevensset met één eigenschapssleutel met de naam deviceId en het type String.

Items met referentiegegevens plaatsen

Voegt het volledige referentiegegevensitem $.put[i] in of vervangt het (het i-de item in de array met de sleutel). De eenheid van commit is $.put[i]. De operatie is idempotent.

  • Eindpunt en werking:

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

  • Voorbeeld van een aanvraagbody:

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

  • Antwoordvoorbeeld:

    {
  "put": [
    null,
    null
  ]
}

Gegevensitems voor patchreferentie

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

  • Eindpunt en werking:

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

  • Voorbeeld van een aanvraagbody:

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

  • Voorbeeld van antwoordtekst:

    {
  "patch": [
    null,
    null
  ]
}

Eigenschappen in verwijzingsgegevensitems verwijderen

Verwijdert de opgegeven eigenschappen uit het item met referentiegegevens.$.deleteproperties[i]

  • Eindpunt en werking:

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

  • Voorbeeld van een aanvraagbody:

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

  • Voorbeeld van antwoordtekst:

    {
  "deleteProperties": [
    null
  ]
}

Items met referentiegegevens verwijderen

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

  • Eindpunt en werking:

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

  • Voorbeeld van een aanvraagbody:

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

  • Voorbeeld van antwoordtekst:

    {
  "delete": [
    null
  ]
}

Referentiegegevensitems ophalen

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

  • Eindpunt en werking:

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

  • Voorbeeld van een 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 het beheer van referentiegegevens verwerkt elk item afzonderlijk en een fout met het ene item voorkomt niet dat de andere items worden geschreven. Als uw aanvraag bijvoorbeeld 100 artikelen bevat en één artikel een fout bevat, worden 99 artikelen geschreven en wordt één artikel afgewezen.

Foutcodes van artikelen

Artikelfoutcodes 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 JSON-query-items voor aanvraagbody's geen eigenschappen mogen bevatten die geen sleuteleigenschappen zijn (dat wil zeggen eigenschappen die zijn opgegeven in het schema van de verwijzingsset). De belangrijkste eigenschappen zijn te vinden 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 JSON-query-items voor de hoofdtekst van JSON-aanvragen alle sleuteleigenschappen moeten bevatten (dat wil zeggen eigenschappen die zijn opgegeven in het schema van de referentieset). De belangrijkste eigenschappen zijn te vinden in Azure Portal.

    {
  "code": "InvalidInput",
  "message": "Payload item should contain all key properties.",
  "target": null,
  "details": null,
  "innerError": null
}

Voorbeeld van deelname aan referentiegegevens

Beschouw een Event Hub-bericht met de volgende structuur:

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

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

apparaat-ID Kleur maximale snelheid floor
Ventilator 1 Rood 5
Ventilator 2 Wit 2

Wanneer de twee gebeurtenissen in het Event Hub-bericht worden verwerkt door Azure Time Series Insights Gen1 ingress engine, worden ze samengevoegd met het juiste referentiegegevensitem. De uitvoer van gebeurtenissen 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
  }
]

Doe mee met regels en semantiek

Wanneer u referentiegegevens samenvoegt, moet u zich aan de volgende beperkingen houden:

  • Vergelijking van sleutelnamen is hoofdlettergevoelig.
  • De vergelijking van de sleutelwaarden is hoofdlettergevoelig voor tekenreekseigenschappen.

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

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

Gegeven deze beperkingen, kan de join-engine de join in willekeurige volgorde toepassen voor een bepaalde gebeurtenis. Hiërarchie en ordening worden niet in aanmerking genomen.

Huidige limieten

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

Naam beperken Limietwaarde Betrokken SKU's Opmerkingen
Aantal belangrijke eigendommen 3 S1, S2 Per referentie dataset; Alleen Azure Resource Manager en de Azure Portal
Grootte van de belangrijkste eigenschap 1 kB S1, S2 Per referentie dataset
Aantal items met referentiegegevens 2.000/20.000 (S1/S2) S1, S2 Per stuk; bijvoorbeeld 4 eenheid S1 SKU = 8.000 artikelen (4 x 2.000)
Max gelijktijdige transacties 2/10 (S1/S2) S1, S2
Max. transacties met referentiegegevens 120/600 (S1/S2) S1, S2 Per uur
Max. aantal items met referentiegegevens 1,000 S1, S2 Per transactie
Maximale grootte van het referentiegegevensitem 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.

Tools die helpen bij het testen van HTTP-verzoeken en -antwoorden zijn onder andere:

  • Vioolspeler. Deze gratis proxy voor webfoutopsporing kan uw REST-verzoeken onderscheppen, zodat u de HTTP-verzoeken en antwoordberichten kunt diagnosticeren.
  • JWT.io. U kunt deze tool gebruiken om de claims snel in uw bearer token te dumpen en vervolgens de inhoud ervan te valideren.
  • Postbode. Dit is een gratis tool voor het testen van HTTP-verzoeken en -antwoorden voor het debuggen van REST API's.

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

  • Last updated on