Auswerten von Ereignissen mit Streaming-Segmentierung nahezu in Echtzeit

Mit der Streaming-Segmentierung in Adobe Experience Platform können Kundinnen und Kunden die Segmentierung nahezu in Echtzeit durchführen und sich dabei auf die Relevanz der Daten konzentrieren. Im Rahmen der Streaming-Segmentierung erfolgt jetzt eine Segmentqualifizierung, wenn Streaming-Daten in Platform aufgenommen werden. So wird die Notwendigkeit verringert, Segmentierungsvorgänge zu planen und auszuführen. Mit dieser Funktion können die meisten Segmentregeln jetzt ausgewertet werden, während Daten an Platform übermittelt werden. Das bedeutet, dass die Segmentzugehörigkeit auch ohne Ausführung geplanter Segmentierungsvorgänge auf dem neuesten Stand gehalten wird.

Erste Schritte

Dieses Entwicklerhandbuch setzt Grundkenntnisse der verschiedenen Adobe Experience Platform-Services voraus, die mit Streaming-Segmentierungen zusammenhängen. Bevor Sie mit diesem Tutorial beginnen, lesen Sie bitte die Dokumentation für die folgenden Services:

Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie benötigen, um die Platform-APIs erfolgreich aufrufen zu können.

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:

Alle Ressourcen in Experience Platform sind auf bestimmte virtuelle Sandboxes beschränkt. Bei allen Anfragen an Platform-APIs ist eine Kopfzeile erforderlich, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt werden soll:

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

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 query-types

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

Eine Segmentdefinition wird für die Streaming-Segmentierung in den folgenden Szenarien nicht aktiviert:

Bitte beachten Sie bei der Streaming-Segmentierung die folgenden Richtlinien:

Wenn eine Segmentdefinition geändert wird, sodass sie die Kriterien für die Streaming-Segmentierung nicht mehr erfüllt, wird die Segmentdefinition automatisch von „Streaming“ zu „Batch“ geändert.

Darüber hinaus erfolgt die Aufhebung der Segmentqualifikation, ähnlich wie die Segmentqualifikation selbst, in Echtzeit. Wenn ein Profil daher nicht mehr für eine Segmentdefinition qualifiziert ist, wird es sofort nicht qualifiziert. Wenn in der Segmentdefinition beispielsweise nach „Alle Benutzenden, die in den letzten drei Stunden rote Schuhe gekauft haben“ gefragt wird, wird die Qualifikation nach drei Stunden für alle Profile, die sich ursprünglich für die Segmentdefinition qualifiziert haben, aufgehoben.

Abrufen aller für Streaming-Segmentierung aktivierten Segmentdefinitionen

Sie können eine Liste aller Segmentdefinitionen abrufen, die für die Streaming-Segmentierung innerhalb Ihres Unternehmens aktiviert sind, indem Sie eine GET-Anfrage an den Endpunkt /segment/definitions senden.

API-Format

Um Streaming-fähige Segmentdefinitionen 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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Antwort

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

{
    "segments": [
        {
            "id": "15063cb-2da8-4851-a2e2-bf59ddd2f004",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "imsOrgId": "{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"
            },
            "imsOrgId": "{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": {}
}

Erstellen einer Streaming-fähigen Segmentdefinition

Eine Segmentdefinition wird automatisch für Streaming aktiviert, wenn sie 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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "schema": {
        "name": "_xdm.context.profile"
    },
    "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
        }
    }
}'

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"
    },
    "imsOrgId": "{ORG_ID}",
    "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 enable-scheduled-segmentation

Nachdem die Streaming-Auswertung aktiviert wurde, muss eine Grundlinie erstellt werden (danach ist die Segmentdefinition immer aktuell). Geplante Auswertungen (auch als geplante Segmentierung bezeichnet) müssen zuerst aktiviert werden, damit das System automatisch Grundlinien erstellt. Bei geplanter Segmentierung kann Ihr Unternehmen einen Zeitplan einhalten, um Exportaufträge automatisch auszuführen und Segmentdefinitionen zu bewerten.

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
        "name": "{SCHEDULE_NAME}",
        "type": "batch_segmentation",
        "properties": {
            "segments": ["*"]
        },
        "schedule": "0 0 1 * * ?",
        "state": "inactive"
        }'

Antwort

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

