FileMaker Cloud 2.18 OData Handbuch
Die Verwendung von OData mit FileMaker-Datenbanken
Übersicht
Open Data Protocol (OData) ist eine als Branchenstandard etablierte API-Implementierung, die eine Standardmethode für die Abfrage und Aktualisierung von Daten bietet und REST API-Clients ermöglicht, auf FileMaker®-Daten zuzugreifen, die von FileMaker Cloud® bereitgestellt werden. OData entspricht der Representational State Transfer- (REST) Architektur und ist somit ein REST API. OData ähnelt Open Database Connectivity (ODBC) und Java Database Connectivity (JDBC), da es Anwendungen Dritter wie Excel eine Standardmethode für den Zugriff auf FileMaker-Daten bietet. Siehe OData 4.0 Protocol (Englisch).
Zusätzlich gibt OData Daten in den Formaten JavaScript Object Notation (JSON) und Atom Syndication Format (Atom) zurück. JSON ist ein Textformat, das häufig zusammen mit REST APIs verwendet wird, da es kompakt ist und ein von Menschen lesbares Format besitzt. Atom ist ein XML-Format, das für die Erstellung und Aktualisierung von Webressourcen verwendet und für Anwendungen unterstützt wird, die XML-strukturierte Daten statt JSON verwenden.
Dieses Handbuch setzt voraus, dass Sie vertraut sind mit:
- der Verwendung von FileMaker Pro Advanced, um Datenbanken zu erstellen. Sie sollten sich mit den Grundlagen der Datenbankgestaltung von FileMaker Pro Advanced auskennen und die Konzepte von Feldern, Tabellen, Beziehungen und Containerfeldern verstehen. Siehe FileMaker Pro Advanced Hilfe.
- der Verwendung von FileMaker Cloud, um Datenbanken bereitzustellen. Sie sollten in der Lage sein, FileMaker Cloud einzurichten, den Zugang zu bereitgestellten Datenbanken zu ermöglichen und bereitgestellte Datenbanken über FileMaker Cloud Admin Console zu überwachen. Weitere Informationen finden Sie in der FileMaker Cloud-Dokumentation in der Produktdokumentation.
- der Verwendung von REST APIs in serverseitigen Anwendungen bzw. Webdiensten, die POST-, GET-, PATCH- und DELETE-Methoden aufrufen.
Allgemeine Schritte für die Verwendung von OData mit FileMaker-Datenbanken
- Bereiten Sie Ihre FileMaker-Datenbank für den OData-Zugriff mit FileMaker Pro Advanced vor. Siehe Aktivieren von OData-Zugriff.
- Programmieren Sie Code, der OData-Methoden aufruft, um Datensätze zu suchen und zu ändern, FileMaker-Scripts auszuführen und das Schema einer bereitgestellten Datenbank zu ändern. Siehe Schreiben von OData API-Aufrufen.
- Stellen Sie Ihre FileMaker-Datenbank mit Hilfe von FileMaker Cloud mit aktiviertem OData-Zugriff bereit. Siehe Bereitstellen von Datenbanken für OData-Zugriff.
- Testen Sie, um sicherzustellen, dass der OData-Zugriff korrekt funktioniert. Siehe Testen des OData-Zugriffs.
- Überwachen Sie Ihre bereitgestellte Datenbank mit Hilfe von FileMaker Cloud Admin Console. Siehe Überwachen des OData-Zugriffs.
Verarbeitung von OData-Aufrufen
- Ein REST API-Client sendet einen OData-Aufruf (HTTPS-Anforderung) über den HTTPS-Port (Port 443) an den Web-Server.
- Der Web-Server leitet die Anforderung über das FileMaker Web-Server-Modul an den FileMaker OData Listener weiter.
- Der OData Listener wandelt die HTTPS-Anforderung (URL mit JSON- oder Atom-Daten) in ein Format um, das die Datenbank-Server-Komponente versteht, und fordert Daten von der vom Datenbank-Server bereitgestellten Datenbank an.
- Der Datenbank-Server sendet die angeforderten FileMaker-Daten zurück an den OData Listener.
- Der OData Listener wandelt FileMaker-Daten in eine HTTPS-Antwort (URL mit JSON- oder Atom-Daten) um, um auf den Aufruf zu reagieren, und gibt die Daten an den Web-Server zurück.
- Der Web-Server sendet die HTTPS-Antwort an den anfordernden REST API-Client.
API-Lösungsvergleich
Die FileMaker-Plattform bietet zwei REST APIs für den Zugriff auf Daten in bereitgestellten FileMaker-Datenbanken. Bestimmen Sie, welche Lösung für Ihre Unternehmensziele und Ihre -umgebung sinnvoller ist.
Lösung | Verwenden bei | Vorteile |
---|---|---|
OData-Standard |
|
|
FileMaker Data API |
|
|
Terminologie von OData und FileMaker
Dieses Handbuch verwendet, soweit möglich, FileMaker-Terminologie. Aus Abgrenzungsgründen wird manchmal der OData-Begriff zusammen mit dem FileMaker-Begriff verwendet. Die folgende Tabelle zeigt entsprechende Begriffe und Definitionen.
Informationen zur FileMaker-Terminologie finden Sie in der Produktdokumentation.
OData-Begriff | FileMaker-Begriff |
---|---|
entity | Datensatz |
entity set | Tabelle |
entity container | Gruppe von Feldern, die nicht notwendigerweise ein Datensatz ist (wie ein Datenbankname und eine URL) |
collection of entity containers | Liste einer Gruppe von Feldern (z. B. eine Liste mit Datenbanknamen) |
property | Feld |
path segment | Wert zwischen zwei Schrägstrichzeichen (in einer URL) |
raw value | ein Binärwert, der eine Zeichenfolge von Bytes anstelle eines menschlich lesbaren, strukturierten JSON- oder Atom-Werts darstellt |
Vorbereiten von Datenbanken für OData-Zugriff
Aktivieren von OData-Zugriff
Um OData-Zugriff auf FileMaker-Daten zu gewähren, müssen Sie das erweiterte Zugriffsrecht „fmodata“ in FileMaker Pro Advanced aktivieren. Wenn Sie das erweiterte Zugriffsrecht „fmodata“ nicht aktivieren, können OData-Anwendungen keine OData-Aufrufe verwenden, um auf die Datenbank zuzugreifen, selbst wenn die Datenbank bereitgestellt wird.
Hinweis:Aktivieren Sie das erweiterte Zugriffsrecht „fmodata“ aus Sicherheitsgründen nur in den Berechtigungen für Konten, denen Sie den Zugriff über OData erlauben wollen.
Siehe „Bearbeiten der erweiterten Zugriffsrechte für eine Berechtigung“ in der FileMaker Pro Advanced Hilfe.
OData-Standardkonformität und Funktionsunterstützung
Unterstützte OData-Funktionen
OData verwendet Konventionen, die mit bestehenden Standards (REST, JSON, XML, Atom) arbeiten, für eine Darstellung gemeinsamer Funktionalität. Die FileMaker-Plattform unterstützt mit einigen Ausnahmen OData auf einer mittleren Konformitätsstufe. Siehe Spezifikationen und Referenzhandbuch zu OData 4.0 Protocol (Englisch).
Mit Hilfe des OData-APIs können Sie:
- Informationen über FileMaker Cloud abrufen; z. B. bereitgestellte Datenbanknamen und Tabellennamen sowie Metadaten für eine Datenbank. Siehe Datenbankstruktur und Metadaten.
- Datensätze erstellen, bearbeiten und löschen. Siehe Ändern von Daten.
- einen Datensatz suchen oder alle Datensätze aufrufen. Siehe Anfordern von Daten.
- Kriterien angeben, um eine Datensatzmenge zu suchen. Siehe Abfrage-Optionen.
- FileMaker-Scripts ausführen. Siehe Ausführen von Scripts.
- Containerdaten hochladen. Siehe Arbeiten mit Containerdaten.
Nicht unterstützte OData-Funktionen
Diese OData-Funktionen der mittleren Konformitätsstufe werden nicht unterstützt:
$search
Abfrage-Option$expand
(nur als Teil der Operation$crossjoin
unterstützt)lambda
Operatorenany
undall
$filter
bei erweiterten Entitätenintegrierte kanonische Funktionen und Operatoren:
- indexof()
- fractionalseconds()
- isof()
- geo.distance()
- geo.length()
- geo.intersects()
Zusätzlich werden folgende Aktionen nicht unterstützt:
- Zugriff auf Daten in externen ODBC-Datenquellen
- Verwendung von FileMaker-Plugins
- Script-Trigger-Aktivierung durch Benutzerinteraktion; OData aktiviert Script-Trigger nur durch Ausführen von FileMaker-Scripts.
- Zugriff auf das Dateisystem des Servercomputers; z. B. unterstützt OData nicht die Funktion „Hole ( TemporärerPfad )“.
OData-Referenzinformationen
Verschiedene API-Referenzmaterialien enthalten Spezifikationen für OData:
- OData 4.0 Protocol (Englisch)
- OData 4.0 URL Conventions (Englisch)
- OData 4.0 Common Schema Definition Language (Englisch)
- OData 4.0 JSON Format (Englisch)
Hinweise zu URLs und Datenformaten
- Die maximale URL-Länge kann durch Unterschiede in den Betriebssystemen, Web-Servern und Webbrowsern beeinflusst werden. Beschränken Sie für einen optimalen plattformübergreifenden Einsatz die URL-Länge auf 2.000 Zeichen.
- Zeichenfolgen in URLs müssen URL-Verschlüsselung, auch Prozent-Verschlüsselung genannt, verwenden, was für HTTP-Anforderungen üblich ist.
- Zeichenfolgendatenwerte, die in Parametern im Hauptteil der Anforderung angegeben werden, müssen UTF-8-Kodierung verwenden.
FileMaker-Scripts und OData
Ein FileMaker-Script ist eine benannte Menge von Scriptschritten, die häufig durchgeführte Aufgaben automatisieren und die verschiedene Aufgaben kombinieren können. In Kombination mit OData ermöglichen FileMaker-Scripts den Webdiensten, mehrere Aufgaben oder eine Aufgabenserie auszuführen. Siehe Ausführen von Scripts.
Hinweise
- Verwenden Sie Konten und Zugriffsrechte, um die Scripts einzuschränken, die ein Webdienst ausführen kann. Stellen Sie sicher, dass die Scripts nur webkompatible Scriptschritte enthalten und nur Zugang zu Scripts gewähren, die von einem Webdienst ausgeführt werden sollen.
- Berücksichtigen Sie die Effekte von Scripts, die eine Kombination von Scriptschritten ausführen, die durch Zugriffsrechte kontrolliert werden. Wenn ein Script beispielsweise einen Scriptschritt zum Löschen von Datensätzen enthält und der Webdienst sich nicht mit einem Konto anmeldet, das das Löschen von Datensätzen zulässt, führt das Script den Scriptschritt zum Löschen von Datensätzen nicht aus. Das Script könnte jedoch weiter ausgeführt werden, so dass unerwartete Ergebnisse auftreten können.
- Geben Sie einem Script im Scriptarbeitsbereich die Berechtigung „Voller Zugriff“, damit dieses Script Aufgaben ausführen kann, für die Sie einzelnen Benutzern an sich keinen Zugang gewähren wollen. Beispielsweise können Sie verhindern, dass Benutzer mit ihren Konten und Zugriffsrechten Datensätze löschen, ihnen aber die Ausführung eines Scripts erlauben, das unter vordefinierten Bedingungen innerhalb des Scripts bestimmte Datensätze löscht.
- Scripts, die Daten ändern, sollten den Scriptschritt „Schreibe Änderung Datens./Abfrage“ enthalten, da auf Datenänderungen erst zugegriffen werden kann, wenn die Daten auf dem Server gespeichert wurden. Dies gilt für Scriptschritte wie Ausschneiden, Kopieren oder Einfügen. Wandeln Sie einzelne Aktionen in Scripts um, um den Scriptschritt „Schreibe Änderung Datens./Abfrage“ aufzunehmen. Wenn Sie Scripts entwerfen, die von einem Webdienst ausgeführt werden, nehmen Sie den Scriptschritt „Schreibe Änderung Datens./Abfrage“ am Ende des Scripts auf, um sicherzustellen, dass alle Änderungen gespeichert werden.
- Öffnen Sie jedes Script, das Webbenutzer ausführen könnten, und stellen Sie sicher, dass das Script richtig ausgeführt wird, wenn die Datenbank für OData-Zugriff bereitgestellt wird. Stellen Sie sicher, dass das Script nur Scriptschritte verwendet, die von OData wie oben beschrieben unterstützt werden.
Schreiben von OData API-Aufrufen
OData-Aufrufkomponenten
OData-Aufrufe bestehen aus den folgenden Komponenten.
Komponente | Beschreibung |
---|---|
HTTP-Methode | OData verwendet die folgenden HTTP-Methoden:
|
HTTP-Header | OData verwendet die folgenden Header:
|
URL | https://host/fmi/odata/version/datenbankname host – FileMaker Cloud-Hostname Beispiel: |
Parameterdaten in JSON- und Atom-Beispiel | Nur für die Methoden POST und PATCH. |
Erstellen einer authentifizierten Verbindung zum FileMaker-Host
OData erfordert die Authentifizierung über ein FileMaker-ID Konto.
So definieren Sie eine Verbindung zum FileMaker-Host:
- Generieren Sie einen FileMaker-ID Token für externe Authentifizierung. Siehe FileMaker Customer Console Hilfe.
- Nehmen Sie den FileMaker-ID Token aus Schritt 1 in den Authorization Header für alle OData-Aufrufe auf.
Verwenden Sie beispielsweise folgende URL und folgenden Header:
- URL:
https://host/fmi/odata/v4/datenbankname/$metadata
Host – FileMaker Cloud-Host
datenbankname – der Name der FileMaker-Datenbank - Header:
Authorization FMID FileMaker_ID_Token
- URL:
Datenbankstruktur und Metadaten
Informationen über bereitgestellte Datenbanken und ihre Struktur sind über das Ausführen von HTTP GET-Methoden verfügbar.
Abrufen von Datenbanknamen
Um eine Liste der Datenbanknamen zu erhalten, verwenden Sie die GET-Methode, ohne einen Datenbanknamen in der URL anzugeben.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version host – FileMaker Cloud-Hostname Beispiel: |
FileMaker-Informationen
- OData gibt eine Liste der Datenbanknamen und ihrer entsprechenden Endpunkt-URLs zurück.
Abrufen einer Liste von Tabellen
Um eine Liste der Tabellen in einer Datenbank abzurufen, verwenden Sie die HTTP GET-Methode mit dem angehängten Datenbanknamen in der URL.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname host – FileMaker Cloud-Hostname Beispiel: |
Abrufen von Metadaten
Um Tabellen-Metadateninformationen anzufordern, verwenden Sie die HTTP GET-Methode.
Verwenden Sie das Schlüsselwort $metadata
mit dem Datenbankdienst root, um eine vollständige Metadatenliste für die Datenbank anzufordern.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/$metadata host – FileMaker Cloud-Hostname Beispiel: |
FileMaker-Informationen
Für Informationen über die FileMaker-Tabellen in den Datenbanken werden Anmerkungen (Informationen, die nicht im OData-Standard definiert sind) zu den Metadatenergebnissen wie FileMaker-Produktversionsnummer hinzugefügt.
Die Anmerkungen unten haben den Booleschen Wert „true“, wenn sie vorhanden sind. Andernfalls ist der Wert „false“.
- AutoGenerated: gibt an, ob der Feldwert automatisch von FileMaker Pro Advanced generiert wird
- Index: gibt an, ob die Feldwerte indiziert sind
- VersionID: gibt an, ob das Feld ein Zeitstempelfeld ist und ein neuer Zeitstempelwert generiert wird, wenn der Datensatz geändert wird
- Global: gibt an, ob das Feld einen Variablenwert enthält
- Calculation: gibt an, ob das Feld vom Typ Formel ist
- Summary: gibt an, ob das Feld vom Typ Statistik ist
Andere Anmerkungen:
- MaxRepetitions: ein Ganzzahlwert, der die maximalen Wiederholungen für ein Wiederholfeld definiert. Wenn diese Anmerkung nicht vorhanden ist, ist das Feld kein Wiederholfeld.
- ExternalSecurePath: eine Zeichenfolge, die den relativen Pfad anzeigt, der für den sicheren Speicher eines Containerfelds angegeben wurde.
- BestRowID: enthält immer ROWID, ein Systemfeld, das explizit in einer Ergebnismenge durch Angabe von
$select=ROWID
enthalten ist. Der Wert in der Ergebnismenge ist identisch mit der Funktion „Hole ( DatensatzIDNr )“ für einen Datensatz. - RowVersion: enthält immer ROWMODID, ein Systemfeld, das explizit in einer Ergebnismenge durch Angabe von
$select=ROWMODID
enthalten ist. Der Wert in der Ergebnismenge ist identisch mit der Funktion „Hole ( DatensatzÄnderungenAnzahl )“ für einen Datensatz.
Wichtig: OData verlangt, dass jede Tabelle einen Primärschlüssel definiert. OData verwendet Felder, die nicht leer sind und die einen eindeutigen Wert als Primärschlüssel erfordern. Wenn daher für Ihre Tabellen solche Felder nicht definiert sind, wird das Systemfeld ROWID als Primärschlüssel verwendet. Das Systemfeld ROWID enthält den gleichen Wert wie die Funktion „Hole ( DatensatzIDNr )“ für den Datensatz.
Ändern von Daten
OData unterstützt das Erstellen, Aktualisieren und Löschen von Datensätzen entsprechend den Zugriffsrechten, die ein Konto besitzt.
Datensatz erstellen
Um einen Datensatz für eine Tabelle zu erstellen, verwenden Sie die POST-Methode. Der POST-Teil muss die Daten eines einzelnen Datensatzes im JSON-Format enthalten.
Komponente | Beschreibung |
---|---|
HTTP-Methode | POST |
URL | https://host/fmi/odata/version/datenbankname/tabellenname host – FileMaker Cloud-Hostname Beispiel: |
Parameter | JSON-Beispiel: { Atom-Beispiel: |
FileMaker-Informationen
- Werte für einzelne Wiederholungen in einem Wiederholfeld werden übergeben, indem die Wiederholungsnummer in eckigen Klammern angegeben wird (z. B.
Name[4]
). - Wenn Sie einen Datensatz mit leeren Datenobjekten in JSON-Format erstellen, muss mindestens ein Feld Null-Werte zulassen.
- FileMaker-Variablenfelder sind nur lesbar und können nicht mit OData aktualisiert werden.
Datensatz löschen
Um einen Datensatz zu löschen, verwenden Sie die HTTP DELETE-Methode unter Angabe des Tabellennamens und des Primärschlüsselwerts des Datensatzes in der URL.
Komponente | Beschreibung |
---|---|
HTTP-Methode | DELETE |
URL | https://host/fmi/odata/version/datenbankname/tabellenname (primärschlüsselwert) host – FileMaker Cloud-Hostname Beispiel: |
FileMaker-Informationen
- Sie können mehrere Datensätze löschen, indem Sie das Kriterium
$filter
angeben.
Datensatz aktualisieren
Um einen Datensatz zu aktualisieren, verwenden Sie eine HTTP PATCH-Methode mit dem Datensatz, den Sie aktualisieren möchten, in der URL.
Komponente | Beschreibung |
---|---|
HTTP-Methode | PATCH |
URL | https://host/fmi/odata/version/datenbankname/tabellenname (primärschlüsselwert) host – FileMaker Cloud-Hostname Beispiel: |
Parameter | JSON-Beispiel: { |
FileMaker-Informationen
- Containerwerte werden entweder durch Angabe eines Base64-kodierten Werts wie in Aktualisieren eines Datensatzes mit einem Bild- oder PDF-Containerfeld beschrieben oder durch Angabe der Binärdaten wie in Aktualisieren eines Datensatzes mit einem Bild- oder PDF-Containerfeld mit Binärdaten beschrieben aktualisiert.
- Werte für einzelne Wiederholungen in einem Wiederholfeld werden übergeben, indem der Wiederholungsindex in eckigen Klammern angegeben wird (z. B.
Name[4]
). Die Angabe einer Wiederholung eines Containerfelds wird bei der Aktualisierung eines Datensatzes nicht unterstützt. - Sie können mehrere Datensätze löschen, indem Sie das Kriterium
$filter
angeben.
Arbeiten mit Containerdaten
Sie können eine HTTP POST- oder PATCH-Methode senden, um Bilder oder PDF-Dateien in Containerfelder einzufügen. Daten in Containerfeldern können im Feld eingebettet, als Dateireferenz oder extern gespeichert werden.
Erstellen eines Datensatzes mit einem Bild- oder PDF-Containerfeld
Um einen Datensatz für eine Tabelle mit einem oder mehreren Containerfeldern zu erstellen, geben Sie das Feld mit Base64-kodierten Daten an. Es werden nur die Dateitypen GIF, PNG, JPEG, TIFF und PDF unterstützt. Der POST-Teil muss eine einzige gültige Datensatzdarstellung enthalten.
Komponente | Beschreibung |
---|---|
HTTP-Methode | POST |
URL | https://host/fmi/odata/version/datenbankname/tabellenname host – FileMaker Cloud-Hostname Beispiel: |
Parameter | JSON-Beispiel: { |
FileMaker-Informationen
- Der Medientyp eines Base64-kodierten Containerwerts wird durch einen Vergleich der ersten Bytes der Daten mit den erwarteten Werten für die unterstützten Medientypen bestimmt.
Aktualisieren eines Datensatzes mit einem Bild- oder PDF-Containerfeld mit Binärdaten
Die Anforderung in dieser Tabelle aktualisiert den Wert in einem Fotofeld eines Kontaktdatensatzes mit der PATCH-Methode mit binären GIF-Bytes (unstrukturiert) im Datenteil der Anforderung. Der Content-Type-Header muss den Datentyp angeben, der im Datenteil enthalten ist (image/gif, image/png, image/jpeg, image/tiff oder application/pdf).
Komponente | Beschreibung |
---|---|
HTTP-Methode | PATCH |
URL | https://host/fmi/odata/version/datenbankname/tabellenname (primärschlüsselwert)/feldname host – FileMaker Cloud-Hostname Beispiel: |
Parameter | "474946383961090009008001007F7F7FFFFFFF21F90401000001002C00000000090009 |
Aktualisieren eines Datensatzes mit einem Bild- oder PDF-Containerfeld
Um den Wert eines Containerfelds für einen Datensatz zu aktualisieren, verwenden Sie die HTTP PATCH-Methode mit einem Base64-kodierten Wert.
Komponente | Beschreibung |
---|---|
HTTP-Methode | PATCH |
URL | https://host/fmi/odata/version/datenbankname/tabellenname (primärschlüsselwert) host – FileMaker Cloud-Hostname Beispiel: |
Parameter | JSON-Beispiel: { |
Anfordern von Daten
Anfordern von Datensätzen aus einer Tabelle
Um eine Sammlung von Datensätzen aus der FileMaker-Datenbank zurückzugeben, verwenden Sie die HHTP GET-Methode mit dem Tabellennamen in der URL.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/tabellenname host – FileMaker Cloud-Hostname Beispiel: |
FileMaker-Informationen
- Containerfelder sind im Antwortergebnis nicht enthalten, wenn Sie alle Datensätze oder einen einzelnen Datensatz erhalten. Siehe Anfordern eines einzelnen Feldwerts für Informationen zur Anforderung von Containerfeldwerten.
Anfordern eines einzelnen Datensatzes
Um einen einzelnen Datensatz in einer Datenbanktabelle anzufordern, geben Sie Datenbanknamen und Tabellennamen sowie den Primärschlüsselwert für den Datensatz an.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/tabellenname (primärschlüsselwert) host – FileMaker Cloud-Hostname Beispiel: |
FileMaker-Informationen
- Der in der URL angegebene Primärschlüsselwert ist das als Primärschlüssel festgelegte Feld oder das Systemfeld ROWID, falls kein Primärschlüssel festgelegt wurde. Siehe Abrufen von Metadaten. Für Wiederholfelder ist der Wert der ersten Wiederholung enthalten. Für einzelne Wiederholungen siehe Anfordern eines einzelnen Feldwerts.
Anfordern eines einzelnen Feldwerts
Um einen einzelnen Feldwert anzufordern, geben Sie Tabellenname, Primärschlüsselwert für den Datensatz und Feldname an.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/tabellenname (primärschlüsselwert)/feldname host – FileMaker Cloud-Hostname Beispiel: |
FileMaker-Informationen
- In einer URL wird bei der Anforderung einer einzelnen Wiederholung die Verwendung von eckigen Klammern ([ ]) für die Angabe des Wiederholungsindex nicht unterstützt.
- Wenn das Wiederholfeld ein Containerfeld ist, wird nur die erste Wiederholung zurückgegeben. Andernfalls werden alle Wiederholungen zurückgegeben.
Anfordern des Binärwerts für ein einzelnes Feld
Um ein als Binärwert gespeichertes einzelnes Feld abzurufen, verwenden Sie die Abfrage-Option $value
.
Das Binärwert-Standardformat für das FileMaker-Feld ist text/plain. Für Containerfelder hängt das Standardformat vom Typ des Containerfelds ab und umfasst image/gif, image/png, image/jpeg, image/tiff, application/pdf bzw. application/octet-stream.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/tabellenname (primärschlüsselwert)/feldname/$value host – FileMaker Cloud-Hostname Beispiel: Die Anforderung oben gibt den Binärwert des Felds „Name“ für den Kontaktdatensatz zurück. |
FileMaker-Informationen
- Wenn der Binärwert (Rohwert) eines Wiederholfelds angefordert wird, wird nur der Binärwert (Rohwert) der ersten Wiederholung zurückgegeben.
Navigieren in Bezugstabellen
Sie können in Beziehungen zwischen FileMaker-Tabellen navigieren, ohne die Abgleichsfelder für jede Beziehung anzugeben. Alle Operationen und Ergebnisse beziehen sich auf die letzte Tabelle in der URL.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/tabellenname (primärschlüsselwert)/bezugstabelle host – FileMaker Cloud-Hostname Beispiel: Die obige Anforderung gibt alle Produkte zurück, die von einem Kunden mit der angegebenen ID gekauft wurden. |
FileMaker-Informationen
- Bei Verwendung der Abfrage-Option
$filter
werden Feldnamen eindeutig gemacht, indem der Tabellenname vorne an den Feldnamen im Ausdruck angehängt wird (z. B.$filter=Kauf/ID eq 7
).
Anfordern eines Cross-Join von nicht in Beziehung stehender Tabellen
Um einen Cross-Join von nicht in Beziehung stehenden Tabellen anzufordern, verwenden Sie das Schlüsselwort $crossjoin
und führen Sie die Tabellen auf, die Sie verbinden möchten. Wenn Sie die Abfrage-Option $filter
verwenden, geben Sie jedes Feld an, das für die Verbindung der beiden Tabellen verwendet wird.
Verwenden Sie die Abfrage-Option $expand
und die Abfrage-Option $select
, um sicherzustellen, dass anstelle des Standardverhaltens (eine Liste der DatensatzIDs) die Datenfelder zurückgegeben werden. Siehe „Addressing the cross join of entity sets“ in OData 4.0 URL Conventions (Englisch).
Hinweis: Ein Cross-Join ist der einzige Kontext, in dem das Schlüsselwort $expand
unterstützt wird.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/$crossjoin(tabelle 1, tabelle 2)?$filter= host – FileMaker Cloud-Hostname Beispiel: |
Abfrage-Optionen
OData unterstützt verschiedene Abfrage-Optionen für das Abfragen von Daten.
Abfrage-Option $filter
Verwenden Sie die Abfrage-Option $filter
, um die Datensätze zu filtern. Der mit $filter
angegebene Ausdruck wird für jeden Datensatz in der Sammlung ausgewertet und nur Objekte, bei denen der Ausdruck mit wahr ausgewertet wird, werden in die Antwort aufgenommen.
OData unterstützt eine Menge integrierter Operatoren und Funktionen, die innerhalb von $filter
-Operationen verwendet werden. Für weitere Informationen über verfügbare Operatoren und integrierte Funktionen siehe OData 4.0 Protocol (Englisch).
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/tabellenname?$filter=(ausdruck) host – FileMaker Cloud-Hostname Beispiel: Die Anforderung oben verwendet die GET-Methode und die System-Abfrage-Option |
FileMaker-Informationen
Folgende integrierte Funktionen werden nicht unterstützt:
- indexof()
- isof()
- geo.distance()
- geo.length()
- geo.intersects()
- fractionalseconds()
- Datums-, Zeit- und Zeitstempelformate entsprechen ISO 8601. Der Zeitzonenversatz ist relativ zu der Zeitzone des Servers.
- Umschließen Sie Feldnamen, die Sonderzeichen wie Leerzeichen oder Unterstriche enthalten, in doppelten Anführungszeichen.
Abfrage-Option $orderby
Verwenden Sie die Abfrage-Option $orderby
, um Datensätze in aufsteigender oder absteigender Reihenfolge anzufordern. Wenn Sie keine Reihenfolge angeben, ist die Standardfolge aufsteigend.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/tabellenname?$orderby=feldname {asc/desc} host – FileMaker Cloud-Hostname Beispiel: Die Anforderung oben sortiert Kontaktdatensätze, sortiert in absteigender Reihenfolge nach dem Feld Firma. |
FileMaker-Informationen
- Umschließen Sie Feldnamen, die Sonderzeichen wie Leerzeichen oder Unterstriche enthalten, in doppelten Anführungszeichen.
- Die Abfrage-Option
$orderby
unterstützt keine integrierten OData-Funktionen.
Abfrage-Optionen $top und $skip
Verwenden Sie die Abfrage-Optionen $top
und $skip
, um durch eine größere Ergebnismenge zu blättern. Sie können diese Abfrage-Optionen getrennt oder gemeinsam verwenden, je nachdem, welche Datensätze Sie in Ihrer Antwort wünschen.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/tabellenname{?$top/?$skip}=anzahl host – FileMaker Cloud-Hostname Abfrage-Optionen {?$top/?$skip} – die Abfrage-Option Beispiel:
|
Abfrage-Option $count
Verwenden Sie die Abfrage-Option $count
(Wert auf „wahr“ gesetzt), um die Rückgabe einer Anzahl an übereinstimmenden Datensätzen zusammen mit den Datensätzen in der Antwort anzufordern. Die Abfrage-Option $count
ignoriert etwaige Abfrage-Optionen $top
oder $skip
und gibt die Gesamtzahl an Ergebnissen über alle Datensätze einschließlich der Ergebnisse zurück, die den $filter-Kriterien $filter
, falls angegeben, entsprechen.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/tabellenname?$count=true host – FileMaker Cloud-Hostname Beispiel: |
Abfrage-Option $select
Verwenden Sie die Abfrage-Option $select
, um eine begrenzte Menge von Feldern jeder Tabelle anzufordern. Standardmäßig werden alle Felder außer Containerfeldern zurückgegeben.
Komponente | Beschreibung |
---|---|
HTTP-Methode | GET |
URL | https://host/fmi/odata/version/datenbankname/tabellenname?$select=feld 1, feld 2 host – FileMaker Cloud-Hostname Beispiel: Die Anforderung oben gibt die Daten aus „Firma“ und „Website“ für alle Datensätze in der Tabelle „Kontakte“ zurück. |
FileMaker-Informationen
- Die Systemfelder ROWID und ROWMODID sind in der Ergebnismenge enthalten, indem sie mit der Abfrage-Option
$select
angegeben werden. Beispiel:$select=ROWID, ROWMODID.
- ROWID entspricht dem Wert, den die Funktion „Hole ( DatensatzIDNr )“ zurückgibt, ROWMODID entspricht dem Wert, den die Funktion „Hole ( DatensatzÄnderungenAnzahl )“ zurückgibt.
Ändern des Schemas
OData unterstützt das Erstellen und Löschen für das Erstellen und Löschen von Tabellen und Indizes entsprechend den für ein Konto definierten Zugriffsrechten.
Erstellen einer Tabelle
Um eine neue Tabelle zu erstellen, verwenden Sie die HTTP POST-Methode. Der POST-Datenteil muss eine einzige gültige Tabellendarstellung enthalten, die eine ID beinhaltet, die der Tabellenname ist.
Komponente | Beschreibung |
---|---|
HTTP-Methode | POST |
URL | https://host/fmi/odata/version/datenbankname/FileMaker_Tables host – FileMaker Cloud-Hostname Beispiel: |
Parameter | JSON-Beispiel: { "tableName": "Firma", "fields": [ { "name": "FirmenID", "type": "int", "primary": true }, { "name": "BenutzerID", "type": "varchar(20)", "unique": true, "default": "CURRENT_USER" }, { "name": "Firmenname", "type": "varchar(100)", "nullable": false }, { "name": "Bemerkungen", "type": "varchar(2000)", "global": true }, { "name": "Vertrag unterzeichnet", "type": "blob", "externalSecurePath": "Files/KontaktMgmt/" } ] } Atom-Beispiel: <TableDefinition tableName="Firma"> <FieldDefinition name="FirmenID" type="int" primary="true"/> <FieldDefinition name="BenutzerID" type="varchar(20)"unique="true" default="CURRENT_USER"/> <FieldDefinition name="Firmenname" type="varchar(100)" nullable="false"/> <FieldDefinition name="Bemerkungen" type="varchar(2000) global="true"/> </TableDefinition> |
FileMaker-Informationen
- FileMaker_Tables ist eine Systemtabelle für das Erstellen, Ändern und Löschen von Tabellen. Der Parameter
type
ist einer der folgenden Typen: NUMERIC, DECIMAL, INT, DATE, TIME, TIMESTAMP, VARCHAR, CHARACTER VARYING, BLOB, VARBINARY, LONGVARBINARY oder BINARY VARYING. - Wiederholungen werden in eckigen Klammern nach dem Typ angegeben (z. B.
"INT[4]"
). Sie können die maximale Länge eines Textfelds in Klammern angeben (z. B."VARCHAR(200)"
). Optionale Parameter für Feldname und Feldtyp sind:
"primary"
: „true“ oder „false“ (ob das Feld ein Primärschlüssel ist; Standard „false“)"unique"
: „true“ oder „false“ (ob das Feld einen eindeutigen Wert haben muss; Standard „false“)"nullable"
: „true“ oder „false“ (ob das Feld einen Wert haben muss; Standard „true“)"global"
: „true“ oder „false“ (ob das Feld ein Variablenfeld ist; Standard „false“)"default"
: eine Zeichenfolge mit einem Schlüsselwort, das dem Datentyp entspricht; gültige Schlüsselwörter sind USER, USERNAME, CURRENT_USER, CURRENT_DATE, CURDATE, CURRENT_TIME, CURTIME, CURRENT_TIMESTAMP und CURTIMESTAMP"externalSecurePath"
(nur Containerfeld): eine Zeichenfolge mit einem relativen Pfad für sichere Dateien in "externalSecurePath". Schließen Sie den „[datenbankspeicherort]/"-Teil des Basisverzeichnisses aus. Legen Sie dies auf jeden Fall für jede FileMaker-Datenbank in FileMaker Pro Advanced fest. Siehe FileMaker Pro Advanced Hilfe.
Hinzufügen von Feldern in einer Tabelle
Um ein neues Feld in einer bestehenden Tabelle hinzuzufügen, senden Sie eine PATCH-Anforderung an die Systemtabelle FileMaker_Tables, gefolgt von dem Tabellennamen in der URL. Der PATCH-Datenteil muss ein Feldarray enthalten, das der Tabelle hinzugefügt wird.
Falls die Anforderung fehlerbedingt fehlschlägt, während ein Feld hinzugefügt wird, können dennoch andere Felder der Tabelle hinzugefügt werden.
Komponente | Beschreibung |
---|---|
HTTP-Methode | PATCH |
URL | https://host/fmi/odata/version/datenbankname/FileMaker_Tables/tabellenname host – FileMaker Cloud-Hostname Beispiel: Die Anforderung oben erstellt ein Feld namens „Telefon“ in der Tabelle „Firma“. |
Parameter | JSON-Beispiel: { "fields": [ { "name": "Telefon", "type": "varchar(25)" } ] } Atom-Beispiel: <TableDefinition tableName="Firma"> <FieldDefinition name="Telefon" type="varchar(25)"/> </TableDefinition>
|
FileMaker-Informationen
- FileMaker_Tables ist eine Systemtabelle für das Erstellen, Ändern und Löschen von Tabellen. Siehe Erstellen einer Tabelle für gültige Optionen.
Löschen einer Tabelle
Um eine Tabelle und alle ihre Datensätze zu löschen, verwenden Sie die HTTP DELETE-Methode und verwenden den Tabellennamen in der URL.
Komponente | Beschreibung |
---|---|
HTTP-Methode | DELETE |
URL | https://host/fmi/odata/version/datenbankname/FileMaker_Tables/tabellenname host – FileMaker Cloud-Hostname Beispiel: |
FileMaker-Informationen
- FileMaker_Tables ist eine Systemtabelle für das Erstellen, Ändern und Löschen von Tabellen.
- Dieser Vorgang löscht eine Tabelle und alle Daten in ihr, ohne eine Bestätigung zu erfordern. Um Datenverluste zu vermeiden, erstellen Sie ein Konto mit Zugriffsrechten für das Löschen von Tabellen und verwenden Sie dieses Konto ausschließlich für diesen Vorgang.
Löschen eines Felds aus einer Tabelle
Um ein Feld aus einer Tabelle zu löschen, verwenden Sie die HTTP DELETE-Methode mit dem an den Tabellennamen in der URL angehängten Feldnamen.
Komponente | Beschreibung |
---|---|
HTTP-Methode | DELETE |
URL | https://host/fmi/odata/version/datenbankname/FileMaker_Tables/tabellenname/feldname host – FileMaker Cloud-Hostname Beispiel: |
Erstellen eines Feldindex
Um einen neuen Index zu erstellen, senden Sie eine POST-Anforderung an den Tabellennamen nach der Systemtabelle FileMaker_Indexes. Der POST-Datenteil muss eine einzige gültige Indexdarstellung enthalten, die eine ID beinhaltet, die der Feldname ist.
Komponente | Beschreibung |
---|---|
HTTP-Methode | POST |
URL | https://host/fmi/odata/version/datenbankname/FileMaker_Indexes/tabellenname host – FileMaker Cloud-Hostname Beispiel: |
Parameter | JSON-Beispiel: { Atom-Beispiel: <IndexDefinition indexName="Bundesland"/> |
FileMaker-Informationen
- FileMaker_Indexes ist eine Systemtabelle für das Erstellen und Löschen von Indizes.
Löschen eines Index
Um einen Index zu löschen, senden Sie eine HTTP DELETE-Anforderung an die Systemtabelle FileMaker_Indexes, gefolgt von Tabellennamen und Feldnamen in der URL.
Komponente | Beschreibung |
---|---|
HTTP-Methode | DELETE |
URL | https://host/fmi/odata/version/datenbankname/FileMaker_Indexes/tabellenname/feldname host – FileMaker Cloud-Hostname Beispiel: |
FileMaker-Informationen
- FileMaker_Indexes ist eine Systemtabelle für das Erstellen und Löschen von Indizes in Feldern.
- Um einen Index zu löschen, muss die URL zuerst den Tabellennamen, gefolgt vom Feldnamen, angeben.
Ausführen von Scripts
Um ein Script auszuführen, senden Sie eine POST-Anforderung an die Systemtabelle „Script“, gefolgt vom Namen des Scripts in der URL. Der POST-Datenteil muss vollständig leer sein, wenn das Script keine Parameter akzeptiert, bzw. muss ein einzelnes Feld „scriptParameterValue“ enthalten, wenn ein Parameter an das Script übergeben wird. „scriptParameterValue“ akzeptiert die Objekttypwerte string, number und JSON.
OData unterstützt Scriptnamen mit Sonderzeichen (z. B. @, &, /) oder Scriptnamen, die mit einer Zahl beginnen, nicht. Wenn das Script den Scriptschritt „Aktuelles Script verlassen“ enthält, wird das Textergebnis von „Aktuelles Script verlassen“ in einem Feld „resultParameter“ in den Ergebnissen zurückgegeben.
Das Script „HalloScript“ hängt den Parameterwert an die Zeichenfolge „Hallo“ an und gibt das Ergebnis zurück. OData gibt das Ergebnis im Antwortteil mit einem Content-Type „application/json“ zurück.
{
"scriptResult":
{
"code": 0,
"resultParameter": "Hallo Welt"
}
}
Hinweis: OData unterstützt nur Scripts, die ohne Benutzerinteraktion ablaufen.
Ausführen eines Scripts
Um ein Script auszuführen, verwenden Sie die HTTP POST-Methode.
Komponente | Beschreibung |
---|---|
HTTP-Methode | POST |
URL | https://host/fmi/odata/version/datenbankname/Script.scriptname host – FileMaker Cloud-Hostname Beispiel: Welt aus. |
Parameter | JSON-Beispiel: |
FileMaker-Informationen
- Um dem OData-Konzept einer Aktion zu entsprechen, sind alle Scripts Teil der Systemtabelle namens „Script“.
Bereitstellen, Testen und Überwachen von OData
Bereitstellen von Datenbanken für OData-Zugriff
- Führen Sie die Schritte unter Aktivieren von OData-Zugriff durch.
- Stellen Sie sicher, dass der OData-Zugriff auf FileMaker-Datenbanken in FileMaker Cloud Admin Console aktiviert und richtig konfiguriert ist. Weitere Informationen finden Sie in der FileMaker Cloud-Dokumentation in der Produktdokumentation.
- Stellen Sie sicher, dass der Web-Server und die OData Listener laufen.
-
Verschlüsseln Sie die Kommunikation.
OData erfordert eine HTTPS-Verbindung. HTTPS-Verbindungen verwenden Secure-Sockets-Layer- (SSL-) Verschlüsselung für die Kommunikation.
Die Programmiersprache bzw. Technologie, die Sie verwenden, um das OData API aufzurufen, muss Transport Layer Security (TLS) v1.2 unterstützen, um mit dem Web-Server zu kommunizieren.
Testen des OData-Zugriffs
Bevor Sie Ihre OData API-Lösung in einer produktiven Umgebung einsetzen, stellen Sie sicher, dass sie wie erwartet funktioniert.
- Testen Sie Funktionen wie Suchen, Hinzufügen und Löschen von Datensätzen mit unterschiedlichen Konten und Berechtigungen.
- Stellen Sie sicher, dass Berechtigungen wie erwartet arbeiten, indem Sie mit unterschiedlichen Konten testen. Vergewissern Sie sich, dass nicht autorisierte Benutzer nicht auf Ihre Daten zugreifen bzw. sie nicht ändern können.
- Testen Sie, ob sich Ihre Lösung gleich verhält, wenn sie in unterschiedlichen Betriebssystemen ausgeführt wird.
Überwachen des OData-Zugriffs
Der Server-Administrator verwendet FileMaker Customer Console, um den OData Listener zu starten bzw. zu stoppen, die OData-Aufrufnutzung zu überwachen und die OData-Protokolldatei herunterzuladen.
Für | Verwenden Sie |
---|---|
Starten oder Stoppen des OData Listener | Das FileMaker Customer Console-Register Konnektoren > OData. Weitere Informationen finden Sie in der FileMaker Cloud Hilfe in der Produktdokumentation. |
Überwachen der OData-Aufrufnutzung | Das FileMaker Customer Console-Register Konnektoren > OData. Dieses Register zeigt das OData-Jahreslimit, das Ihr FileMaker Cloud-Abonnement festlegt, die Datenmenge, die seit dem letzten jährlichen Rückstelldatum übertragen wurde, und das jährliche Rückstelldatum für Ihr Abonnement an. Wenn das Jahreslimit bald erreicht ist, können Sie das Limit über das FileMaker Customer Console-Register Abonnement erhöhen. Weitere Informationen finden Sie in der FileMaker Customer Console Hilfe in der Produktdokumentation. |
Anzeigen des OData API-Protokolls | Während OData-Clients mit einer Datenbank verbunden sind, werden Statistikdaten über die Clients in der Datei fmodata-log aufgezeichnet. Weitere Informationen finden Sie in der FileMaker Cloud Hilfe in der Produktdokumentation. |