cURL Beispiele nach FileMaker übersetzen

Allgemein, FileMaker, FileMaker Client, FileMaker Server / 9. April 2023 / schube / 2

In meinem letzten Beitrag Zahlungen per Kreditkarte oder Debitkarte entgegennehmen habe ich folgenden cURL Befehl gezeigt, den man beispielsweise im macOS Terminal ausführen kann, um mit einem Hobex Kreditkartenterminal Zahlungen entgegennehmen zu können:

## Login
curl -X POST \          
  https://hobexplus.brunn.hobex.at/api/account/login \
  -H 'Content-Type: application/json' \
  -d '{
      "userName": "schulz",
      "password": "XXXXXX"
}'       

## Zahlungsprozess starten
curl -X POST \
  https://hobexplus.brunn.hobex.at/api/transaction/payment \
  -H 'content-type: application/json' \
    -H 'token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUXXXXX.eyJleHBpcmF0XXXXXXMjAzMy0wMS0yMlQxMjozOTozMiIsImVtYWlsIjoiYmVybmhhcmQuc2NodWx6QHNjaHViZWMuY29tIiwidXNlciI6InNjaHVseiIsImlXXXXXXMjMtMDEtMjJUMTI6Mzk6MzIifQ.XXXXXXXcB5mF8wVuvTDjc0HGtRk_204RzMOwG1q7k' \
    -d '{  "transaction": {
    "transactionType": 1,
    "transactionId": "20230122134300001",
    "tid": "3600150",
    "currency": "EUR",
    "reference": "schubec Test",
    "amount": 10.5,
    "language": "DE"
  }
}'

Als FileMaker Entwickler ist das für uns nur die halbe Miete, denn wir möchten diese cURL Befehle ja nicht im Terminal, sondern innerhalb von FileMaker selbst ausführen.

Wir wollen die oben genannten Anweisungen im Folgenden zu FileMaker “übersetzen”.

cURL Befehle mit FileMaker ausführen

Um cURL Befehle mit FileMaker (und ohne Plugins) auszuführen, wird der Befehl Aus URL einfügen verwendet.

Analyse des CURL Befehls

Sehen wir uns den Loginvorgang per cURL einmal im Detail an:

## Login
curl -X POST \          
  https://hobexplus.brunn.hobex.at/api/account/login \
  -H 'Content-Type: application/json' \
  -d '{
      "userName": "schulz",
      "password": "XXXXXX"
}'    

• curl ==> Der Name des Programms, damit das macOS Terminal weiß, welches Programm ausgeführt werden soll.
• -X POST ==> Wir senden eine HTTP-POST Nachricht. Lässt man das -X POST weg, so wird automatisch eine HTTP-GET Nachricht gesendet. Ob hier ein POST, ein GET oder ein DELETE, PUT, PATCH, HEAD etc. benötigt wird, ist von der jeweiligen API, die man nutzt, abhängig und dort dokumentiert. Im Falle des Hobex Logins ist hier eben ein POST notwendig.
• https://hobexplus.brunn.hobex.at/api/account/login ==> Die URL, an die der Befehl gesendet wird.
• -H 'Content-Type: application/json' ==> Mit unsere Anfrage senden wir den HTTP-Header Content-Type mit dem Wert application/json. Statt -H kann man hier auch die längere Schreibweise --header verwenden. Welche Header gesendet werden müssen, ist wieder der jeweiligen API-Dokumentation zu entnehmen.
• -d '{"userName": "schulz","password": "XXXXXX" }' ==> Hier senden wir die Daten an den Server. In unserem Fall ist das ein JSON-Dokument. An dieser Stelle könnten wir aber auch Dateien hochladen, XML-Dokumente oder Formular-Daten senden etc. etc. etc. Auch hier gilt. Was der Server erwartet, das steht in der API-Dokumentation der Schnittstelle.

Umsetzung in FileMaker

Nachdem wir nun wissen, wie der cURL Befehl aufgebaut ist, übertragen wir das Ganze zu FileMaker in den Aus URL einfügen Befehl.

Als erstes definieren wir die URL. Die URL ist bei uns ein fix definierter Text und wird daher in Anführungszeichen in den entsprechenden Dialog eingetragen. Theoretisch könnte man die URL auch per FileMaker Formel berechnen, aber das ist bei unserem einfachen Beispiel nicht notwendig.

