DokumentationExperience PlatformHandbuch zum Segmentierungs-Service

Endpunkt für externe Zielgruppen

Last update: Fri Feb 20 2026 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Themen:

Erstellt für:

  • Benutzende

Mit externen Zielgruppen können Sie Profildaten aus Ihren externen Quellen in Adobe Experience Platform hochladen. Sie können den /external-audience-Endpunkt in der Segmentierungs-Service-API verwenden, um eine externe Zielgruppe in Experience Platform aufzunehmen, Details anzuzeigen und Ihre externen Zielgruppen zu aktualisieren sowie Ihre externen Zielgruppen zu löschen.

Leitlinien

Ab der März-Version werden die folgenden Leitplanken erzwungen, wenn der Endpunkt Externe Zielgruppen verwendet wird:

Leitplanke
Limit
Art des Limits
Beschreibung
Anzahl der Zielgruppen-Erfassungsdurchgänge pro Tag
100
Vom System erzwungene Leitplanken
Die maximal zulässige Anzahl von Zielgruppen-Erfassungsdurchgängen pro Tag. Dieses Limit gilt pro Sandbox Ebene.
Anzahl der Aufnahmen pro Zielgruppe
10
Vom System erzwungene Leitplanken
Die Anzahl der Aufnahmen, die für eine bestimmte Zielgruppe durchgeführt werden können.
Größe der externen Zielgruppe
10 GB
Leistungs-Schutzmaßnahme
Die empfohlene Gesamtgröße der externen Zielgruppe beträgt 10 GB.

Erste Schritte

IMPORTANT
Den Endpunkten in diesem Handbuch wird im Gegensatz zu /core/ais das Präfix /core/ups vorangestellt.

Um Experience Platform-APIs verwenden zu können, müssen Sie das Authentifizierungs-Tutorial abgeschlossen haben. Im Rahmen des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Kopfzeilen in Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:

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

Alle Ressourcen in Experience Platform sind auf bestimmte virtuelle Sandboxes beschränkt. Alle an Experience Platform-APIs gerichtete Anfragen müssen über eine Kopfzeile verfügen, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt wird:

  • x-sandbox-name: {SANDBOX_NAME}
NOTE
Weitere Informationen zum Arbeiten mit Sandboxes in Experience Platform finden Sie in der Sandbox-Übersichtsdokumentation.

Externe Zielgruppe erstellen create-audience

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

API-Format

POST /external-audience/

Anfrage

Beispielanfrage zum Erstellen einer externen Zielgruppe.
code language-shell 
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"
    }'
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3 11-row-3
Eigenschaft Typ Beschreibung
name Zeichenfolge Der Name für die externe Zielgruppe.
description Zeichenfolge Eine optionale Beschreibung für die externe Zielgruppe.
customAudienceId Zeichenfolge Eine optionale Kennung für Ihre externe Zielgruppe.
fields Array von Objekten

Liste der Felder und ihrer Datentypen Ihr Array muss mindestens 1 Feld und maximal 41 Felder enthalten. Eines der Felder muss ein Identitätsfeld sein und die identityNs enthalten. Beim Erstellen der Feldliste können Sie die folgenden Elemente hinzufügen:

  • name: Erforderlich Der Name des Felds, das Teil der Spezifikation der externen Zielgruppe ist.
  • type: Erforderlich Der Datentyp, der in das Feld aufgenommen wird. Unterstützte Werte sind string, number, long, integer, date (2025-05-13), datetime (2025-05-23T20:19:00+00:00) und boolean.
  • identityNs: Erforderlich für Identitätsfeld Der Namespace, der vom Identitätsfeld verwendet wird. Unterstützte Werte umfassen alle gültigen Namespaces, z. B. ECID oder email.
  • labels: Optional Ein Array von Zugriffssteuerungsbeschriftungen für das Feld. Weitere Informationen zu den verfügbaren Zugriffssteuerungsbeschriftungen finden Sie im Glossar zu Datennutzungsbeschriftungen.
sourceSpec Objekt

