Anforderungen an einen OData-Dienst (Referenz)

Der Treiber spricht jeden OData-v4-Dienst, der die Pflichtmerkmale unten anbietet. Bietet ein Dienst zusätzlich eine der Erweiterungen an, nutzt der Treiber sie; ohne sie verhält er sich, als gäbe es sie nicht. Diese Seite brauchen Sie, wenn Sie prüfen, ob ein Dienst mit dem Treiber zusammenarbeitet, oder wenn Sie selbst einen Dienst für Access-Anwendungen bauen. Der Datendienst Wkl.Data.Gateway bietet alle Merkmale dieser Seite an.

GET  <Dienststamm>/$metadata                       Schemadokument (CSDL, XML)
GET  <Dienststamm>/<Menge>?$select=…&$filter=…     Lesen, Antwort JSON
POST/PATCH/DELETE <Dienststamm>/<Menge>[(<Schlüssel>)]   Schreiben

Die Merkmale sind nach ihrer Verbindlichkeit für den Treiber gegliedert: Ohne die Pflicht zum Lesen verbindet der Treiber nicht oder liest falsch; ohne die Pflicht zum Schreiben bleiben alle Mengen schreibgeschützt; die Erweiterungen sind Empfehlungen, deren Fehlen eine Funktion abschaltet, aber nichts verfälscht. Die Grundlagen von OData v4 beschreiben die Normen von OASIS: OData Version 4.01 Part 1: Protocol, Part 2: URL Conventions (Abfrageoptionen, Literale), OData Common Schema Definition Language (CSDL) XML Representation 4.01 ($metadata) und OData JSON Format 4.01. Der Treiber verlangt nur Merkmale, die schon OData 4.0 kennt; $query (4.01) nutzt er, wenn vorhanden.

Pflicht zum Lesen

Pflicht zum Schreiben

Erweiterungen (empfohlen), die der Treiber nutzt, wenn der Dienst sie anbietet

Begriffe des Vokabulars Wkl.Store.V1. Das Vokabular ist eine Erweiterung dieses Produkts, kein Teil von OData. Ein Dienst, der es anbietet, legt es unter einer eigenen Adresse ab und bindet es mit edmx:Reference ein (Beispiel unten); der Treiber erkennt die Begriffe am Namensraum, mit oder ohne Alias.

Welche Zusage des Treibers gilt, hängt davon ab, was der Dienst anbietet und einhält. Der Treiber erkennt Ankündigungen in $metadata, nicht aber, ob ein Dienst eine Kopfzeile wie Idempotency-Key tatsächlich beachtet. Was er nicht erkennen kann, müssen Sie vor dem Einsatz beim Anbieter des Dienstes klären oder selbst prüfen.

Was ein Dienst für die Wiederholung zusagen muss. Der Treiber wiederholt eine Änderung höchstens zweimal, nach 1 und nach 3 Sekunden, mit demselben Idempotency-Key. Der Dienst muss deshalb die erste Antwort zu einem Schlüssel mindestens einige Sekunden aufbewahren und auf die Wiederholung genau diese Antwort geben, ohne die Änderung noch einmal auszuführen. Eine überschrittene Zeitgrenze (HYT00) wiederholt der Treiber nicht: Ob die Änderung ausgeführt wurde, ist dann unbekannt, und die Anwendung muss den Satz neu lesen. Den Abschluss einer Transaktion (commit, rollback) wiederholt er ebenfalls nicht.

Was ein Dienst aus Sicherheitsgründen zusagen muss. Er lehnt eine Anfrage ohne gültige Anmeldung oder zweiten Faktor ab, bevor er etwas ausführt; der Treiber sendet sie danach erneut. Und er leitet Adressen unter dem Dienststamm nicht auf einen anderen Ursprung um (siehe Restrisiken).

Keiner. Der Treiber prüft die Merkmale beim Verbinden und beim jeweiligen Gebrauch, nicht vorab.