Im URL-Dialog hat man die Möglichkeit, die URL automatisch zu kodieren. Dann würde eine URL wie https://www.schubec.com/?Das ist ein Beispiel, verständlich automatisch in https://www.schubec.com/?Das%20ist%20ein%20Beispiel%2C%20verst%C3%A4ndlich umgewandelt werden: Leerzeichen, Umlaute und andere Sonderzeichen werden dann korrekt URL-kodiert.

Aber ich persönlich mag nicht, wenn das automatisch passiert sondern würde das explizit mit dem FileMaker-Befehl LiesAlsURLVerschlüsselt machen, daher deaktiviere ich diese Zusatzoption immer.

Als nächstes definieren wir das Ziel. Das heißt, wo möchten wir die Antwort des Servers in FileMaker weiterverarbeiten. Hier kann man ein Feld oder eine Variable angeben. Ich speichere das Ergebnis in der globale Variable $$curl.

cURL-Optionen

Kommen wir nun zu den cURL-Optionen

Das ist nun der komplizierteste Teil.

Die erste Option in unserem cURL Terminal Befehl war, dass wir eine POST Anfrage senden. Das können wir einfach in FileMaker übernehmen. Die Option ist als Text in FileMaker einzutragen, daher benötigen wir Anführungszeichen am Anfang und Ende des Befehls:

Die zweite Option in unserem cURL Terminal Befehl war die Header Angabe -H 'Content-Type: application/json'. Die können wir wieder als Text (also mit Anführungszeichen) im FileMaker-Dialog ergänzen. Die beiden Texte verbinden wir in FileMaker wie gewohnt mit dem &-Zeichen:

Leider klappt das so nun nicht ganz. Das erste Problem wird vermutlich schnell sichtbar, denn wenn man die beiden Texte verknüpft kommt da nun -X POST-H 'Content-Type: application/json' heraus. Zwischen POST und -H benötigen wir mindestens ein Leerzeichen! Das lässt sich natürlich sehr einfach lösen, indem man nach dem POST ein Leerzeichen ergänzt. Bei umfangreichen Formeln, die über 10-20 Zeilen gehen, ist das aber eher unübersichtlich, daher habe ich mir angewöhnt, die Leerzeichen IMMER am Anfang der Zeile zu machen. Und ich mache das auch beim ersten Befehl, denn so kann ich später die Reihenfolge der Zeilen problemlos ändern, ohne an Leerzeichen denken zu müssen. Das sieht dann so aus:

Das zweite Problem, das wir hier haben, ist ziemlich tricky und hat mich beim aller ersten Mal Stunden an Lebenszeit gekostet, bis ich das Problem erkannt hatte.

Fast alle cURL Beispiele im Internet haben die Header Angabe in der Form -H 'Content-Type: application/json'. FileMaker, die Diva, akzeptiert das aber nicht und erwartet hier statt einfachen Hochkommata ' die doppelten Hochkommata ". Das Argument zu FileMaker übersetzt heißt daher -H “Content-Type: application/json“. Wenn man es weiß, ist es eh kein Problem, aber wissen muss man es halt!

Ja, und weil FileMaker Texte selbst in Hochkommata einschließt und nicht wüsste, wo der Text anfängt und aufhört, müssen wir die Hochkommata im Text mit dem Backslash escapen. Somit wird dann folgendes daraus:

Fehlen noch die Daten selbst, also der Teil -d '{"userName": "schulz","password": "XXXXXX" }'. Wie man sieht, ist das ein JSON Dokument. Da das so oft verwendet wird, gibt es hier in FileMaker eine sehr bequeme Funktion, um solche Daten per cURL zu versenden.

Zuerst brauchen wir in einer Variable namens $json unser JSON-Dokument mit dem FileMaker Befehl JSONSetElement zusammen.

JSONSetElement ( "" ; //Wir fangen mit einem leeren JSON-Dokument an

["userName"; "Schulz"; JSONString]; //Wir ergänzen userName als String/Text

["password"; "xxxxxxx"; JSONString] //Wir ergänzen password als String/Text

)

Diese JSON-Dokument können wir nun wie folgt beim cURL Befehl ergänzen:

Das hat den großen Vorteil, dass sich FileMaker selbst um das Escapen von Sonderzeichen im JSON Dokument kümmert und wir einfach per Referenz auf die Variable mit @$variable-namen die Daten senden können.

Dokumentiert ist diese Schreibweise inkl. aller anderen Optionen unter https://help.claris.com/en/pro-help/content/curl-options.html

Fehlerhandling