Ein Objekt, das die Informationen enthält, wo sich die externe Zielgruppe befindet. Wenn Sie dieses Objekt verwenden müssen die folgenden Informationen einschließen:

  • path: Erforderlich: Der Speicherort der externen Zielgruppe oder des Ordners, der die externe Zielgruppe in der Quelle enthält. Der Dateipfad darf Leerzeichen enthalten. Wenn Ihr Pfad beispielsweise activation/sample-source/Example CSV File.csv ist, legen Sie den Pfad auf activation/sample-source/ExampleCSVFile.csv fest. Den Pfad zu Ihrer Quelle finden Sie in der Spalte Source im Abschnitt Datenflüsse .
  • type: Erforderlich Der Typ des Objekts, das Sie aus der Quelle abrufen. Dieser Wert kann entweder file oder folder sein.
  • sourceType: Optional Der Typ der Quelle, von der Sie abrufen. Derzeit wird nur der Wert Cloud Storage unterstützt.
  • cloudType: Erforderlich Der Typ des Cloud-Speichers, basierend auf dem Quelltyp. Zu den unterstützten Werten gehören S3, DLZ, GCS, Azure und SFTP.
  • baseConnectionId: Die ID der Basisverbindung und wird von Ihrem Quellanbieter bereitgestellt. Dieser Wert ist erforderlich wenn ein cloudType Wert von S3, GCS oder SFTP verwendet wird. Andernfalls Sie diesen Parameter. Weitere Informationen finden Sie unter Übersicht über Quell-Connectoren.
ttlInDays Ganzzahl Die Datengültigkeit für die externe Zielgruppe in Tagen. Dieser Wert kann zwischen 1 und 90 eingestellt werden. Standardmäßig ist der Ablauf der Daten auf 30 Tage festgelegt.
audienceType Zeichenfolge Der Zielgruppentyp für die externe Zielgruppe. Derzeit wird nur people unterstützt.
originName Zeichenfolge Erforderlich Die Herkunft der Zielgruppe. Hier wird angegeben, woher die Zielgruppe stammt. Für externe Zielgruppen sollten Sie CUSTOM_UPLOAD verwenden.
namespace Zeichenfolge Der Namespace für die Zielgruppe. Standardmäßig ist dieser Wert auf CustomerAudienceUpload gesetzt.
labels Zeichenfolgen-Array Die für die externe Zielgruppe geltenden Zugriffssteuerungsbeschriftungen. Weitere Informationen zu den verfügbaren Zugriffssteuerungsbeschriftungen finden Sie im Glossar zu Datennutzungsbeschriftungen.
tags Zeichenfolgen-Array Die Tags, die Sie auf die externe Zielgruppe anwenden möchten. Wenn Sie das Array von Tags hinzufügen, müssen die tagId verwenden. Weitere Informationen zu Tags finden Sie im Handbuch zum Verwalten von Tags.

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Status 202 mit Details zur neu erstellten externen Zielgruppe zurückgegeben.

Beispielantwort beim Erstellen einer externen Zielgruppe.
code language-json 
{
    "operationId": "df8cd82f-a214-4b72-b549-d6ee23f1ff1a",
    "operationDetails": {
        "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"
    }
}
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3 11-row-3
Eigenschaft Typ Beschreibung
operationId Zeichenfolge Die ID des Vorgangs. Anschließend können Sie diese ID verwenden, um den Status der Erstellung Ihrer Zielgruppe abzurufen.
operationDetails Objekt Ein -Objekt, das die Details der Anfrage enthält, die Sie zum Erstellen der externen Zielgruppe übermittelt haben.
name Zeichenfolge Der Name für die externe Zielgruppe.
description Zeichenfolge Die Beschreibung für die externe Zielgruppe.
fields Array von Objekten Liste der Felder und ihrer Datentypen Dieses Array bestimmt, welche Felder Sie in Ihrer externen Zielgruppe benötigen.
sourceSpec Objekt Ein Objekt, das die Informationen enthält, wo sich die externe Zielgruppe befindet.
ttlInDays Ganzzahl Die Datengültigkeit für die externe Zielgruppe in Tagen. Dieser Wert kann zwischen 1 und 90 eingestellt werden. Standardmäßig ist der Ablauf der Daten auf 30 Tage festgelegt.
audienceType Zeichenfolge Der Zielgruppentyp für die externe Zielgruppe.
originName Zeichenfolge Erforderlich Die Herkunft der Zielgruppe. Dies gibt an, woher die Zielgruppe kommt.
namespace Zeichenfolge Der Namespace für die Zielgruppe.
labels Zeichenfolgen-Array Die für die externe Zielgruppe geltenden Zugriffssteuerungsbeschriftungen. Weitere Informationen zu den verfügbaren Zugriffssteuerungsbeschriftungen finden Sie im Glossar zu Datennutzungsbeschriftungen.

