Zielgruppen bei Bedarf über die Ad-hoc-Aktivierungs-API aktivieren

Überblick overview

Mit der Ad-hoc-Aktivierungs-API können Marketing-Experten Zielgruppen für Situationen, in denen eine sofortige Aktivierung erforderlich ist, schnell und effizient programmgesteuert für Ziele aktivieren.

Verwenden Sie die Ad-hoc-Aktivierungs-API, um Zielgruppen bei Bedarf für Batch-dateibasierte Ziele und ab Version 4 für Streaming- und API-basierte Ziele zu aktivieren. Siehe Trigger eines Ad-hoc-Aktivierungsdurchgangs weiter unten in diesem Tutorial.

Die folgende Abbildung zeigt den kompletten Workflow zum Aktivieren von Zielgruppen über die Ad-hoc-Aktivierungs-API, einschließlich der Segmentierungsaufträge, die alle 24 Stunden in Experience Platform stattfinden.

Anwendungsfälle use-cases

Flash-Verkäufe oder -Promotions flash-sales

Ein Online-retailer bereitet einen begrenzten Flash-Verkauf vor und möchte die Kunden kurzfristig benachrichtigen. Über die Ad-hoc-Aktivierungs-API von Experience Platform kann das Marketing-Team Zielgruppen bei Bedarf exportieren und schnell Werbe-E-Mails an den Kundenstamm senden.

Aktuelle Ereignisse oder aktuelle Nachrichten current-events

Ein Hotel erwartet in den nächsten Tagen ungünstiges Wetter und das Team möchte die ankommenden Gäste schnell informieren, damit sie entsprechend planen können. Das Marketing-Team kann die Ad-hoc-Aktivierungs-API von Experience Platform verwenden, um Zielgruppen bei Bedarf zu exportieren und die Gäste zu benachrichtigen.

Integrationstests integration-testing

IT-Manager können die Ad-hoc-Aktivierungs-API von Experience Platform verwenden, um Zielgruppen bei Bedarf zu exportieren, sodass sie ihre benutzerdefinierte Integration mit Adobe Experience Platform testen und sicherstellen können, dass alles ordnungsgemäß funktioniert.

Zielgruppen-Aktualisierung für Streaming-Ziele audience-refresh-streaming

Ein Streaming- oder API-basiertes Ziel wendet eine Time-to-Live (TTL) auf die Zielgruppenzugehörigkeit an, die es von Adobe Experience Platform erhält. Wenn diese TTL auf der Zielseite abläuft, werden zuvor qualifizierte Profile als inaktiv behandelt, obwohl sie in Experience Platform qualifiziert bleiben. Das Marketing-Team kann die v4 der Ad-hoc-Aktivierungs-API verwenden, um die aktuelle Vollmitgliedschaft einer Zielgruppe bei Bedarf erneut zu senden, ohne auf die nächste geplante Aktualisierung zu warten. Siehe Trigger eines Ad-hoc-Aktivierungsdurchgangs weiter unten in diesem Tutorial.

Leitlinien guardrails

Beachten Sie die folgenden Leitplanken bei der Verwendung der Ad-hoc-Aktivierungs-API.

Überlegungen zur Segmentierung segmentation-considerations

Adobe Experience Platform führt geplante Segmentierungsaufträge alle 24 Stunden aus. Die Ad-hoc-Aktivierungs-API wird auf der Grundlage der neuesten Segmentierungsergebnisse ausgeführt.

Schritt 1: Voraussetzungen prerequisites

Bevor Sie die Adobe Experience Platform-APIs aufrufen können, stellen Sie sicher, dass Sie die folgenden Voraussetzungen erfüllen:

Schritt 2: Sammeln von Anmeldeinformationen credentials

Um Experience Platform-APIs aufzurufen, müssen Sie zunächst das Authentifizierungs-Tutorial“ ​. Im Rahmen des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Kopfzeilen in allen Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:

Ressourcen in Experience Platform lassen sich in spezifischen virtuellen Sandboxes isolieren. Bei Anfragen an Experience Platform-APIs können Sie den Namen und die ID der Sandbox angeben, in der der Vorgang ausgeführt werden soll. Dies sind optionale Parameter.

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

API-Referenzdokumentation api-reference-documentation

Eine zugehörige Referenzdokumentation für alle API-Vorgänge finden Sie in diesem Tutorial. Siehe die Ad Hoc Activation API-Referenz.

