Zum Inhalt springen

Komplexe REST-API-Strukturen in Jitterbit App Builder

Übersicht

Standardmäßig gibt eine GET-Anfrage gegen eine App Builder REST-API-Ressource Daten aus einer einzelnen Tabelle zurück. Die REST-API von App Builder unterstützt auch komplexe Strukturen: Verschachtelung von Daten aus verknüpften Tabellen in eine einzelne JSON-Antwort, anstatt dass der Aufrufer für jede verknüpfte Tabelle eine separate Anfrage stellen muss.

Beispielsweise könnte eine customer-Ressource ihre zugehörigen orders verschachteln, und jede Bestellung könnte wiederum ihre items verschachteln, sodass eine einzelne GET-Anfrage gegen customer einen Kunden zusammen mit seinen Bestellungen und den Positionen jeder Bestellung in einer Antwort zurückgibt.

Hinweis

Komplexe Strukturen werden nur für GET-Operationen unterstützt. Andere HTTP-Methoden wie POST und PUT werden nicht unterstützt.

Diese Seite behandelt:

  • Einen untergeordneten Knoten hinzufügen
    Verschachteln Sie die Daten einer Tabelle unter einer vorhandenen Ressource oder einem Knoten.

  • Knotenparameter
    Die Eigenschaften, die auf jedem Knoten verfügbar sind und beim Hinzufügen oder Bearbeiten eines Knotens festgelegt werden.

  • Knotenfelder
    Die auf einem Knoten verfügbaren Felder und wie sie die JSON-Ausgabe des Knotens steuern.

  • Eine verschachtelte Struktur abfragen
    Wie sich die Abfrageparameter $fields und $expand verhalten, sobald eine Ressource eine verschachtelte Struktur hat.

Einen untergeordneten Knoten hinzufügen

Nachdem Sie eine Ressource für Ihre Stammressource veröffentlicht haben, verschachteln Sie zusätzliche Daten darunter, indem Sie untergeordnete Knoten hinzufügen. Jeder hinzugefügte Knoten wird zu einer Ebene in der resultierenden JSON-Struktur und kann selbst weitere untergeordnete Knoten haben, sodass Sie Daten so tief verschachteln können, wie Ihr Datenmodell es erfordert.

  1. Gehen Sie zu IDE > REST APIs.

  2. Die Registerkarte REST APIs listet alle aktuellen Endpunkte im Bereich Services auf. Suchen Sie die Kachel der gesuchten Ressource und klicken Sie auf das Symbol Chevron, um die Seite REST API dieser Ressource zu öffnen.

  3. Suchen Sie den Endpunkt, dem Sie untergeordnete Knoten hinzufügen möchten, im Bereich Resources. Klicken Sie auf das Symbol Details, um das Dialogfeld Resource anzuzeigen.

  4. Klicken Sie auf der Registerkarte Nodes auf + Node. Das Dialogfeld Node wird geöffnet:

    Node dialog

  5. Legen Sie die Parameter des neuen Knotens fest, einschließlich des übergeordneten Knotens, unter dem er verschachtelt wird, und der Tabelle, aus der er Daten abruft.

  6. Klicken Sie auf Save. Der Bereich Fields wird für diesen Knoten verfügbar.

  7. Klicken Sie im Bereich Fields auf + Field, um die Felder des Knotens hinzuzufügen und zu konfigurieren.

  8. Wiederholen Sie die Schritte 4 bis 7 nach Bedarf, um zusätzliche untergeordnete Knoten zu verschachteln, auch unter dem gerade erstellten Knoten, um eine Struktur mehr als eine Ebene tief zu verschachteln.

Node-Parameter

Jeder Knoten, ob der implizite Stammknoten einer Ressource oder ein hinzugefügter untergeordneter Knoten, hat die folgenden Eigenschaften, die steuern, wie diese Ebene der Struktur abgerufen und in der Antwort dargestellt wird:

