Arbeiten mit der Capping-API

Einführung

Die APIs von Journey Orchestration unterstützen 5.000 Ereignisse/Sekunde, doch manche externe Systeme oder APIs verfügen nicht über den gleichen Durchsatz. Deshalb bietet Journey Orchestration eine spezielle Funktion namens Capping-API zur Überwachung und Begrenzung der Rate, die wir externen Systemen auferlegen.

Bei der Konfiguration von Datenquellen definieren Sie eine Verbindung zu einem System, um zusätzliche Informationen abzurufen, die in Ihren Journeys verwendet werden; für eine Aktionsdefinition konfigurieren Sie eine Verbindung zu einem Drittanbietersystem, um Nachrichten oder API-Aufrufe zu senden. Jedes Mal, wenn eine Journey einen API-Aufruf vornimmt, wird die Capping-API abgefragt, bevor der Aufruf über die API-Engine erfolgt. Wenn eine Begrenzung definiert wurde, wird der Aufruf abgelehnt, damit das externe System nicht überlastet wird.

Bei externen Datenquellen wird die maximale Anzahl von Aufrufen pro Sekunde auf 15 festgelegt. Wenn die Anzahl der Aufrufe 15 pro Sekunde überschreitet, werden die verbleibenden Aufrufe verworfen. Sie können diese Beschränkung für private externe Datenquellen erhöhen. Wenden Sie sich an Adobe, um den Endpunkt in die Zulassungsliste aufzunehmen. Dies ist für öffentliche externe Datenquellen nicht möglich. Weiterführende Informationen zu Best Practices und Einschränkungen bei der Integration externer Systeme finden Sie auf dieser Seite.

Weitere Informationen zur Konfiguration von Aktionen oder Datenquellen finden Sie unter Informationen zu Aktionen oder Informationen zu Datenquellen

Ressourcen

Um diese API mit Ihrer Journey Orchestration-Instanz verwenden zu können, müssen Sie die Adobe I/O-Konsole verwenden. Sie können damit beginnen, indem Sie zuerst Erste Schritte mit Adobe Developer Console und dann die Abschnitte auf dieser Seite befolgen.

Um Ihre Integration zu testen und vorzubereiten, steht Ihnen hier eine Postman-Sammlung zur Verfügung.

Authentifizierung

Einrichten von API-Zugriff

Der API-Zugriff für Journey Orchestration wird wie folgt eingerichtet: Jeder dieser Schritte wird in der Adobe I/O-Dokumentation beschrieben.

1. Überprüfen Sie, ob Sie ein digitales Zertifikat haben, oder erstellen Sie bei Bedarf eines. Die mit dem Zertifikat bereitgestellten öffentlichen und privaten Schlüssel werden in den folgenden Schritten benötigt.
2. Erstellen Sie eine neue Integration mit dem Journey Orchestration-Service in Adobe I/O und konfigurieren Sie sie. Der Produktprofilzugriff wird für Journey Orchestration und Adobe Experience Platform benötigt. Dann werden Ihre Zugangsdaten generiert (API-Schlüssel, Client-Geheimnis…).
3. Erstellen Sie einen JSON-Web-Token (JWT) aus den zuvor erstellten Anmeldedaten und signieren Sie ihn mit Ihrem privaten Schlüssel. Der JWT kodiert alle Identitäts- und Sicherheitsdaten, die Adobe zum Überprüfen Ihrer Identität und zum Erteilen des Zugriffs auf die API benötigt. Dieser Schritt wird in diesem Abschnitt genau beschrieben.
4. Ersetzen Sie Ihr JWT durch einen Zugriffstoken, und zwar über eine POST-Anfrage oder über die Developer Console-Oberfläche. Dieser Zugriffstoken muss in allen Kopfzeilen Ihrer API-Anfragen verwendet werden.

Um eine sichere Service-to-Service-Adobe I/O-API-Sitzung herzustellen, muss jede Anfrage an einen Adobe-Dienst folgende Informationen in der Autorisierungskopfzeile umfassen.

curl -X GET https://journey.adobe.io/authoring/XXX \
 -H 'Authorization: Bearer <ACCESS_TOKEN>' \
 -H 'x-api-key: <API_KEY>' \
 -H 'x-gw-ims-org-id: <ORGANIZATION>'

• <ORGANIZATION>: Dies ist Ihre persönliche Organisationskennung; von Adobe erhalten Sie für jede Ihrer Instanzen eine Organisationskennung:

  • <ORGANIZATION>: Ihre Produktionsinstanz

  Wenden Sie sich an Ihren Administrator oder Ihren technischen Ansprechpartner bei Adobe, um den Wert Ihrer Organisationskennung zu erhalten. Sie können sie auch beim Erstellen einer neuen Integration in Adobe I/O abrufen, und zwar in der Lizenzliste (siehe Adobe I/O-Dokumentation).

• <ACCESS_TOKEN>: Ihr persönlicher Zugriffstoken, der beim Austausch Ihres JWT über eine POST-Anfrage abgerufen wurde.

• <API_KEY>: Ihr persönlicher API-Schlüssel. Er wird in Adobe I/O bereitgestellt, nachdem eine neue Integration mit dem Journey Orchestration-Service erstellt wurde.

Beschreibung der Capping-API

