Freigeben über

Azure Time Series Insights Gen1-Referenzdaten-API

  • Artikel

Achtung

Dies ist ein Artikel zu Azure Time Series Insights Gen1.

In diesem Artikel wird die Azure Time Series Insights Gen1-Referenz-Datenverwaltung-API beschrieben, die zum Verwalten von Elementen in einem Verweisdataset verwendet wird. Es wird davon ausgegangen, dass das Verweisdataset bereits innerhalb der Umgebung erstellt wurde.

Referenzdaten umfassen Hersteller- oder Standortdaten, die sich selten ändern. Referenzdaten werden zum Kontextieren von Telemetriedaten verwendet und dienen zum Vergleichen von Telemetriedaten.

Tipp

Da Datasets bereits vorhanden und behoben sind, enthält jedes Datenpaket, das von einem Gerät gesendet wird, identische Informationen. Daher werden Verweisdaten nicht von Geräten gesendet, und Sie verwalten die Daten mithilfe der Referenz-Datenverwaltung-API oder der Azure-Portal.

API-Übersicht

Die Referenz-Datenverwaltung-API ist eine Batch-API.

Wichtig

  • Alle Vorgänge für diese API sind HTTP POST-Vorgänge.
  • Jeder Vorgang akzeptiert JSON-Objekte als Anforderungsnutzlast.
  • JSON-Objekte mit HTTP-Anforderung definieren einen einzelnen Eigenschaftsnamen, der den von der API auszuführenden Vorgang angibt.

Gültige Eigenschaftennamen des JSON-Anforderungsvorgangs sind:

Wichtig

  • Der -Eigenschaftswert ist ein Array von Verweisdatenelementen, auf die der Vorgang angewendet werden muss.
  • Jedes Element wird einzeln verarbeitet, und ein Fehler mit einem Element verhindert nicht, dass die anderen elemente erfolgreich geschrieben werden. Wenn Ihre Anforderung beispielsweise 100 Elemente enthält und ein Element einen Fehler aufweist, werden 99 Elemente geschrieben, und eines wird abgelehnt.
  • Verweisdatenelemente werden mithilfe ihrer vollständig aufgezählten Schlüsseleigenschaften abgefragt.

Hinweis

Alle folgenden JSON-Textbeispiele setzen ein Verweisdataset mit einem einzelnen Eigenschaftsschlüssel mit dem Namen deviceId und dem Typ String voraus.

Platzieren von Verweisdatenelementen

Fügt das gesamte Verweisdatenelement $.put[i] (das ite Element im Array durch den Key Put) ein oder ersetzt es. Die Commiteinheit ist $.put[i]. Der Vorgang ist idempotent.

  • Endpunkt und Vorgang:

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

  • Beispiel für Anforderungstext:

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

  • Beispielantwort:

    {
  "put": [
    null,
    null
  ]
}

Patchen von Verweisdatenelementen

Updates und fügt bestimmte Eigenschaften für das Verweisdatenelement ein$.patch[i].

  • Endpunkt und Vorgang:

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

  • Beispiel für Anforderungstext:

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

  • Beispiel für einen Antworttext:

    {
  "patch": [
    null,
    null
  ]
}

Löschen von Eigenschaften in Verweisdatenelementen

Löscht die angegebenen Eigenschaften aus dem Verweisdatenelement $.deleteproperties[i].

  • Endpunkt und Vorgang:

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

  • Beispiel für Anforderungstext:

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

  • Beispiel für einen Antworttext:

    {
  "deleteProperties": [
    null
  ]
}

Löschen von Verweisdatenelementen

Löscht das gesamte Verweisdatenelement, das durch die in den einzelnen $.delete[i]angegebenen Schlüsseleigenschaftswerte identifiziert wird.

  • Endpunkt und Vorgang:

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

  • Beispiel für Anforderungstext:

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

  • Beispiel für einen Antworttext:

    {
  "delete": [
    null
  ]
}

Abrufen von Verweisdatenelementen

Ruft das gesamte Verweisdatenelement ab, das durch die in den einzelnen $.get[i]angegebenen Schlüsseleigenschaftswerte identifiziert wird.

  • Endpunkt und Vorgang:

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

  • Beispiel für Anforderungstext:

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

  • Beispiel für einen Antworttext:

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

Validierung und Fehlerbehandlung

Die Referenz-Datenverwaltung-API verarbeitet jedes Element einzeln, und ein Fehler mit einem Element verhindert nicht, dass die anderen Elemente erfolgreich geschrieben werden. Wenn Ihre Anforderung beispielsweise 100 Elemente enthält und ein Element einen Fehler aufweist, werden 99 Elemente geschrieben, und eines wird abgelehnt.

Elementfehlercodes

