Validieren der Streaming-Erfasssung

Mit der Streaming-Aufnahme können Sie Ihre Daten mithilfe von Streaming-Endpunkten in Echtzeit in Adobe Experience Platform hochladen. Streaming-Aufnahme-APIs unterstützen zwei Validierungsmodi: synchron und asynchron.

Erste Schritte

Dieses Handbuch setzt ein Verständnis der folgenden Komponenten von Adobe Experience Platform voraus:

Lesen von Beispiel-API-Aufrufen

In diesem Tutorial 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 Experience 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, einschließlich der Ressourcen, die zum Schema Registry gehören, sind in bestimmten virtuellen Sandboxes isoliert. Bei allen Anfragen an Experience 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:

Validierungsabdeckung

Streaming Validation Service umfasst die Validierung in den folgenden Bereichen:

Synchrone Überprüfung

Die synchrone Validierung ist eine Validierungsmethode, die sofortiges Feedback darüber liefert, warum eine Aufnahme fehlgeschlagen ist. Bei einem Fehler werden die Datensätze, die die Validierung nicht bestehen, jedoch gelöscht und daran gehindert, nachgelagert gesendet zu werden. Daher sollte die synchrone Validierung nur während des Entwicklungsprozesses verwendet werden. Bei der synchronen Validierung werden die Aufrufer sowohl über das Ergebnis der XDM-Validierung als auch, falls sie fehlschlägt, über den Grund für den Fehler informiert.

Standardmäßig ist die synchrone Validierung nicht aktiviert. Um sie zu aktivieren, müssen Sie bei API-Aufrufen den optionalen Abfrageparameter syncValidation=true übergeben. Darüber hinaus ist die synchrone Validierung derzeit nur verfügbar, wenn sich Ihr Stream-Endpunkt im VA7-Rechenzentrum befindet.

Wenn eine Nachricht bei der synchronen Validierung fehlschlägt, wird die Nachricht nicht in die Ausgabeschlange geschrieben, was Benutzern sofortiges Feedback liefert.

API-Format

POST /collection/{CONNECTION_ID}?syncValidation=true

Anfrage

Senden Sie die folgende Anfrage, um Daten mit synchroner Validierung in Ihr Dateneingangsmodul aufzunehmen:

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
  -H "Content-Type: application/json" \
  -d '{JSON_PAYLOAD}'

Antwort

Bei aktivierter synchroner Validierung enthält eine erfolgreiche Antwort alle aufgetretenen Validierungsfehler in der Payload:

{
    "type": "http://ns.adobe.com/adobecloud/problem/data-collection-service/inlet",
    "status": 400,
    "title": "Invalid XDM Message Format",
    "report": {
        "message": "inletId: [6aca7aa2d87ebd6b2780ca5724d94324a14475f140a2b69373dd5c714430dfd4] imsOrgId: [7BF122A65C5B3FE40A494026@AdobeOrg] Message is invalid",
        "cause": {
            "_streamingValidation": [
                {
                    "schemaLocation": "#",
                    "pointerToViolation": "#",
                    "causingExceptions": [
                        {
                            "schemaLocation": "#",
                            "pointerToViolation": "#",
                            "causingExceptions": [],
                            "keyword": "additionalProperties",
                            "message": "extraneous key [workEmail] is not permitted"
                        },
                        {
                            "schemaLocation": "#",
                            "pointerToViolation": "#",
                            "causingExceptions": [],
                            "keyword": "additionalProperties",
                            "message": "extraneous key [person] is not permitted"
                        },
                        {
                            "schemaLocation": "#/properties/_id",
                            "pointerToViolation": "#/_id",
                            "causingExceptions": [],
                            "keyword": "type",
                            "message": "expected type: String, found: Long"
                        }
                    ],
                    "message": "3 schema violations found"
                }
            ]
        }
    }
}

Die obige Antwort listet auf, wie viele Schemaverletzungen gefunden wurden und welche Verstöße begangen wurden. In dieser Antwort wird beispielsweise angegeben, dass die Schlüssel workEmail und person nicht im Schema definiert wurden und daher nicht zulässig sind. Außerdem wird der Wert für _id als falsch gekennzeichnet, da das Schema eine string erwartet, stattdessen jedoch eine long eingefügt wurde. Beachten Sie, dass der Validierungs-Service die Verarbeitung dieser Nachricht , wenn fünf Fehler sind. Andere Nachrichten werden jedoch weiterhin geparst.

Asynchrone Validierung

Asynchrone Validierung ist eine Validierungsmethode, die kein sofortiges Feedback liefert. Stattdessen werden die Daten an einen fehlgeschlagenen Batch gesendet, Data Lake Datenverlust zu vermeiden. Diese fehlgeschlagenen Daten können später zur weiteren Analyse und Wiederholung abgerufen werden. Diese Methode sollte in der Produktion verwendet werden. Sofern nicht anders angefordert, erfolgt die Streaming-Aufnahme im asynchronen Validierungsmodus.

API-Format

POST /collection/{CONNECTION_ID}

Anfrage

Senden Sie die folgende Anfrage, um Daten mit asynchroner Validierung in Ihr Dateneingangsmodul aufzunehmen:

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID} \
  -H "Content-Type: application/json" \
  -d '{JSON_PAYLOAD}'

Antwort

Bei aktivierter asynchroner Validierung gibt eine erfolgreiche Antwort Folgendes zurück:

{
    "inletId": "f6ca9706d61de3b78be69e2673ad68ab9fb2cece0c1e1afc071718a0033e6877",
    "xactionId": "1555445493896:8600:8",
    "receivedTimeMs": 1555445493932,
    "syncValidation": {
        "skipped": true
    }
}

Beachten Sie, dass in der Antwort angegeben wird, dass die synchrone Validierung übersprungen wurde, da sie nicht explizit angefordert wurde.

Anhang

Dieser Abschnitt enthält Informationen darüber, was die verschiedenen Status-Codes für Antworten bei der Datenaufnahme bedeuten.

Status-Codes