Bewerten Sie Ereignis in Echtzeit mit der Streaming-Segmentierung.

Die Streaming-Segmentierung für Adobe Experience Platform ermöglicht es Kunden, die Segmentierung in Echtzeit durchzuführen und sich dabei auf den Datenreichtum zu konzentrieren. Mit der Streaming-Segmentierung erfolgt die Segmentqualifizierung jetzt, wenn Daten in Streaming übertragen werden, Platformwas die Planung und Ausführung von Segmentierungsaufträgen erleichtert. With this capability, most segment rules can now be evaluated as the data is passed into Platform, meaning segment membership will be kept up-to-date without running scheduled segmentation jobs.

Erste Schritte

This developer guide requires a working understanding of the various Adobe Experience Platform services involved with streaming segmentation. Bevor Sie mit diesem Tutorial beginnen, lesen Sie bitte die Dokumentation für die folgenden Dienste:

• Real-time Customer Profile: Bietet ein einheitliches Verbraucherdatenquellen-Profil in Echtzeit, basierend auf aggregierten Daten aus mehreren Quellen.
• Segmentation: Ermöglicht das Erstellen von Segmenten und Audiencen aus Ihren Real-time Customer Profile Daten.
• Experience Data Model (XDM): Das standardisierte Framework, mit dem Platform Kundenerlebnisdaten organisiert.

The following sections provide additional information that you will need to know in order to successfully make calls to Platform APIs.

Lesen von Beispiel-API-Aufrufen

In diesem Entwicklerhandbuch wird anhand von Beispielen für API-Aufrufe die korrekte Formatierung von Anfragen aufgezeigt. Dazu gehören Pfade, erforderliche Kopfzeilen und ordnungsgemäß formatierte Anfrage-Payloads. Außerdem wird ein Beispiel für eine von der API im JSON-Format zurückgegebene Antwort bereitgestellt. Informationen zu den Konventionen, die in der Dokumentation für Beispiel-API-Aufrufe verwendet werden, finden Sie im Abschnitt zum Lesen von Beispiel-API-Aufrufen im Handbuch zur Fehlerbehebung für Experience Platform

Sammeln von Werten für erforderliche Kopfzeilen

Um Platform-APIs aufzurufen, müssen Sie zunächst das Authentifizierungs-Tutorial abschließen. 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: {IMS_ORG}

All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

• x-sandbox-name: {SANDBOX_NAME}

Bei allen Anfragen mit einer Payload (POST, PUT, PATCH) ist eine zusätzliche Kopfzeile erforderlich:

• Content-Type: application/json

Zum Ausführen spezifischer Anfragen können zusätzliche Kopfzeilen erforderlich sein. Die richtigen Kopfzeilen werden in jedem der Beispiele in diesem Dokument angezeigt. Achten Sie besonders auf die Beispielanfragen, um dafür zu sorgen, dass alle erforderlichen Kopfzeilen enthalten sind.

Für Streaming-Segmentierung aktivierte Abfragetypen

Damit ein Segment mithilfe der Streaming-Segmentierung bewertet werden kann, muss die Abfrage den folgenden Richtlinien entsprechen.

Abfragetyp	Details
Eingehender Treffer	Eine Segmentdefinition, die auf ein einzelnes eingehendes Ereignis ohne Zeitbeschränkung verweist.
Eingehender Treffer innerhalb eines relativen Zeitfensters	Eine Segmentdefinition, die auf ein einzelnes eingehendes Ereignis verweist.
Nur Profil	Eine Segmentdefinition, die nur auf ein Profil-Attribut verweist.
Eingehender Treffer, der sich auf ein Profil bezieht	Eine Segmentdefinition, die sich auf ein einzelnes eingehendes Ereignis ohne Zeitbeschränkung und ein oder mehrere Profil-Attribute bezieht.
Eingehender Treffer, der sich auf ein Profil innerhalb eines relativen Zeitfensters bezieht	Eine Segmentdefinition, die auf ein einzelnes eingehendes Ereignis und ein oder mehrere Profil-Attribute verweist.
Mehrere Ereignis, die auf ein Profil verweisen	Eine Segmentdefinition, die sich innerhalb der letzten 24 Stunden auf mehrere Ereignis bezieht und (optional) ein oder mehrere Profil-Attribute besitzt.

In den folgenden Szenarien wird eine Segmentdefinition für die Streaming-Segmentierung nicht aktiviert:

• Die Segmentdefinition umfasst Adobe Audience Manager-Segmente oder -Eigenschaften (AAM).
• Die Segmentdefinition umfasst mehrere Entitäten (Abfragen mit mehreren Entitäten).

Darüber hinaus gelten einige Richtlinien bei der Streaming-Segmentierung:

Abfragetyp	Leitlinie
Abfrage mit einem Ereignis	Das Lookback-Fenster unterliegt keinen Einschränkungen.
Abfrage mit Ereignis-Verlauf	Das Lookback-Fenster ist auf einen Tag beschränkt. Zwischen den Ereignissen muss eine strikte Bedingung für die zeitliche Reihenfolge bestehen. Abfragen mit mindestens einem negierten Ereignis werden unterstützt. Das gesamte Ereignis kann jedoch keine Negation sein.

Rufen Sie alle Segmente ab, die für die Streaming-Segmentierung aktiviert sind.

Sie können eine Liste aller Segmente abrufen, die für die Streaming-Segmentierung in Ihrer IMS-Organisation aktiviert sind, indem Sie eine GET an den /segment/definitions Endpunkt anfordern.

API-Format

Um Streaming-fähige Segmente abzurufen, müssen Sie den Abfrageparameter evaluationInfo.continuous.enabled=true in den Anfragepfad einbeziehen.

GET /segment/definitions?evaluationInfo.continuous.enabled=true

Anfrage

curl -X GET \
  'https://platform.adobe.io/data/core/ups/segment/definitions?evaluationInfo.continuous.enabled=true' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Antwort

Eine erfolgreiche Antwort gibt eine Gruppe von Segmenten in Ihrer IMS-Organisation zurück, die für Streaming-Segmentierung aktiviert sind.

{
    "segments": [
        {
            "id": "15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{IMS_ORG_ID}",
            "sandbox": {
                "sandboxId": "",
                "sandboxName": "",
                "type": "production",
                "default": true
            },
            "name": " People who are NOT on their homepage ",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = false"
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": false
                },
                "continuous": {
                    "enabled": true
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "creationTime": 1572029711000,
            "updateEpoch": 1572029712000,
            "updateTime": 1572029712000
        },
        {
            "id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{IMS_ORG_ID}",
            "sandbox": {
                "sandboxId": "",
                "sandboxName": "",
                "type": "production",
                "default": true
            },
            "name": "Homepage_continuous",
            "description": "People who are on their homepage - continuous",
            "expression": {
                "type": "PQL",
                "format": "pql/text",
                "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
            },
            "evaluationInfo": {
                "batch": {
                    "enabled": true
                },
                "continuous": {
                    "enabled": true
                },
                "synchronous": {
                    "enabled": false
                }
            },
            "creationTime": 1572021085000,
            "updateEpoch": 1572021086000,
            "updateTime": 1572021086000
        }
    ],
    "page": {
        "totalCount": 2,
        "totalPages": 1,
        "sortField": "creationTime",
        "sort": "desc",
        "pageSize": 2,
        "limit": 100
    },
    "link": {}
}

Streaming-fähiges Segment erstellen

Ein Segment wird automatisch für das Streaming aktiviert, wenn es mit einem der oben aufgeführtenStreaming-Segmentierungstypen übereinstimmt.

API-Format

POST /segment/definitions

Anfrage

curl -X POST \
  https://platform.adobe.io/data/core/ups/segment/definitions \
  -H 'Authorization: Bearer {ACCESS_TOKEN}'  \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 30,
    "name": "Homepage_continuous",
    "description": "People who are on their homepage - continuous",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
    }
}'

Antwort

Eine erfolgreiche Antwort gibt die Details der Definition des neu erstellten Streaming-fähigen Segments zurück.

{
    "id": "f15063cb-2da8-4851-a2e2-bf59ddd2f004",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 30,
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "{SANDBOX_ID}",
        "sandboxName": "{SANDBOX_NAME}",
        "type": "production",
        "default": true
    },
    "name": "Homepage_continuous",
    "description": "People who are on their homepage - continuous",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "select var1 from xEvent where var1._experience.analytics.endUser.firstWeb.webPageDetails.isHomePage = true"
    },
    "evaluationInfo": {
        "batch": {
            "enabled": false
        },
        "continuous": {
            "enabled": true,
                   },
        "synchronous": {
            "enabled": false
        }
    },
    "creationTime": 1572021085000,
    "updateEpoch": 1572021086000,
    "updateTime": 1572021086000
}