Schritt 3: Erstellen eines Aktivierungsflusses in der Experience Platform-Benutzeroberfläche activation-flow

Bevor Sie Zielgruppen über die Ad-hoc-Aktivierungs-API aktivieren können, muss zunächst in der Experience Platform-Benutzeroberfläche ein Aktivierungsfluss für das ausgewählte Ziel konfiguriert worden sein.

Dazu gehören der Einstieg in den Aktivierungs-Workflow, die Auswahl Ihrer Zielgruppen, die Konfiguration eines Zeitplans und die Aktivierung. Sie können die Benutzeroberfläche oder API verwenden, um einen Aktivierungsfluss zu erstellen:

Schritt 4: Abrufen der neuesten Zielgruppen-Exportvorgangs-ID (in Version 2 nicht erforderlich) segment-export-id

Nachdem Sie einen Aktivierungsfluss für Ihr Batch-Ziel konfiguriert haben, werden geplante Segmentierungsaufträge automatisch alle 24 Stunden ausgeführt.

Bevor Sie den Ad-hoc-Aktivierungsauftrag ausführen können, müssen Sie die ID des neuesten Zielgruppen-Exportauftrags abrufen. Sie müssen diese ID in der Ad-hoc-Aktivierungsanfrage übergeben.

Befolgen Sie die hier beschriebenen Anweisungen, um eine Liste aller Zielgruppenexportvorgänge abzurufen.

Suchen Sie in der Antwort nach dem ersten Datensatz, der die folgende Schemaeigenschaft enthält.

"schema":{
   "name":"_xdm.context.profile"
}

Die Auftrags-ID des Zielgruppenexports befindet sich in der id-Eigenschaft, wie unten dargestellt.

Schritt 5: Ad-hoc-Aktivierungsauftrag ausführen activation-job

Adobe Experience Platform führt geplante Segmentierungsaufträge alle 24 Stunden aus. Die Ad-hoc-Aktivierungs-API wird auf der Grundlage der neuesten Segmentierungsergebnisse ausgeführt.

Stellen Sie vor der Ausführung eines Ad-hoc-Aktivierungsauftrags sicher, dass der geplante Zielgruppenexportauftrag für Ihre Zielgruppen abgeschlossen ist. Informationen ​ Überwachen des Status ​ Aktivierungsflüsse finden Sie unter „Ziel-Datenflussüberwachung“. Wenn Ihr Aktivierungsdatenfluss beispielsweise den Status Verarbeitung läuft aufweist, warten Sie, bis er abgeschlossen ist, bevor Sie den Ad-hoc-Aktivierungsauftrag ausführen, um eine vollständige Datei zu exportieren.

Nachdem der Zielgruppenexport abgeschlossen ist, können Sie einen Trigger für die Aktivierung erstellen.

Anfrage request

Für Zielgruppen, die nicht vom Segmentierungs-Service stammen (z. B. externe oder benutzerdefinierte Upload-Zielgruppen), müssen Sie in Ihrer Anfrage die von Experience Platform generierte Zielgruppen-ID und nicht die externe Zielgruppen-ID angeben. Die systemgenerierte ID finden Sie oben im Bereich Zielgruppenzusammenfassung, die als ID# gefolgt von einer UUID angezeigt wird, wenn Sie die Seite mit den Zielgruppendetails in der Zielgruppen-Benutzeroberfläche öffnen.

curl --location --request POST 'https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun' \
--header 'x-gw-ims-org-id: 5555467B5D8013E50A494220@AdobeOrg' \
--header 'Authorization: Bearer {{token}}' \
--header 'x-sandbox-id: 6ef74723-3ee7-46a4-b747-233ee7a6a41a' \
--header 'x-sandbox-name: {sandbox-id}' \
--header 'Accept: application/vnd.adobe.adhoc.activation+json; version=2' \
--header 'Content-Type: application/json' \
--data-raw '{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   }
}'

Eigenschaft

Beschreibung

• destinationId1
• destinationId2

Die IDs der Zielinstanzen, für die Sie Zielgruppen aktivieren möchten. Sie können diese IDs über die Experience Platform-Benutzeroberfläche abrufen, indem Sie zur Registerkarte Ziele > Durchsuchen navigieren und auf die gewünschte Zielzeile klicken, um die Ziel-ID in der rechten Leiste aufzurufen. Weitere Informationen finden Sie in der Dokumentation zum Arbeitsbereich „Ziele.

