Herstellen einer Verbindung zu E-Mail-Marketingzielen und Aktivieren von Daten mithilfe der Flow Service API

In dieser Anleitung erfahren Sie, wie Sie mithilfe von API-Aufrufen eine Verbindung zu Ihren Adobe Experience Platform-Daten herstellen, ein E-Mail-Marketing-Ziel erstellen, einen Datenfluss zu Ihrem neu erstellten Ziel einrichten und Daten zu Ihrem neu erstellten Ziel aktivieren können.

In dieser Anleitung wird für alle Beispiele das Ziel „Adobe Campaign“ verwendet, die Schritte sind aber für alle E-Mail-Marketing-Ziele identisch.

Übersicht – Schritte zum Erstellen eines Ziels und Aktivieren von Segmenten

Wenn Sie es vorziehen, die Benutzeroberfläche in Platform zu verwenden, um ein Ziel zu verbinden und Daten zu aktivieren, lesen Sie die Lernprogramme Ein Ziel und Profil und Segmente an ein Ziel anschließen.

Erste Schritte

Dieses Handbuch setzt ein Verständnis der folgenden Komponenten von Adobe Experience Platform voraus:

  • Experience Data Model (XDM) System: Das standardisierte Framework, mit dem Experience Platform Kundenerlebnisdaten organisiert.
  • Catalog Service: Catalog ist das Datensatzsystem für die Datenposition und -linie innerhalb Experience Platform.
  • Sandboxes: Experience Platform bietet virtuelle Sandboxes, die eine einzelne Platform Instanz in separate virtuelle Umgebung unterteilen, um Anwendungen für digitale Erlebnisse zu entwickeln und weiterzuentwickeln.

Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie zur Aktivierung von Daten an E-Mail-Marketing-Ziele in der Plattform benötigen.

Erforderliche Anmeldedaten sammeln

Um die Schritte in dieser Anleitung abzuschließen, benötigen Sie die folgenden Anmeldedaten, je nach Art der Ziele, mit denen Sie Segmente verbinden und aktivieren möchten.

  • Für S3-Verbindungen zu E-Mail-Marketingplattformen: accessId, secretKeyAmazon
  • Bei SFTP-Verbindungen zu E-Mail-Marketing-Plattformen: domain, port, username oder password ssh key (je nach Verbindungsmethode zum FTP-Speicherort)

Lesen von Beispiel-API-Aufrufen

In diesem Tutorial wird anhand von Beispielen für API-Aufrufe die korrekte Formatierung von Anfragen aufgezeigt. Dazu gehören Pfade, erforderliche Kopfzeilen und ordnungsgemäß formatierte Anfrage-Payloads. Außerdem wird ein Beispiel für eine von der API im JSON-Format zurückgegebene Antwort bereitgestellt. Informationen zu den Konventionen, die in der Dokumentation für Beispiel-API-Aufrufe verwendet werden, finden Sie im Abschnitt zum Lesen von Beispiel-API-Aufrufen im Fehlerbehebungshandbuch für Experience Platform

Werte für erforderliche und optionale Kopfzeilen sammeln

Um Platform-APIs aufzurufen, müssen Sie zunächst das Authentifizierungs-Tutorial abschließen. Durch Abschluss des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Header in allen Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

Ressourcen in Experience Platform können zu bestimmten virtuellen Sandboxen isoliert werden. Bei Anforderungen an Platform-APIs können Sie den Namen und die ID der Sandbox angeben, in der der Vorgang ausgeführt wird. Dies sind optionale Parameter.

  • x-sandbox-name: {SANDBOX_NAME}
HINWEIS

Weitere Informationen zu Sandboxen in Experience Platform finden Sie in der Sandbox-Übersichtsdokumentation.

Bei allen Anfragen, die eine Payload enthalten (POST, PUT, PATCH), ist eine zusätzliche Medientyp-Kopfzeile erforderlich:

  • Content-Type: application/json

