Endpunkt für externe Zielgruppen
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.
Erste Schritte
/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}
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
code language-shell |
---|
|
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 |
String | Eine optionale Beschreibung für die externe Zielgruppe. |
customAudienceId |
String | Eine optionale Kennung für Ihre externe Zielgruppe. |
fields |
Array von Objekten |
Liste der Felder und ihrer Datentypen Beim Erstellen der Feldliste können Sie die folgenden Elemente hinzufügen:
|
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:
|
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 |
String | Der Zielgruppentyp für die externe Zielgruppe. Derzeit wird nur people unterstützt. |
originName |
String | Erforderlich Die Herkunft der Zielgruppe. Hier wird angegeben, woher die Zielgruppe stammt. Für externe Zielgruppen sollten Sie CUSTOM_UPLOAD verwenden. |
namespace |
String | 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. 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.
code language-json |
---|
|
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 |
String | Der Name für die externe Zielgruppe. |
description |
String | 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 |
String | Der Zielgruppentyp für die externe Zielgruppe. |
originName |
String | Erforderlich Die Herkunft der Zielgruppe. Dies gibt an, woher die Zielgruppe kommt. |
namespace |
String | 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}
{OPERATION_ID}
id
des Vorgangs, den Sie abrufen möchten.Anfrage
code language-shell |
---|
|
Antwort
Bei einer erfolgreichen Antwort wird der HTTP-Status 200 mit Details zum Aufgabenstatus der externen Zielgruppe zurückgegeben.
code language-json |
---|
|
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 |
String | 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 |
String | Die ID der externen Zielgruppe, die vom Vorgang gesendet wird. |
createdBy |
String | 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 |
String | 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
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
code language-shell |
---|
|
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.
code language-json |
---|
|
Zielgruppenerfassung starten start-audience-ingestion
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.
code language-shell |
---|
|
table 0-row-3 1-row-3 2-row-3 | ||
---|---|---|
Eigenschaft | Typ | Beschreibung |
dataFilterStartTime |
Zeitstempel der Epoche | Erforderlich Der Bereich, der die Startzeit angibt, zu der der Fluss ausgeführt wird, um die zu verarbeitenden Dateien auszuwählen. |
dataFilterEndTime |
Zeitstempel der Epoche | Der Bereich, der die Endzeit angibt, zu der der Fluss ausgeführt wird, um die zu verarbeitenden Dateien auszuwählen. |
Antwort
Eine erfolgreiche Antwort gibt den HTTP-Status-Code 200 mit Details zur Aufnahmeausführung zurück.
code language-json |
---|
|
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 |
String | Die ID der Zielgruppe. |
runId |
String | 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 |
String | Die ID des Benutzers, der die externe Zielgruppe erstellt hat. |
Abrufen eines bestimmten Status der Zielgruppenaufnahme retrieve-ingestion-status
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.
code language-shell |
---|
|
Antwort
Eine erfolgreiche Antwort gibt den HTTP-Status-Code 200 mit Details zur Aufnahme externer Zielgruppen zurück.
code language-json |
---|
|
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 |
String | Die ID der Zielgruppe. |
runId |
String | Die ID des Aufnahmedurchgangs. |
status |
String | 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 |
String | Die ID des Benutzers, der die externe Zielgruppe erstellt hat. |
details |
Array von Objekten |
Ein Objekt, das die Details des Aufnahmevorgangs enthält.
|
Auflisten der Aufnahmedurchgänge von Zielgruppen list-ingestion-runs
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.
code language-shell |
---|
|
Antwort
Bei einer erfolgreichen Antwort wird der HTTP-Status 200 mit einer Liste von Aufnahmedurchgängen für die angegebene externe Zielgruppe zurückgegeben.
code language-json |
---|
|
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". |
Löschen einer externen Zielgruppe delete-audience
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.
code language-shell |
---|
|
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.
BAD_REQUEST
BAD_REQUEST
UNAUTHORIZED
UNAUTHORIZED
imsOrgId
wurde angegeben.UNAUTHORIZED
NOT_FOUND
DUPLICATE_RESOURCE
UNPROCESSABLE_ENTITY
INTERNAL_SERVER_ERROR
BAD_GATEWAY