FileMaker 17 Data API Handbuch
Über das FileMaker Data API
Übersicht
Das FileMaker® Data API ist ein Application Programming Interface (API), das Webdiensten ermöglicht, auf Daten in bereitgestellten Datenbanken zuzugreifen. Da dieses API der Representational-State-Transfer- (REST-) Architektur entspricht, ist das FileMaker Data API ein REST API.
Ihr Webdienst bzw. Ihre Anwendung ruft das FileMaker Data API auf, um einen Authentifizierungstoken für den Zugriff auf eine bereitgestellte Datenbank zu erhalten, und verwendet dann in nachfolgenden Aufrufen diesen Token, um Datensätze zu erstellen, zu aktualisieren und zu löschen sowie Suchabfragen durchzuführen.
Das FileMaker Data API gibt Daten in JavaScript-Object-Notation- (JSON-) Format zurück, einem Textformat, das häufig bei REST APIs verwendet wird, da es unabhängig von bestimmten Programmiersprachenformaten ist.
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, Beziehungen, Layouts, Ausschnitten und Containerfeldern verstehen. Siehe FileMaker Pro Advanced Hilfe.
- der Verwendung von FileMaker Server, um Datenbanken bereitzustellen. Sie sollten in der Lage sein, FileMaker Server einzusetzen, den Zugang zu bereitgestellten Datenbanken zu ermöglichen und bereitgestellte Datenbanken über FileMaker Server Admin Console zu überwachen. Siehe FileMaker Server Hilfe.
- der Verwendung von REST APIs in serverseitigen Anwendungen bzw. Webdiensten, die POST-, GET-, PATCH- und DELETE-Methoden mit Daten in JSON-Format aufrufen. Sie können Programmiersprachen und -werkzeuge je nach Wunsch einsetzen.
Um das FileMaker Data API zu verwenden, gehen Sie wie folgt vor:
- Bereiten Sie Ihre Datenbank für den FileMaker Data API-Zugriff mit FileMaker Pro Advanced vor. Sie können eine Datenbank neu erstellen oder eine vorhandene Datenbank vorbereiten. Siehe Vorbereiten von Datenbanken für FileMaker Data API-Zugriff.
- Schreiben Sie Programmcode, der FileMaker Data API-Methoden aufruft, um Datensätze in einer bereitgestellten Datenbank zu suchen, zu erstellen, zu bearbeiten und zu löschen. Siehe Schreiben von FileMaker Data API-Aufrufen.
- Stellen Sie Ihre Lösung mit FileMaker Server mit aktiviertem FileMaker Data API-Zugriff bereit. Siehe Bereitstellen einer FileMaker Data API-Lösung.
- Testen Sie, ob der FileMaker Data API-Zugriff korrekt funktioniert. Siehe Test einer FileMaker Data API-Lösung.
- Überwachen Sie Ihre bereitgestellte Lösung mithilfe von Admin Console. Siehe Überwachen von FileMaker Data API-Lösungen.
Bearbeitung eines FileMaker Data API-Aufrufs
REST API-Client
1
6
Web-Server
2
5
FileMaker Data API Engine
3
4
Datenbank-Server
-
Ein REST API-Client sendet einen FileMaker Data API-Aufruf (HTTPS-Abfrage) über den HTTPS-Port (Port 443) an den FileMaker Server-Web-Server. FileMaker Pro Advanced muss weder installiert sein noch ausgeführt werden.
- Der Web-Server leitet die Abfrage über das FileMaker Web-Server-Modul an die FileMaker Data API Engine weiter.
- Die FileMaker Data API Engine wandelt die HTTPS-Abfrage (URL und JSON-Daten) in ein Format um, das die Datenbank-Server-Komponente versteht, und fragt Daten von der vom Datenbank-Server bereitgestellten Datenbank ab.
- Der Datenbank-Server sendet die angeforderten FileMaker-Daten zurück an die FileMaker Data API Engine.
- Die FileMaker Data API Engine wandelt die FileMaker-Daten in eine HTTPS-Antwort (URL mit JSON-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.
Die FileMaker Data API Engine erfordert, dass die Ports 3000 und 8989 verfügbar sind.
Der Datenbank-Server erfordert, dass Port 5003 verfügbar ist.
Web Publishing-Alternativen
Wenn Sie keine Erfahrung in der Verwendung von REST APIs besitzen, können Sie die folgenden Alternativen in Erwägung ziehen, um Ihre FileMaker-Daten im Internet zu veröffentlichen.
FileMaker WebDirect™: Webbenutzer verbinden sich mit Ihrer auf FileMaker Server bereitgestellten Datenbank, um Datensätze anzuzeigen, zu bearbeiten, zu sortieren oder zu suchen, wenn Sie ihnen die entsprechenden Zugriffsrechte geben. Sie müssen keine zusätzliche Software installieren – lediglich kompatible Webbrowser-Software und der Zugang zum Internet bzw. zu einem Intranet sind erforderlich. Die Benutzeroberfläche ähnelt der FileMaker Pro Advanced-Desktop-Anwendung. Die Webseiten und Formulare, mit denen der Webbenutzer arbeitet, hängen von den in der FileMaker Pro Advanced-Datenbank definierten Layouts und Ansichten ab.
Informationen hierzu finden Sie im Handbuch FileMaker WebDirect.
Statische Veröffentlichung: Wenn sich Ihre Daten selten ändern oder wenn Sie keine Live-Verbindung Ihrer Benutzer zu Ihrer Datenbank wünschen, können Sie die Daten statisch veröffentlichen. Bei der statischen Veröffentlichung exportieren Sie die FileMaker Pro Advanced-Daten, um eine Webseite zu erstellen, die Sie anhand von HTML weiter anpassen können. Die Webseite ändert sich nicht, wenn sich Informationen in Ihrer Datenbank ändern, und die Benutzer stellen keine Verbindung zu Ihrer Datenbank her.
Siehe Veröffentlichen von Daten auf statischen Webseiten in der FileMaker Pro Advanced Hilfe.
Custom Web Publishing: Um Ihre FileMaker-Datenbank in eine individuelle Website zu integrieren, verwenden Sie die Techniken für Custom Web Publishing.
Weitere Informationen hierzu finden Sie im Handbuch FileMaker Server Custom Web Publishing.
Vorbereiten von Datenbanken für FileMaker Data API-Zugriff
Festlegen der Daten für den Zugriff
Sie können eine FileMaker Pro Advanced-Datenbank erstellen, die mit dem FileMaker Data API verwendet wird, oder eine bestehende Datenbank verwenden. Wenn Sie eine Datenbank erstellen, können Sie die Layouts und Felder anlegen, die Ihre FileMaker Data API-Lösung erfordert. Wenn Sie eine bestehende Datenbank verwenden, ziehen Sie in Betracht, ein Layout zu erstellen, das speziell für Ihre FileMaker Data API-Lösung gedacht ist.
FileMaker Data API-Aufrufe, die auf Datensatzdaten zugreifen, erfordern, dass Sie ein Layout angeben. Das FileMaker Data API verwendet die Standardansicht, die für das von Ihnen angegebene Layout definiert ist. Geben Sie ein Layout an, das die Formularansicht als Standardansicht für das Layout definiert. Wenn Sie ein Layout verwenden, das die Tabellenansicht als Standardansicht definiert, kann das FileMaker Data API keine Daten aus Bezugsdatensätzen abrufen.
Schützen Ihrer FileMaker Data API-Lösungen
Das FileMaker Data API benötigt Ihren REST API-Programmcode, um sich über ein passwortgeschütztes Konto bei einer Datenbanksitzung anzumelden. Weisen Sie Datenbankkonten, die für REST API-Zugriff verwendet werden, Passwörter zu oder verwenden Sie einen OAuth-Identitätsdienstleister für diese Konten.
Hinweis: Wenn Sie Kontonamen und Passwörter für FileMaker Data API-Lösungen definieren, verwenden Sie druckbare ASCII-Zeichen. Beispiel: a-z, A-Z und 0-9. Verwenden Sie für sicherere Kontonamen und Passwörter zudem Satzzeichen wie „!“ und „%“, aber verwenden Sie keine Doppelpunkte. Siehe FileMaker Pro Advanced Hilfe.
Aktivieren des FileMaker Data API
Sie müssen das erweiterte Zugriffsrecht „Zugriff über FileMaker Data API“ in jeder Datenbank verwenden, auf die mithilfe des FileMaker Data API zugegriffen werden soll. Wenn Sie das erweiterte FileMaker Data API-Zugriffsrecht nicht in der Datenbank aktivieren, können REST API-Anwendungen das FileMaker Data API nicht verwenden, um auf die Datenbank zuzugreifen, selbst wenn die Datenbank von FileMaker Server bereitgestellt wird.
So aktivieren Sie FileMaker Data API-Zugriff für eine Datenbank:
- Öffnen Sie die Datenbank in FileMaker Pro Advanced mit einem Konto, das über die Berechtigung für vollen Zugriff verfügt. Alternativ können Sie die Datenbank mit einem Konto öffnen, das über die Berechtigung „Erweiterte Zugriffsrechte verwalten“ verfügt.
- Aktivieren Sie im Register „Erweiterte Berechtigungen“ im Dialogfeld „Sicherheit verwalten“ das erweiterte Zugriffsrecht fmrest.
- Weisen Sie die Berechtigungen, die das erweiterte Zugriffsrecht „fmrest“ beinhalten, einem oder mehreren Konten zu.
Hinweis: Aktivieren Sie das erweiterte Zugriffsrecht „fmrest“ aus Sicherheitsgründen nur in den Berechtigungen für Konten, denen Sie den Zugriff auf Ihre bereitgestellte Datenbank erlauben wollen.
Siehe „Erstellen und Bearbeiten von Berechtigungen“ in der FileMaker Pro Advanced Hilfe.
Gestalten der FileMaker Data API-Lösung
FileMaker Data API-Funktionen
Das FileMaker Data API stellt ein REST API bereit, um auf Daten in bereitgestellten Datenbanken zuzugreifen. Das FileMaker Data API ermöglicht Ihrem Programmcode:
- sich bei einer bereitgestellten Datenbank an- und abzumelden. Siehe Herstellen bzw. Trennen der Verbindung zu einer Datenbank.
- einen Datensatz zu erstellen, zu bearbeiten, zu löschen oder abzurufen oder einen Datensatzbereich abzurufen. Siehe Arbeiten mit Datensätzen.
- Suchabfragen auszuführen. Siehe Suchen.
- Variablenfeldwerte zu setzen. Siehe Setzen von Variablenfeldwerten.
- FileMaker-Scripts auszuführen. Siehe FileMaker-Scripts und FileMaker Data API.
- den Upload von Daten in Containerfelder. Siehe Hochladen von Containerdaten.
- auf Daten in externen FileMaker-Tabellen zuzugreifen. Siehe Anmeldung bei einer externen Datenquelle.
- ein anderes Layout für Antwortdaten zu verwenden, wenn ein Datensatz oder ein Datensatzbereich abgerufen wird. Siehe Abrufen eines einzelnen Datensatzes, Abrufen eines Datensatzbereichs und Suchen.
Das FileMaker Data API unterstützt Folgendes nicht:
- den Zugriff auf Daten in externen ODBC-Datenquellen.
- FileMaker-Plugins.
- Script-Trigger durch Benutzerinteraktion aktivieren. Eine FileMaker Data API-Lösung kann Script-Trigger nur durch das Ausführen von FileMaker-Scripts aktivieren.
- Zugriff auf das Dateisystem des Servercomputers. Beispielsweise unterstützt das FileMaker Data API nicht die FileMaker Pro Advanced-Funktion „Hole (TemporärerPfad)“. Diese Funktion gibt eine leere Zeichenfolge zurück, wenn sie mit dem FileMaker Data API verwendet wird. Dateien lassen sich in einem Containerfeld speichern, jedoch gibt es keinen Zugriff auf das Dateisystem des Servers.
Das FileMaker Data API gibt Felddaten so zurück, wie sie in der Datenbank gespeichert sind, nicht wie sie in FileMaker Pro Advanced angezeigt werden.
FileMaker Data API-Referenzinformationen
Bei der Installation von FileMaker Server haben Sie die FileMaker Data API-Referenzdateien installiert. Diese Referenz stellt detaillierte Informationen über alle vom FileMaker Data API unterstützten Aufrufe bereit.
Hinweis:Damit die Referenzinformationen sichtbar sind, muss in Admin Console der Zugriff auf das FileMaker Data API aktiviert sein. Siehe FileMaker Server Hilfe.
- Um die Referenz in einem Browserfenster auf dem Mastercomputer anzuzeigen, geben Sie folgende URL ein:
https://localhost/fmi/data/apidoc/ - Um die Referenz in einem Browserfenster auf Remotecomputer anzuzeigen, geben Sie folgende URL ein:
https://host/fmi/data/apidoc/
Hierbei isthostdie IP-Adresse oder der Hostname des Mastercomputers, auf dem FileMaker Server ausgeführt wird. Auf einem Windows-Server befinden sich die Referenzdateien im Ordner
[Laufwerk]:\Programme\FileMaker\FileMaker Server\Documentation\Data API Documentation,
wobei[Laufwerk]das Laufwerk bezeichnet, auf dem Ihr FileMaker Server-Einsatz gespeichert ist.Wenn Sie unter Windows an einem anderen als dem Standardort installieren, ersetzt Ihr Installationsort den Beginn des Standard-Installationspfads
[Laufwerk]:[Installationsort]\Programme\FileMaker\FileMaker Server\Documentation\Data API Documentation- Auf einem macOS-Server befinden sich die Referenzdateien im Ordner
/Library/FileMaker Server/Documentation/Data API Documentation
Hinweise
- Die Referenzdateien zeigen Variablen in den URLs mithilfe eines Schlüsselworts, dem ein Doppelpunkt (:) vorangestellt ist. Beispiel:
:datenbank - Dieses Handbuch zeigt Variablen in den URLs in Kursivschrift. Beispiel:
datenbankname
Hinweise zu URLs und Datenformaten
- Es kann URLs oder URL-Teile geben, in denen Groß- und Kleinschreibung keine Rolle spielt, aber in der Regel sollten Sie URLs so behandeln, als würden Groß- und Kleinbuchstaben unterschieden. Beispiel: Wenn Sie einen Datenbanknamen in Kleinbuchstaben angeben, um sich bei einer Datenbanksitzung anzumelden, verwenden Sie diesen Datenbanknamen für alle weiteren URLs, die denselben Sitzungstoken übergeben, in Kleinbuchstaben. Anderenfalls können Sie eine Fehlermeldung über einen ungültigen Token erhalten.
- Zeichenfolgen in URLs müssen URL-Verschlüsselung, auch Prozent-Verschlüsselung genannt, verwenden, was für HTTP-Abfragen üblich ist. Um zum Beispiel einen Layoutnamen anzugeben, der einen Schrägstrich enthält, müssen Sie den Schrägstrich als verschlüsselten Wert angeben: "%2F"
- Zeichenfolgendatenwerte, die in Parametern im Hauptteil der Abfrage angegeben werden, müssen UTF-8-Kodierung verwenden.
- Generell behandelt das FileMaker Data API numerische Datenwerte so, als wären sie im Gleitkommaformat mit doppelter Genauigkeit (binary64). Verwenden Sie das entsprechende Datenformat in der Programmiersprache, die Sie nutzen. (Numerische Datenwerte sollten nicht in Anführungszeichen eingeschlossen sein und keine URL-Codierung verwenden.)
- Datenwerte für Zahlen-, Datums-, Zeit- und Zeitstempelfelder unterliegen denselben Beschränkungen wie durch FileMaker Pro Advanced vorgegeben. Siehe FileMaker Pro Advanced Hilfe.
- Die Felder und Ausschnitte, die Sie angeben, müssen sich in dem Layout befinden, das sie angeben.
- Um Bezugsfelder anzugeben, verwenden Sie die
portalData-Syntax.Hinweis:Die Syntax
tabellenname::bezugsfeld(wiederholungnummer).record-idaus der vorherigen Version wird immer noch unterstützt, aber dieportalData-Syntax wird bevorzugt. - Für Containerfelddaten gibt das FileMaker Data API eine URL mit dem Pfadverweis an das Containerdatenobjekt zurück.
FileMaker-Scripts und FileMaker Data API
FileMaker-Scripts können häufig ausgeführte Aufgaben automatisieren und mehrere Aufgaben kombinieren. In Kombination mit dem FileMaker Data API ermöglichen FileMaker-Scripts den Webdiensten, mehrere Aufgaben oder eine Aufgabenserie auszuführen. Siehe Ausführen von FileMaker-Scripts.
Um Scriptschritte zu sehen, die das FileMaker Data API unterstützt, klicken Sie im FileMaker Pro Advanced-Scriptarbeitsbereich auf Kompatibilität und wählen Sie FileMaker Data API. Scriptschritte, die nicht grau dargestellt werden, werden für das FileMaker Data API unterstützt. Einige Scriptschritte verhalten sich im FileMaker Data API anders als in FileMaker Pro Advanced. Siehe FileMaker Pro Advanced Hilfe.
Scripts in FileMaker Data API können keine Scripts in anderen FileMaker-Dateien ausführen, es sei denn, die Dateien werden auf derselben Installation von FileMaker Server bereitgestellt und das erweiterte Zugriffsrecht „fmrest“ ist in den anderen Dateien aktiviert.
In FileMaker Pro Advanced können sowohl Scripts als auch Benutzeraktionen (wie zum Beispiel ein Benutzer, der in ein Feld klickt) Script-Trigger aktivieren. In FileMaker Data API-Lösungen können jedoch nur Scripts Script-Trigger aktivieren. Informationen zu Script-Triggern finden Sie in der FileMaker Pro Advanced Hilfe.
Hinweise
- Beachten Sie die Datenmenge und die Anzahl der Datensätze, die ein Script zurückgeben kann, und definieren Sie die Scripts entsprechend. In FileMaker Pro Advanced kann ein Script alle Datensätze aus einer Tabelle oder der aktuellen Ergebnismenge zurückgeben. Wenn jedoch ein Script alle Datensätze aus einer Tabelle liefert, verfügt ein Webdienst möglicherweise nicht über genügend Arbeitsspeicher, um die Datensätze zu verarbeiten.
- Verwenden Sie Konten und Zugriffsrechte, um die Scripts einzuschränken, die ein Webdienst ausführen kann. Stellen Sie sicher, dass die Scripts nur Web-kompatible Scriptschritte enthalten und nur Zugang zu Scripts gewähren, die von einem Webdienst ausgeführt werden sollen.
- Berücksichtigen Sie die Nebeneffekte von Scripts, die eine Reihe 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 volle Zugriffsrechte, damit dieses Script Aufgaben ausführen kann, für die Sie dem Benutzer 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.
- Einige Scripts, die bei Ausführung im FileMaker Pro Advanced-Client nur einen Scriptschritt brauchen, benötigen eventuell den zusätzlichen Scriptschritt „Schreibe Änderung Datens./Abfrage“, wenn sie in einer FileMaker Data API-Lösung ausgeführt werden. Da Dienste nicht über eine direkte Verbindung zum Host verfügen, werden sie nicht benachrichtigt, wenn sich Daten ändern. Beispiel: Funktionen wie bedingte Wertelisten funktionieren möglicherweise nicht wie erwartet, da die Daten auf dem Host gespeichert werden müssen.
- 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. Viele Aktionen mit nur einem Scriptschritt sollten in Scripts umgewandelt werden, die den Schritt „Schreibe Änderung Datens./Abfrage“ enthalten. Wenn Sie Scripts entwerfen, die von einem Webdienst ausgeführt werden, nehmen Sie den Schritt „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 als FileMaker Data API-Lösung bereitgestellt wird. Stellen Sie sicher, dass das Script nur Scriptschritte verwendet, die vom FileMaker Data API wie oben beschrieben unterstützt werden.
Schreiben von FileMaker Data API-Aufrufen
REST API-Aufrufkomponenten
Die FileMaker Data API-Aufrufe bestehen aus den folgenden Komponenten.
| Komponente | Beschreibung |
|---|---|
Eine HTTP-Methode (auch als HTTP-Verb bezeichnet) |
Das FileMaker Data API verwendet die folgenden HTTP-Methoden:
|
HTTP-Header |
Das FileMaker Data API verwendet die folgenden Header:
|
| Eine Aufruf-URL | Die FileMaker Data API-URLs beginnen alle mit einer der folgenden Angaben:
|
| Parameterdaten in JSON-Format | Nicht nötig beim Abmelden von einer Datenbanksitzung, Löschen eines Datensatzes, Abrufen eines einzelnen Datensatzes oder Abrufen eines Datensatzbereichs. |
Herstellen bzw. Trennen der Verbindung zu einer Datenbank
Das FileMaker Data API verwendet einen Zugriffstoken, um eine Verbindung zu einer Datenbank zu definieren. Dieser Zugriffstoken muss im Header aller nachfolgenden Aufrufe an die bereitgestellte Datenbank verwendet werden. Der Zugriffstoken ist so lange gültig, bis Sie sich von der Datenbanksitzung abmelden, bzw. bis 15 Minuten nach dem letzten Aufruf, der diesen Token angegeben hat. (Während der Token gültig ist, setzt jeder Aufruf, der den Token angibt, den Zähler für das Zeitlimit der Sitzung wieder zurück.)
Anmelden bei einer Datenbanksitzung
Um sich bei einer bereitgestellten Datenbank anzumelden, verwenden Sie eine HTTP POST-Methode mit der sessions-URL, die den Namen einer bereitgestellten Datenbank angibt. Kontoname und Passwort werden in einer Authorization-Zeichenfolge im Header angegeben. Wenn der Kontoname und das Passwort authentifiziert sind, erhält Ihr Programmcode einen Zugriffstoken, der Ihre Verbindung zu der Datenbank definiert. Bei dieser Verbindung handelt es sich um eine so genannte Datenbanksitzung.
| HTTP-Methode | POST |
|---|---|
| URL | /fmi/data/v1/databases/datenbankname/sessions datenbankname – der Name der bereitgestellten Datenbank |
| HTTP-Header | Content-Type: application/json Authorization: eine Base64-kodierte Zeichenfolge, die den Kontonamen und das Passwort für die Anmeldung bei der bereitgestellten Datenbank angibt. Diese Base64-kodierte Zeichenfolge muss sich nach dem Schema der HTTP-Standardauthentifizierung richten. (Kontoname und Passwort sind durch einen Doppelpunkt getrennt.) |
| Parameter |
Leeres Paar geschweifte Klammern. Beispiel:
Kann optional den Parameter |
| Antwort | Der Zugriffstoken, ein leerer Antworthauptteil und ein Meldungsarray mit dem Fehlercode 0. Der Header X-FM-Data-Access-Token wird als Antwort zurückgegeben. Dabei handelt es sich um den Sitzungstoken, der für anschließende API-Aufrufe zu verwenden ist. Beispiel: X-FM-Data-Access-Token: 823c0f48bb80f2187bde6f3859dabd4dcf8ea43be420dfeadf34 { "response": {}, "messages":[{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
Anmeldung bei einer externen Datenquelle
Wenn sich Ihre bereitgestellte Datenbank bei einer externen Datenquelle anmelden muss, wird der Name der bereitgestellten Datenbank in der URL angegeben. Kontoname und Passwort für die bereitgestellte Datenbank werden in der Header-Zeichenfolge „Authorization“ angegeben. Datenbankname, Kontoname und Passwort für die externe Datenquelle werden im Parameter fmDataSource als ein JSON-Array angegeben.
| HTTP-Methode | POST |
|---|---|
| URL | /fmi/data/v1/databases/datenbankname/sessions datenbankname – der Name der bereitgestellten Datenbank |
| HTTP-Header | Content-Type: application/json Authorization: eine Base64-kodierte Zeichenfolge, die den Kontonamen und das Passwort für die Anmeldung bei der bereitgestellten Datenbank angibt. Diese Base64-kodierte Zeichenfolge muss sich nach dem Schema der HTTP-Standardauthentifizierung richten. |
| Parameter | Der Parameter Beispiel: { "fmDataSource": [ { "Datenbank":"Kontakte", "Benutzername":"admin", "Passwort":"admin" } ] }
Um ein OAuth-Konto für die Anmeldung bei der externen Datenquelle zu verwenden, geben Sie den Wert des Headers X-FMS-Request-ID ( { "fmDataSource": [ { "Datenbank":"Kontakte", "oAuthRequestId": "E65B98BB17429CO643B31119F", "oAuthIdentifier": "B164A3459A776E5177445DR223"} ] }
|
| Antwort | Der Zugriffstoken, ein leerer Antworthauptteil und ein Meldungsarray mit dem Fehlercode 0. Der Header X-FM-Data-Access-Token wird als Antwort zurückgegeben. Dabei handelt es sich um den Sitzungstoken, der für anschließende API-Aufrufe zu verwenden ist. Beispiel: X-FM-Data-Access-Token: c13c0f486780f2187bde6f3859dabd4dcf8ea43be420dfeadf34 { "response": {}, "messages":[{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
Hinweis:FileMaker-Datenbanken sind die einzigen unterstützten externen Datenquellen. Geben Sie den Datenbanknamen ohne die Dateinamenerweiterung .fmp12 an.
Anmelden bei einer Datenbanksitzung mithilfe eines OAuth-Identitätsdienstleisters
Verwenden Sie für die Anmeldung bei einer bereitgestellten Datenbank über einen OAuth-Identitätsdienstleister eine HTTP POST-Methode mit der sessions-URL, die die Datenbank angibt. Geben Sie die Zeichenfolge X-FM-Data-OAuth-Request-Id und die Zeichenfolge X-FM-Data-OAuth-Identifier im Header an, um den Zugriff auf die bereitgestellte Datenbank zu authentifizieren. Wenn die Authentifizierung akzeptiert wird, erhält Ihr Programmcode einen Zugriffstoken, der Ihre Verbindung zu der Datenbank definiert. Bei dieser Verbindung handelt es sich um eine so genannte Datenbanksitzung.
| HTTP-Methode | POST |
|---|---|
| URL | /fmi/data/v1/databases/datenbankname/sessions datenbankname – der Name der bereitgestellten Datenbank |
| HTTP-Header | Content-Type: application/json X-FM-Data-OAuth-Request-Id: Abfrage-ID X-FM-Data-OAuth-Identifier: ID-Parameter |
| Parameter |
Leeres Paar geschweifte Klammern. Beispiel: Kann optional den Parameter |
| Antwort | Der Zugriffstoken, ein leerer Antworthauptteil und ein Meldungsarray mit dem Fehlercode 0. Der Header X-FM-Data-Access-Token wird als Antwort zurückgegeben. Dabei handelt es sich um den Sitzungstoken, der für anschließende API-Aufrufe zu verwenden ist. Beispiel: X-FM-Data-Access-Token: 823c0f48bb80f2187bde6f3859dabd4dcf8ea43be420dfeadf34 { "response": {}, "messages":[{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
So erhalten Sie die OAuth-Parameter in JSON-Format:
-
Rufen Sie die Liste unterstützter OAuth-Dienstleister ab, indem Sie eine HTTP GET-Methode mit dieser URL verwenden:
https://host/fmws/oauthproviderinfoDabei steht host für die IP-Adresse oder den Domänennamen des Mastercomputers Ihres FileMaker Server-Einsatzes. Die Liste wird in JSON-Format zurückgegeben.
- Wählen Sie einen unterstützten OAuth-Dienstleister und rufen Sie eine Tracking-ID für Ihre Sitzung ab.
-
Verwenden Sie eine HTTP GET-Methode mit dieser URL:
http://host/oauth/getoauthurl?trackingID=Tracking-ID&provider=OAuth-Dienstleister&address=127.0.0.1&X-FMS-OAuth-AuthType=2Dabei steht host für die IP-Adresse bzw. den Domänennamen des Mastercomputers in Ihrem FileMaker Server-Einsatz, Tracking-ID für die vom Entwickler generierte Tracking-ID für Ihre Sitzung und OAuth-Dienstleister für den Namen des von Ihnen ausgewählten OAuth-Dienstleisters.
Der HTTP-Header für diese Abfrage muss Folgendes beinhalten:
- X-FMS-Application-Type: 9
- X-FMS-Application-Version: 15
- X-FMS-Return-URL: http://127.0.0.1/
- Lesen Sie den Antwortheader für die X-FMS-Request-ID-Daten. Dieser Antwortheader enthält die OAuth-Request-ID, die Sie für die Zeichenfolge X-FM-Data-OAuth-Request-ID im Header verwenden werden.
- Lesen Sie den Antwortheader für die X-FMS-Return-URL-Daten. Rufen Sie die URL auf, die dieser Parameter zurückgibt, damit der Benutzer sich beim OAuth-Dienstleister authentifizieren kann.
- Der vom OAuth-Dienstleister zurückgegebene „Identifier“ ist der OAuth-Identifier-Parameter, den Sie für die Zeichenfolge X-FM-Data-OAuth-Identifier im Header verwenden werden.
Siehe „Erstellen von Konten, die über einen OAuth-Identitätsdienstleister authentifiziert werden“ in der FileMaker Pro Advanced Hilfe.
Abmeldung aus einer Datenbanksitzung
Wenn der Zugriff auf die bereitgestellte Datenbank durch Ihren Programmcode abgeschlossen ist, verwenden Sie eine HTTP DELETE-Methode mit der sessions-URL, die den Namen der bereitgestellten Datenbank und den Zugriffstoken für die Sitzung angibt. Wenn Ihr Programmcode sich nicht von der Datenbanksitzung abmeldet, wird der Zugriffstoken ungültig, sobald die FileMaker Data API-Sitzung eine Zeit von 15 Minuten nach dem letzten Aufruf dieses angegebenen Tokens überschreitet.
| HTTP-Methode | DELETE |
|---|---|
| URL | /fmi/data/v1/databases/datenbankname/sessions/session-token datenbankname – der Name der bereitgestellten Datenbank session-token – der X-FM-Data-Access-Token für die Datenbanksitzung |
| HTTP-Header | Content-Type: application/json |
| Parameter | Keine |
| Antwort |
Ein leerer Antworthauptteil und ein Meldungsarray mit dem Fehlercode 0. Beispiel: { "response": {}, "messages":[{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
Mit Datensätzen arbeiten
Datensatz erstellen
Um einen Datensatz zu erstellen, verwenden Sie eine HTTP POST-Methode mit der records-URL, die Datenbankname und Layout angibt.
| HTTP-Methode | POST |
|---|---|
| URL | /fmi/data/v1/databases/datenbankname/layouts/layoutname/records datenbankname – der Name der bereitgestellten Datenbank |
| HTTP-Header | Content-Type: application/json Authorization: session-token des Inhabers, wobei session-token den eindeutigen Wert des X-FM-Data-Access-Token für die Datenbanksitzung darstellt |
| Parameter | Datensatzdaten in JSON-Format mit Feld-Wert-Paaren, die Werte für Felder angeben, die sich im Ziellayout befinden. Die Daten können mithilfe von „portalData“ Bezugsdatensätze oder Ausschnitte angeben, die sich in dem Layout befinden. Ein Ausschnittname kann entweder der im Inspektor in FileMaker Pro Advanced angegebene Objektname oder der Name der Bezugstabelle sein. Beispiel: {"fieldData": { "Zeichenfeld": "wert_1", "Zahlenfeld": 99.99, "wiederholungFeld(1)" : "feldWert" } }
Hinweis:Um einen leeren Datensatz mit den Standardwerten für ein Feld abzugeben, geben Sie ein leeres Datenobjekt in JSON-Format als Parameter ein. Beispiel: {"fieldData": { } }
Sie können FileMaker-Scripts als Teil dieser Abfrage ausführen, indem Sie die Parameter |
| Antwort |
Die Datensatz-ID des Datensatzes, der erstellt wurde, und ein Meldungsarray, das nur den Fehlercode 0 zeigt. Beispiel: { "response": {"recordId":147}, "messages":[{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
Hinweise
- Wenn Sie Datensätze mithilfe des FileMaker Data API erstellen, wird die Feldwertüberprüfung durchgesetzt. Wenn die Daten die Feldwertüberprüfung nicht bestehen, erhalten Sie eine Fehlermeldung und der Datensatz wird nicht erstellt.
Bearbeiten eines Datensatzes
Um einen Datensatz zu bearbeiten, verwenden Sie eine HTTP PATCH-Methode mit der records-URL, die Datenbankname, Layout und Datensatz-ID angibt.
| HTTP-Methode | PATCH |
|---|---|
| URL | /fmi/data/v1/databases/datenbankname/layouts/layoutname/records/record-id datenbankname – der Name der bereitgestellten Datenbank |
| HTTP-Header |
Content-Type: application/json Authorization: session-token des Inhabers, wobei session-token den eindeutigen Wert des X-FM-Data-Access-Token für die Datenbanksitzung darstellt |
| Parameter | Datensatzdaten in JSON-Format mit Feld-Wert-Paaren, die Sie aktualisieren möchten. Die Daten können mithilfe von „portalData“ Bezugsdatensätze oder Ausschnitte angeben, die sich in dem Layout befinden. Ein Ausschnittname kann entweder der im Inspektor in FileMaker Pro Advanced angegebene Objektname oder der Name der Bezugstabelle sein.
Nur die Felder, die Sie angeben, werden aktualisiert. Andere Felder im Datensatz werden nicht geändert. Wenn „{}“ als Optionaler Parameter: Änderungs-ID ( Beispiel: { "fieldData": { "Vorname": "Joe", }, "portalData": { "JobsTable": [ { "recordId": 70, "modId": 4, "Job::Name": "Auftragnehmer" } ] } }
Sie können FileMaker-Scripts als Teil dieser Anforderung ausführen, indem Sie die Parameter |
| Antwort |
Ein leerer Antworthauptteil und ein Meldungsarray mit dem Fehlercode 0. Beispiel: { "response": {}, "messages":[{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
Hinweise
- Wenn Sie Datensätze mithilfe des FileMaker Data API bearbeiten, wird die Feldwertüberprüfung durchgesetzt. Wenn die Daten die Feldwertüberprüfung nicht bestehen, erhalten Sie eine Fehlermeldung und der Datensatz wird nicht aktualisiert.
-
Um einen Bezugsdatensatz zu löschen, verwenden Sie die Syntax
deleteRelated.Beispiel:
"deleteRelated" : "Bestellungen.3"Pro Aufruf zum Löschen von Datensätzen kann nur ein Datensatz gelöscht werden.
Datensatz löschen
Um einen Datensatz zu löschen, verwenden Sie eine HTTP DELETE-Methode mit der records-URL, die Datenbankname, Layout und Datensatz-ID angibt.
| HTTP-Methode | DELETE |
|---|---|
| URL | /fmi/data/v1/databases/datenbankname/layouts/layoutname/records/record-id datenbankname – der Name der bereitgestellten Datenbank Sie können FileMaker-Scripts als Teil dieser Abfrage ausführen, indem Sie die Parameter |
| HTTP-Header | Authorization: session-token des Inhabers, wobei session-token den eindeutigen Wert des X-FM-Data-Access-Token für die Datenbanksitzung darstellt |
| Parameter | Keine |
| Antwort |
Ein leerer Antworthauptteil und ein Meldungsarray mit dem Fehlercode 0. Beispiel: { "response": {}, "messages":[{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
Abrufen eines einzelnen Datensatzes
Um einen Datensatz abzurufen, verwenden Sie eine HTTP GET-Methode mit der records-URL, die Datenbankname, Layout und Datensatz-ID angibt. Sie können zudem Ausschnittinformationen angeben, um die Anzahl der zurückgegebenen Bezugsdatensätze zu begrenzen.
| HTTP-Methode | GET |
|---|---|
| URL | Format 1: /fmi/data/v1/databases/datenbankname/layouts/layoutname/records/record-id
datenbankname – der Name der bereitgestellten Datenbank Für das Schlüsselwort „portal“: Der Ausschnittteil der URL ist optional. Wenn das Layout Ausschnitte umfasst, geben Sie die Ausschnittnamen an, um die Leistung zu optimieren. Wenn der Ausschnittteil weggelassen wird, gibt der Aufruf alle Bezugsdatensätze in allen Ausschnitten im Layout zurück. Für Für Wenn Sie die Antwortdaten im Kontext eines anderen Layouts wünschen, verwenden Sie den Parameter Sie können FileMaker-Scripts als Teil dieser Abfrage ausführen, indem Sie die Parameter |
| HTTP-Header | Authorization: session-token des Inhabers, wobei session-token den eindeutigen Wert des X-FM-Data-Access-Token für die Datenbanksitzung darstellt |
| Parameter | Keine |
| Antwort |
Die Datensatzdaten in JSON-Format und ein Meldungsarray, das den Fehlercode 0 zeigt. Beispiel: { "response": { "data": [ ... ] }, "messages": [{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
Hinweise
- Um Daten für bestimmte Ausschnittzeilen zurückzugeben, verwenden Sie
_offset.ausschnittnameund_limit.ausschnittname, wobei ausschnittname den Namen für den Ausschnitt im Inspektor in FileMaker Pro Advanced angibt. Wenn Sie die Versatz- und Limit-Werte für Ausschnittzeilen weglassen, ist der Standard für Versatz 1 und für Limit 50.
Abrufen eines Datensatzbereichs
Um einen Bereich von Datensätzen abzurufen, verwenden Sie eine HTTP GET-Methode, wobei die records-URL den Datenbanknamen, das Layout und weitere Informationen enthält, um einen Startdatensatz und die Anzahl der Datensätze anzugeben. Optional können Sie die Sortierfolge der Datensätze angeben. Sie können zudem Ausschnittinformationen angeben, um die Anzahl der zurückgegebenen Bezugsdatensätze zu begrenzen.
| HTTP-Methode | GET |
|---|---|
| URL |
Format 1 (gibt maximal die ersten 100 Datensätze zurück): datenbankname – der Name der bereitgestellten Datenbank Für Für Die Angabe Für das Schlüsselwort „portal“: Der Ausschnittteil der URL ist optional. Wenn das Layout Ausschnitte umfasst, geben Sie die Ausschnittnamen an, um die Leistung zu optimieren. Wenn der Ausschnittteil weggelassen wird, gibt der Aufruf alle Bezugsdatensätze in allen Ausschnitten im Layout zurück. Für Für Wenn Sie die Antwortdaten im Kontext eines anderen Layouts wünschen, verwenden Sie den Parameter
Sie können FileMaker-Scripts als Teil dieser Abfrage ausführen, indem Sie die Parameter |
| HTTP-Header | Authorization: session-token des Inhabers, wobei session-token den eindeutigen Wert des X-FM-Data-Access-Token für die Datenbanksitzung darstellt |
| Parameter | Keine |
| Antwort |
Die Datensatzdaten in JSON-Format und ein Meldungsarray, das den Fehlercode 0 zeigt. Beispiel: { "response": { "data": [ ... ] }, "messages": [{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
Hinweise
- Wenn Sie die Versatz- und Limit-Werte weglassen, ist der Standard für Versatz 1 und für Limit 100:
_offset=1&_limit=100 - Wenn Sie das Schlüsselwort „sortOrder“ weglassen, ist der Standard
ascend. Beispiel:&_sort=[{ "fieldName": "recordId" }]wird identisch behandelt wie:&_sort=[{ "fieldName": "recordId", "sortOrder": "ascend" }] - Um Daten für bestimmte Ausschnittzeilen zurückzugeben, verwenden Sie
_offset.ausschnittnameund_limit.ausschnittname, wobei ausschnittname den Namen für den Ausschnitt im Inspektor in FileMaker Pro Advanced angibt. Wenn Sie die Versatz- und Limit-Werte für Ausschnittzeilen weglassen, ist der Standard für Versatz 1 und für Limit 50.
Hochladen von Containerdaten
Verwenden Sie zum Hochladen von Containerdaten eine HTTP POST-Methode mit der containers-URL und geben Sie Datenbankname, Layoutname, Datensatz-ID, Feldname und eine Feldwiederholung an.
| HTTP-Methode | POST |
|---|---|
| URL | Format: /fmi/data/v1/databases/datenbankname/layouts/layoutname/records/record-id/containers/feldname/feld-wiederholung
|
| HTTP-Header |
Content-Type: multipart/form-data Authorization: session-token des Inhabers, wobei session-token den eindeutigen Wert des X-FM-Data-Access-Token für die Datenbanksitzung darstellt |
| Parameter | Ein mehrteiliger MIME-Datenstrom (Content-Type: multipart/form-data), in dem das Containerfeld als ein Teil mit Verwenden Sie eine Bibliothek, die die Angabe von „multipart/form-data“ unterstützt. |
| Antwort |
Ein leerer Antworthauptteil und ein Meldungsarray mit dem Fehlercode 0. Beispiel: { "response": {}, "messages":[{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
Hinweise
- Das Containerfeld muss ein Feld im Tabellenauftreten des angegebenen Layouts sein. Es kann kein Containerfeld in einer Bezugstabelle sein.
- Das FileMaker Data API erlaubt alle MIME-Typen. Die MIME-Typen werden nicht geprüft, um sie auf die von FileMaker-Software oder dem Web-Server unterstützten Typen zu beschränken.
- Das FileMaker Data API legt die Containerfelddaten in einem Cache-Ordner auf dem Mastercomputer ab, wenn sie hochgeladen werden. Jedoch werden die im Cache gespeicherten Daten nach Abschluss der Abfrage gelöscht.
Suchen
Um eine Suchabfrage auszuführen, verwenden Sie eine HTTP POST-Methode mit der _find-URL, die den Datenbanknamen und das Layout sowie zusätzliche Informationen angibt, um Abfragefelder und Kriterien, Sortierfolge, Startdatensatz und Anzahl der Datensätze anzugeben. Sie können zudem Ausschnittinformationen angeben, um die Anzahl der zurückgegebenen Bezugsdatensätze zu begrenzen.
| HTTP-Methode | POST |
|---|---|
| URL |
/fmi/data/v1/databases/datenbankname/layouts/layoutname/_find datenbankname – der Name der bereitgestellten Datenbank |
| HTTP-Header |
Content-Type: application/json Authorization: session-token des Inhabers, wobei session-token den eindeutigen Wert des X-FM-Data-Access-Token für die Datenbanksitzung darstellt |
| Parameter | Eine Abfrage in JSON-Format, die Felder und Suchkriterien angibt. Optionale Parameter geben Ausschlussabfragen, Sortierfolge, Startdatensatz (Versatz), Anzahl der Datensätze (Limit) und Ausschnitte für die Begrenzung der Anzahl an Bezugsdatensätzen an, die zurückgegeben werden. Wenn Sie die Antwortdaten im Kontext eines anderen Layouts wünschen, verwenden Sie den Parameter Beispiel: { "query":[ {"Group": "=Chirurg"}, {"Ort" : "NY", "omit" : "true"}], "sort":[ {"fieldName": "Ort","sortOrder": "ascend"}, {"fieldName": "Vorname", "sortOrder": "ascend"} ] }
Beispiel mit Versatz, Limit und Ausschnitten: { "query":[ {"Group": "=Chirurg"}, {"Ort" : "NY", "omit" : "true"}], "portal": ["Ausschnitt1","Ausschnitt2"], "limit": "10", "offset": "1", "offset.Ausschnitt1": "1", "limit.Ausschnitt1": "5", "layout.response": "Ärzte" }
Sie können FileMaker-Scripts als Teil dieser Abfrage ausführen, indem Sie die Parameter |
| Antwort |
Die Datensatzdaten in JSON-Format und ein Meldungsarray, das den Fehlercode 0 zeigt. Beispiel: { "response": { "data": [ ... ] }, "messages": [{"code":"0","message":"OK"}] }
Siehe Fehlerantworten. |
Hinweise
- In einer Datenbank mit vielen Bezugsdatensätzen kann das Abfragen und Sortieren von Ausschnittdatensätzen ziemlich zeitaufwendig sein. Um die Anzahl der Datensätze und der anzuzeigenden Zeilen in einer Bezugsmenge zu begrenzen, geben Sie die Parameter offset.ausschnittname und _limit.ausschnittname an.
- Variablenfelder können Sie nicht als Suchkriterien angeben. Wenn Sie eine Variable in einer Suchabfrage angeben, erhalten Sie eine Fehlermeldung. Setzen Sie den Variablenfeldwert stattdessen vor der Suchabfrage. Siehe Setzen von Variablenfeldwerten.
Setzen von Variablenfeldwerten
Um die Werte von Variablenfeldern zu setzen, verwenden Sie eine HTTP PATCH-Methode mit der globals-URL, die den Datenbanknamen angibt.
| HTTP-Methode | PATCH |
|---|---|
| URL | /fmi/data/v1/databases/datenbankname/globals datenbankname – der Name der bereitgestellten Datenbank |
| HTTP-Header |
Content-Type: application/json Authorization: session-token des Inhabers, wobei session-token den eindeutigen Wert des X-FM-Data-Access-Token für die Datenbanksitzung darstellt |
| Parameter | Ein JSON-Objekt mit Feld-und-Wert-Paaren, die die zu setzenden Variablenfelder angeben. Die Variablenfelder müssen mit vollständig qualifizierten Feldnamen (tabellenname::feldname) angegeben werden. Beispiel: { "globalFields": { "basisTabelle::vFirma":"FileMaker", "basisTabelle::vCode":"95054" } }
|
| Antwort |
Ein leerer Antworthauptteil und ein Meldungsarray mit dem Fehlercode 0. Beispiel: { "response": {}, "messages":[{"code":"0","message":"OK"}] }
|
Ausführen von FileMaker-Scripts
| Parameter | Wert |
|---|---|
script
|
Der Name des Scripts, das ausgeführt werden soll, nachdem die vom API-Aufruf angegebene Aktion (abrufen, erstellen, bearbeiten, löschen, suchen) und die anschließende Sortierung abgeschlossen sind. |
script.param
|
Die Textzeichenfolge, die als Parameter für das durch script angegebene Script fungieren soll.
|
script.prerequest
|
Der Name des Scripts, das vor der vom API-Aufruf angegebenen Aktion und der anschließenden Sortierung ausgeführt werden soll. |
script.prerequest.param
|
Die Textzeichenfolge, die als Parameter für das durch script.prerequest angegebene Script fungieren soll.
|
script.presort
|
Der Name des Scripts, das nach der vom API-Aufruf angegebenen Aktion, jedoch vor der anschließenden Sortierung ausgeführt werden soll. |
script.presort.param
|
Die Textzeichenfolge, die als Parameter für das durch script.presort angegebene Script fungieren soll.
|
Ausführungsreihenfolge von Scripts
Sie können die Parameter script.prerequest, script.presort und script in einem einzigen API-Aufruf angeben. Jedes Schlüsselwort kann nur einmal angegeben werden. FileMaker Server verarbeitet diese Parameter als Teil des API-Aufrufs in dieser Reihenfolge:
- Wechsel in das Layout, das im Script angegeben ist
- Ausführen des durch
script.prerequestbezeichneten Scripts, falls angegeben - Ausführen der durch den API-Aufruf angegebenen Aktion (abrufen, erstellen, bearbeiten, löschen, suchen)
- Ausführen des durch
script.presortbezeichneten Scripts, falls angegeben - Ausführen der im API-Aufruf angegebenen Sortierung:
- Für Abrufen eines Datensatzbereichs Ausführen der durch den Parameter
_sortangegebenen Sortierung - Für Suchen Ausführen der durch den Parameter
sortangegebenen Sortierung
- Für Abrufen eines Datensatzbereichs Ausführen der durch den Parameter
- Ausführen des durch
scriptbezeichneten Scripts, falls angegeben - Zurückgeben der Ergebnismenge für den API-Aufruf mit angewandten offset- und limit-Parametern, sofern angegeben
Hinweise
- Für Aufrufe, die die HTTP GET- und HTTP DELETE-Methode verwenden, werden diese Scriptparameter als URL-Parameter angegeben. Siehe dazu Abrufen eines einzelnen Datensatzes, Abrufen eines Datensatzbereichs und Löschen eines Datensatzes.
- Für Aufrufe, die die HTTP POST- und HTTP PATCH-Methoden verwenden, werden die Scriptparameter im Hauptteil der Abfrage angegeben. Siehe Erstellen eines Datensatzes, Bearbeiten eines Datensatzes und Suchen.
- Für die Scriptparameter
script.param,script.prerequest.paramundscript.presort.paramkönnen Sie nur eine einzige Textzeichenfolge angeben. Um mehrere Parameter zu übergeben, können Sie einen String erstellen, der die Parameter begrenzt, und Ihr Script die einzelnen Parameter auslesen lassen. Übergeben Sie z. B. „param1|param2|param3“ als Liste mit dem Zeichen |, die so URL-kodiert ist:param1%7Cparam2%7Cparam3
Beispiel:
https://<host>/fmi/data/v1/databases/kunden/layouts/eingabe/records/14?script=UpdateVerarbeitung&script.param=14
Beispiel:
{"query":[{"Titel":"Büroleiter"}], "script.prerequest":"Duplikate entfernen"}
Fehlerantworten
Wenn ein Fehler auftritt, gibt das FileMaker Data API Folgendes zurück:
- einen HTTP 400-Level-Statuscode für Standard-HTTP-Fehler
- einen HTTP 500-Statuscode für FileMaker Server-Fehler
| HTTP-Statuscode | HTTP-Kategorie | Beschreibung |
|---|---|---|
| 400 | Ungültige Abfrage | Tritt auf, wenn der Server die Abfrage aufgrund eines Client-Fehlers nicht bearbeiten kann. |
| 401 | Nicht autorisiert | Tritt auf, wenn der Client nicht autorisiert ist, auf das API zuzugreifen. Wenn dieser Fehler bei dem Versuch auftritt, sich bei einer Datenbanksitzung anzumelden, gibt es ein Problem mit dem angegebenen Benutzerkonto bzw. Passwort. Wenn dieser Fehler bei anderen Aufrufen auftritt, wurde der Zugriffstoken nicht angegeben oder ist nicht gültig. |
| 403 | Gesperrt | Tritt auf, wenn der Client autorisiert ist, aber der Aufruf eine Aktion versucht, die aus einem anderen Grund gesperrt ist. |
| 404 | Nicht gefunden | Tritt auf, wenn der Aufruf eine URL mit einem ungültigen URL-Schema verwendet. Prüfen Sie die angegebene URL auf Syntaxfehler. |
| 405 | Methode nicht erlaubt | Tritt auf, wenn mit einem Aufruf eine fehlerhafte HTTP-Methode verwendet wird. |
| 415 | Nicht unterstützter Medientyp | Tritt auf, wenn der erforderliche Header fehlt oder für die Abfrage nicht korrekt ist:
|
| 500 | FileMaker Server-Fehler | Enthält FileMaker-Fehlermeldungen und -Fehlercodes. Weitere Informationen hierzu finden Sie unter FileMaker-Fehlercodes in der FileMaker Pro Advanced Hilfe. |
Hinweise
- Wenn die FileMaker Data API Engine nicht läuft oder nicht erreichbar ist, hängen die zurückgegebenen Fehlercodes oder -meldungen von Ihrem Web-Server (Apache oder IIS) ab.
- Weitere Informationen zu zusätzlichen HTTP-Statuscodes, die zurückgegeben werden, finden Sie unter www.w3.org.
Bereitstellen, Testen und Überwachen von FileMaker Data API-Lösungen
Bereitstellen einer FileMaker Data API-Lösung
- Arbeiten Sie alle Schritte unter Vorbereiten von Datenbanken für FileMaker Data API-Zugriff durch.
- Stellen Sie sicher, dass der FileMaker Data API-Zugriff in Admin Console aktiviert und richtig konfiguriert wurde. Siehe FileMaker Server Hilfe.
- Stellen Sie sicher, dass der Web-Server und die FileMaker Data API Engine ausgeführt werden.
-
Verschlüsseln Sie die Kommunikation.
Das FileMaker Data API verlangt, dass Ihre REST API-Anwendungen eine HTTPS-Verbindung verwenden. HTTPS-Verbindungen verwenden Secure-Sockets-Layer- (SSL-) Verschlüsselung für die Kommunikation.
FileMaker Server bietet ein von FileMaker, Inc. signiertes Standard-SSL-Zertifikat an, das den Servernamen nicht prüft. Das Standardzertifikat von FileMaker dient nur für Testzwecke. Ein eigenes SSL-Zertifikat wird für die Produktion benötigt. Siehe FileMaker Server Installation und Konfiguration.
Die Programmiersprache bzw. Technologie, die Sie verwenden, um das FileMaker Data API aufzurufen, muss Transport Layer Security (TLS) v1.2 unterstützen, um mit dem Web-Server zu kommunizieren.
Testen einer FileMaker Data API-Lösung
Bevor Sie Ihre FileMaker Data 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 von unterschiedlichen Betriebssystemen aufgerufen wird.
Überwachen von FileMaker Data API-Lösungen
Der Server-Administrator kann Admin Console verwenden, um die FileMaker Data API Engine zu starten und zu stoppen, FileMaker Data API-Clients zu überwachen, die Verwendung von FileMaker Data API-Aufrufen zu überwachen und die FileMaker Data API-Protokolldatei herunterzuladen.
| Für | Verwenden Sie |
|---|---|
| Starten oder stoppen der FileMaker Data API Engine | Das Admin Console-Register Konnektoren > FileMaker Data API oder einen CLI-Befehl. Siehe „Starten und Stoppen von FileMaker Server-Komponenten“ in der FileMaker Server Hilfe. |
| Überwachen von FileMaker Data API-Clients | Die Clients-Liste auf der Admin Console-Seite Datenbanken. Diese Seite zeigt die Details zu den Clients und Datenbanken, auf die zugegriffen wird. Siehe „Verwalten von Clients“ in der FileMaker Server Hilfe. Von dieser Seite aus trennen Sie FileMaker Data API-Clients, können ihnen aber keine Meldungen senden. |
| Überwachen der Verwendung von FileMaker Data API-Aufrufen | Das Admin Console-Register Konnektoren > FileMaker Data API. Dieses Register zeigt das FileMaker Data API-Jahreslimit, das durch Ihre FileMaker Server-Lizenz festgelegt ist, wie viele Daten bereits in dieser Lizenzperiode übertragen wurden, und das Verlängerungsdatum für Ihre Lizenz. Wenn das Jahreslimit bald erreicht ist, können Sie es im Admin Console-Register Administration > FileMaker-Lizenzen erhöhen. Siehe „FileMaker Data API-Einstellungen“ in der FileMaker Server Hilfe. |
| Anzeigen des FileMaker Data API-Protokolls |
Während FileMaker Data API-Clients mit einer Datenbank verbunden sind, werden Statistikdaten über die Clients im Protokoll fmdapi.log aufgezeichnet. Siehe „FileMaker Data API-Protokoll“ in der FileMaker Server Hilfe. |
FileMaker Data API-Integration mit Tableau
Über die Integration mit Tableau
FileMaker Server beinhaltet den Tableau Web Data Connector, eine Beispielimplementierung, die REST API-Aufrufe in JSON-Format akzeptiert. Verwenden Sie den Tableau Web Data Connector, um eine Verbindung zwischen FileMaker Server und Tableau Desktop zu definieren. Die Verbindung verwendet das FileMaker Data API, um Daten von bereitgestellten FileMaker-Datenbanken in Tableau Desktop zu importieren.
Anforderungen für den Tableau Web Data Connector
- Tableau Desktop, mindestens Version 10, für Windows oder macOS.
- Eine passwortgeschützte FileMaker Pro Advanced-Datenbank mit den zu importierenden Daten. Die Datenbank muss von FileMaker Server bereitgestellt werden.
-
Einen gültigen REST API-Endpunkt. Für FileMaker Server ist der Endpunkt ein HTML-Verbindungspunkt, der für Webdienste nötige Informationen bereitstellt. Der Endpunkt hat folgendes Format:
https://<hostname>/fmi/data/v1/tableau/fm_connector.html
Dabei isthostnameder vollständig qualifizierte Hostname Ihres FileMaker Servers.Beispiel:
https://meinserver.firma.com/fmi/data/v1/tableau/fm_connector.html Ein gültiges eigenes SSL-Zertifikat auf FileMaker Server. Der Tableau Web Data Connector lässt den Import von Daten von FileMaker Server nicht ohne ein eigenes gültiges SSL-Zertifikat zu. Wenn Ihr Server ein Zwischenzertifikat benötigt, muss dieses auf dem Server installiert werden, auf dem FileMaker Server eingesetzt wird. Starten Sie den Servercomputer neu, nachdem Sie die Änderungen am installierten Zertifikat vorgenommen haben, und verbinden Sie ihn erst danach mit Tableau.
Hinweis:Wenn Ihr Server ein Subject-Alternative-Name- (SAN-) Zertifikat verwendet, muss der Hostname mit dem Common Name im SAN-Zertifikat übereinstimmen.
Vorbereiten des Datenimports in Tableau
Folgen Sie der Anleitung unter Vorbereiten von Datenbanken für den FileMaker Data API-Zugriff, um das Layout für den Import zu definieren und die Datenbank für FileMaker Data API-Zugriff zu aktivieren.
Hinweis:Um Daten in Tableau zu importieren, muss die Tabelle mindestens einen Datensatz mit Datensatzdaten enthalten.
Die folgenden FileMaker-Feldtypen werden als Tableau-Datentypen importiert.
| FileMaker-Feldtyp | Tableau-Datentyp |
|---|---|
| Text | string |
| Datum | date |
| Zeit | string |
| Zeitstempel | datetime |
| Zahl | float |
Die folgenden FileMaker-Feldtypen werden beim Import in Tableau nicht unterstützt:
- Containerfelder
- Statistikfelder. Sie können ein Statistikfeld in Tableau basierend auf den Daten erstellen, die Sie aus FileMaker importieren.
- Formelfelder. Sie können ein Formelfeld in Tableau basierend auf den Daten erstellen, die Sie aus FileMaker importieren.
- Diagrammdaten
- Daten aus FileMaker Pro Advanced-Ausschnitten. Um Daten aus Bezugsdatensätzen zu importieren, erstellen Sie ein FileMaker Pro Advanced-Layout basierend auf der Bezugstabelle oder importieren Sie Daten aus separaten FileMaker Pro Advanced-Tabellen in Tableau und verknüpfen Sie die Tabellen dann in Tableau.
- Feldwiederholungen, bei denen die Anzeige von Wiederholfeldern für Wiederholungen anzeigen mehrere Werte umfasst. Eine einzelne Wiederholung wird unterstützt.
- Nicht numerische Werte in Zahlenfeldern. Wenn Tableau nicht numerische Werte in Zahlenfeldern erkennt, werden die Daten nicht importiert.
Verwenden Sie keine reservierten Wörter als Feldnamen in FileMaker Pro Advanced.
Einrichten der Datenverbindung in Tableau Desktop
- Wählen Sie in Tableau Desktop unter Verbinden (links am Bildschirm) Mehr > Webdaten-Connector.
- Geben Sie die URL für Ihren FileMaker Server-Endpunkt ein:
https://<hostname>/fmi/data/v1/tableau/fm_connector.html
Dabei ist<hostname>der vollständig qualifizierte Hostname Ihres FileMaker Servers. -
Im Dialogfeld „Daten aus FileMaker-Datei importieren“:
-
Melden Sie sich an der FileMaker Pro Advanced-Datenbank an, indem Sie die folgenden Informationen eingeben oder einen OAuth-Identitätsdienstleister verwenden.
- Quelle Datenbankname: der Name der FileMaker Pro Advanced-Datenbank
- Quelle Layoutname: der Name des FileMaker Pro Advanced-Layouts
- Kontoname: der Name des FileMaker Pro Advanced-Kontos mit dem Zugriffsrecht „fmrest“
- Passwort: das Passwort für das FileMaker Pro Advanced-Konto
- Wählen Sie Inkrementelle Aktualisierung aktivieren, um die inkrementelle Aktualisierung zu aktivieren.
-
- Klicken Sie auf FileMaker-Daten importieren.
Tableau importiert die Daten. Die Verarbeitungszeit hängt von der Anzahl der importieren Datensätze, der Server-Auslastung und dem Netzwerkdurchsatz ab. Tableau ordnet die FileMaker Pro Advanced-Feldnamen und Daten den Dimensionen und Kennzahlen zu. String-Daten werden in der Regel Dimensionen zugeordnet, wohingegen numerische Daten in der Regel Kennzahlen zugeordnet werden. Die Zuordnung erfolgt automatisch während des Imports, Sie können sie aber anpassen.
Hinweise
-
Wenn Sie Quelle Layoutname angeben, stellen Sie sicher, dass der Layoutname eindeutig ist. Wenn Ihre Datenbank zwei Layouts mit dem gleichen Namen enthält, kann die Tableau-Datenverbindung nicht zwischen ihnen unterscheiden. Tableau zeigt nur einen Namen an und es kann ggf. nicht das Layout sein, das Sie meinten.
-
Verwenden Sie Inkrementelle Aktualisierung aktivieren, um nur die neuen Datensätze zu importieren.
- Nach dem Import von FileMaker-Daten mit inkrementeller Aktualisierung wählen Sie das Register Arbeitsblatt in Tableau, um zu dem Arbeitsblatt zu wechseln.
- Wählen Sie Daten > FM: datenbankname / layoutname > Extrahieren > Aktualisieren (Inkrementell).
- Wählen Sie das Register Datenquelle.
- Klicken Sie auf Jetzt aktualisieren, um die neuen Datensätze anzuzeigen.
- Das Aktivieren der inkrementellen Aktualisierung erzeugt keine anhaltende Live-Verbindung zwischen Tableau und der bereitgestellten FileMaker-Datenbank. Sie müssen die inkrementelle Aktualisierung manuell ausführen.
- Die inkrementelle Aktualisierung importiert nur die neuen Datensätze. FileMaker Pro Advanced-Datensätze, die geändert oder gelöscht wurden, werden nicht aktualisiert. Um geänderte Daten abzurufen oder gelöschte Datensätze zu entfernen, müssen Sie in Tableau eine neue Arbeitsmappe erstellen und die Daten neu importieren.
- Die inkrementelle Aktualisierung erstellt ein Feld mit dem Namen -recordId. Wenn Sie Änderungen an diesem Feld vornehmen, können Sie eine inkrementelle Aktualisierung eventuell nicht durchführen.
- In Tableau können Sie Schema und Daten ändern, die importiert wurden. Wenn Sie aber das Schema oder Daten in Tableau ändern, werden diese Änderungen nicht zurück in die FileMaker Pro Advanced-Datei übertragen.
- Wenn Sie das Schema in der FileMaker Pro Advanced-Datei ändern, müssen Sie in Tableau eine neue Arbeitsmappe erstellen und die Daten neu importieren.
- Die Tableau Desktop-Datenbank kann auf Tableau Server für Windows bereitgestellt werden.
- Wenn Sie die Tableau-Arbeitsmappe schließen und erneut öffnen, funktioniert die inkrementelle Aktualisierung nicht mehr.
- Nachdem die Datenverbindung zu Tableau hergestellt wurde, speichert der FileMaker Web Data Connector Benutzerkonto und Passwort zwischen, bis die Arbeitsmappe geschlossen wird. Beachten Sie dabei Folgendes:
- Wenn die FileMaker-Sitzung abläuft, während Sie mit Tableau verbunden sind, versucht der FileMaker Web Data Connector, den Benutzer wieder mit FileMaker Server zu verbinden.
- Wenn die Tableau-Verbindung abläuft, versucht der FileMaker Web Data Connector, die Verbindung zu FileMaker Server so lange wiederherzustellen, wie die Tableau-Arbeitsmappe geöffnet ist.
- Wenn die Arbeitsmappe geschlossen und wieder geöffnet wird, müssen Sie Ihren Kontonamen und Ihr Passwort erneut während des anfänglichen Datenimports eingeben.
- Die Seite „Tableau-Datenquelle“ zeigt bis zu 1.000.000 (eine Million) Zeilen an, selbst wenn mehr Datensätze importiert werden.