Segmentdefinitionsergebnisse auswerten und aufrufen

Dieses Dokument bietet ein Tutorial zum Auswerten von Segmentdefinitionen und zum Zugriff auf diese Ergebnisse mithilfe von Segmentation API.

Erste Schritte

Dieses Tutorial setzt ein Verständnis der verschiedenen Adobe Experience Platform-Dienste voraus, die am Erstellen von Zielgruppen beteiligt sind. 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 außerdem das Authentifizierungs-Tutorial abgeschlossen haben, damit Sie erfolgreich Aufrufe an Platform -APIs durchführen 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. Für Anfragen an Platform -APIs ist eine Kopfzeile erforderlich, 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:

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.

Mit der Funktion Geplante Auswertung (auch als "geplante Segmentierung"bezeichnet) können Sie einen wiederkehrenden Zeitplan für die Ausführung eines Exportauftrags zu einem bestimmten Zeitpunkt erstellen, während bei der On-Demand-Auswertung ein Segmentauftrag erstellt werden muss, um die Zielgruppe sofort zu erstellen. Die Schritte für die einzelnen Schritte sind unten beschrieben.

Wenn Sie das Tutorial Erstellen einer Segmentdefinition mithilfe der Segmentation API noch nicht abgeschlossen haben oder eine Segmentdefinition mithilfe von Segment Builder erstellt haben, führen Sie dies vor dem Fortfahren mit diesem Tutorial durch.

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 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 Endpunktleitfaden für Zeitpläne .

Zeitplanaktualisierung

Der Zeitplan-Timing kann aktualisiert werden, indem eine PATCH-Anfrage an den /config/schedules -Endpunkt gesendet wird und die Kennung des Zeitplans in den Pfad aufgenommen wird.

Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im 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 überlappende Attribute über Ihre Profilfragmente hinweg zusammenführt. 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 den /segment/jobs -Endpunkt in der Real-Time Customer Profile -API richten.

Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Endpunktleitfaden für Segmentaufträge .

Status des Segmentauftrags nachschlagen

Sie können die id für einen bestimmten Segmentauftrag verwenden, um eine Suchanfrage (GET) auszuführen, um den aktuellen Status des Auftrags anzuzeigen.

Weitere Informationen zur Verwendung dieses Endpunkts finden Sie im Endpunktleitfaden für Segmentaufträge .

Interpretieren von Segmentauftragsergebnissen

Wenn Segmentaufträge erfolgreich ausgeführt werden, wird die segmentMembership-Zuordnung für jedes Profil aktualisiert, das in der Segmentdefinition enthalten ist. segmentMembership speichert auch alle vorab ausgewerteten Zielgruppen, die in Platform erfasst werden, sodass sie mit anderen Lösungen wie Adobe Audience Manager integriert werden können.

Das folgende Beispiel zeigt, wie das Attribut segmentMembership 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"
      }
    }
  }
}

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 tun. Die vollständigen Schritte zum Zugriff auf einzelne Profile finden Sie im Tutorial Zugriff auf Echtzeit-Kundenprofil-Daten mithilfe der Profil-API .

Segment exportieren export

Nachdem ein Segmentierungsauftrag erfolgreich abgeschlossen wurde (der Wert des Attributs status lautet "SUCCEEDED"(GELUNGEN)), können Sie Ihre Zielgruppe in einen Datensatz exportieren, in dem sie aufgerufen und bearbeitet werden kann.

Die folgenden Schritte sind erforderlich, um Ihre Audience zu exportieren:

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 unten stehenden API-Beispielanfrage). Um eine Segmentdefinition zu exportieren, muss der Datensatz auf dem XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union) basieren. 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:

Wenn Sie bereits über einen kompatiblen Datensatz verfügen und dessen Kennung kennen, können Sie direkt mit dem Schritt zum Generieren von Zielgruppenprofilen fortfahren.

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"
    }
}'

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 Vereinigungspersistenz speichert, können Sie einen Exportauftrag erstellen, um die Zielgruppenmitglieder im Datensatz zu behalten, indem Sie eine POST-Anfrage an den /export/jobs -Endpunkt in der Real-Time Customer Profile -API richten und die Datensatz-ID sowie die Segmentdefinitionsinformationen für die Segmentdefinitionen angeben, die Sie exportieren möchten.

Ausführlichere Informationen zur Verwendung dieses Endpunkts finden Sie im Endpunkthandbuch zu Exportvorgängen .

Fortschritt des Exports überwachen

Bei der Verarbeitung eines Exportauftrags können Sie dessen Status überwachen, indem Sie eine GET-Anfrage an den /export/jobs -Endpunkt senden und die id des Exportauftrags in den Pfad einschließen. Der Exportauftrag ist abgeschlossen, sobald das Feld status den Wert "SUCCEEDED"zurückgibt.

Ausführlichere Informationen zur Verwendung dieses Endpunkts finden Sie im Endpunkthandbuch zu Exportvorgängen .

Nächste Schritte

Nach erfolgreichem Abschluss des Exports sind Ihre Daten im Bereich Data Lake in Experience Platform verfügbar. Anschließend können Sie mit dem Data Access API auf die Daten zugreifen, indem Sie den mit dem Export verknüpften batchId verwenden. 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 zum Verwenden der Data Access-API für den Zugriff auf und den Download von Batch-Dateien finden Sie im Tutorial zum Datenzugriff .

Sie können auch mit Adobe Experience Platform Query Service auf erfolgreich exportierte Segmentdefinitionsdaten zugreifen. Mithilfe der Benutzeroberfläche oder der RESTful-API können Sie mit Query Service Abfragen zu Daten innerhalb des Data Lake schreiben, validieren und ausführen.

Weitere Informationen zum Abfragen von Zielgruppendaten finden Sie in der Dokumentation zu Query Service.