Swagger-Dokumentation

Eine zugehörige Referenzdokumentation für alle API-Aufrufe finden Sie in dieser Anleitung in Swagger. Weitere Informationen finden Sie in der Dokumentation zur Flow Service API für Adobe I/O🔗. Es wird empfohlen, diese Anleitung sowie die Seite mit der Swagger-Dokumentation parallel zu verwenden.

Liste der verfügbaren Ziele abrufen

Übersicht über die Zielschritte – Schritt 1

Als ersten Schritt sollten Sie entscheiden, für welches E-Mail-Marketing-Ziel Daten aktiviert werden sollen. Führen Sie also zunächst einen Aufruf durch, um eine Liste der verfügbaren Ziele anzufordern, mit denen Sie eine Verbindung herstellen und Segmente aktivieren können. Führen Sie die folgende GET-Anfrage an den connectionSpecs-Endpunkt aus, um eine Liste der verfügbaren Ziele zu erhalten:

API-Format

GET /connectionSpecs

Anfrage

curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Antwort

Eine erfolgreiche Antwort enthält eine Liste der verfügbaren Ziele und ihre eindeutigen Kennungen (id). Notieren Sie sich den Wert des Ziels, das Sie verwenden möchten, da Sie ihn in weiteren Schritten benötigen werden. Wenn Sie z. B. Segmente mit Adobe Campaign verbinden und bereitstellen möchten, suchen Sie in der Antwort nach folgendem Code-Ausschnitt:

{
    "id": "0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
  "name": "Adobe Campaign",
  ...
  ...
}

Stellen Sie eine Verbindung zu den Experience Platform-Daten her.

Übersicht über die Zielschritte – Schritt 2

Als Nächstes müssen Sie eine Verbindung zu den Experience Platform-Daten herstellen, damit Sie die Profil-Daten exportieren und sie in Ihrem bevorzugten Ziel aktivieren können. Das umfasst zwei Unterschritte, die nachfolgend beschrieben werden.

  1. Zunächst müssen Sie einen Aufruf ausführen, um den Zugriff auf Ihre Daten in Experience Platform zu autorisieren, indem Sie eine Basisverbindung einrichten.
  2. Dann führen Sie mit der Basis-Verbindungs-ID einen weiteren Aufruf durch, bei dem Sie eine Quellverbindung erstellen, die die Verbindung zu Ihren Experience Platform-Daten herstellt.

Zugriff auf Ihre Daten in Experience Platform genehmigen

API-Format

POST /connections

Anfrage

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Base connection to Experience Platform",
            "description": "This call establishes the connection to Experience Platform data",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            }
}'
  • {CONNECTION_SPEC_ID}: Verwenden Sie die Verbindungsspezifikations-ID für Unified Profil Service - 8a9c3494-9708-43d7-ae3f-cda01e5030e1.

Antwort

Eine erfolgreiche Antwort enthält die eindeutige Kennung der Basisverbindung (id). Notieren Sie sich diesen Wert, da Sie ihn im nächsten Schritt zum Erstellen der Quellverbindung benötigen werden.

{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Stellen Sie eine Verbindung zu den Experience Platform-Daten her.

API-Format

POST /sourceConnections

Anfrage

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Connecting to Unified Profile Service",
            "description": "Optional",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            },
            "baseConnectionId": "{BASE_CONNECTION_ID}",
            "data": {
                "format": "CSV",
                "schema": null
            },
            "params" : {}
}'
  • {BASE_CONNECTION_ID}: Verwenden Sie die Kennung, die Sie im vorherigen Schritt erhalten haben.
  • {CONNECTION_SPEC_ID}: Verwenden Sie die Verbindungsspezifikations-ID für Unified Profile Service - 8a9c3494-9708-43d7-ae3f-cda01e5030e1.

Antwort