Abrufen des Erstellungsstatus der Zielgruppe retrieve-status

Sie können den Status der Übermittlung Ihrer externen Zielgruppe abrufen, indem Sie eine GET-Anfrage an den Endpunkt /external-audiences/operations stellen und die ID des Vorgangs angeben, den Sie in der Antwort „Externe Zielgruppe erstellen“ erhalten haben.

API-Format

GET /external-audiences/operations/{OPERATION_ID}
Parameter
Beschreibung
{OPERATION_ID}
Der id des Vorgangs, den Sie abrufen möchten.

Anfrage

Eine Beispielanfrage zum Abrufen des Vorgangsstatus einer externen Zielgruppe.
code language-shell 
curl -X GET https://platform.adobe.io/data/core/ais/external-audience/operations/df8cd82f-a214-4b72-b549-d6ee23f1ff1a \
 -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}'

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Status 200 mit Details zum Aufgabenstatus der externen Zielgruppe zurückgegeben.

Eine Beispielantwort, wenn Sie den Aufgabenstatus einer externen Zielgruppe abrufen.
code language-json 
{
    "operationId": "df8cd82f-a214-4b72-b549-d6ee23f1ff1a",
    "status": "SUCCESS",
    "operationDetails": {
        "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"
    },
    "audienceName": "Sample external audience",
    "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
    "createdBy": "{USER_ID}",
    "createdAt": 1749324248,
    "updatedBy": "{USER_ID}",
    "updatedAt": 1749624273
}
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3
Eigenschaft Typ Beschreibung
operationId Zeichenfolge Die ID des Vorgangs, den Sie abrufen.
status Zeichenfolge Der Status des Vorgangs. Dies kann einer der folgenden Werte sein: SUCCESS, FAILED, PROCESSING.
operationDetails Objekt Ein Objekt, das Details zur Zielgruppe enthält.
audienceId Zeichenfolge Die ID der externen Zielgruppe, die vom Vorgang gesendet wird.
createdBy Zeichenfolge Die ID des Benutzers, der die externe Zielgruppe erstellt hat.
createdAt Zeitstempel für lange Epochen Der Zeitstempel in Sekunden, wann die Anfrage zur Erstellung der externen Zielgruppe gesendet wurde.
updatedBy Zeichenfolge Die ID des Benutzers, der die Zielgruppe zuletzt aktualisiert hat.
updatedAt Zeitstempel für lange Epochen Der Zeitstempel in Sekunden, wann die Zielgruppe zuletzt aktualisiert wurde.

Aktualisieren einer externen Zielgruppe update-audience

NOTE
Um den folgenden Endpunkt verwenden zu können, benötigen Sie die audienceId Ihrer externen Zielgruppe. Sie können Ihre audienceId von einem erfolgreichen Aufruf an den GET /external-audiences/operations/{OPERATION_ID}-Endpunkt abrufen.

Sie können Felder Ihrer externen Zielgruppe aktualisieren, indem Sie eine PATCH-Anfrage an den /external-audience-Endpunkt senden und im Anfragepfad die ID der Zielgruppe angeben.

Bei Verwendung dieses Endpunkts können Sie die folgenden Felder aktualisieren:

  • Zielgruppen-Beschreibung
  • Kennzeichnungen für die Zugriffssteuerung auf Feldebene
  • Zugriffssteuerungsbeschriftungen auf Zielgruppenebene
  • Ablauf der Daten der Zielgruppe

Durch Aktualisieren des Felds mit diesem Endpunkt ersetzt der Inhalt des angeforderten Felds.

API-Format

PATCH /external-audience/{AUDIENCE_ID}

Anfrage

Eine Beispielanfrage zum Aktualisieren der Beschreibung der externen Zielgruppe.
code language-shell 
curl -X PATCH https://platform.adobe.io/data/core/ais/external-audience/60ccea95-1435-4180-97a5-58af4aa285ab\
 -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 '{
    "description": "New sample description"
 }'