• segmentId1
• segmentId2
• segmentId3

Die IDs der Zielgruppen, die Sie für das ausgewählte Ziel aktivieren möchten. Mit der Ad-hoc-API können Sie Experience Platform-generierte Zielgruppen sowie externe (benutzerdefinierte Upload-)Zielgruppen exportieren. Verwenden Sie beim Aktivieren externer Zielgruppen die systemgenerierte ID anstelle der Zielgruppen-ID. Die systemgenerierte ID finden Sie in der Ansicht „Zielgruppenzusammenfassung“ in der Benutzeroberfläche „Zielgruppen“.
{width="100" modal="regular"}
{width="100" modal="regular"}

Anfrage mit Export-IDs request-export-ids

curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   },
   "exportIds":[
      "exportId1"
   ]
}

Antwort response

Eine erfolgreiche Antwort gibt den HTTP-Status 200 zurück.

{
   "order":[
      {
         "segment":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "order":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "statusURL":"https://platform.adobe.io/data/foundation/flowservice/runs/88d6da63-dc97-460e-b781-fc795a7386d9"
      }
   ]
}

Umgang mit API-Fehlern api-error-handling

Destination SDK-API-Endpunkte folgen den allgemeinen Grundsätzen von Experience Platform API-Fehlermeldungen. Siehe API-StatusCodes und Fehler in der Anfragekopfzeile im Handbuch zur Fehlerbehebung bei Experience Platform.

API-Fehler-Codes und Meldungen, die spezifisch für die Ad-hoc-Aktivierungs-API sind specific-error-messages

Bei Verwendung der Ad-hoc-Aktivierungs-API können Sie auf Fehlermeldungen stoßen, die für diesen API-Endpunkt spezifisch sind. Überprüfen Sie die Tabelle, um zu verstehen, wie Sie darauf reagieren, wenn sie angezeigt werden.

(Beta) Trigger einer Ad-hoc-Aktivierungsausführung streaming-destinations

Verwenden Sie v4 der Ad-hoc-Aktivierungs-API zum Trigger Jetzt aktivieren einer On-Demand-Vollmitgliedschafts-Aktualisierung einer Zielgruppe zu einem Streaming- oder API-basierten Ziel.

Viele Streaming- und API-basierte Ziele wenden eine Time-to-Live (TTL) auf die Zielgruppenzugehörigkeit an, die sie von Adobe Experience Platform erhalten. Wenn diese TTL auf der Zielseite abläuft, werden zuvor qualifizierte Profile als inaktiv behandelt, obwohl sie in Experience Platform qualifiziert bleiben. Ad-hoc-Aktivierungsausführung von Trigger A V4, um jedes aktuell qualifizierte Profil über die vorhandene Streaming-Aktivierungs-Pipeline erneut zu senden, ohne auf die nächste geplante Aktualisierung zu warten.

Sie können diese Aktualisierung auch über die Experience Platform-Benutzeroberfläche mit einem Trigger versehen. Lesen Sie Jetzt für Streaming-Ziele aktivieren.

Leitplanken für Streaming streaming-guardrails

Die Ad-hoc-Aktivierung an Streaming-Ziele setzt die folgende Beschränkung durch:

Streaming-Anfrage streaming-request

curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -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}' \
 -H 'Accept: application/vnd.adobe.adhoc.streaming.activation+json; version=1' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ]
   }
}'

Streaming-Antwort streaming-response

Bei einer erfolgreichen Antwort wird der HTTP-Status 202 (Akzeptiert) zurückgegeben und ein Streaming-Auftrag pro angeforderter Zielgruppe erstellt.

{
   "jobs":[
      {
         "jobId":"88d6da63-dc97-460e-b781-fc795a7386d9",
         "flowId":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "audienceId":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "imsOrgId":"{ORG_ID}",
         "status":"QUEUED",
         "createdAt":"2026-08-17T14:00:00Z"
      }
   ]
}

Wenn für diesen Datenfluss innerhalb der letzten 24 Stunden bereits dieselbe Zielgruppe ausgelöst wurde, wird die Anfrage mit HTTP 409 und einer Retry-After-Kopfzeile mit der Anzahl der Sekunden abgelehnt, bis Sie es erneut versuchen können.

Verwandte Informationen related-information