Elementfehlercodes treten in einem erfolgreichen JSON-Antworttext auf, der den HTTP-status Code 200 aufweist.

  • InvalidInput: Key not found.: Gibt an, dass das abgefragte Element nicht im Verweisdataset gefunden werden kann.

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

  • InvalidInput: Payload key should not contain any non-key property.: Gibt an, dass JSON-Anforderungstextabfrageelemente keine Eigenschaften enthalten dürfen, die keine Schlüsseleigenschaften sind (d. h. Eigenschaften, die im Verweissatzschema angegeben sind). Wichtige Eigenschaften finden Sie im Azure-Portal.

    {
  "code": "InvalidInput",
  "message": "Payload key should not contain any non-key property.",
  "target": null,
  "details": null,
  "innerError": null
}

  • InvalidInput: Das Nutzlastelement sollte alle Schlüsseleigenschaften enthalten.: Gibt an, dass JSON-Anforderungstextabfrageelemente alle Schlüsseleigenschaften enthalten sollen (d. h. Eigenschaften, die im Referenzsatzschema angegeben sind). Wichtige Eigenschaften finden Sie in Azure-Portal.

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

Beispiel für Verweisdatenjoin

Betrachten Sie eine Event Hub-Nachricht mit der folgenden Struktur:

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

Betrachten Sie ein Verweisdatenelement, das mit dem Namen contoso und dem Schlüssel deviceId des Typs String festgelegt ist und über die folgende Struktur verfügt:

deviceId color maxSpeed floor
Fan1 Red 5
Fan2 White 2

Wenn die beiden Ereignisse in der Event Hub-Nachricht von Azure Time Series Insights Gen1-Eingangsmodul verarbeitet werden, werden sie mit dem richtigen Verweisdatenelement verknüpft. Die Ereignisausgabe hat die folgende 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
  }
]

Joinregeln und Semantik

Beachten Sie beim Verknüpfen von Verweisdaten die folgenden Einschränkungen:

  • Beim Schlüsselnamenvergleich wird die Groß-/Kleinschreibung beachtet.
  • Beim Schlüsselwertvergleich wird bei Zeichenfolgeneigenschaften zwischen Groß-/Kleinschreibung unterschieden.

Für Umgebungen mit mehr als einem Verweisdataset werden während joins drei weitere Einschränkungen erzwungen:

  • Jedes Element in einem Verweisdataset kann eine eigene Liste von Nicht-Schlüsseleigenschaften angeben.
  • Für zwei beliebige Referenzdatasets A und B dürfen sich nicht schlüsselfremde Eigenschaften nicht überschneiden.
  • Verweisdatasets werden nur direkt mit Ereignissen verknüpft, niemals mit anderen Datasets, auf die verwiesen wird (und dann mit Ereignissen). Um ein Verweisdatenelement mit einem Ereignis zu verbinden, müssen alle wichtigen Eigenschaften, die im Verweisdatenelement verwendet werden, im Ereignis vorhanden sein. Außerdem sollten die Schlüsseleigenschaften nicht aus den Nichtschlüsseleigenschaften stammen, die über ein anderes Verweisdatenelement mit einem Ereignis verknüpft sind.

Angesichts dieser Einschränkungen kann die Join-Engine die Join-Engine in beliebiger Reihenfolge auf ein bestimmtes Ereignis anwenden. Hierarchie und Reihenfolge werden nicht berücksichtigt.

Aktuelle Grenzwerte

Sie können bis zu zwei Verweisdatasets pro Azure Time Series Insights Gen1-Umgebung hinzufügen. Zusätzliche Einschränkungen im Zusammenhang mit Azure Time Series Insights Gen1-Verweisdaten sind in der folgenden Tabelle aufgeführt:

Limitname Grenzwert Betroffene SKUs Notizen
Anzahl der Schlüsseleigenschaften 3 E1, E2 Pro Verweisdataset; Nur Azure Resource Manager und die Azure-Portal
Größe der Schlüsseleigenschaft 1 KB E1, E2 Pro Verweisdataset
Anzahl der Referenzdatenelemente 2.000/20.000 (S1/S2) E1, E2 Pro Einheit; Beispiel: SKU 4 Einheit S1 = 8.000 Elemente (4 x 2.000)
Max. gleichzeitige Transaktionen 2/10 (S1/S2) E1, E2
Max. Verweisdatentransaktionen 120/600 (S1/S2) E1, E2 Pro Stunde
Maximale Anzahl von Verweisdatenelementen 1\.000 E1, E2 Pro Transaktion
Max. Größe des Verweisdatenelements 8.192 KB E1, E2 Pro Transaktion

Weitere Informationen

Weitere Informationen zur Anwendungsregistrierung und zum Azure Active Directory-Programmiermodell finden Sie unter Azure Active Directory für Entwickler.

Informationen zu Anforderungs- und Authentifizierungsparametern finden Sie unter Authentifizierung und Autorisierung.

Zu den Tools, die beim Testen von HTTP-Anforderungen und -Antworten helfen, gehören:

  • Fiddler. Dieser kostenlose Webdebugproxy kann Ihre REST-Anforderungen abfangen, sodass Sie die HTTP-Anforderung und -Antwortnachrichten diagnostizieren können.
  • JWT.io. Sie können dieses Tool verwenden, um die Ansprüche in Ihrem Bearertoken schnell abzuspeichern und dann deren Inhalt zu überprüfen.
  • Postman. Dies ist ein kostenloses HTTP-Anforderungs- und Antworttesttool zum Debuggen von REST-APIs.

Weitere Informationen zu Azure Time Series Insights Gen1 finden Sie in der Gen1-Dokumentation.