FileMaker 18 Admin API Handbuch

Dieses Handbuch informiert über die Verwendung von FileMaker Admin API Version 2 (v2) für die Durchführung von Administrationsaufgaben für FileMaker Cloud-Produkte und FileMaker Server. (Informationen über FileMaker Admin API Version 1 (v1) finden Sie in der FileMaker Admin API Referenz, die mit unterstützten Produkten installiert wird.)

Dieses Handbuch setzt voraus, dass Sie vertraut sind mit:

• der Verwendung von FileMaker Pro Advanced, um Datenbanken hochzuladen. Siehe FileMaker Pro Advanced Hilfe.
• der Verwendung von FileMaker Server bzw. einem FileMaker Cloud-Produkt für die Bereitstellung und Verwaltung von Datenbanken. Siehe FileMaker Server Hilfe und FileMaker Cloud-Produktdokumentation unter Produktdokumentation.
• 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.

Hinweise

• FileMaker Cloud ist ein Dienst, der Zugriff auf eigene Apps, die FileMaker Pro Advanced, FileMaker Go und FileMaker WebDirect nutzen, in der Cloud bietet. FileMaker Cloud verwendet das integrierte Anmeldesystem FileMaker-ID, um Benutzer zu authentifizieren. Es wird direkt von FileMaker, Inc. angeboten.
• FileMaker Cloud for AWS ist ein Dienst, der Zugriff auf eigene Apps, die FileMaker Pro Advanced, FileMaker Go und FileMaker WebDirect nutzen, in der Cloud bietet. FileMaker Cloud for AWS läuft in der Amazon Web Services (AWS) Cloud und wird über den AWS Marketplace angeboten.
• FileMaker Cloud-Produkte bezieht sich sowohl auf FileMaker Cloud als auch auf FileMaker Cloud for AWS.
• Dieses Handbuch verwendet Admin Console, um sich auf Admin Console für FileMaker Server, FileMaker Cloud for AWS und FileMaker Cloud zu beziehen, wenn kein bestimmtes Produkt angegeben ist. FileMaker Cloud Admin Console bezieht sich auf Admin Console für beide FileMaker Cloud-Produkte, wenn kein spezifisches Produkt genannt wird.
• Eigene App, Lösung, Datenbank und Datei sind Bezeichnungen für das, was Sie mit FileMaker-Produkten erstellen und mit denen Sie arbeiten.
• Dieses Handbuch verwendet Zugriffstoken, um sich auf den JSON Web Token zu beziehen, der für die Authentifizierung benötigt wird.

Das FileMaker^® Admin API ist ein Application Programming Interface (API), das Webdiensten gestattet, administrative Aufgaben in FileMaker Cloud-Produkten und FileMaker Server auszuführen. Da dieses API der Representational-State-Transfer- (REST-) Architektur entspricht, ist das FileMaker Admin API ein REST API.

Das FileMaker Admin API gibt Daten in JavaScript-Object-Notation- (JSON-) Format zurück, einem Textformat, das häufig bei REST APIs verwendet wird, da JSON unabhängig von bestimmten Programmiersprachenformaten ist.

So verwenden Sie das FileMaker Admin API:

1. Programmieren Sie so, dass FileMaker Admin API-Aufrufe Verwaltungsaufgaben ausführen.
2. Testen Sie, ob der FileMaker Admin API-Zugriff korrekt funktioniert.
3. Kontrollieren Sie Ihre Ergebnisse durch Prüfen der Datei gateway.log für ein FileMaker Cloud-Produkt bzw. fac.log für FileMaker Server. Dort werden alle API-Aufrufe protokolliert. Sie können die Datei gateway.log über die FileMaker Cloud Admin Console herunterladen. Die Datei fac.log befindet sich in folgendem Ordner: .../FileMaker Server/Admin/FAC/logs.

Hinweise

• Um auf Daten in bereitgestellten Datenbanken zuzugreifen, siehe das FileMaker Data API Handbuch.

REST API-Client

1

6

Web-Server

2

5

FileMaker Admin API Engine

3

4

Datenbank-Server

Einige der FileMaker Admin API-Aufrufe wie Authentifizierungsaufrufe werden nur basierend auf den zwei ersten Schritten unten bearbeitet. Andere Aufrufe wie Aufrufe in Bezug auf das Erstellen von Zeitplänen oder das Aktualisieren der Konfiguration werden basierend auf allen Schritten unten bearbeitet.