table 0-row-3 1-row-3
Eigenschaft Typ Beschreibung
description Zeichenfolge Die aktualisierte Beschreibung für die externe Zielgruppe.

Darüber hinaus können Sie die folgenden Parameter aktualisieren:

table 0-row-3 1-row-3 2-row-3 3-row-3
Eigenschaft Typ Beschreibung
labels Array Ein Array, das die aktualisierte Liste der Zugriffsbeschriftungen für die Zielgruppe enthält. Weitere Informationen zu den verfügbaren Zugriffssteuerungsbeschriftungen finden Sie im Glossar zu Datennutzungsbeschriftungen.
fields Array von Objekten Ein Array mit den Feldern und den zugehörigen Kennzeichnungen für die externe Zielgruppe. Nur die Felder, die in der PATCH-Anfrage aufgeführt sind, werden aktualisiert. Weitere Informationen zu den verfügbaren Zugriffssteuerungsbeschriftungen finden Sie im Glossar zu Datennutzungsbeschriftungen.
ttlInDays Ganzzahl Die Datengültigkeit für die externe Zielgruppe in Tagen. Dieser Wert kann zwischen 1 und 90 eingestellt werden.

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Status 200 mit Details zur aktualisierten externen Zielgruppe zurückgegeben.

Eine Beispielantwort beim Aktualisieren der Beschreibung der externen Zielgruppe.
code language-json 
{
    "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
    "audienceName": "Sample external audience",
    "description": "New sample description",
    "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": {
        "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",
    "createdBy": "{USER_ID}",
    "createdAt": 1749324248,
    "updatedBy": "{USER_ID}",
    "updatedAt": 1749624273
}

Zielgruppenerfassung starten start-audience-ingestion

IMPORTANT
Sie eine Aufnahme für die externe Zielgruppe starten, wenn bereits eine vorherige Zielgruppenaufnahme in Bearbeitung ist.
NOTE
Um den folgenden Endpunkt verwenden zu können, benötigen Sie die audienceId Ihrer externen Zielgruppe. Sie können Ihre audienceId von einem erfolgreichen Aufruf an den GET /external-audiences/operations/{OPERATION_ID}-Endpunkt abrufen.

Sie können eine Zielgruppenaufnahme starten, indem Sie eine POST-Anfrage an den folgenden Endpunkt senden und dabei die Zielgruppen-ID angeben.

API-Format

POST /external-audience/{AUDIENCE_ID}/runs

Anfrage

Mit der folgenden Anfrage wird ein Aufnahmevorgang für die externe Zielgruppe Trigger.

Eine Beispielanfrage zum Starten einer Zielgruppen-Aufnahme.
code language-shell 
curl -X POST https://platform.adobe.io/data/core/ais/external-audience/60ccea95-1435-4180-97a5-58af4aa285ab/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
 }'
table 0-row-3 1-row-3 2-row-3
Eigenschaft Typ Beschreibung
dataFilterStartTime Zeitstempel der Epoche Erforderlich Der Bereich, der die Startzeit angibt, um zu bestimmen, welche Dateien verarbeitet werden. Das bedeutet, dass die ausgewählten Dateien nach angegebenen als Dateien angezeigt werden.
dataFilterEndTime Zeitstempel der Epoche Der Bereich, der die Endzeit angibt, zu der der Fluss ausgeführt wird, um die zu verarbeitenden Dateien auszuwählen. Das bedeutet, dass die ausgewählten Dateien Dateien vor) angegebenen Zeit sein werden.

Antwort

Eine erfolgreiche Antwort gibt den HTTP-Status-Code 200 mit Details zur Aufnahmeausführung zurück.

