Erstellen und Aktivieren einer externen Zielgruppe mithilfe der API

In diesem Tutorial werden die Schritte erläutert, die zum Erstellen einer externen Zielgruppe mithilfe der Adobe Experience Platform-APIs erforderlich sind.

Erste Schritte

Dieses Tutorial setzt Grundkenntnisse der verschiedenen Experience Platform-Services voraus, die bei der Erstellung einer externen Zielgruppe zum Einsatz kommen. Bevor Sie mit diesem Tutorial beginnen, lesen Sie bitte die Dokumentation für die folgenden Services:

Erforderliche Kopfzeilen

Für dieses Tutorial müssen Sie auch das Authentifizierungs-Tutorial abgeschlossen haben, um Experience Platform APIs erfolgreich aufrufen zu können. Durch Abschluss des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Header in allen Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:

Alle Ressourcen in Experience Platform sind auf bestimmte virtuelle Sandboxes beschränkt. Anfragen an Experience Platform-APIs erfordern eine Kopfzeile, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt werden soll:

Für alle POST-, PUT- und PATCH-Anfragen ist eine zusätzliche -Kopfzeile erforderlich:

Externe Zielgruppe vorbereiten prepare

Bevor Sie eine externe Zielgruppe in Experience Platform erstellen können, müssen Sie eine Datei vorbereiten, die die Zielgruppendaten enthält.

Für dieses Beispiel sollten Sie eine CSV-Datei verwenden. Stellen Sie sicher, dass Ihre CSV Datei eine Spalte mit einem Identitätswert wie einer ECID, einer E-Mail-ID oder einer CRM-ID enthält. Stellen Sie außerdem sicher, dass alle Anreicherungsattribute enthält, die Sie für die Segmentierung und Aktivierung benötigen.

Außerdem müssen Sie sicherstellen, dass die Datei den Anforderungen Ihres Experience Platform-Schemas entspricht. Weitere Informationen zum Erstellen eines Schemas finden Sie entweder im Tutorial zum Erstellen eines Schemas mithilfe der ​ oder im Tutorial zum Erstellen eines Schemas mithilfe der Benutzeroberfläche.

Nachdem Sie bestätigt haben, dass Ihre CSV-Datei alle benötigten Informationen enthält und dem Schema entspricht, müssen Sie die CSV-Datei in Ihren Cloud-Speicheranbieter hochladen, damit Sie Quellen verwenden können, um die Daten in Experience Platform aufzunehmen. Weitere Informationen zur Verwendung einer Cloud-Speicherquelle finden Sie entweder im Tutorial zum Erkunden von Cloud-Speicheroptionen mithilfe der API oder in der Quellen - Übersicht.

Erstellen einer externen Zielgruppe create

Nachdem Sie Ihre CSV-Datei vorbereitet haben, können Sie jetzt mit dem Erstellen der externen Zielgruppe beginnen.

Sie können eine externe Zielgruppe erstellen, indem Sie eine POST-Anfrage an den /external-audience/-Endpunkt senden.

Bei dieser Anfrage müssen Sie die folgenden Informationen angeben:

Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Handbuch zu Endpunkten für externe Zielgruppen.

curl -X POST https://platform.adobe.io/data/core/ais/external-audience/ \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
        "name": "Sample external audience",
        "description": "A sample version of an external audience",
        "fields": [
            {
                "name": "ppid",
                "type": "string",
                "identityNs": "email"
            },
            {
                "name": "list_id",
                "type": "string",
                "labels": ["core/C2", "custom/deep"]
            },
            {
                "name": "delete",
                "type": "number"
            },
            {
                "name": "process_consent",
                "type": "string"
            }
        ],
        "sourceSpec": {
            "params": {
                "path": "activation/sample-source/example.csv",
                "type": "file",
                "sourceType": "Cloud Storage",
                "baseConnectionId": "1d1d4bc5-b527-46a3-9863-530246a61b2b"
            }
        },
        "ttlInDays": "40",
        "labels": ["core/C1"],
        "audienceType": "people",
        "originName": "CUSTOM_UPLOAD"
    }'

Nachdem Sie diese Anfrage gestellt haben, notieren Sie sich die operationId, die Sie von der Antwort erhalten, damit Sie die Zielgruppen-ID abrufen können.

Abrufen der Zielgruppen-ID retrieve-audience-id

Nachdem Sie die externe Zielgruppe erstellt haben, müssen Sie die Zielgruppen-ID abrufen, damit Sie die Zielgruppe in Experience Platform aufnehmen können.

Sie können die Zielgruppen-ID abrufen, indem Sie eine GET-Anfrage an den /external-audiences/operations-Endpunkt stellen und die ID des Vorgangs angeben, den Sie zuvor aus der Antwort zum Erstellen einer externen Zielgruppe erhalten haben.

Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Handbuch für Endpunkte externer Zielgruppen.

curl -X GET https://platform.adobe.io/data/core/ais/external-audience/operations/{OPERATION_ID} \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Nachdem Sie diese Anfrage gestellt haben, notieren Sie sich die audienceId, die Sie von der Antwort erhalten, damit Sie den Aufnahmeauftrag für die Zielgruppe als Trigger verwenden können.

Zielgruppenerfassung starten start-ingestion

Da Sie Ihre audienceId haben, können Sie jetzt die Aufnahme Ihrer externen Zielgruppe in Experience Platform als Trigger festlegen.

Sie können eine Zielgruppenaufnahme starten, indem Sie eine POST-Anfrage an den folgenden Endpunkt senden und dabei die Zielgruppen-ID angeben. Darüber hinaus müssen Sie die Startzeit angeben, um zu bestimmen, welche Dateien verarbeitet werden.

Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Handbuch zu Endpunkten für externe Zielgruppen

curl -X POST https://platform.adobe.io/data/core/ais/external-audience/{AUDIENCE_ID}/runs \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
    "dataFilterStartTime": 764245635
 }'

Nachdem Sie diese Anfrage gestellt haben, notieren Sie sich die runId, die Sie von der Antwort erhalten, damit Sie den Aufnahmestatus überwachen können.

Überwachen des Aufnahmestatus monitor-ingestion

Nachdem Sie die Aufnahme der Zielgruppe ausgelöst haben, können Sie jetzt den Fortschritt der Aufnahme überwachen, um den Erfolg der Aufnahme zu bestätigen und die Verfügbarkeit der Zielgruppe für die nachgelagerte Aktivierung zu überprüfen.

Sie können den Status einer Zielgruppenaufnahme abrufen, indem Sie eine GET-Anfrage an den folgenden Endpunkt senden und dabei sowohl die Zielgruppen- als auch die Ausführungs-IDs angeben.

Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Handbuch für Endpunkte externer Zielgruppen.

curl -X GET https://platform.adobe.io/data/core/ais/external-audience/{AUDIENCE_ID}/runs/{RUN_ID} \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Nächste Schritte next-steps

Nachdem Sie bestätigt haben, dass die externe Zielgruppe erfolgreich aufgenommen wurde, können Sie sie in Audience Portal sehen und in nachgelagerten Services wie Zielen verwenden.

Weitere Informationen zu Audience Portal finden Sie im Handbuch zur Audience Portal-Benutzeroberfläche. Weitere Informationen zu Zielen finden Sie unter Ziele - Übersicht.