Mit der Capping-API können Sie Begrenzungskonfigurationen erstellen, konfigurieren und überwachen.

Bei der Erstellung oder Aktualisierung einer Konfiguration wird automatisch eine Überprüfung durchgeführt, um die Syntax und Integrität der Payload sicherzustellen.
Wenn Probleme auftreten, gibt der Vorgang eine Warnung oder Fehler zurück, die Ihnen beim Korrigieren der Konfiguration helfen.

Endpunktkonfiguration

Die grundlegende Struktur einer Endpunktkonfiguration sieht wie folgt aus:

{
    "url": "<endpoint URL>",  //wildcards are allowed in the endpoint URL
    "methods": [ "<HTTP method such as GET, POST, >, ...],
    "services": {
        "<service name>": { . //must be "action" or "dataSource"
            "maxHttpConnections": <max connections count to the endpoint>
            "rating": {
                "maxCallsCount": <max calls to be performed in the period defined by period/timeUnit>,
                "periodInMs": <integer value greater than 0>
            }
        },
        ...
    }
}

Beispiel:

`{
  "url": "https://api.example.org/data/2.5/*",
  "methods": [
    "GET"
  ],
  "services": {
    "dataSource": {
      "maxHttpConnections": 30000,
      "rating": {
        "maxCallsCount": 5000,
        "periodInMs": 1000
      }
    }
  },
  "orgId": "<IMS Org Id>"
}

Warnung und Fehler

Wenn eine canDeploy-Methode aufgerufen wird, validiert der Prozess die Konfiguration und gibt den durch seine eindeutige Kennung identifizierten Validierungsstatus zurück:

"ok" or "error"

Mögliche Fehler sind:

• ERR_ENDPOINTCONFIG_100: capping config: missing or invalid url
• ERR_ENDPOINTCONFIG_101: capping config: malformed url
• ERR_ENDPOINTCONFIG_102: capping config: malformed url: wildchar in url not allowed in host:port
• ERR_ENDPOINTCONFIG_103: capping config: missing HTTP methods
• ERR_ENDPOINTCONFIG_104: capping config: no call rating defined
• ERR_ENDPOINTCONFIG_107: capping config: invalid max calls count (maxCallsCount)
• ERR_ENDPOINTCONFIG_108: capping config: invalid max calls count (periodInMs)
• ERR_ENDPOINTCONFIG_111: capping config: can't create endpoint config: invalid payload
• ERR_ENDPOINTCONFIG_112: capping config: can't create endpoint config: expecting a JSON payload
• ERR_AUTHORING_ENDPOINTCONFIG_1: invalid service name <!--<given value>-->: must be 'dataSource' or 'action'

Die potenzielle Warnung lautet:

ERR_ENDPOINTCONFIG_106: capping config: max HTTP connections not defined: no limitation by default

Anwendungsfälle

In diesem Abschnitt finden Sie die fünf Hauptanwendungsfälle für die Verwaltung Ihrer Begrenzungskonfiguration in Journey Orchestration.

Um Ihnen bei Tests und der Konfiguration behilflich zu sein, steht Ihnen hier eine Postman-Sammlung zur Verfügung.

Diese Postman-Sammlung wurde eingerichtet, um die Postman-Variablensammlung freizugeben, die über Integrationen der Adobe I/O-Konsole > Testen > Für Postman herunterladen generiert wurde. Dadurch wird eine Postman-Umgebung mit den ausgewählten Integrationswerten erzeugt.

Nach dem Herunterladen und Hochladen in Postman müssen Sie drei Variablen hinzufügen: {JO_HOST}, {Base_Path} und {SANDBOX_NAME}.

• {JO_HOST} : Journey Orchestration-Gateway-URL
• {BASE_PATH} : Einstiegspunkt für die API. Der Wert lautet „/authoring“
• {SANDBOX_NAME}: der Header x-sandbox-name (z. B. „prod“), der dem Sandbox-Namen entspricht, in dem die API-Vorgänge stattfinden. Weiterführende Informationen dazu finden Sie unter Sandbox-Übersicht.

Im folgenden Abschnitt finden Sie die sortierte Liste der Rest-API-Aufrufe, um den Anwendungsfalls auszuführen.

Anwendungsfall 1: Erstellen und Bereitstellen einer neuen Begrenzungskonfiguration

1. list
2. create
3. candeploy
4. deploy

Anwendungsfall 2: Aktualisieren und Bereitstellen einer noch nicht bereitgestellten Begrenzungskonfiguration

1. list
2. get
3. Aktualisieren
4. candeploy
5. deploy

Anwendungsfall 3: Aufheben einer Bereitstellung und Löschen einer bereitgestellten Begrenzungskonfiguration

1. list
2. undeploy
3. delete

Anwendungsfall 4: Löschen einer bereitgestellten Begrenzungskonfiguration.

In nur einem API-Aufruf können Sie die Bereitstellung aufheben und die Konfiguration mithilfe des forceDelete-Parameters löschen.

1. list
2. delete mit forceDelete-Parameter

Anwendungsfall 5: Aktualisieren einer bereits bereitgestellten Begrenzungskonfiguration

1. list
2. get
3. Aktualisieren
4. undeploy
5. candeploy
6. deploy

Ressourcen für Business.Adobe.com