Eine erfolgreiche Antwort gibt den eindeutigen Bezeichner (id) für die neu erstellte Quellverbindung zu Unified Profile Service zurück. Dies bestätigt, dass Sie erfolgreich eine Verbindung zu Ihren Experience Platform-Daten hergestellt haben. Notieren Sie sich diesen Wert, da Sie ihn in einem späteren Schritt benötigen werden.

{
    "id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}

Verbindung zum E-Mail-Marketing-Ziel herstellen

Übersicht über die Zielschritte – Schritt 3

In diesem Schritt richten Sie eine Verbindung zu Ihrem gewünschten E-Mail-Marketing-Ziel ein. Das umfasst zwei Unterschritte, die nachfolgend beschrieben werden.

  1. Sie müssen zunächst einen Aufruf ausführen, um den Zugriff auf den E-Mail-Dienstleister zu autorisieren, indem Sie eine Basisverbindung einrichten.
  2. Mithilfe der Kennung der Basisverbindung führen Sie dann einen weiteren Aufruf aus, mit dem Sie eine Zielverbindung erstellen. In dem Aufruf sind der Ort in Ihrem Speicherkonto, an dem die exportierten Daten bereitgestellt werden, sowie das Format der zu exportierenden Daten angegeben.

Zugriff auf das E-Mail-Marketing-Ziel autorisieren

API-Format

POST /connections

Anfrage

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "S3 Connection for Adobe Campaign",
    "description": "summer advertising campaign",
    "connectionSpec": {
        "id": "{_CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "auth": {
        "specName": "{S3 or SFTP}",
        "params": {
            "accessId": "{ACCESS_ID}",
            "secretKey": "{SECRET_KEY}"
        }
    }
}'
  • {CONNECTION_SPEC_ID}: Verwenden Sie die Verbindungsspezifikations-ID, die Sie im Schritt Liste der verfügbaren Ziele anfordern erhalten haben.
  • {S3 or SFTP}: Geben Sie den gewünschten Verbindungstyp für dieses Ziel ein. Blättern Sie im Zielkatalog zu Ihrem bevorzugten Ziel, um zu sehen, ob S3- und/oder SFTP-Verbindungstypen unterstützt werden.
  • {ACCESS_ID}Amazon: Ihre Zugriffskennung für Ihren S3-Datenspeicherort.
  • {SECRET_KEY}Amazon: Ihr geheimer Schlüssel für Ihren S3-Datenspeicherort.

Antwort

Eine erfolgreiche Antwort enthält die eindeutige Kennung der Basisverbindung (id). Notieren Sie sich diesen Wert, da Sie ihn im nächsten Schritt benötigen, um eine Zielverbindung zu erstellen.

{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Speicherort und Datenformat angeben

Adobe Experience Platform exportiert Daten für E-Mail-Marketing- und Cloud-Datenspeicherung-Ziele in CSV Dateiform.

WICHTIG

Adobe Experience Platform teilt die Exportdateien automatisch mit 5 Millionen Datensätzen (Zeilen) pro Datei auf. Jede Zeile stellt ein Profil dar.

Dateinamen mit Teilinformationen werden mit einer Zahl angehängt, die angibt, dass die Datei Teil eines größeren Exports ist. Dies bedeutet: filename.csv, filename_2.csv, filename_3.csv.

API-Format

POST /targetConnections

Anfrage

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "TargetConnection for Adobe Campaign",
    "description": "Connection to Adobe Campaign",
    "baseConnectionId": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "{CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "data": {
        "format": "json",
        "schema": {
            "id": "1.0",
            "version": "1.0"
        }
    },
    "params": {
        "mode": "S3",
        "bucketName": "{BUCKETNAME}",
        "path": "{FILEPATH}",
        "format": "CSV"
    }
}'
  • {BASE_CONNECTION_ID}: Nutzen Sie die Kennung der Basisverbindung, die Sie im obigen Schritt erhalten haben.
  • {CONNECTION_SPEC_ID}: Verwenden Sie die Verbindungsspezifikation, die Sie im Schritt Liste der verfügbaren Ziele abrufen erhalten haben.
  • {BUCKETNAME}: Ihr Amazon S3-Behälter, in dem die Plattform den Datenexport einlagert.
  • {FILEPATH}: Der Pfad in Ihrem Amazon S3-Bucket-Ordner, in dem Platform den Datenexport hinterlegt.