Name Beschreibung
Parent Der übergeordnete Knoten in der Hierarchie.
Name Der Name dieses Knotens in der Baumstruktur. Der Name kann Schrägstriche enthalten, um die Struktur noch tiefer zu verschachteln, ohne für jede Ebene einen Zwischenknoten erstellen zu müssen.
Table Die Tabelle, aus der Daten abgerufen werden.
Node Type Der Knotentyp.
  • Array of objects: Dies ist der Standardtyp, bei dem jede Zeile in der Tabelle ein JSON-Objekt ist.
  • Array of scalars: Ein Array von Einzelwert-Elementen, serialisiert in ein JSON-Array von Skalaren. Die Tabelle muss die Spalten Index und Value enthalten.
  • Object: Wird einem einzelnen JSON-Objekt zugeordnet und eliminiert das JSON-Array vollständig. Die Tabelle sollte höchstens eine Zeile zurückgeben.
Expand By Default Bestimmt, ob die Daten des Knotens automatisch in die Antwort einbezogen werden. Aufrufer können dies mit dem Abfrageparameter $expand überschreiben.
  • Do not expand: (Standard.) Die Daten des Knotens werden nicht einbezogen, es sei denn, der Aufrufer fordert sie an.
  • Expand for items: Die Daten des Knotens werden nur einbezogen, wenn das übergeordnete Element als einzelnes Element angefordert wird (z. B. /orders/101).
  • Expand for items and collections: Die Daten des Knotens werden sowohl einbezogen, wenn das übergeordnete Element als einzelnes Element als auch als Sammlung angefordert wird (z. B. /orders).
GET Max Limit Das maximale Limit für Elemente, die in einer GET-Anfrage zurückgegeben werden können, unabhängig davon, was der Aufrufer anfordert. Wenn NULL, wird der Standardmaxwert für die REST API verwendet.
Bindings Richtet die Bindungen zwischen übergeordneten und untergeordneten Knoten ein, damit App Builder weiß, welche übergeordnete Spalte welcher untergeordneten Spalte entspricht, wenn die Daten verschachtelt werden. Nachdem Sie den Knoten speichern, wird neben Parent ein Link-Symbol angezeigt. Klicken Sie darauf, um das Dialogfeld Bindings zu öffnen, und ordnen Sie dann jede übergeordnete Spalte ihrer entsprechenden untergeordneten Spalte zu.

Knotenfelder

Jedes Feld, das Sie zum Panel Felder eines Knotens hinzufügen, steuert einen Datensatz in der JSON-Ausgabe des Knotens:

Name Beschreibung
Index Die Position des Feldes im Knoten.
Name Der Objektschlüssel, der für dieses Feld im JSON-Dokument verwendet wird. Feldnamen müssen innerhalb eines bestimmten Knotens eindeutig sein und sollten sicher als JSON-Schlüssel verwendbar sein: Vermeiden Sie Leerzeichen und Sonderzeichen.
Column Die Tabelle oder das Geschäftsobjekt-Spalte, die das Feld unterstützt.
Include By Default Gibt an, ob das Feld standardmäßig im Dokument enthalten ist. Aufrufer können dies mithilfe des Abfrageparameters $fields überschreiben.

Verschachtelte Struktur abfragen

Sobald eine Ressource eine verschachtelte Struktur hat, verhalten sich zwei vorhandene REST-URI-Konventions-Abfrageparameter unterschiedlich, wenn ein Aufrufer diese abfragt:

  • $fields akzeptiert einen Pfad zu einer untergeordneten Tabelle, sodass Aufrufer Felder aus verschachtelten Daten auswählen können, anstatt nur die Stammtabelle:

    Wert Wählt aus
    details/* Alle Felder der untergeordneten Tabelle details.
    details/name Nur das Feld name der untergeordneten Tabelle details.
    * Alle Felder in allen Tabellen.

  • $expand ist ein Parameter mit Wert „true" oder „false", mit dem ein Aufrufer die Einstellung Expand By Default eines Knotens für Item- und Collection-Anfragen überschreiben kann. $expand=true erweitert den Knoten unabhängig von seiner Standardeinstellung; $expand=false unterdrückt die Erweiterung unabhängig von seiner Standardeinstellung.