• Ohne Core.OptimisticConcurrency stellt Access beim Ändern die alten Werte aller Spalten in die Bedingung. Das lässt sich in OData nicht ausdrücken; der Treiber weist es ab, statt die Prüfung fallen zu lassen. Abhilfe schafft der Dienst, etwa mit einer berechneten Nebenläufigkeitseigenschaft.
• Ohne Gruppieren und ohne Adresse für eigene Anweisungen scheitern Summenabfragen und Verbünde aus Access mit „ODBC-Aufruf fehlgeschlagen“; siehe Fehlerbehebung.
• Ohne Idempotency-Key-Unterstützung kann eine Wiederholung nach einem Verbindungsabbruch einen Satz doppelt anlegen oder einen Schreibkonflikt melden, obwohl die Änderung durchging. Ein Dienst, der die Kopfzeile nicht kennt, übergeht sie; der Treiber erkennt das nicht. Die Kopfzeile beschreibt ein abgelaufener Entwurf der IETF, kein Standard (siehe Normen und Spezifikationen).
• Eigene Anweisungen auf der Leitung. Der Treiber schickt {"sql": …, "parameters": {…}} und erwartet {"columns": […], "data": […], "affectedRowCount": …}. Gebundene Werte bleiben Werte: Die Platzhalter ?, die ODBC nach Position zählt, werden zu benannten Platzhaltern – ein Fragezeichen in einer Zeichenkette, einem geklammerten Namen oder einem Kommentar bleibt dabei unangetastet. Eine Antwort ohne columns wird abgewiesen. Die Typen aus den Werten der ersten Zeile zu erschließen, hieße: eine ganze Zahl in einer Dezimalspalte wird zur Ganzzahl, ein Zeitpunkt wird Text, und ein leeres Ergebnis hat gar keine Form – während die Anwendung ihre Puffer bindet, bevor sie die erste Zeile liest.
• Ausgabeparameter, weitere Ergebnismengen, Beschreiben. Bindet eine Anwendung Ausgabeparameter, schickt der Treiber zusätzlich "outputs": {"p1": "Edm.Int32", "p2": {"type": "Edm.String", "maxLength": 20}} und liest die Werte aus outputs der Antwort; weitere Ergebnismengen liest er aus results (je Menge columns, data, truncated). Fragt eine Anwendung vor dem Ausführen nach den Spalten, schickt er "describe": true und erwartet die Spalten der ersten Menge, ohne dass der Dienst etwas ausführt. Das Beschreiben verlangt er nur von einem Dienst, der die Adresse selbst in Store.PassThrough nennt: Ein Dienst, der describe übergeht, würde die Anweisung sonst ausführen. Liefert ein Dienst kein outputs, erhält die Anwendung NULL als Ausgabewert.
• Beschreibung der Spalten. Neben name, type und den Facetten (maxLength, precision, scale) liest der Treiber drei optionale Angaben je Spalte: storeType (der Typname der Datenbank, wie Store.Type in $metadata), identity (true für einen Wert, den die Datenbank vergibt) und label (der Name, den die Datenbank der Spalte gibt, wo er von name abweicht). Zeilen sind JSON-Objekte; für eine Spalte ohne Namen oder mit einem schon vergebenen Namen muss der Dienst deshalb einen eigenen Schlüssel vergeben. Mit label zeigt der Treiber der Anwendung den Namen der Datenbank – leer oder doppelt, wie der ODBC Driver 18 – und liest die Werte unter name. Ohne label sieht die Anwendung diesen Schlüssel.
• Store.PassThrough gilt nur am selben Ursprung (Schema, Rechner, Port) wie der Dienststamm.
• Felder einer Antwort, die der Treiber nicht kennt, übergeht er. Auf dem Durchreichepfad liest er columns, data, affectedRowCount, truncated, results und outputs (siehe Grenzen).
• Keine Umleitung an einen anderen Ursprung. Der Treiber folgt einer Umleitung nur beim Lesen und nur am selben Schema, Rechner und Port; leitet der Dienst anderswohin um, scheitert die Anfrage mit 08S01.

Ausschnitt eines Schemadokuments mit den Erweiterungen, die Access zum Bearbeiten und Gruppieren braucht:

<edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.xml">
  <edmx:Include Namespace="Org.OData.Aggregation.V1" Alias="Aggregation" />
</edmx:Reference>
<edmx:Reference Uri="https://daten.example.com/odata/v4/$vocabulary/Wkl.Store.V1.xml">
  <edmx:Include Namespace="Wkl.Store.V1" Alias="Store" />
</edmx:Reference>
…
<EntityContainer Name="Container">
  <Annotation Term="Store.Product" String="Microsoft SQL Server" />
  <Annotation Term="Store.ProductVersion" String="17.00" />
  <Annotation Term="Store.Schema" String="dbo" />
  <Annotation Term="Aggregation.ApplySupported">
    <Record>
      <PropertyValue Property="Transformations">
        <Collection><String>filter</String><String>compute</String><String>groupby</String><String>aggregate</String></Collection>
      </PropertyValue>
      <PropertyValue Property="Rollup" EnumMember="Aggregation.RollupType/None" />
    </Record>
  </Annotation>
  <Annotation Term="Aggregation.CustomAggregationMethods">
    <Collection><String>Wkl.Store.V1.count</String></Collection>
  </Annotation>
</EntityContainer>

So liefert es der Datendienst (gekürzt). Die Begriffe stehen mit dem Alias, den die edmx:Reference vergibt; der Treiber liest beide Schreibweisen.

Treiber Wkl OData, beide Bitbreiten. OData v2 und v3 sowie Dienste ohne $metadata oder ohne JSON werden nicht unterstützt.

• Wie der Treiber Anweisungen übersetzt
• Verbindungszeichenfolge des Treibers