In diesem Artikel wird erläutert, wie Sie mithilfe der REST API von Campaign Standard Vorgänge in Ihrer Datenbank durchführen können.

Umfang

In diesem Dokument wird beschrieben, wie Sie die APIs von Adobe Campaign Standard verwenden. Außerdem finden Sie hier allgemeine Richtlinien sowie Beispiele zum Implementieren und Verwenden dieser APIs.

  1. Szenarien für die Nutzung der APIs von ACS.
  2. Authentifizierung über Adobe I/O und Generieren von JWTs (JSON Web Token).
  3. Ausführen/Lesen/Aktualisieren/Löschen (CRUD) von Vorgängen in einem Profil mithilfe von APIs von ACS. (praktische Übung)
  4. Subscribing und Unsubscribing eines Profils von einem Dienst, mithilfe der APIs von ACS. (praktische Übung)
  5. Integrieren der APIs in eine Test-Website. (Beispiel) 

 

Voraussetzungen

Ein Marketing-Business-Benutzer für ACS APIS sollte ein Verständnis für Folgendes haben:

  1. Zweck der API-Aufrufe. 
  2. Anwendungsfälle für API-Aufrufe. 
  3. Anwendung technischer Lösungen zur Lösung von Problemen in der realen Welt. 

Ein Entwickler für ACS-APIs sollte über die folgenden Rechte und Kenntnisse verfügen:

  1. Zweck und Verwendung von REST-APIs.
  2. Administratorrechte für ACS.
  3. Adobe.IO-Authentifizierungs-Konfigurationsschritte und Wissen über die Generierung von JWT-Token.

Referenzmaterial

Die folgenden Artikel sind gute Referenzmaterialien zu ACS-APIs und verwandte Technologie-Frameworks, einschließlich Adobe I/O.

Reales Beispiel für ACS-APIs

Der Adobe Campaign Standard bietet APIs, mit denen vorhandene Systeme in die ACS-Plattform integriert werden können, um reale Probleme in Echtzeit zu lösen. Öffentliche Webseiten wie die Anmeldeseite oder die „Opt-out“-Seite müssen eine Verbindung zu Backend-Systemen herstellen, um Profilinformationen zu speichern. Backend-Systeme wie Adobe Campaign verfügen über die Flexibilität und die Fähigkeit, Profildaten in benutzerdefinierte Daten aufzunehmen und mit ihnen benutzerdefinierte Vorgänge auszuführen. 

Anmelde-Landingpage und Präferenzzentrum.

Die Anmeldeseite – von der Beispielwebseite Geometrixx – bietet Kunden oder Interessenten die Möglichkeit, ihren Namen und ihre E-Mail-Adresse zu registrieren. Sobald ACS die Profilinformationen und -einstellungen erfasst, kann ACS personalisierte Nachrichten basierend auf den Interessen der Person senden. 

1. Ein Registrierungsformular mit Kampagnen-API-Listeners.

L4281_1

2. Benutzerdefinierte Aktionen werden durchgeführt, basierend auf den Kontrollkästchen. Ein Kunde, der „E-Mail-Sonderangebote“ auswählt, erhält im Vergleich zum normalen Registrierungsprozess eine andere benutzerdefinierte E-Mail mit einem Geschenkgutschein.

L4281_2

3. Ein Profil kann seine Angaben ändern, nachdem auf den „Details aktualisieren“-Link in der E-Mail geklickt wurde. Das bringt das Profil auf die „Aktualisieren Sie Ihr Profil und Präferenzangaben“-Seite. Um die Handlung auszuführen, werden die Profildetails (Pkey) an den Campaign-Server übergeben und das Profil wird abgerufen und dargestellt. Sobald das Profil auf die Schaltfläche „Aktualisieren“ klickt, werden die Informationen im System aktualisiert (über den PATCH-Befehl). 

L4281_3

Dieses Dokument konzentriert sich hauptsächlich darauf, es Entwicklern zu ermöglichen, ACS APIs in Szenarien wie dem vorherigen zu verwenden und dabei zu helfen, erfolgreiche Emailkampagnen und Systeme zu entwerfen.  

Die Vorteile von ACS APIs

Für geschäftliche Zwecke

Integration der Campaign Standard-Plattform auf der Website und/oder geschäftlichen Systemen (Auftragsbearbeitung, Transaktionssysteme, POS etc.) um die Nutzer-Profil-Synchronisation in Echtzeit durchzuführen und Nachrichten auszulösen.  