Nun kann es sein, dass etwas nicht klappt. Der Server ist nicht erreichbar, wir haben den Content-Type falsch gesetzt, der Parameter fürs Passwort ist nicht korrekt gesetzt – was auch immer. Wir wollen für diese Fälle vorsorgen und ergänzen bei den cURL Optionen das FileMaker Fehlerhandling " --show-error" wie folgt:

Interessante Befehle zum Fehlersuchen sind auch --dump-header und --trace-ascii. Das sind aber Befehle für einen späteren Blogartikel.

Durch die --show-error Option liefert der FileMaker Befehl Hole(LetzteFehlerNummer) den Wert 1631 im cURL Fehlerfall, sodass wir darauf reagieren können.

Warum genau 1631? Weil das unter https://help.claris.com/en/pro-help/content/curl-options.html genau so festgelegt hat.

Weitere FileMaker Fehlernummern findet man unter https://help.claris.com/en/pro-help/content/error-codes.html

Um den genauen cURL Fehler zu bekommen, nutzen wir die Hole(LetzteFehlerNrDetail) Funktion. Diese liefert uns dann Details zum Fehler. Die cURL Fehler findet man unter https://curl.se/libcurl/c/libcurl-errors.html

cURL gibt uns oft die HTTP-Fehlercodes retour. Im Beispiel weiter unten zum Beispiel die 404. Das sind dann HTTP-Statuscodes, die man unter https://de.wikipedia.org/wiki/HTTP-Statuscode nachlesen kann.

In der Praxis ist es nun so, dass wir mit dem FileMaker 1631-Fehlercode herausfinden, ob unsere cURL Abfrage geklappt oder eben nicht geklappt hat.

Wenn der Fehlerdetailcode dann unter 100 ist, ist es ziemlich sicher ein cURL Fehler und wenn er über 100 ist, ist es ziemlich sicher ein HTTP-Statuscode. Mit dem Wissen ausgestattet und ein wenig Übung lassen sich diese Fehler dann rasch lösen.

Wir ergänzen unser Script daher wie folgt:

Wenn Sie das Script nun genau ausführen (und vorher noch die Option Mit Dialog:aus bei Aus URL einfügen aktivieren), dann erhalten Sie:

Es hat also geklappt – sprich es gab keinen Fehler, obwohl Benutzer oder Passwort falsch ist.

Technisch hat die Anfrage geklappt und es kam eine korrekte Antwort vom Server retour. Dass inhaltlich ein Fehler vorliegt (Passwort falsch), ist eine andere Geschichte und in jeder API ein wenig anders.

Wenn wir die Anfrage einmal absichtlich falsch absenden, beispielsweise an die nicht existierende URL https://hobexplus.brunn.hobex.at/api/account/login2, dann bekommen wir auch eine entsprechende Fehlermeldung:

Beispieldatei – Download

Damit Sie nicht alles selbst abtippen müssen, können Sie hier die fertige Datei herunterladen:

So sieht übrigens die Antwort vom Server aus, wenn man das korrekte Passwort angibt:

Hier kann man dann mit JSONGetElement($$curl; "token") den Token auslesen und für weitere Aufrufe verwenden.

Wie geht es weiter?

Ich persönlich finde es sehr wichtig, dass man die Basics versteht und cURL Befehle (aus dem Internet) in die FileMaker Variante übersetzen kann und dabei auch (halbwegs) versteht was man macht und nicht nur blind irgendetwas abtippt.

Sobald man die Grundlagen verstanden hat, darf man sich das Leben aber leichter machen und Tools verwenden, die beim “Übersetzen” helfen. Zum Beispiel:

• https://www.soliantconsulting.com/blog/translating-auto-generated-curl-to-filemaker-curl/
• https://dbservices.com/blog/filemaker-curl-options

Selbstverständlich gibt es noch viele weitere Beispiele online – meist englischsprachig – zum Beispiel:

• https://mossrock.com/intro-to-curl-filemaker/
• https://skeletonkey.com/an-almost-universal-api-template-for-claris-filemaker-and-filemaker-pro/

Kompatibilität

Das schöne ist, dass der Aus URL einfügen Befehl auf der ganzen Claris Plattform zur Verfügung steht. Sie können das Erlernte also nutzen mit

• FileMaker Pro Client
• FileMaker Go
• FileMaker Server
• FileMaker Web Direct

Ihnen gefällt, was Sie hier lesen?

Ich freue mich über Feedback per Email!

Und ich freue mich, falls Sie über meine Amazon Wunschliste stolpern und mir vor lauter Begeisterung ein Geschenk zusenden 🙂

curl, filemaker, filemaker go, filemaker server