Show Menu
THEMEN×

Externe API

Beschreibung

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.
Aus Sicherheitsgründen wird die Verwendung von JSSPs in Campaign Standard nicht unterstützt. Wenn Sie Code ausführen müssen, können Sie eine Adobe I/O Runtime-Instanz über eine externe API-Aktivität aufrufen.
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

Mit Version 20.4 von Campaign Standard wurden die Limits für die Größenbeschränkung für HTTP-Antwortdaten und das Antwort-Timeout gesenkt, um den Best Practices zu entsprechen (siehe Abschnitt "Einschränkungen und Limits"). Diese Änderungen der Limits 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.
Wenn Sie ein Upgrade von Campaign Standard 20.2 (oder früher) durchführen, beachten Sie bitte, dass die externe API-Funktionalität in der Version 20.3 von Beta auf "Allgemeine Verfügbarkeit" verschoben wurde.
Wenn Sie also in der Betaversion externe API-Aktivitäten verwendet haben, müssen Sie sie in allen Workflows durch allgemein verfügbare externe API-Aktivitäten ersetzen.  Workflows, die die Betaversion der externen API verwenden, funktionieren ab Version 20.3 von Campaign Standard nicht mehr.
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.
Sie können keine aktivitätenspezifische Header-Werte kopieren, da diese in der Aktivität maskiert sind.
Konfigurieren Sie anschließend andere Aktivitäten im Workflow, die auf Daten der externen API-Aktivität (Beta) verweisen bzw. solche Daten verwenden, sodass sie stattdessen auf Daten der neuen externen API-Aktivität verweisen bzw. solche Daten verwenden. Beispiele für Aktivitäten: E-Mail-Versand (Personalisierungsfelder), Anreicherungsaktivität usw.

Einschränkungen und Limits

Für diese Aktivität gelten die folgenden Limits:
  • 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-Weiterleitungen 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 Limits 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.
Die Externe API-Aktivität ist zum Abrufen von Daten aus der gesamten Kampagne (letzte Angebotspakete, aktuelle Bewertungen usw.) und nicht zum Abrufen spezifischer Informationen für jedes Profil gedacht, da dies zu einer Übertragung großer Datenmengen führen kann. Sollte dies dennoch erforderlich sein, wird empfohlen, die Aktivität Datei übertragen zu verwenden.

Konfiguration

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. Im Feld URL können Sie den HTTPS-Endpunkt definieren, der Daten an ACS sendet.
Falls der Endpunkt dies benötigt, stehen zwei Authentifizierungsmechanismen zur Verfügung:
  • Einfache Authentifizierung: Geben Sie Ihren Benutzernamen und das Kennwort in das Feld Header abrufen 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

Dieser Tab wird angezeigt, wenn das Antwortdatenformat ausgefüllt und im Tab "Ausgehendes Mapping" validiert wird.
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 .

Problembehebung

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.
Nachrichtenformat Beispiel
API-URL '%s' wird aufgerufen.
API-URL 'https://example.com/api/v1/web-coupon?count=2' wird aufgerufen.
Wiederholen der API-URL '%s' wegen %s in %d ms, Versuch %d.
Wiederholen der API URL 'https://example.com/api/v1/web-coupon?count=0' wegen HTTP - 401 in 2364 ms, Versuch 2.
Inhalt wird aus '%s' (%s / %s) transferiert.
Inhalt wird aus 'https://example.com/api/v1/web-coupon?count=2' (1234 / 1234) transferiert.
Verwendung des Zugriffs-Tokens im Cache für Anbieter-ID '%s'.
Verwendung des Zugriffs-Tokens im Cache für Anbieter-ID 'EXT25'. Hinweis: EXT25 ist die ID (oder der Name) des externen Kontos.
Zugriffs-Token für Anbieter-ID '%s' vom Server abgerufen.
Zugriffs-Token für Anbieter-ID 'EXT25' vom Server abgerufen. Hinweis: EXT25 ist die ID (oder der Name) des externen Kontos.
Aktualisierung des OAuth-Zugriffs-Tokens aufgrund eines Fehlers (HTTP: '%d').
Aktualisierung des OAuth-Zugriffs-Tokens aufgrund eines Fehlers (HTTP: '401').
Fehler beim Aktualisieren des OAuth-Zugriffs-Tokens (Fehler: '%d').
Fehler beim Aktualisieren des OAuth-Zugriffs-Tokens (Fehler: '404').
Das OAuth-Zugriffstoken konnte mit dem spezifizierten externen Konto bei Versuch %d nicht abgerufen werden, Wiederholungsversuch in %d ms.
Das OAuth-Zugriffstoken konnte mit dem spezifizierten externen Konto bei Versuch 1 nicht abgerufen werden, Wiederholungsversuch in 1387 ms.

Fehler