Geplante Auswertung aktivieren

Nach dem Aktivieren der Streaming-Auswertung muss eine Grundlinie eingerichtet werden (danach ist das Segment immer auf dem neuesten Stand). Zuerst muss eine geplante Evaluierung (auch als geplante Segmentierung bezeichnet) aktiviert werden, damit das System automatisch Baselining durchführen kann. Bei der geplanten Segmentierung kann Ihr IMS-Org an einen wiederkehrenden Zeitplan festhalten, um Exportaufträge automatisch zur Segmentauswertung auszuführen.

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.

API-Format

POST /config/schedules

Anfrage

Mit der folgenden Anfrage wird basierend auf den in der Payload bereitgestellten Angaben ein neuer Zeitplan erstellt.

curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "{SCHEDULE_NAME}",
        "type": "batch_segmentation",
        "properties": {
            "segments": ["*"]
        },
        "schedule": "0 0 1 * * ?",
        "state": "inactive"
        }'

Eigenschaft	Beschreibung
name	(Erforderlich) Der Name des Zeitplans. Muss eine Zeichenfolge sein.
type	(Erforderlich) Der Auftragstyp im Zeichenfolgenformat. Die unterstützten Typen sind batch_segmentation und export.
properties	(Erforderlich) Ein Objekt, das zusätzliche Eigenschaften im Zusammenhang mit dem Zeitplan enthält.
properties.segments	(Erforderlich, wenn type gleich batch_segmentation) Die Verwendung von ["*"] stellt sicher, dass alle Segmente einbezogen werden.
schedule	(Erforderlich) Eine Zeichenfolge, die den Auftragszeitplan enthält. Aufträge können nur einmal pro Tag ausgeführt werden, d. h., Sie können einen Auftrag nicht so planen, dass er während eines Zeitraums von 24 Stunden mehr als einmal ausgeführt wird. Das folgende Beispiel (0 0 1 * * ?) bedeutet, dass der Auftrag jeden Tag um 1:00:00 Uhr (UTC) ausgelöst wird. Weiterführende Informationen finden Sie in der Dokumentation zum Cron-Ausdrucksformat.
state	(Optional) Zeichenfolge, die den Zeitplanstatus enthält. Verfügbare Werte: active und inactive. Der Standardwert ist inactive. Eine IMS-Organisation kann nur einen Zeitplan erstellen. Schritte zum Aktualisieren des Zeitplans finden Sie weiter unten in dieser Anleitung.

Antwort

Eine erfolgreiche Antwort gibt die Details des neu erstellten Zeitplans zurück.

{
    "id": "cd585edf-962d-420d-94ad-3be03e619ac2",
    "imsOrgId": "{IMS_ORG}",
    "sandbox": {
        "sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "name": "{SCHEDULE_NAME}",
    "state": "inactive",
    "type": "batch_segmentation",
    "schedule": "0 0 1 * * ?",
    "properties": {
        "segments": [
            "*"
        ]
    },
    "createEpoch": 1568267948,
    "updateEpoch": 1568267948
}

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.

API-Format

POST /config/schedules/{SCHEDULE_ID}

Anfrage

Die folgende Anfrage nutzt die JSON-Patch-Formatierung, um den state des Zeitplans in active zu ändern.

curl -X POST \
  https://platform.adobe.io/data/core/ups/config/schedules/cd585edf-962d-420d-94ad-3be03e619ac2 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
        {
          "op": "add",
          "path": "/state",
          "value": "active"
        }
      ]'

Antwort

Bei erfolgreicher Aktualisierung werden ein leerer Antworttext und der HTTP-Status 204 (Kein Inhalt) zurückgegeben.

Derselbe Vorgang kann zum Deaktivieren eines Zeitplans verwendet werden, indem der „Wert“ in der vorherigen Anfrage durch „inactive“ ersetzt wird.

Nächste Schritte

Nachdem Sie sowohl neue als auch vorhandene Segmente für Streaming-Segmentierung und die geplante Segmentierung aktiviert haben, um eine Grundlinie zu entwickeln und wiederkehrende Auswertungen auszuführen, können Sie mit der Erstellung von Segmenten für Ihre Organisation beginnen.

Weiterführende Informationen zum Durchführen ähnlicher Aktionen und zum Verwenden von Segmenten unter Einsatz der Benutzeroberfläche von Adobe Experience Platform finden Sie im Segment Builder-Benutzerhandbuch.