Nachstehend sind einige Beispiele aufgeführt: 

  • Möglichkeit einer Onlineregistrierung.
  • Bestehende Nutzerprofile und Marketing-Kommunikations-Vorzugs-Management.
  • Ereignisbasiertes Auslösen der Transaktionskommunikation – Auftragsbestätigung, Buchungsablauf, Passwortrücksetzung etc.
  • Sogar der Warenkorbabbruch über E-Mail-Kommunikation.

Technische Lösung

ACS-APIs ermöglichen es Entwicklern und Programmierern, die folgenden Operationen nahtlos durchzuführen:

  1. Daten in Echtzeit synchronisieren.
    1. CRUD-Operationen an Profilen und Diensten durchführen. 
    2. Profile für einen Dienst abonnieren und abbestellen. 
  2. Nachrichtenauslösung in Echtzeit.
    1. Senden Sie benutzerdefinierte E-Mails oder SMS an Profile, die auf dem Anwenderverhalten basieren.  

Einrichten

Authentifizieren mit Adobe und Generieren des Zugriffstokens

APIs von Adobe Campaign erfordern einen „API-Schlüssel und ein „Anwendertoken“, um Benutzer zu authentifizieren, die APIs anfordern. In diesem Abschnitt wird beschrieben, wie der Administrator der Experience Cloud Organisation die einmalige Einrichtung von Adobe.IO durchführen würde, um sie zu den ACS APIs hinzuzufügen.  

Konfigurieren von Adobe.IO für die Verwendung des öffentlichen Tokens für den Zugriff auf ACS APIs