Eine Beispielantwort beim Starten der Zielgruppen-Aufnahme.
code language-json 
{
    "audienceName": "Sample external audience",
    "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
    "runId": "fb342311-725d-4b48-ab7d-c6105fbc2b8b",
    "differentialIngestion": true,
    "dataFilterStartTime": 764245635,
    "dataFilterEndTime": 4565657575,
    "createdAt": 4565657575,
    "createdBy:" "{USER_ID}"
}
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3
Eigenschaft Typ Beschreibung
audienceName Zeichenfolge Der Name der Zielgruppe, für die Sie einen Aufnahmevorgang starten.
audienceId Zeichenfolge Die ID der Zielgruppe.
runId Zeichenfolge Die ID des von Ihnen gestarteten Aufnahmevorgangs.
differentialIngestion Boolesch Ein Feld, das bestimmt, ob es sich bei der Aufnahme um eine partielle Aufnahme handelt, basierend auf der Differenz seit der letzten Aufnahme oder einer vollständigen Zielgruppenaufnahme.
dataFilterStartTime Zeitstempel der Epoche Der Bereich, der die Startzeit angibt, zu der der Fluss ausgeführt wird, um auszuwählen, welche Dateien verarbeitet wurden.
dataFilterEndTime Zeitstempel der Epoche Der Bereich, der die Endzeit angibt, zu der der Fluss ausgeführt wird, um auszuwählen, welche Dateien verarbeitet wurden.
createdAt Zeitstempel für lange Epochen Der Zeitstempel in Sekunden, wann die Anfrage zur Erstellung der externen Zielgruppe gesendet wurde.
createdBy Zeichenfolge Die ID des Benutzers, der die externe Zielgruppe erstellt hat.

Abrufen eines bestimmten Status der Zielgruppenaufnahme retrieve-ingestion-status

NOTE
Um den folgenden Endpunkt verwenden zu können, müssen Sie sowohl die audienceId Ihrer externen Zielgruppe als auch die runId Ihrer Aufnahme-Ausführungs-ID haben. Sie können Ihre audienceId von einem erfolgreichen Aufruf an den GET /external-audiences/operations/{OPERATION_ID}-Endpunkt und Ihre runId von einem vorherigen erfolgreichen Aufruf des POST /external-audience/{AUDIENCE_ID}/runs-Endpunkts abrufen.

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.

API-Format

GET /external-audience/{AUDIENCE_ID}/runs/{RUN_ID}

Anfrage

Die folgende Anfrage ruft den Aufnahmestatus für die externe Zielgruppe ab.

Eine Beispielanfrage zum Abrufen des Aufnahmestatus der externen Zielgruppe.
code language-shell 
curl -X GET https://platform.adobe.io/data/core/ais/external-audience/60ccea95-1435-4180-97a5-58af4aa285ab/runs/fb342311-725d-4b48-ab7d-c6105fbc2b8b \
 -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}'

Antwort

Eine erfolgreiche Antwort gibt den HTTP-Status-Code 200 mit Details zur Aufnahme externer Zielgruppen zurück.

Eine Beispielantwort beim Abrufen der Aufnahme der externen Zielgruppe.
code language-json 
{
    "audienceName": "Sample external audience",
    "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
    "runId": "fb342311-725d-4b48-ab7d-c6105fbc2b8b",
    "status": "SUCCESS",
    "differentialIngestion": true,
    "dataFilterStartTime": 764245635,
    "dataFilterEndTime": 3456788568,
    "createdAt": 1749324248,
    "createdBy": "{USER_ID}",
    "details": [
        {
            "stage": "DATASET_INGEST",
            "status": "SUCCESS",
            "flowRunId": "{FLOW_RUN_ID}"
        },
        {
            "stage": "PROFILE_STORE_INGEST",
            "status": "SUCCESS",
            "flowRunId": "{FLOW_RUN_ID}"
        }
    ]
}
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3
Eigenschaft Typ Beschreibung
audienceName Zeichenfolge Der Name der Zielgruppe.
audienceId Zeichenfolge Die ID der Zielgruppe.
runId Zeichenfolge Die ID des Aufnahmedurchgangs.
status Zeichenfolge Der Status des Aufnahmedurchgangs. Mögliche Status sind SUCCESS und FAILED.
differentialIngestion Boolesch Ein Feld, das bestimmt, ob es sich bei der Aufnahme um eine partielle Aufnahme handelt, basierend auf der Differenz seit der letzten Aufnahme oder einer vollständigen Zielgruppenaufnahme.
dataFilterStartTime Zeitstempel der Epoche Der Bereich, der die Startzeit angibt, zu der der Fluss ausgeführt wird, um auszuwählen, welche Dateien verarbeitet wurden.
dataFilterEndTime Zeitstempel der Epoche Der Bereich, der die Endzeit angibt, zu der der Fluss ausgeführt wird, um auszuwählen, welche Dateien verarbeitet wurden.
createdAt Zeitstempel für lange Epochen Der Zeitstempel in Sekunden, wann die Anfrage zur Erstellung der externen Zielgruppe gesendet wurde.
createdBy Zeichenfolge Die ID des Benutzers, der die externe Zielgruppe erstellt hat.
details Array von Objekten