In diesen Lognachrichten werden Informationen zu unerwarteten Fehlerbedingungen protokolliert, die letztendlich dazu führen können, dass die Workflow-Aktivität fehlschlägt.
Code - Nachrichtenformat Beispiel
WKF-560250 - API-Anfrage-Hauptteil überschritt Limit (Limit: '%d').
API-Anfrage-Hauptteil überschritt Limit (Limit: '5242880‘).
WKF-560239 - API-Antwort hat Limit überschritten (Limit: '%d').
API-Antwort hat Limit überschritten (Limit: 5242880').
WKF-560245 - API-URL konnte nicht geparst werden (Fehler: '%d').
API-URL konnte nicht geparst werden (Fehler: '-2010').
Hinweis: Dieser Fehler wird protokolliert, wenn die API-URL die Validierungsregeln nicht erfüllt.
WKF-560244 - API-URL-Host darf nicht 'localhost' oder IP-Adressen-Literal sein (URL-Host: '%s').
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]‘).
WKF-560238 - API-URL muss eine sichere URL sein (HTTPS) (angefragte URL: '%s').
API-URL muss eine sichere URL (HTTPS) sein (angeforderte URL: 'https://example.com/api/v1/web-coupon?count=2').
WKF-560249 - angeforderte JSON konnte nicht erstellt werden. Fehler beim Hinzufügen von '%s'.
Angeforderte JSON konnte nicht erstellt werden. Fehler beim Hinzufügen von 'params'.
Angeforderte JSON konnte nicht erstellt werden. Fehler beim Hinzufügen von 'data'.
WKF-560246 - HTTP-Header-Schlüssel ist ungültig (Header-Schlüssel: '%s').
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.
WKF-560248 - HTTP-Header-Schlüssel ist nicht erlaubt (Header-Schlüssel: '%s').
HTTP-Header-Schlüssel ist nicht erlaubt (Header-Schlüssel: 'Accept').
WKF-560247 - Ein HTTP-Header-Wert ist fehlerhaft (Header-Wert: '%s').
HTTP-Header-Wert ist ungültig (Header-Wert: '%s').
Hinweis: Dieser Fehler wird protokolliert, wenn der benutzerdefinierte Header-Wert die RFC -Validierung nicht besteht.
WKF-560240 - JSON-Payload hat ungültige Eigenschaft '%s'.
JSON-Payload hat ungültige Eigenschaft 'blah'.
WKF-560241 - Ungültige JSON oder falsches Format.
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.
WKF-560246 - Aktivität fehlgeschlagen (Grund: '%s').
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').
WKF-560278 – "Fehler beim Initialisieren des OAuth-Helfers (Fehler: '%d')".
Dieser Fehler weist darauf hin, dass die Aktivität die interne OAuth2.0-Hilfsfunktion nicht initialisieren konnte, da die im externen Konto konfigurierten Attribute zur Initialisierung der Hilfsfunktion fehlerhaft verwendet wurden.
WKF-560279 – "HTTP-Header-Schlüssel ist nicht erlaubt (Header-Schlüssel: '%s')."
Diese Warnmeldung (keine Fehlermeldung) weist darauf hin, dass das externe OAuth 2.0-Konto so konfiguriert wurde, dass Zugangsdaten als ein HTTP-Header hinzugefügt werden, der verwendete Header-Schlüssel jedoch nicht zulässig ist, da es sich um einen reservierten Header-Schlüssel handelt.
WKF-560280 – Das externe Konto der Kennung '%s' kann nicht gefunden werden.
Das externe Konto der Kennung 'EXT25' kann nicht gefunden werden. Hinweis: Dieser Fehler weist darauf hin, dass die Aktivität für die Verwendung eines externen Kontos konfiguriert ist, das nicht mehr gefunden werden kann. Dies ist am wahrscheinlichsten, wenn das Konto aus der Datenbank gelöscht wurde, und ist als solches unter normalen Betriebsbedingungen nicht zu erwarten.
WKF-560281 – Das externe Konto der Kennung '%s' ist deaktiviert.
Das externe Konto der Kennung 'EXT25' ist deaktiviert. Hinweis: Dieser Fehler weist darauf hin, dass die Aktivität zur Verwendung eines externen Kontos konfiguriert ist, dieses Konto jedoch deaktiviert (oder als inaktiv markiert) wurde.
WKF-560282 – Protokoll wird nicht unterstützt.
Dieser Fehler weist darauf hin, dass das mit der Aktivität verknüpfte externe Konto kein externes OAuth2.0-Konto ist. Daher ist es unwahrscheinlich, dass dieser Fehler auftritt, es sei denn, die Konfiguration der Aktivität wurde beschädigt oder manuell geändert.
WKF-560283 – Abrufen des OAuth-Zugriffs-Tokens fehlgeschlagen.
Die häufigste Ursache dieses Fehlers ist eine Fehlkonfiguration des externen Kontos (z. B.: Verwendung des externen Kontos ohne Prüfung, ob die Verbindung erfolgreich hergestellt wurde). Möglicherweise werden die URL-/Zugangsdaten im externen Konto geändert.
CRL-290199 – Seite nicht erreichbar unter: %s.
Diese Fehlermeldung wird auf dem Bildschirm der Benutzeroberfläche des externen Kontos angezeigt, wenn dieses für OAuth eingerichtet wird. Sie bedeutet, dass die URL für den externen Autorisierungs-Server entweder falsch oder geändert wurde oder der Server mit "Seite nicht gefunden" antwortet.
CRL-290200 – Unvollständige/falsche Zugriffsdaten.
Diese Fehlermeldung wird auf dem Bildschirm der Benutzeroberfläche des externen Kontos angezeigt, wenn dieses für OAuth eingerichtet wird. Sie bedeutet, dass die Zugangsdaten entweder falsch sind oder andere erforderliche Zugangsdaten für die Verbindung mit dem Autorisierungs-Server fehlen.