1. Melden Sie sich bei der Adobe Input-/Output-Konsole an (https://www.adobe.io/console) und wählen Sie Ihre IMS-Organisation aus der Organisations-Ausgliederung aus. Wählen Sie danach neue Integration.

Screen Shot 2017-05-22 at 11.52.09

2. Wählen Sie die Art der Integration aus, die Sie konfigurieren möchten. Wählen Sie hier API-Zugriff und klicken Sie auf Weiter.

Screen Shot 2017-05-22 at 11.58.58

3. Wählen Sie Adobe Campaign in der Liste der möglichen Integrationen im Bereich Experience Cloud und klicken Sie auf Weiter.

Screen Shot 2017-05-22 at 12.10.27

4. Wählen Sie Neue Integration und klicken Sie auf Weiter.

Screen Shot 2017-05-22 at 12.15.11

5. Geben Sie die erforderlichen Details ein, um die neue Integration einzurichten:

  • Geben Sie den Namen und die Beschreibung der Integration an.
  • Registrieren Sie Zertifikate in Adobe I/O, indem Sie Ihren öffentlichen Schlüssel hochladen. Die Schlüssel werden später bei der Generierung von JWTs verwendet. Ihre Schlüssel sollten .crt-Dateien sein.
  • Wählen Sie den zu verwendenden Campaign-Service. Diese Liste besteht aus Campaign-Benutzergruppen, die für die Organisation verfügbar sind, die Sie im ersten Schritt ausgewählt haben.

Klicken Sie dann auf Integration erstellen.

Die Integration wird automatisch erstellt und Sie können nun auf ihre Details zugreifen.

Screen Shot 2017-05-22 at 12.21.19
Screen Shot 2017-05-22 at 12.25.53

6. Bewahren Sie die folgenden Anmeldedaten zum Generieren des JWT auf. 

  • API key
  • Kundengeheimnis
  • Technische Konto-ID
  • Organisations-ID
Screen_Shot_2017-05-22_at_12_36_11
Screen_Shot_2017-05-22_at_12_36_40

Generieren eines Tokens mit JWT

Um ACS-APIs-Zugriffstoken zu nutzen, werden sie für die Benutzerauthentifizierung bereitgestellt. Verwenden Sie die oben gespeicherten Anmeldedaten um das JWT zu generieren. Ein Python-Beispielskript ist unten angegeben um das JWT zu generieren. 
Andere Sprachen werden von der Open-Source-Community unterstützt.

Sie finden weitere Informationen auf dieser Seite: https://www.adobe.io/apis/cloudplatform/usermanagement/docs/setup.html

import sys
if sys.version_info[0] ==2:
from ConfigParser import RawConfigParser
from urllib import urlencode
elif sys.version_info[0] >=3:
from configparser import RawConfigParser
from urllib.parse import urlencode
import time
import jwt
import requests
import json
import email.utils
import math
import random
expiry = int(time.time()) + 60*60*24
payload = {
"https://ims-na1.adobelogin.com/s/ent_campaign_sdk" : True,
"exp" : expiry,
"iss" : "<Organization ID> ", // Example : 3CAF2DEA571E82A87F000101@AdobeOrg
"sub" : "<Technical account ID> ", // Example : A5714DE558B7A30C0A495C3A@techacct.adobe.com "aud" : https://ims-na1.adobelogin.com/c/< API key> // Example : 43e61e5733c34c2882d0b4af9580016f
}
priv_file = open("<Path to private key>") // Example : ‘C:/Users/njia/Work/API/ACS API/private.key’
priv_key = priv_file.read()
priv_file.close()
jwt_token = jwt.encode(payload, priv_key, algorithm='RS256')
jwt_token = jwt_token.decode("utf-8")
print(jwt_token)

Zugriffstoken

Sie müssen ein Token generieren und verwenden, um REST-Vorgänge durchzuführen. 

Quellennachweis 


Erfahren Sie mehr über den Authentifizierungsprozess und die Token-Generierung: https://www.adobe.io/apis/cloudplatform/usermanagement/docs/setup.html

Die Generierung von JSON Webtokens ist für die Verwendung der APIs unerlässlich. 

Über Postman

Um die Verwendung von APIs zu zeigen, verwenden die Vorgehensweisen dieses Dokuments das Postman-Werkzeug, um Anrufe zu löschen.  

  • Stellen Sie sicher, dass Sie Postman auf Ihrem Desktop starten können (installieren Sie das Chrome-Zusatzprogramm): https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=de
  • Importieren der JSON-Sammlung mit allen Postman-Proben (3 Dateien, eine pro Fall), per E-Mail geteilt.
  • Jede JSON-Sammlung besitzt Folgendes:
    • Fest programmierter API-Schlüssel.
    • Korrekte URL für API endpoint, die den Namen des tenant enthält.
    • Vorkonfigurierter Event Name für die Verwendung in Echtzeit-messaging (gleich in drei Fällen).
  • Access Token muss in POSTMAN eingefügt werden. 

Daten in Echtzeit synchronisieren

Mit den APIs können Entwickler die folgenden CRUD für ein Profil ausführen:

  1. Fügen Sie ein Profil hinzu.
  2. Abrufen eines Profils aus einer E-Mail-ID. 
  3. Ändern Sie ein Profil. 
  4. Listen Sie Dienste in einem Konto auf.
  5. Abonnieren Sie ein Profil für einen Dienst. 
  6. Ein Profil von einem Dienst abmelden. 

Lektion 1 – Profil hinzufügen

1. Starten Sie POSTMAN und importieren Sie eine Sammlung (siehe unten auf dieser Seite).

L4281_12

2. Öffnen Sie den REST-API-Aufruf "ACS Profile Insert" und beobachten Sie die Werte der Request-Header. 

L4281_13

3. X-API-Schlüssel und URL sollten festgelegt werden basierend auf Ihrer Instanz.

4. Autorisierung festlegen basierend auf dem Token, das Sie erstellt haben.

L4281_14

5. Schaltfläche "Senden" klicken. 

6. Validieren Sie Ergebnisse im Ausgabefenster (JSON-Objekt) Post Body. 

L4281_15

Die Antwort der Anforderung wird unten angezeigt. Die eindeutige ley, die mit allen Objekten verknüpft ist, die im ACS system verknüpft sind, wird als PKey bezeichnet. Nachdem ein Profil erstellt wurde, enthält die Antwort PKey zusammen mit anderen Attributen. 

L4281_16

7. Profilüberprüfung. Melden Sie sich bei ACS an und sehen Sie, dass das Profil erstellt wurde.

  • Melden Sie sich mit den angegebenen Anmeldeinformationen bei ACS an und navigieren Sie in der oberen Kopfzeile zu „Profile“. 
L4281_17
  • Suchen Sie über die E-mailadresse nach Ihrem Profil: 
    • Klicken Sie auf das Symbol „Suche anzeigen“ oben links unter „Adobe Campaign“.
L4281_18
  • Geben Sie Suchkriterien per E-Mail ein. In diesem Fall sample@adobe.com. 
  • Klicken Sie auf „Eingabetaste“ und die Ergebnisse werden im rechten Fensterbereich angezeigt. 
L4281_19
  • Ergebnisse überprüfen.
L4281_20

Um das POST-Profil zusammenzufassen, ist der API-Aufruf wie folgt aufgebaut:

API – https://mc.adobe.io/<tenant_name>/campaign/profileAndServicesExt/profile/

Request-Header:

  • X-Api-Key: Der Wert des API-Schlüssels, der von Adobe I/O bereitgestellt wird.
  • Autorisierung: Zugriffstoken im „Bearer“-Format. 
  • Cache-Kontrolle: no-cache (empfohlen, um Probleme beim Zwischenspeichern von Inhalten zu vermeiden).
  • Inhaltstyp: application/json – Die Anfrage erwartet die Nutzlast im JSON-Format. 

Anforderungsmethode – POST

 
Abfrage-Body
Der Abfrage-Body muss ein JSON-BLOB sein, das Profilinformationen enthält:

{
"email":"hello@abd.com",
"cusCustomer_ID":"Adobe1000003",
"firstName":"Hello",
"lastName":"World"
}

Antwort-Body

{
"PKey": “@YDiPuQnFDXw_QJhpYrDS08PihTZGn88AszVPWMNLlM1smuI8hYnGwxCGo9CcvrhxnKhf2ZeF4mLWBqKlPYvvfR5lZac",
"age": 0,
"birthDate": ""
}

Lektion 2 – Laden Sie ein Profil aus einer E-Mail-Adresse

Ein Profil kann mithilfe der GET method in der API von ACS gesucht und abgerufen werden.

API – https://mc.adobe.io/<tenant_name>/campaign/profileAndServicesExt/profile/byEmail?email=abcd@adobe.com

Request-Header:

  • X-Api-Key: Der Wert des API-Schlüssels, der von Adobe I/O bereitgestellt wird.
  • Autorisierung: Access Token im Format „Bearer“. 
  • Cache-Kontrolle: kein Cache (empfohlen, um Probleme beim Caching von Inhalten zu vermeiden).

Anforderungsmethode – GET

 
Antwortrumpf
Der Antwortrumpf hat einen JSON-Blob mit Profilinformationen. Wie in der Abbildung unten mit dem PKey und anderen Profilschlüsseln und Werten dargestellt.

L4281_21

Lektion 3 – Profil aktualisieren

L4281_22

Ein Profil kann mit der PATCH-Methode auf der ACS-API aktualisiert werden.

Suchen Sie anhand seiner E-Mail-Adresse nach einem Profil. Ermitteln Sie den PKey-Wert wie in der obigen Lektion beschrieben und verwenden Sie den PKey, um das Profil zu aktualisieren. 

API – https://mc.adobe.io/<tenant_name>/campaign/profileAndServicesExt/profile/

Request-Header

  • X-Api-Key: Wert der von Adobe I/O bereitgestellten API.
  • Autorisierung: Zugriffstoken im „Bearer“-Format.
  • Cache-Kontrolle: kein Cache (empfohlen, um Probleme beim Caching von Inhalten zu vermeiden)
  • Content-Typ: application/json – Der Request erwartet die Payload im JSON-Format. 

Anforderungsmethode – PATCH


Request-Body
Der Request-Body muss ein JSON-Blob mit spezifischen Informationen sein, die aktualisiert werden müssen.


Response Body
Der Response Body besteht aus PKey und der Profil-URI wie im Bild unten gezeigt.

L4281_23

Um die Änderungen zu überprüfen, verwenden Sie die href im Response-Body. 

Lektion 4 – Erhalten Sie die Liste der Abonnements für ein Profil

Ein Profil kann mithilfe der GET-Methode in der ACS-API gesucht und abgerufen werden.


API – https://mc.adobe.io/<tenant_name>/campaign/profileAndServicesExt/profile/<profile_pkey>/subscriptions

Request-Header

  • X-Api-Key: Wert des von Adobe I/O bereitgestellten API.
  • Autorisierung: Zugriffstoken im „Bearer“-Format.
  • Cache-Kontrolle: no-cache (empfohlen, um Probleme beim Zwischenspeichern von Inhalten zu vermeiden).

Anforderungsmethode – GET

Antwort-Body
Der Antwort-Body enthält ein JSON-Blob mit einer Liste von Abonnements für das Profil.

Lektion 5 – Dienste auflisten

Um alle Dienste in einem Konto aufzulisten, verwenden Sie die GET-Methode um die Service-API aufzurufen.


API – https://mc.adobe.io/<instance name>.adobe.com/campaign/profileAndServices/service

Request-Header

  • X-Api-Key: Wert des von Adobe I/O bereitgestellten API.
  • Autorisierung: Zugriffstoken im „Bearer“-Format.
  • Cache-Kontrolle: no-cache (empfohlen, um Probleme beim Zwischenspeichern von Inhalten zu vermeiden).

Anforderungsmethode

L4281_24

Lektion 6 – Ein Profil für einen Dienst abonnieren

Ein Profil kann für einen Dienst abonniert werden, indem man seinen PKey an die folgende API sendet.

API – https://mc.adobe.io/<mieter_name>/campaign/profileAndServices/service/<service_id>/subscriptions

Request-Header

  • X-Api-Key: Wert des von Adobe I/O bereitgestellten API.
  • Autorisierung: Zugriffstoken im „Bearer“-Format.
  • Cache-Kontrolle: no-cache (empfohlen, um Probleme beim Zwischenspeichern von Inhalten zu vermeiden).
  • Inhaltstyp: application/json – Die Anfrage erwartet die Nutzlast im JSON-Format. 

Anforderungsmethode – POST


Request-Body
Der Request-Body muss ein JSON-Blob sein, der den PKey eines Profils enthält.

{
"subscriber":{"PKey": " @YDiPuQnFDXw_QJhpYrDS08PihTZGn88AszVPWMNLlM1smuI8hYnGwxCGo9CcvrhxnKhf2ZeF4mLWBqKlPYvvfR5lZac"}
}

Lektion 7 – Profil von einem Dienst abmelden

Ein Profil kann von einem Dienst abgemeldet werden, indem die DELETE-Methode für die Service-API aufgerufen und der Profil-PKey übergeben wird. 


API – https://mc.adobe.io/<tenant_name>/campaign/profileAndServices/service/<service_id>/subscriptions

Request-Header

  • Autorisierung: Zugriffstoken im „Bearer“-Format.
  • Inhaltstyp: application/json – Die Anfrage erwartet die Nutzlast im JSON-Format. 

Anforderungsmethode – DELETE


Anfragetext
Der Anfragetext muss ein JSON-Blob sein, der den PKey eines Profils enthält.

{
"subscriber":{"PKey": " @YDiPuQnFDXw_QJhpYrDS08PihTZGn88AszVPWMNLlM1smuI8hYnGwxCGo9CcvrhxnKhf2ZeF4mLWBqKlPYvvfR5lZac"}
}

Lektion 8 – Auslösen von E-Mails basierend auf Echtzeitereignissen

Basierend auf der Aktion des Kunden können wir eine E-Mail auslösen. Eine Ereignis-Aktivität kann die POST-Methode für ein benutzerdefiniertes registriertes Campaign-Ereignis aufrufen, um bei dessen Auftreten die gewünschte Aktion auszuführen. 


API – https://<instance name>.adobe.com/rest/<instanace id>/Form_Registration

Request-Header

  • Autorisierung: Zugriffstoken im „Bearer“-Format.
  • Inhaltstyp: application/json – Die Anfrage erwartet die Nutzlast im JSON-Format. 

Anforderungsmethode – POST


Abfrage-Body
Der Abfrage-Body muss ein JSON-BLOB sein, der den PKey eines Profils enthält.

{
"email": "hw@adobe.com",
"ctx":
{
"MOBILE": "111",
"Email": "hw@adobe.com",
"FNAME": "Xaxaxa"
}
}

Lesson 9 – SMS auslösen basierend auf Echtzeitereignissen

Wir können eine SMS basierend auf der Aktion eines Kunden auslösen. Ein Event-Handle kann die POST-Methode für ein benutzerdefiniertes registriertes Campaign-Event aufrufen, um eine gewünschte Aktion auszuführen. 


API – https://<instance name>.adobe.com/rest/<instance id>/EVTsms_trigger

Request-Header

  • Autorisierung: Zugriffstoken im „Bearer“-Format.
  • Inhaltstyp: application/json – Die Anfrage erwartet die Nutzlast im JSON-Format. 

Anforderungsmethode – POST


Request Body
Der Request-Body muss ein JSON-Blob mit dem PKey eines Profils sein.

{
"mobilePhone":"+9197####5013",
"ctx":
{
"mobile":"+919711##5013",
"coupon":2147483647,
"fname":"Hello",
"email":”helloworld@adobe.com”
}
}

Herunterladen

Dieses Werk unterliegt den Bedingungen der Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.  Twitter™- und Facebook-Beiträge fallen nicht unter die Bedingungen der Creative Commons-Lizenz.

Rechtliche Hinweise   |   Online-Datenschutzrichtlinie