Integration und HTTP

Lerne, wie du externe Dienste aufrufst, XML gegen XSD-Schemas validierst, XML transformierst, E-Mails sendest und Kalendereinträge in Ninox Skripten erstellst.

Integrationsfunktionen verbinden deine App mit Diensten und Kommunikationstools außerhalb von Ninox. Du kannst APIs aufrufen, XML gegen Schemas validieren, XML transformieren, E-Mails senden und Termine oder Erinnerungen erstellen, wenn deine Umgebung das unterstützt.

In diesem Kapitel lernst du, wie du:

• externe Dienste mit HTTP aufrufst.

• XML transformierst.

• Termine erstellst.

Funktion (A-Z)	Aufgabe
appointment()	Erstellt einen Terminwert
email()	Gibt einen E-Mail-Wert zurück oder verwendet ihn wieder
formatXML()	Konvertiert JSON-Daten in XML-Text
http()	Sendet eine HTTP-Anfrage
parseXML()	Konvertiert XML-Text in ein JSON-Objekt

Externe Dienste aufrufen

Nutze diese Funktionen, um jede REST API aufzurufen, Daten aus einem anderen Dienst zu holen oder Daten zwischen Ninox Datenbanken zu übertragen.

Mit http() eine API aufrufen

Nutze http(), um eine Anfrage an einen externen Dienst zu senden.

Nutze es, wenn du:

• Daten aus einem anderen System holen oder Updates dorthin senden willst.

• Ninox mit REST APIs und anderen Ninox Datenbanken verbinden willst.

Setze http() nicht in do as transaction...end ein

Transaktionen nutzen eine single-threaded Schreibwarteschlange. Ein HTTP-Aufruf innerhalb einer Transaktion blockiert alle anderen Schreibvorgänge, bis die Anfrage abgeschlossen ist. Die App hängt nicht dauerhaft, aber jeder wartende Schreibvorgang wartet über die komplette Laufzeit des Aufrufs. Das kann die App langsam wirken lassen.

http(method, url) http(method, url, body) http(method, url, header, body) http(method, url, header, body, files)

• method: Textwert der HTTP-Methode, zum Beispiel "GET" oder "POST"

• url: Textwert der Endpoint-URL

• header: optionale Header als JSON-Objekt, zum Beispiel { Authorization: token }

• body: optionaler Request-Body als JSON-Objekt

• files: optionale Dateien zum Upload als [file], wenn der aktuelle Ausführungskontext Datei-Uploads unterstützt (Server-Kontext)

Beim Zugriff auf Ninox Daten ist ein Body erforderlich

Wenn du http() nutzt, um auf Daten in Ninox zuzugreifen, musst du einen Body übergeben. Wenn keine Informationen im Body nötig sind, bleibt er einfach leer. Ein Beispiel dafür ist:

http(“GET”, “https://api.ninox.com/v1/[...]”, {Authorization: “Bearer xxxx-xxxx-xxxx”, content-type: “application/json”}, {})

Schauen wir uns einige Beispiele an:

http("GET", "https://api.example.com/status")

Ruft den externen Dienst auf und gibt ein JSON-Antwortobjekt oder ein Fehlerobjekt zurück.

let url := "https://api.ninoxdb.de/v1/teams/" + teamId() +
           "/databases/" + databaseId() + "/tables/";
let apiKey := "Bearer abcd1234-0000-xxxx-zzzz-1a1aa1aaa1a111";

let response := http("GET", url, {
    Authorization: apiKey
});
response

Listet Tabellen aus der aktuellen Datenbank über die Ninox API oder gibt ein Fehlerobjekt zurück.

do as server
   let url := "https://api.ninoxdb.de/v1/teams/" + teamId() +
             "/databases/" + databaseId() + "/query";
   let apiKey := "Bearer abcd1234-0000-xxxx-zzzz-1a1aa1aaa1a111";
   
   let response := http("POST", url, {
             Authorization: apiKey, 
             "content-type": "application/json"
   }, {
    query: "select customers where status = 4"
   });
   response
end

Sendet eine POST-Anfrage und gibt passende Datensätze oder ein Fehlerobjekt zurück.

let response ::= do as server
    http("POST",
        "https://example.com/upload",
        { "content-type": "multipart/form-data" },
        null,
        [myFile])
end

Lädt eine Datei zu einem externen Dienst hoch, wenn Datei-Uploads im aktuellen Ausführungskontext unterstützt werden.

Tipps:

• http() gibt ein JSON-Objekt zurück, keinen Klartext.

• Wenn du auf eine andere Ninox Datenbank zugreifst, brauchst du einen API-Key.

• Manche Endpoints erwarten selbst bei GET-Anfragen einen Body. Nutze {}, wenn der Ziel-Endpoint einen Body verlangt und du keine Felder senden musst.

• Datei-Uploads hängen vom Ausführungskontext ab.

• Teste Integrationsskripte mit echten Antworten des Dienstes, nicht nur mit Beispielausgaben.

XML transformieren

Nutze diese Funktionen, wenn ein anderes System XML sendet oder erwartet, besonders wenn das XML zu einem definierten Schema passen muss.

Mit parseXML() XML-Text in Daten umwandeln

Nutze parseXML(), um XML-Text in ein JSON-Objekt umzuwandeln, das du in Ninox prüfen kannst. Das ist besonders nützlich, wenn du Ninox per API mit externen Diensten verbindest und XML-Antworten verarbeiten musst. XML ist neben JSON ein gängiges Austauschformat.

Nutze es, wenn du:

• Werte aus einer XML-Antwort lesen willst.

• Felder aus importiertem XML extrahieren willst.

• XML für spätere Logik in strukturierte Daten umwandeln willst.

parseXML(string)

• string: der XML-Text, den du in ein JSON-Objekt umwandeln willst

Schauen wir uns einige Beispiele an:

let xml := "<?xml version=""1.0"" encoding=""UTF-8""?>
<note>
    <to>Jane Doe</to>
    <from>Ninox</from>
    <heading>Save the world!</heading>
    <body>Please save the world!</body>
</note>";
parseXML(xml)

Gibt ein JSON-Objekt zurück, das aus dem XML-Text erzeugt wurde, zum Beispiel:

{
  "note": {
    "to": {
      "@": "Jane Doe"
    },
    "from": {
      "@": "Ninox"
    },
    "heading": {
      "@": "Save the world!"
    },
    "body": {
      "@": "Please save the world!"
    }
  }
}

Tipp:

• Wenn du ein XSD-Schema hast, validiere externes XML vor dem Parsen.

Mit formatXML() XML-Text erstellen

Nutze formatXML(), um JSON-Daten in XML-Text umzuwandeln.

Nutze es, wenn du:

• XML für einen anderen Dienst vorbereiten willst.

• geparste Daten in lesbares XML umformatieren willst.

formatXML(JSON) formatXML(JSON, boolean)

• JSON: die strukturierten Daten, die du in XML umwandeln willst

• boolean: ob die Ausgabe zur besseren Lesbarkeit optisch strukturiert sein soll

Schauen wir uns einige Beispiele an:

let x := parseXML("<root><item>1</item></root>");
formatXML(x, true)

Formatiert das geparste Objekt zurück in gut lesbaren XML-Text.

formatXML({
    contact: {
        @type: "Person",
        firstName: {
            @: "Max"
        },
        lastName: {
            @: "Mustermann"
        },
        phone: [{
            @type: "Mobile",
            @: "(+1) (202) 123 45 67"
        }, {
            @type: "Phone",
            @: "+1.151.11 ++66 14 66"
        }]
    }
}, true)

Konvertiert das JSON-Objekt in strukturierten XML-Text. Schlüssel wie @type werden zu XML-Attributen. @ wird zum Textwert des Knotens.

Tipps:

• Nutze die Pretty-Option, wenn Menschen das Ergebnis lesen sollen.

• Nutze kompakte Ausgabe, wenn das Zielsystem nur die Nutzlast braucht.

• Diese Funktion ist besonders nützlich für API-Integrationen, die XML statt JSON erwarten.

Termine erstellen

Nutze diese Funktionen, wenn du für deinen Workflow ein zeitbasiertes Element erstellen willst.

Mit appointment() einen Terminwert erstellen

Nutze appointment(), um zeitbezogene Werte in einen Terminwert umzuwandeln.

Nutze es, wenn du:

• einen Termin oder Zeitslot aus Start- und Endwerten aufsetzen willst.

• einen Zeitraum aus einem Startwert und einer Dauer erstellen willst.

• einen geplanten Zeitraum an spätere Logik übergeben willst.

appointment(any, any)

• erstes any: der Start-Zeitstempel

• zweites any: der End-Zeitstempel des Termins oder eine Dauer

Schauen wir uns einige Beispiele an:

appointment(datetime(2021, 3, 16, 19), datetime(2021, 3, 6, 17))

Erstellt einen Termin aus zwei Zeitstempeln. Ninox nutzt automatisch den früheren Zeitstempel als Start.

appointment(datetime(2021, 5, 22, 10), time(1, 45))

Erstellt einen Termin aus einem Start-Datum mit Uhrzeit und einer Dauer von 1 Stunde und 45 Minuten.

Tipps:

• Die Reihenfolge der Argumente ist egal, wenn du zwei Zeitstempel übergibst. Ninox nutzt den früheren Wert als Start.

• Wenn Start und Ende am selben Tag liegen, zeigt die Anzeige meist nur ein Datum. Wenn der Zeitraum mehrere Tage umfasst, werden beide Daten gezeigt.

Das Verhalten von Integrationen kann von deiner Umgebung, dem Client und verbundenen Diensten abhängen. Prüfe HTTP- und E-Mail-Workflows in derselben Umgebung, die deine Nutzer in Produktion verwenden.