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 und E-Mails senden, wenn deine Umgebung das unterstützt.

In diesem Kapitel lernst du, wie du:

• externe Dienste mit HTTP aufrufst.
• XML transformierst.

Funktion (A-Z)	Aufgabe
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.

E-Mail-Nachrichten senden

Nutze diese Funktion, um E-Mail-Adressen als klickbare Werte anzuzeigen.

E-Mail-Werte mit email() verwenden

Nutze email(), um Text in einen E-Mail-Wert umzuwandeln.

Nutze die Funktion, wenn du:

• die E-Mail-App deines Geräts über eine E-Mail-Adresse öffnen willst.
• ein Logikfeld als E-Mail-Feld anzeigen willst.
• eine E-Mail-Adresse aus Text extrahieren und mit einem Klick nutzen willst.

email(string)

• string der Textwert für die E-Mail-Adresse. Gib ein @ und eine gültige Domain an.

Klicke in einem Feld oder Button auf . Ninox öffnet die Standard-E-Mail-App deines Geräts.

Schauen wir uns einige Beispiele an:

email(email_adresse)

Wandelt den Wert im Feld "E-Mail-Adresse" in einen E-Mail-Wert um.

email("[e-mail]")

Zeigt die Adresse als E-Mail-Wert mit klickbarer E-Mail-Aktion an.

Tipps:

• Formatiere E-Mail-Adressen korrekt. Andernfalls gibt die E-Mail-Aktion einen Fehler zurück.
• Eine korrekt formatierte Adresse öffnet die Standard-E-Mail-App deines Geräts.

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.