{
    "id": "cd585edf-962d-420d-94ad-3be03e619ac2",
    "imsOrgId": "{ORG_ID}",
    "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: {ORG_ID}' \
  -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 Segmentdefinitionen für Streaming-Segmentierung aktiviert und die geplante Segmentierung aktiviert haben, um eine Grundlinie zu entwickeln und wiederkehrende Auswertungen durchzuführen, können Sie mit der Erstellung von Streaming-fähigen Segmentdefinitionen für Ihre Organisation beginnen.

Weitere Informationen zum Ausführen ähnlicher Aktionen und zum Arbeiten mit Segmentdefinitionen mithilfe der Adobe Experience Platform-Benutzeroberfläche finden Sie im Segment Builder-Benutzerhandbuch.

Anhang

Im folgenden Abschnitt finden Sie häufig gestellte Fragen zur Streaming-Segmentierung:

Tritt die „Nicht-Qualifizierung“ der Streaming-Segmentierung auch in Echtzeit auf?

In den meisten Fällen geschieht die Aufhebung der Qualifizierung von Streaming-Segmentierungen in Echtzeit. Streaming-Segmentdefinitionen, die Segmente von Segmenten verwenden, machen die Qualifizierung in Echtzeit jedoch nicht ungültig, anstatt die Qualifizierung nach 24 Stunden aufzuheben.

Mit welchen Daten arbeitet die Streaming-Segmentierung?

Die Streaming-Segmentierung funktioniert bei allen Daten, die über eine Streaming-Quelle aufgenommen wurden. Segmente, die mit einer Batch-basierten Quelle erfasst werden, werden jede Nacht ausgewertet, selbst wenn sie für die Streaming-Segmentierung geeignet sind. In das System gestreamte Ereignisse mit einem Zeitstempel, der älter als 24 Stunden ist, werden im nachfolgenden Batch-Vorgang verarbeitet.

Wie werden Segmentdefinitionen als Batch- oder Streaming-Segmentierung definiert?

Eine Segmentdefinition wird entweder als Batch- oder Streaming-Segmentierung basierend auf einer Kombination aus Abfragetyp und Ereignisverlaufsdauer definiert. Eine Liste der Segmentdefinitionen, die als Streaming-Segment ausgewertet werden, finden Sie im Abschnitt Streaming-Segmentierungs-Abfragetypen.

Bitte beachten Sie, dass ein Segment, das sowohl einen inSegment-Ausdruck als auch eine direkte Einzelereigniskette enthält, nicht für die Streaming-Segmentierung in Frage kommt. Wenn Sie möchten, dass diese Segmentdefinition für Streaming-Segmentierung qualifiziert ist, sollten Sie die direkte Single-Event-Kette zur eigenen Segmentdefinition machen.

Warum steigt die Anzahl der "gesamten qualifizierten"Segmentdefinitionen weiter, während die Zahl unter "Letzte X Tage"im Abschnitt mit den Segmentdefinitionsdetails bei null bleibt?

Die Anzahl der insgesamt qualifizierten Segmentdefinitionen wird aus dem täglichen Segmentierungsauftrag gezogen, der Zielgruppen enthält, die sich sowohl für Batch- als auch für Streaming-Segmentdefinitionen qualifizieren. Dieser Wert wird sowohl für Batch- als auch für Streaming-Segmentdefinitionen angezeigt.

Die Zahl unter „Letzte X Tage“ umfasst nur Zielgruppen, die für Streaming-Segmentierung qualifiziert sind. Sie erhöht sich nur dann, wenn Sie Daten in das System gestreamt haben, und zählt dann für diese Streaming-Definition. Dieser Wert ist nur, der für Streaming-Segmentdefinitionen angezeigt wird. Daher wird dieser Wert may für Batch-Segmentdefinitionen als 0 angezeigt.

Wenn Sie also feststellen, dass die Zahl unter "Letzte X Tage"null ist und das Liniendiagramm ebenfalls null meldet, haben Sie nicht alle Profile in das System gestreamt, die für diese Segmentdefinition qualifiziert wären.

Wie lange dauert es, bis eine Segmentdefinition verfügbar ist?

Es dauert bis zu einer Stunde, bis eine Segmentdefinition verfügbar ist.

Gibt es Einschränkungen beim Streamen von Daten?

Damit Streaming-Daten in der Streaming-Segmentierung verwendet werden können, muss zwischen den eingetretenen Ereignissen 1} ein Abstand vorhanden sein. Wenn zu viele Ereignisse innerhalb derselben Sekunde gestreamt werden, behandelt Platform diese Ereignisse als Bot-generierte Daten und sie werden verworfen. Es hat sich bewährt, mindestens fünf Sekunden zwischen den Ereignisdaten zu verwenden, um sicherzustellen, dass die Daten ordnungsgemäß verwendet werden.