1. Ein REST API-Client sendet einen FileMaker Admin API-Aufruf (eine HTTPS-Anforderung) an den Web-Server.
2. Der Web-Server leitet die Anforderung über das FileMaker Web-Server-Modul an die FileMaker Admin API Engine weiter.
3. Die FileMaker Admin API Engine konvertiert die HTTPS-Anforderung (URL und JSON-Daten) in ein Format, das mit dem FileMaker Datenbank-Server kompatibel ist.
4. Der Datenbank-Server sendet die Ergebnisse der Anforderung zurück an die FileMaker Admin API Engine.
5. Die FileMaker Admin API Engine wandelt die Ergebnisse in eine HTTPS-Antwort (URL mit JSON-Daten) um und gibt die Daten an den Web-Server zurück.
6. Der Web-Server sendet die HTTPS-Antwort an den anfordernden REST API-Client.

Die FileMaker Admin API-Referenz wird mit FileMaker Server und FileMaker Cloud-Produkten installiert. Die Referenz enthält Detailinformationen zu allen Aufrufen, die FileMaker Admin API unterstützt.

Um die Referenz für das FileMaker Cloud-Produkt anzuzeigen, geben Sie die folgende URL in ein Browserfenster ein:

https://host/fmi/admin/apidoc/

Dabei ist host der Hostname bzw. die IP-Adresse des virtuellen Servers, auf dem das FileMaker Cloud-Produkt läuft.

So greifen Sie auf die Referenz für FileMaker Server zu:

• Um die Referenz in einem Browserfenster auf dem Mastercomputer anzuzeigen, geben Sie folgende URL ein:

  https://localhost/fmi/admin/apidoc/

• Um die Referenz in einem Browserfenster auf einem Remotecomputer anzuzeigen, geben Sie folgende URL ein:

  https://host/fmi/admin/apidoc/

• Auf einem Windows-Server befindet sich die Referenz im folgenden Ordner:

  [Laufwerk]:\Programme\FileMaker\FileMaker Server\Documentation\Admin API Documentation

  Dabei bezeichnet [Laufwerk] das Laufwerk, 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]\FileMaker\FileMaker Server\Documentation\Admin API Documentation

• Auf einem macOS-Server befinden sich die Referenzdateien im Ordner:

  /Library/FileMaker Server/Documentation/Admin API Documentation

Hinweise

• Wenn Sie die URL-Beispiele in der Admin API Referenz verwenden und Sie die Referenzdatei von Ihrer lokalen Festplatte öffnen, beginnen alle Beispiele mit file:///. Um die URLs zu verwenden, ersetzen Sie file:/// mit https://IhrHostName/fmi/admin/api/v2.

Das FileMaker Admin API stellt ein REST API bereit, das Sie verwenden können, um einige routinemäßigen Verwaltungsaufgaben über Scripting anstelle der Verwendung der Admin Console zu automatisieren.

Das FileMaker Admin API überwacht den Status der Interaktionen. Sie können mit einem Authentifizierungsaufruf beginnen oder andere Aufrufe für die Authentifizierung verwenden. Sie können dann den zurückgegebenen Zugriffstoken für nachfolgende Aufrufe verwenden.

Der Token ist so lange gültig, bis er entweder über den Aufruf „Invalidate Access Token“ ungültig gemacht wird oder bis 15 Minuten nach dem letzten Aufruf, der den 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.)

API-Aufrufe in Bezug auf Datenbanken und Zeitplan-API-Aufrufe mit Ausnahme der Aufrufe zum Erstellen und Bearbeiten/Ausführen von Zeitplänen sind asynchron und warten nicht auf eine Antwort vom FileMaker Cloud-Produkt bzw. FileMaker Server. Sie können einem asynchronen Aufruf mit einem GET-Aufruf folgen, um zu bestätigen, dass sich der Dateistatus geändert hat. Folgen Sie zum Beispiel einem Aufruf „Close database“ mit einem Aufruf „GET databases“, um zu bestätigen, dass die Datenbank geschlossen ist. Falls sich der Status nicht unmittelbar ändert, prüfen Sie weiter.

Der Rest der API-Aufrufe ist synchron und wartet auf eine Antwort vom FileMaker Cloud-Produkt bzw. FileMaker Server.