Antwort

Eine erfolgreiche Antwort gibt für die neu erstellte Zielverbindung zu Ihrem E-Mail-Marketing-Ziel die eindeutige Kennung (id) zurück. Notieren Sie sich diesen Wert, da Sie ihn in späteren Schritten benötigen werden.

{
    "id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}

Datenfluss erstellen

Übersicht über die Zielschritte – Schritt 4

Mithilfe der IDs, die Sie in den vorherigen Schritten erhalten haben, können Sie jetzt einen Datenflug zwischen Ihren Experience Platform-Daten und dem Ziel erstellen, an dem Sie Daten aktivieren. Stellen Sie sich diesen Schritt als eine Konstruktion der Pipeline vor, durch die Daten später zwischen Experience Platform und dem gewünschten Ziel fließen.

Um einen Datenfluss zu erstellen, führen Sie eine POST-Anfrage durch (wie unten dargestellt) und geben Sie dabei die unten genannten Werte in der Payload an.

Führen Sie die folgende POST-Anfrage aus, um einen Datenfluss zu erstellen.

API-Format

POST /flows

Anfrage

curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d  '{
   
        "name": "Activate segments to Adobe Campaign",
        "description": "This operation creates a dataflow which we will later use to activate segments to Adobe Campaign",
        "flowSpec": {
            "id": "{FLOW_SPEC_ID}",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "{SOURCE_CONNECTION_ID}"
        ],
        "targetConnectionIds": [
            "{TARGET_CONNECTION_ID}"
        ],
        "transformations": [
            {
                "name": "GeneralTransform",
                "params": {
                    "segmentSelectors": {
                        "selectors": []
                    },
                    "profileSelectors": {
                        "selectors": []
                    }
                }
            }
        ]
    }
  • {FLOW_SPEC_ID}: Verwenden Sie den Fluss für das E-Mail-Marketing-Ziel, mit dem Sie eine Verbindung herstellen möchten. Um die Flussspezifikation abzurufen, senden Sie einen GET-Anfrage an den flowspecs-Endpunkt. Weiterführende Informationen finden Sie in der Swagger-Dokumentation: https://platform.adobe.io/data/foundation/flowservice/swagger#/Flow%20Specs%20API/getFlowSpecs. Suchen Sie in der Antwort nach upsTo und kopieren Sie die entsprechende Kennung des E-Mail-Marketing-Ziels, mit dem Sie eine Verbindung herstellen möchten. Suchen Sie zum Beispiel für Adobe Campaign nach upsToCampaign und kopieren Sie den id-Parameter.
  • {SOURCE_CONNECTION_ID}: Verwenden Sie die Quellverbindungs-ID, die Sie im Schritt Verbindung zu Ihren Experience Platform-Daten herstellen erhalten haben.
  • {TARGET_CONNECTION_ID}: Verwenden Sie die Zielverbindungs-ID, die Sie im Schritt Verbindung mit E-Mail-Marketing-Ziel herstellen erhalten haben.

Antwort

Bei einer erfolgreichen Antwort werden die Kennung (id) des neu erstellten Datenflusses und ein etag zurückgegeben. Notieren Sie sich beide Werte. Sie werden sie im nächsten Schritt benötigen, um Segmente zu aktivieren.