Ein Objekt, das die Details des Aufnahmevorgangs enthält.

  • stage: Das Stadium des Aufnahmevorgangs. Dies kann entweder DATASET_INGEST oder PROFILE_STORE_INGEST sein, die die Data-Lake-Aufnahme und die Profilaufnahme darstellen.
  • status: Der Status der Aufnahme auf dem Staging. Mögliche Status sind SUCCESS und FAILED.
  • flowRunId: Die ID der Aufnahme-Flussausführung des Schritts.

Auflisten der Aufnahmedurchgänge von Zielgruppen list-ingestion-runs

NOTE
Um den folgenden Endpunkt verwenden zu können, benötigen Sie die audienceId Ihrer externen Zielgruppe. Sie können Ihre audienceId von einem erfolgreichen Aufruf an den GET /external-audiences/operations/{OPERATION_ID}-Endpunkt abrufen.

Sie können alle Aufnahmedurchgänge für die ausgewählte externe Zielgruppe abrufen, indem Sie eine GET-Anfrage an den folgenden Endpunkt senden und dabei die Zielgruppen-ID angeben. Es können mehrere Parameter eingeschlossen werden, die durch kaufmännische Und-Zeichen (&) voneinander getrennt werden.

API-Format

GET /external-audience/{AUDIENCE_ID}/runs

Anfrage

Die folgende Anfrage ruft alle Aufnahmedurchgänge für die externe Zielgruppe ab.

Eine Beispielanfrage zum Abrufen einer Liste von Zielgruppen-Erfassungsdurchgängen.
code language-shell 
curl -X GET https://platform.adobe.io/data/core/ais/external-audience/60ccea95-1435-4180-97a5-58af4aa285ab/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}'

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Status 200 mit einer Liste von Aufnahmedurchgängen für die angegebene externe Zielgruppe zurückgegeben.

Eine Beispielantwort, wenn Sie eine Liste der Audience-Aufnahmedurchgänge abrufen.
code language-json 
{
    "runs": [
        {
            "audienceName": "Sample external audience",
            "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
            "runId": "fb342311-725d-4b48-ab7d-c6105fbc2b8b",
            "status": "SUCCESS",
            "differentialIngestion": true,
            "dataFilterStartTime": 764245635,
            "dataFilterEndTime": 3456788568,
            "createdAt": 1785678909,
            "createdBy": "{USER_NAME}"
        },
        {
            "audienceName": "Sample external audience 2",
            "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
            "runId": "406e38e4-fbd5-43e1-8d0c-01ccb3f9ad10",
            "status": "SUCCESS",
            "differentialIngestion": true,
            "dataFilterStartTime": 764245635,
            "dataFilterEndTime": 3456788568,
            "createdAt": 1749324248,
            "createdBy": "{USER_ID}"
        }
    ]
}
table 0-row-3 1-row-3
Eigenschaft Typ Beschreibung
runs Objekt Ein -Objekt, das die Liste der Aufnahmedurchgänge enthält, die zur Audience gehören. Weitere Informationen zu diesem Objekt finden Sie im Abschnitt Abrufen des ​".

Verlängern des Datenablaufs für eine externe Zielgruppe extend-data-expiration

NOTE
Um den folgenden Endpunkt verwenden zu können, benötigen Sie die audienceId Ihrer externen Zielgruppe. Sie können Ihre audienceId von einem erfolgreichen Aufruf an den GET /external-audiences/operations/{OPERATION_ID}-Endpunkt abrufen.

Sie können den Datenablauf einer externen Zielgruppe verlängern, indem Sie eine POST-Anfrage an den folgenden Endpunkt senden und dabei die Zielgruppen-ID angeben.