FileMaker Admin API verwendet einen Zugriffstoken, um eine Verbindung zum Host zu definieren. Verwenden Sie den Authentifizierungsaufruf, um einen Zugriffstoken vom Host mit Administrator-Konto und -Passwort anzufordern. Nehmen Sie einen Authorization-Header mit dem Wert „Basic base64-kodierte Zeichenfolge“ auf. Die base64-kodierte Zeichenfolge sollte basierend auf „benutzername:passwort“ generiert werden. Sie können das Basic-Authentication-Schema auch für andere Aufrufe verwenden.

Wenn Sie das Basic-Authentication-Schema für den Authentifizierungsaufruf verwenden, gibt die Anforderung den Zugriffstoken im Antwortteil zurück. Wenn Sie das Basic-Authentication-Schema für andere Aufrufe verwenden, gibt die Anforderung den Zugriffstoken im Feld X-FM-Access-Token im Antwort-Header zurück.

Verwenden Sie für nachfolgende API-Aufrufe das Bearer-Authentication-Schema und schließen Sie einen Authorization-Header mit dem Wert „Bearer Zugriffstoken“ mit ein.

Hinweise

• Jedes Mal, wenn Sie das Basic-Authentication-Schema verwenden, um einen Zugriffstoken abzurufen, wird eine neue API-Sitzung erstellt. Um zu vermeiden, dass mehrere API-Sitzungen aktiv sind, verwenden Sie den gleichen Zugriffstoken mit dem Bearer-Authentication-Schema für alle API-Aufrufe.

FileMaker Admin API verwendet einen Zugriffstoken, um eine Verbindung zum Host zu definieren.

So authentifizieren Sie Konten für FileMaker Cloud:

1. Generieren Sie den FileMaker-ID Token. Siehe FileMaker Customer Console Hilfe in der Produktdokumentation.

2. Schließen Sie den FileMaker-ID Token aus Schritt 1 im Authentifizierungsaufruf oder anderen Aufrufen mit ein, um einen Zugriffstoken zu generieren.

   Verwenden Sie zum Beispiel folgende URL und Header für den Authentifizierungsaufruf:

   • URL: https://host/fmi/admin/api/v2/user/auth

     Dabei ist host der Hostname bzw. die IP-Adresse des virtuellen Servers, auf dem FileMaker Cloud läuft.

   • Header: Authorization FMID FileMaker_ID_Token

   Wenn Sie den Authentifizierungsaufruf verwenden, wird der Zugriffstoken im Antwortteil zurückgegeben. Wenn Sie andere Aufrufe verwenden, wird der Token im Feld X-FM-Access-Token im Antwort-Header zurückgegeben.

3. Schließen Sie für nachfolgende API-Aufrufe den folgenden Authorization-Header für den Authentifizierungsaufruf mit ein:

   Header: Authorization Bearer Zugriffstoken

Hinweise

• Jedes Mal, wenn Sie das FileMaker-ID Authentication-Schema verwenden, um einen Zugriffstoken abzurufen, wird eine neue API-Sitzung erstellt. Um zu vermeiden, dass mehrere API-Sitzungen aktiv sind, verwenden Sie den gleichen Zugriffstoken mit dem Bearer-Authentication-Schema für alle API-Aufrufe.

Die folgende Tabelle zeigt die unterstützten FileMaker Admin API-Aufrufe für FileMaker Server und FileMaker Cloud-Produkte.

• Der Parameter startupRestorationLogPath für FileMaker Server Admin API gibt den Ordnerpfad für das Speichern von Wiederherstellungsprotokollen an. Ändern Sie den Speicherort des Wiederherstellungsprotokollordners auf ein separates Laufwerk, um optimale Ergebnisse zu erhalten.
• FileMaker Cloud-Produkte verwenden die UTC-Zeit für den Parameter startTimeStamp.
• Für filemakerScriptType müssen Sie sowohl den Parameter fmScriptAccount als auch den Parameter fmScriptPassword für das auszuführende Script ausgeben.
• Verwenden Sie in FileMaker Cloud für filemakerScriptType den Parameter fmScriptAccount, um den FileMaker-ID Token anzugeben, und den Parameter fmScriptPassword, um den FileMaker-ID Refresh-Token anzugeben. Wenn Sie den Refresh-Token nicht angeben, kann das Script nicht ausgeführt werden, nachdem der FileMaker-ID Token abgelaufen ist. Informationen zum Generieren von Tokens finden Sie in der FileMaker Customer Console Hilfe in der Produktdokumentation.
• Wenn der zurückgegebene Wert für den Statusparameter für den Aufruf „List Databases“ Normal ist, ist die Datenbank offen.