Segmentdefinitionsergebnisse auswerten und aufrufen
Dieses Dokument bietet eine Anleitung zum Auswerten von Segmentdefinitionen und zum Zugriff auf diese Ergebnisse mithilfe der Segmentation API.
Erste Schritte
Dieses Tutorial setzt ein Verständnis der verschiedenen Adobe Experience Platform Dienste, die an der Erstellung von Zielgruppen beteiligt sind. Bevor Sie mit diesem Tutorial beginnen, lesen Sie bitte die Dokumentation für die folgenden Services:
- Real-Time Customer Profile: Bietet ein einheitliches Kundenprofil in Echtzeit, das auf aggregierten Daten aus mehreren Quellen basiert.
- Adobe Experience Platform Segmentation Service: Ermöglicht das Erstellen von Zielgruppen aus Real-Time Customer Profile Daten.
- Experience Data Model (XDM): Das standardisierte Framework, mit dem Platform Kundenerlebnisdaten ordnet. Um die Segmentierung optimal zu nutzen, stellen Sie sicher, dass Ihre Daten als Profile und Ereignisse gemäß den Best Practices für die Datenmodellierung aufgenommen werden.
- Sandboxes: Experience Platform bietet virtuelle Sandboxes, die eine einzelne Platform-Instanz in separate virtuelle Umgebungen unterteilen, damit Sie Programme für digitale Erlebnisse entwickeln können.
Erforderliche Kopfzeilen
Für dieses Tutorial müssen Sie außerdem die Authentifizierungs-Tutorial , um erfolgreich Aufrufe an Platform APIs. 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:
{ORG_ID}
Alle Ressourcen in Experience Platform sind auf bestimmte virtuelle Sandboxes beschränkt. Anforderungen an Platform APIs erfordern eine Kopfzeile, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt werden soll:
- x-sandbox-name:
{SANDBOX_NAME}
Für alle POST-, PUT- und PATCH-Anfragen ist eine zusätzliche Kopfzeile erforderlich:
- Content-Type: application/json
Segmentdefinition bewerten evaluate-a-segment
Nachdem Sie Ihre Segmentdefinition entwickelt, getestet und gespeichert haben, können Sie die Segmentdefinition entweder durch eine geplante Auswertung oder eine On-Demand-Auswertung bewerten.
Geplante Auswertung (auch als "geplante Segmentierung"bezeichnet) können Sie einen Zeitplan für die Ausführung eines Exportauftrags zu einem bestimmten Zeitpunkt erstellen, während On-Demand-Evaluierung umfasst die Erstellung eines Segmentauftrags, um die Zielgruppe sofort zu erstellen. Die Schritte für die einzelnen Schritte sind unten beschrieben.
Wenn Sie die Erstellen einer Segmentdefinition mithilfe der Segmentation-API Tutorial oder Erstellen einer Segmentdefinition mithilfe von Segment Buildersollten Sie dies tun, bevor Sie mit diesem Tutorial fortfahren.
Geplante Auswertung scheduled-evaluation
Durch die geplante Auswertung kann Ihr Unternehmen einen Zeitplan für die automatische Ausführung von Exportvorgängen erstellen.
Zeitplan erstellen
Wenn Sie eine POST-Anfrage an den /config/schedules
-Endpunkt senden, können Sie einen Zeitplan erstellen und die genaue Zeit einschließen, zu der der Zeitplan ausgelöst werden soll.
Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Abschnitt Endpunktleitfaden für Zeitpläne
Zeitplan aktivieren
Standardmäßig ist ein Zeitplan bei der Erstellung inaktiv, es sei denn, die state
-Eigenschaft ist im Text der POST-Anfrage (Erstellen) auf active
gesetzt. Sie können einen Zeitplan aktivieren (setzen Sie state
auf active
), indem Sie eine PATCH-Anfrage an den /config/schedules
-Endpunkt senden und die Kennung des Zeitplans in den Pfad einschließen.
Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Abschnitt Endpunktleitfaden für Zeitpläne
Zeitplanaktualisierung
Der Zeitplan kann aktualisiert werden, indem eine PATCH-Anfrage an die /config/schedules
-Endpunkt und die Kennung des Zeitplans in den Pfad einschließen.
Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Abschnitt Endpunktleitfaden für Zeitpläne
On-Demand-Evaluierung
Mit der On-Demand-Auswertung können Sie einen Segmentauftrag erstellen, um bei Bedarf eine Zielgruppe zu generieren. Im Gegensatz zur geplanten Auswertung erfolgt dies nur bei Anforderung und nicht wiederholt.
Erstellen eines Segmentauftrags
Ein Segmentauftrag ist ein asynchroner Prozess, der ein Zielgruppensegment bei Bedarf erstellt. Er verweist auf eine Segmentdefinition sowie auf alle Zusammenführungsrichtlinien, die steuern, wie Real-Time Customer Profile Führt überlappende Attribute über Ihre Profilfragmente hinweg zusammen. Nach erfolgreichem Abschluss eines Segmentauftrags können Sie verschiedene Informationen zur Segmentdefinition sammeln, z. B. Fehler, die während der Verarbeitung aufgetreten sind, und die endgültige Größe Ihrer Zielgruppe. Ein Segmentauftrag muss jedes Mal ausgeführt werden, wenn Sie die Zielgruppe aktualisieren möchten, für die sich die Segmentdefinition derzeit qualifiziert.
Sie können einen neuen Segmentauftrag erstellen, indem Sie eine POST-Anfrage an die /segment/jobs
-Endpunkt im Real-Time Customer Profile API.
Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Abschnitt Endpunktleitfaden für Segmentaufträge
Status des Segmentauftrags nachschlagen
Sie können die id
für einen bestimmten Segmentauftrag, um eine Nachschlageanfrage (GET) auszuführen, um den aktuellen Status des Auftrags anzuzeigen.
Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Abschnitt Endpunktleitfaden für Segmentaufträge
Interpretieren von Segmentauftragsergebnissen
Wenn Segmentaufträge erfolgreich ausgeführt werden, wird die segmentMembership
map wird für jedes Profil aktualisiert, das in der Segmentdefinition enthalten ist. segmentMembership
speichert auch alle vorab ausgewerteten Zielgruppen, die in Platform, wodurch eine Integration mit anderen Lösungen wie Adobe Audience Manager.
Das folgende Beispiel zeigt, was die segmentMembership
-Attribut für jeden einzelnen Profildatensatz aussieht:
{
"segmentMembership": {
"UPS": {
"04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
"timestamp": "2018-04-26T15:52:25+00:00",
"status": "realized"
},
"53cba6b2-a23b-454a-8069-fc41308f1c0f": {
"lastQualificationTime": "2018-04-26T15:52:25+00:00",
"status": "realized"
}
},
"Email": {
"abcd@adobe.com": {
"lastQualificationTime": "2017-09-26T15:52:25+00:00",
"status": "exited"
}
}
}
}
lastQualificationTime
status
Der Teilnahmestatus der Segmentdefinition als Teil der aktuellen Anfrage. Muss einem der folgenden bekannten Werte entsprechen:
realized
: Entität qualifiziert sich für die Segmentdefinition.exited
: Entität beendet die Segmentdefinition.
exited
Status für mehr als 30 Tage, basierend auf der Variablen lastQualificationTime
, kann gelöscht werden.Auf Segmentauftragsergebnisse zugreifen
Auf die Ergebnisse eines Segmentauftrags kann auf zwei Arten zugegriffen werden: Sie können auf einzelne Profile zugreifen oder eine gesamte Zielgruppe in einen Datensatz exportieren.
In den folgenden Abschnitten werden diese Optionen ausführlicher beschrieben.
Profil nachschlagen
Wenn Sie das spezifische Profil kennen, auf das Sie zugreifen möchten, können Sie dies mit der Real-Time Customer Profile API. Die vollständigen Schritte für den Zugriff auf einzelne Profile finden Sie im Abschnitt Zugriff auf Echtzeit-Kundenprofil-Daten mithilfe der Profil-API Tutorial.
Segment exportieren export
Nachdem ein Segmentierungsauftrag erfolgreich abgeschlossen wurde (der Wert des status
-Attributs lautet „SUCCEEDED“ (GELUNGEN)), können Sie Ihre Zielgruppe in einen Datensatz exportieren. In diesem Datensatz ist die Zielgruppe zugänglich und bearbeitbar.
Die folgenden Schritte sind erforderlich, um Ihre Audience zu exportieren:
- Erstellen eines Zieldatensatzes - Erstellen Sie den Datensatz, um Mitglieder der Zielgruppe aufzunehmen.
- Generieren von Zielgruppenprofilen im Datensatz - Füllen Sie den Datensatz mit individuellen XDM-Profilen basierend auf den Ergebnissen eines Segmentauftrags.
- Fortschritt des Exports überwachen - Überprüfen Sie den aktuellen Fortschritt des Exportvorgangs.
- Audience-Daten lesen - Rufen Sie die resultierenden individuellen XDM-Profile ab, die die Mitglieder Ihrer Audience darstellen.
Erstellen eines Zieldatensatzes create-dataset
Beim Exportieren einer Zielgruppe muss zunächst ein Zieldatensatz erstellt werden. Es ist wichtig, dass der Datensatz korrekt konfiguriert ist, um sicherzustellen, dass der Export erfolgreich ist.
Eine der wichtigsten Überlegungen ist das Schema, auf dem der Datensatz basiert (schemaRef.id
in der API-Beispielanfrage unten). Um eine Segmentdefinition zu exportieren, muss der Datensatz auf der XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union
). Ein Vereinigungsschema ist ein systemgeneriertes, schreibgeschütztes Schema, das die Felder von Schemas aggregiert, die dieselbe Klasse teilen, in diesem Fall die Klasse "XDM Individual Profile". Weitere Informationen zu Vereinigungsansichtsschemas finden Sie im Abschnitt "Echtzeit-Kundenprofil"des Entwicklerhandbuchs zur Schema Registry.
Es gibt zwei Möglichkeiten, den erforderlichen Datensatz zu erstellen:
- Verwenden von APIs: In den in diesem Tutorial beschriebenen Schritten wird beschrieben, wie Sie einen Datensatz erstellen, der auf die XDM Individual Profile Union Schema mithilfe der Catalog API.
- Verwenden der Benutzeroberfläche: So verwenden Sie die Adobe Experience Platform -Benutzeroberfläche zum Erstellen eines Datensatzes, der auf das Vereinigungsschema verweist, führen Sie die Schritte im Abschnitt UI-Tutorial und dann zu diesem Tutorial zurückkehren, um mit den Schritten für Erstellen von Zielgruppenprofilen.
Wenn Sie bereits über einen kompatiblen Datensatz verfügen und dessen Kennung kennen, können Sie direkt mit dem Schritt für Erstellen von Zielgruppenprofilen.
API-Format
POST /dataSets
Anfrage
Die folgende Anfrage erstellt einen neuen Datensatz und stellt Konfigurationsparameter in der Payload bereit.
curl -X POST \
https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "Segment Export",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
name
schemaRef.id
Antwort
Eine erfolgreiche Antwort gibt ein Array zurück, das die schreibgeschützte, systemgenerierte eindeutige ID des neu erstellten Datensatzes enthält. Eine ordnungsgemäß konfigurierte Datensatz-ID ist erforderlich, um Audience-Mitglieder erfolgreich zu exportieren.
[
"@/datasets/5b020a27e7040801dedba61b"
]
Generieren von Profilen für Zielgruppenmitglieder generate-profiles
Sobald Sie über einen Datensatz verfügen, der die Vereinigung beibehält, können Sie einen Exportauftrag erstellen, um die Mitglieder der Zielgruppe im Datensatz zu erhalten, indem Sie eine POST-Anfrage an die /export/jobs
-Endpunkt im Real-Time Customer Profile API und Bereitstellung der Datensatz-ID und der Segmentdefinitionsinformationen für die Segmentdefinitionen, die Sie exportieren möchten.
Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Abschnitt Endpunktleitfaden für Exportaufträge
Fortschritt des Exports überwachen
Bei Exportvorgängen können Sie den Status überwachen, indem Sie eine GET-Anfrage an die /export/jobs
-Endpunkt und einschließlich id
des Exportauftrags im Pfad. Der Exportvorgang ist abgeschlossen, sobald die status
gibt den Wert "SUCCEEDED"zurück.
Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Abschnitt Endpunktleitfaden für Exportaufträge
Nächste Schritte
Sobald der Export erfolgreich abgeschlossen wurde, stehen Ihre Daten im Data Lake in Experience Platform. Anschließend können Sie die Data Access API , um auf die Daten mithilfe der batchId
mit dem Export verknüpft ist. Je nach Größe der Segmentdefinition können die Daten in Blöcken vorliegen und der Batch kann aus mehreren Dateien bestehen.
Eine schrittweise Anleitung zur Verwendung der Data Access API zum Zugreifen auf und Herunterladen von Batch-Dateien, folgen Sie dem Tutorial zum Datenzugriff.
Sie können auch auf erfolgreich exportierte Segmentdefinitionsdaten zugreifen mit Adobe Experience Platform Query Service. Verwenden der Benutzeroberfläche oder der RESTful-API, Query Service ermöglicht Ihnen das Schreiben, Validieren und Ausführen von Abfragen zu Daten im Data Lake.
Weiterführende Informationen zur Abfrage von Zielgruppendaten finden Sie in der Dokumentation unter Query Service.