{
    "id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
    "etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}

Daten an Ihr neues Ziel aktivieren

Übersicht über die Zielschritte – Schritt 5

Nachdem Sie alle Verbindungen sowie den Datenfluss erstellt haben, können Sie jetzt Ihre Profildaten für die E-Mail-Marketing-Plattform aktivieren. In diesem Schritt wählen Sie aus, welche Segmente und Profilattribute Sie an das Ziel senden möchten. Außerdem können Sie Daten planen und an das Ziel senden.

Um Segmente für Ihr neues Ziel zu aktivieren, müssen Sie einen JSON-PATCH-Vorgang ausführen, ähnlich dem Beispiel unten. Sie können mehrere Profil- und Segmentattribute in einem Aufruf aktivieren. Weiterführende Informationen zu JSON PATCH finden Sie in der RFC-Spezifikation.

API-Format

PATCH /flows

Anfrage

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
    {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the segment that you are activating",
                "description": "Description of the segment that you are activating",
                "id": "{SEGMENT_ID}"
            }
        }
    },
        {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the segment that you are activating",
                "description": "Description of the segment that you are activating",
                "id": "{SEGMENT_ID}"
            }
        }
    },
        {
        "op": "add",
        "path": "/transformations/0/params/profileSelectors/selectors/-",
        "value": {
            "type": "JSON_PATH",
            "value": {
                "operator": "EXISTS",
                "path": "{PROFILE_ATTRIBUTE}"
            }
        }
    }
]
  • {DATAFLOW_ID}: Verwenden Sie den Datenfluss, den Sie im vorherigen Schritt erstellt haben.
  • {ETAG}: Verwenden Sie das eTag, das Sie im vorherigen Schritt erhalten haben.
  • {SEGMENT_ID}: Geben Sie die Kennung des Segments an, das Sie an dieses Ziel exportieren möchten. Um Segment-IDs für die Segmente abzurufen, die Sie aktivieren möchten, gehen Sie zu https://www.adobe.io/apis/experienceplatform/home/api-reference.html#/, wählen Sie Segmentierungsdienst-API im linken Navigationsmenü und suchen Sie nach dem Vorgang GET /segment/definitions unter Segmentdefinitionen.
  • {PROFILE_ATTRIBUTE}: Beispiel, "person.lastName"

Antwort

Suchen Sie nach einer „202 OK“-Antwort. Es wird kein Antworttext zurückgegeben. Um zu überprüfen, ob die Anfrage korrekt war, lesen Sie den nächsten Schritt „Datenfluss validieren“.

Datenfluss validieren

Übersicht über die Zielschritte – Schritt 6

Als letzten Schritt in der Anleitung sollten Sie überprüfen, ob die Segmente und Profilattribute dem Datenfluss korrekt zugeordnet wurden.

Führen Sie zur Validierung die folgende GET-Anfrage aus:

API-Format

GET /flows

Anfrage

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"' 
  • {DATAFLOW_ID}: Verwenden Sie den Datenfluss aus dem vorherigen Schritt.
  • {ETAG}: Verwenden Sie das eTag aus dem vorherigen Schritt.

Antwort

Die zurückgegebene Antwort sollte im transformations-Parameter die Segmente und Profilattribute enthalten, die Sie im vorherigen Schritt gesendet haben. Ein Beispielparameter transformations in der Antwort könnte wie folgt aussehen:

"transformations": [
    {
        "name": "GeneralTransform",
        "params": {
            "profileSelectors": {
                "selectors": []
            },
            "segmentSelectors": {
                "selectors": [
                    {
                        "type": "PLATFORM_SEGMENT",
                        "value": {
                            "name": "Men over 50",
                            "description": "",
                            "id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
                        }
                    }
                ]
            }
        }
    }
],

Nächste Schritte

In diesem Lernprogramm haben Sie Platform erfolgreich mit einem Ihrer bevorzugten E-Mail-Marketingziele verbunden und einen Datenflug zum jeweiligen Ziel eingerichtet. Ausgehende Daten können jetzt im Ziel für E-Mail-Kampagnen, zielgruppengerechte Werbung und viele andere Anwendungsfälle genutzt werden. Weiterführende Informationen finden Sie auf den folgenden Seiten:

Auf dieser Seite