Der Ablauf der Daten wird um die ursprüngliche Dauer verlängert, die während der Aufnahme festgelegt wurde. Wenn keine Dauer angegeben wurde, wird standardmäßig eine Verlängerung von 30 Tagen angewendet. Wenn Sie die Datengültigkeit verlängern, wird die Zielgruppe mit den Daten der letzten erfolgreichen Aufnahme erneut aufgenommen.

API-Format

/ais/external-audience/extend-ttl/{AUDIENCE_ID}

Anfrage

Die folgende Anfrage erweitert den Datenablauf der angegebenen externen Zielgruppe.

Eine Beispielanfrage zum Erweitern des Datenablaufs einer externen Zielgruppe.
code language-shell 
curl -x POST https://platform.adobe.io/data/core/ais/external-audience/extend-ttl/60ccea95-1435-4180-97a5-58af4aa285ab \
 -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}'

Antwort

Bei einer erfolgreichen Antwort wird der HTTP-Status 200 mit Details zur Audience zurückgegeben.

Eine Beispielantwort bei der Verlängerung der Datengültigkeit.
code language-json 
{
    "audienceId": "60ccea95-1435-4180-97a5-58af4aa285ab",
    "name": "Sample external audience"
}

Löschen einer externen Zielgruppe delete-audience

NOTE
Um den folgenden Endpunkt verwenden zu können, benötigen Sie die audienceId Ihrer externen Zielgruppe. Sie können Ihre audienceId von einem erfolgreichen Aufruf an den GET /external-audiences/operations/{OPERATION_ID}-Endpunkt abrufen.

Sie können eine externe Zielgruppe löschen, indem Sie eine DELETE-Anfrage an den folgenden Endpunkt stellen und dabei die Zielgruppen-ID angeben.

API-Format

DELETE /external-audience/{AUDIENCE_ID}

Anfrage

Die folgende Anfrage löscht die angegebene externe Zielgruppe.

Eine Beispielanfrage zum Löschen der externen Zielgruppe.
code language-shell 
curl -X DELETE https://platform.adobe.io/data/core/ais/external-audience/60ccea95-1435-4180-97a5-58af4aa285ab/ \
 -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}'

Antwort

Eine erfolgreiche Antwort gibt den HTTP-Status 204 mit einem leeren Antworttext zurück.

Nächste Schritte next-steps

Nach dem Lesen dieses Handbuchs haben Sie jetzt ein besseres Verständnis davon, wie Sie Ihre externen Zielgruppen mithilfe der Experience Platform-APIs erstellen, verwalten und löschen können. Informationen zur Verwendung externer Zielgruppen mit der Experience Platform-Benutzeroberfläche finden Sie in der Dokumentation zum Zielgruppenportal.

Anhang appendix

Im folgenden Abschnitt sind die verfügbaren Fehler-Codes bei Verwendung der API für externe Zielgruppen aufgeführt.

Plattform-Fehlercode
Status-Code
Nachricht
Beschreibung
100910-400
400
BAD_REQUEST
Aufgrund eines Fehlers bei der Validierung der Anfragen ist eine ungültige Anfrage aufgetreten.
100911-400
400
BAD_REQUEST
Ein ungültiges Token wird angegeben.
100920-401
401
UNAUTHORIZED
Eine Kopfzeile fehlt.
100921-401
401
UNAUTHORIZED
Ein ungültiger imsOrgId wurde angegeben.
100922-401
401
UNAUTHORIZED
Sie sind nicht berechtigt, die APIs für externe Zielgruppen zu verwenden.
100940-404
404
NOT_FOUND
Die angeforderte Zielgruppe wurde nicht gefunden.
100950-409
409
DUPLICATE_RESOURCE
Die Zielgruppe existiert bereits.
100960-422
422
UNPROCESSABLE_ENTITY
Die Anfragestruktur ist gültig, kann jedoch aufgrund logischer oder semantischer Fehler nicht verarbeitet werden.
100970-500
500
INTERNAL_SERVER_ERROR
Bei der Verarbeitung der Anfrage im System ist ein Problem aufgetreten.
100970-502
502
BAD_GATEWAY
Es gibt Abhängigkeitsprobleme im nachgelagerten Bereich.
recommendation-more-help
770bc05d-534a-48a7-9f07-017ec1e14871