Externe API external-api
Beschreibung description
Mit der Aktivität Externe API können Daten aus einem externen System über einen HTTP-API-Aufruf in den Workflow integriert werden.
Bei den externen Systemendpunkten kann es sich um öffentliche API-Endpunkte, Kunden-Management-Systeme oder Server-lose Anwendungsinstanzen (z. B. Adobe I/O Runtime) handeln, um einige Kategorien zu nennen.
Die Hauptmerkmale dieser Aktivität sind:
- Möglichkeit zur Übertragung von Daten im JSON-Format an einen REST-API-Endpunkt eines Drittanbieters
- Möglichkeit, eine JSON-Antwort zu erhalten, sie mit Ausgabetabellen zu mappen und an nachfolgende Workflow-Aktivitäten zu übermitteln
- Fehlermanagement mit einer speziellen ausgehenden Transition
Hinweise zur Abwärtskompatibilität from-beta-to-ga
Mit Version 20.4 von Campaign Standard wurden die Leitplanken für die Größenbeschränkung für HTTP-Antwortdaten und das Antwort-Timeout abgesenkt, um den Best Practices zu entsprechen (siehe Einschränkungen und Limits). Diese Änderungen der Leitplanken wirken sich nicht auf bestehende externe API-Aktivitäten aus. Daher wird empfohlen, bestehende externe API-Aktivitäten in allen Workflows durch neue zu ersetzen.
Fügen Sie beim Ersetzen externer API-Aktivitäten die neue externe API-Aktivität zum Workflow hinzu, kopieren Sie manuell die Konfigurationsdetails und löschen Sie dann die alte Aktivität.
Einschränkungen und Leitplanken guardrails
Für diese Aktivität gelten die folgenden Schutzmaßnahmen:
- Größenbeschränkung für HTTP-Antwortdaten von 5 MB (Hinweis: Dies ist eine Änderung gegenüber der Beschränkung von 50 MB in der vorherigen Version).
- Die Zeitüberschreitung bei Anfragen beträgt 1 Minute (Hinweis: Dies ist eine Änderung gegenüber der Zeitüberschreitung von 10 Minuten in der vorherigen Version).
- HTTP-Umleitungen sind nicht zulässig.
- Andere URLs als HTTPS werden abgelehnt.
- Erlaubt sind Abfrage-Header vom Typ "Accept: application/json" und Antwort-Header vom Typ "Content-Type: application/json".
Es wurden spezielle Schutzmaßnahmen eingeführt:
- Max. JSON-Tiefe: begrenzt die maximale Tiefe einer benutzerdefinierten verschachtelten JSON, die auf 10 Ebenen verarbeitet werden kann.
- Max. JSON-Schlüssellänge: begrenzt die maximale Länge des internen Schlüssels auf 255. Dieser Schlüssel ist mit der Spaltenkennung verknüpft.
- Max. zulässige Zahl an JSON-Duplikatschlüsseln: begrenzt die maximale Gesamtzahl der als Spaltenkennung verwendeten Duplikat-JSON-Eigenschaftsnamen auf 150.
Konfiguration configuration
Ziehen Sie die Aktivität Externe API in Ihren Workflow und öffnen Sie sie, um sie zu konfigurieren.
Eingehendes Mapping
Beim eingehenden Mapping handelt es sich um eine temporäre Tabelle, die durch eine vorherige eingehende Aktivität generiert wurde. Sie wird in der Benutzeroberfläche als JSON angezeigt und gesendet.
Mithilfe dieser temporären Tabelle kann der Benutzer Änderungen an eingehenden Daten vornehmen.
Im Dropdown-Feld Eingehende Ressource können Sie die Abfrageaktivität auswählen, die die temporäre Tabelle erstellen soll.
Mit der Checkbox Zählerparameter hinzufügen wird ein Zählerwert für jede Zeile hinzugefügt, die aus der temporären Tabelle stammt. Beachten Sie, dass diese Checkbox nur verfügbar ist, wenn die eingehende Aktivität eine temporäre Tabelle generiert.
Der Bereich Eingehende Spalten ermöglicht Ihnen, beliebige Felder der Tabelle für eingehende Transitionen hinzuzufügen. Die ausgewählte(n) Spalte(n) dienen im Datenobjekt als Schlüssel. Das Datenobjekt im JSON-Format ist eine Array-Liste mit Daten für die ausgewählten Spalten aus jeder Zeile der Tabelle eingehender Transitionen.
Mit dem Textfeld Parameter anpassen können ein gültiges JSON-Format mit zusätzlichen Daten hinzufügen, die von der externen API benötigt werden. Diese zusätzlichen Daten werden dem params-Objekt im generierten JSON-Format hinzugefügt.
Ausgehendes Mapping
In diesem Tab können Sie das Muster der JSON-Struktur definieren, das vom API-Aufruf zurückgegeben wird.
Der JSON-Parser ist so konzipiert, dass er mit einigen Ausnahmen standardmäßige JSON-Strukturmustertypen aufnehmen kann. Ein Beispiel für ein Standardmuster ist: {“data”:[{“key”:“value”}, {“key”:“value”},...]}
Die JSON-Definition des Musters muss die folgenden Merkmale aufweisen:
- Array-Elemente müssen Eigenschaften der ersten Ebene enthalten (tiefere Ebenen werden nicht unterstützt).
Eigenschaftsnamen werden zu Spaltennamen für das Ausgabeschema der temporären Ausgabetabelle. - Zu erfassende JSON-Elemente dürfen innerhalb der JSON-Antwort maximal 10 Verschachtelungsebenen aufweisen.
- Die Definition von Column name basiert auf dem ersten Element des "data"-Array.
Die Spaltendefinitionen (Hinzufügen/Entfernen) und der Wert des Eigenschaftentyps können im Tab Spaltendefinition bearbeitet werden.
Verhalten der Checkbox "Abflachen":
Die Checkbox "Abflachen" (Standard: deaktiviert) dient zur Angabe, ob JSON auf eine Schlüssel/Wert-Zuordnung abgeflacht werden soll oder nicht.
-
Wenn die Checkbox deaktiviert (nicht markiert) ist, wird die JSON-Musterdatei analysiert, um nach einem Array-Objekt zu suchen. Der Anwender muss eine reduzierte Version des JSON-Musterformats für die API-Antwort bereitstellen, damit Adobe Campaign genau bestimmen kann, welches Array der Anwender nutzen möchte. Beim Authoring des Workflows wird der Pfad zum verschachtelten Array-Objekt ermittelt und erfasst, sodass er zur Ausführungszeit verwendet werden kann, um auf dieses Array-Objekt aus dem JSON-Antwortteil zuzugreifen, der vom API-Aufruf empfangen wurde.
-
Wenn die Checkbox aktiviert (markiert) ist, wird die JSON-Musterdatei abgeflacht und alle Eigenschaften, die in der bereitgestellten JSON-Musterdatei angegeben sind, werden genutzt, um Spalten der temporären Ausgabentabelle zu erstellen. Zudem erfolgt eine Anzeige auf dem Tab "Spaltendefinitionen". Beachten Sie, dass alle Elemente dieser Array-Objekte ebenfalls abgeflacht werden, wenn sich in der JSON-Musterdatei ein Array-Objekt befindet.
Wenn das Parsen validiert wird, erscheint eine Meldung, die Sie auffordert, das Daten-Mapping im Tab "Spaltendefinition" anzupassen. Andernfalls wird eine Fehlermeldung angezeigt.
Ausführung
In diesem Tab können Sie den Endpunkt der Verbindung definieren. Mit dem Feld URL können Sie den HTTPS-Endpunkt definieren, mit dem Campaign Standard kommuniziert.
Falls der Endpunkt dies benötigt, stehen zwei Authentifizierungsmechanismen zur Verfügung:
-
Einfache Authentifizierung: Geben Sie in den Abschnitt Header abrufen Ihren Benutzernamen und Ihr Passwort ein.
-
OAuth-Authentifizierung: Durch Klicken auf In einem externen Konto definierte Verbindungsparameter verwenden können Sie ein externes Konto auswählen, in dem die OAuth-Authentifizierung definiert ist. Weiterführende Informationen hierzu finden Sie im Abschnitt Externe Konten.
Eigenschaften
In diesem Tab können Sie allgemeine Eigenschaften der externen API-Aktivität steuern, wie den in der Benutzeroberfläche angezeigten Titel. Die interne ID kann nicht verändert werden.
Spaltendefinition
Im Tab Spaltendefinition lässt sich die Datenstruktur für jede Spalte separat definieren, um fehlerfreie Daten zu importieren und die Kompatibilität mit den bereits in der Datenbank existierenden Daten zu gewährleisten.
Es besteht beispielsweise die Möglichkeit, Spaltentitel und Datentyp (String, Ganze Zahl, Datum etc.) anzupassen bzw. den Umgang mit Fehlern zu bestimmen.
Weiterführende Informationen hierzu finden Sie im Abschnitt Datei laden.
Transition
In diesem Tab können Sie die ausgehende Transition und ihren Titel aktivieren. Diese spezifische Transition ist nützlich im Fall von Zeitüberschreitung oder wenn die Payload die maximale Datengröße überschritten hat.
Ausführungsoptionen
Dieser Tab ist in den meisten Workflow-Aktivitäten verfügbar. Lesen Sie für weiterführende Informationen den Abschnitt Aktivitätseigenschaften.
Testen
Wenn Sie die Funktionalität der externen API mit einem einfachen Test-Endpunkt testen möchten, können Sie Postman Echo verwenden: https://docs.postman-echo.com.
Fehlerbehebung
Zu dieser neuen Workflow-Aktivität wurden zwei Arten von Lognachrichten hinzugefügt: Informationen und Fehler. Diese können Ihnen helfen, potenzielle Probleme zu beheben.
Informationen
In diesen Lognachrichten werden während der Ausführung der Workflow-Aktivität Informationen über nützliche Kontrollpunkte protokolliert.
Fehler
In diesen Lognachrichten werden Informationen zu unerwarteten Fehlerbedingungen protokolliert, die letztendlich dazu führen können, dass die Workflow-Aktivität fehlschlägt.
API-URL konnte nicht geparst werden (Fehler: '-2010').
Hinweis: Dieser Fehler wird protokolliert, wenn die API-URL die Validierungsregeln nicht erfüllt.
API-URL-Host darf nicht 'localhost' oder IP-Adressen-Literal sein (URL-Host: 'localhost‘).
API-URL-Host darf nicht 'localhost' oder IP-Adressen-Literal sein (URL-Host: '192.168.0.5').
API-URL-Host darf nicht 'localhost' oder IP-Adressen-Literal sein (URL-Host: '[2001]‘).
Angeforderte JSON konnte nicht erstellt werden. Fehler beim Hinzufügen von 'params'.
Angeforderte JSON konnte nicht erstellt werden. Fehler beim Hinzufügen von 'data'.
HTTP-Header-Schlüssel ist ungültig (Header-Schlüssel: '%s').
Hinweis: Dieser Fehler wird protokolliert, wenn der benutzerdefinierte Header-Schlüssel die RFC-Validierung nicht besteht.
HTTP-Header-Wert ist ungültig (Header-Wert: '%s').
Hinweis: Dieser Fehler wird protokolliert, wenn der benutzerdefinierte Header-Wert die RFC-Validierung nicht besteht.
Ungültige JSON oder falsches Format
Hinweis: Diese Nachricht gilt nur für das Parsen des Antwort-Hauptteils in der externen API und wird protokolliert, wenn versucht wird, zu überprüfen, ob der Antwort-Hauptteil dem durch diese Aktivität vorgeschriebenen JSON-Format entspricht.
Wenn die Aktivität aufgrund der HTTP 401-Fehlerantwort fehlschlägt - Aktivität fehlgeschlagen (Grund: 'HTTP - 401').
Wenn die Aktivität aufgrund eines fehlgeschlagenen internen Aufrufs fehlschlägt - Aktivität fehlgeschlagen (Grund: 'iRc - -Nn').
Wenn die Aktivität aufgrund eines Headers eines ungültigen Inhaltstyps fehlschlägt. - Aktivität fehlgeschlagen (Grund: 'Content-Type - application/html').