Show Menu
THEMEN×

Bewerten Sie Ereignis in Echtzeit mit der Streaming-Segmentierung.

Im folgenden Dokument wird erläutert, wie die Streaming-Segmentierung mithilfe der API verwendet wird. For information on using streaming segmentation using the UI, please read the streaming segmentation UI guide .
Streaming segmentation on Adobe Experience Platform allows customers to do segmentation in near real-time while focusing on data richness. Mit der Streaming-Segmentierung erfolgt die Segmentqualifizierung jetzt, wenn Daten eingehen, Platformwas die Planung und Ausführung von Segmentierungsaufträgen verringert. 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 : Provides a unified consumer profile in real-time, based on aggregated data from multiple sources.
  • 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 Kundenerlebnisdaten Platform organisiert werden.
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

In order to make calls to Platform APIs, you must first complete the authentication tutorial . Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:
  • 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}
For more information on sandboxes in Platform, see the sandbox overview documentation .
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

Sie müssen die geplante Segmentierung für das Unternehmen aktivieren, damit die Streaming-Segmentierung funktioniert. Informationen zur Aktivierung der geplanten Segmentierung finden Sie im Abschnitt zur Aktivierung der geplanten Segmentierung
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 innerhalb der letzten sieben Tage verweist.
Profile only
Eine Segmentdefinition, die nur auf ein Profil-Attribut verweist.
Incoming hit that refers to a profile
Any segment definition that refers to a single incoming event, with no time restriction, and one or more profile attributes.
Eingehender Treffer, der sich auf ein Profil innerhalb eines relativen Zeitfensters bezieht
Eine Segmentdefinition, die sich innerhalb der letzten sieben Tage auf ein einzelnes eingehendes Ereignis und ein oder mehrere Profil-Attribute bezieht.
Mehrere Ereignis, die auf ein Profil verweisen
Jede Segmentdefinition, die sich innerhalb der letzten 24 Stunden auf mehrere Ereignis bezieht und (optional) ein oder mehrere Profil-Attribute besitzt.
Im folgenden Abschnitt werden Segmentdefinitionsbeispiele Liste, die für die Streaming-Segmentierung nicht aktiviert werden.
Abfragetyp
Details
Eingehender Treffer innerhalb eines relativen Zeitfensters
Wenn sich die Segmentdefinition auf ein eingehendes Ereignis bezieht, das nicht innerhalb der letzten sieben Tage liegt. Zum Beispiel innerhalb der letzten zwei Wochen .
Eingehender Treffer, der sich auf ein Profil in einem relativen Fenster bezieht
The following options will not support streaming segmentation:
  • An incoming event not within the last seven-day period .
  • A segment definition that includes Adobe Audience Manager (AAM) segments or traits.
Multiple events that refer to a profile
Die folgenden Optionen unterstützen keine Streaming-Segmentierung:
  • Ein Ereignis, das nicht innerhalb der letzten 24 Stunden auftritt.
  • A segment definition that includes Adobe Audience Manager (AAM) segments or traits.
Abfragen mit mehreren Entitäten
Abfragen mit mehreren Entitäten werden durch Streaming-Segmentierung insgesamt nicht unterstützt.
Additionally, some guidelines apply when doing streaming segmentation:
Abfragetyp
Leitlinie
Abfrage mit einem Ereignis
Das Rückblickfenster ist auf sieben Tage begrenzt.
Abfrage mit Ereignis-Verlauf
  • Das Lookback-Fenster ist auf einen Tag beschränkt.
  • Zwischen den Ereignissen muss eine strikte Zeitbestellbedingung bestehen.
  • Nur einfache Zeitreihenfolgen (vor und nach) zwischen den Ereignissen sind zulässig.
  • Die einzelnen Ereignis können nicht negiert werden. Die gesamte Abfrage kann jedoch negiert werden.

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ührten Streaming-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"
    }
}'

Hierbei handelt es sich um eine Standardanforderung für das Erstellen eines Segments. For more information about creating a segment definition, please read the tutorial on creating a segment .
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.
Scheduled evaluation can be enabled for sandboxes with a maximum of five (5) merge policies for XDM Individual Profile. If your organization has more than five merge policies for XDM Individual Profile within a single sandbox environment, you will not be able to use scheduled evaluation.

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 .