Validieren der Streaming-Erfasssung

Mit der Streaming-Erfassung 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 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: {ORG_ID}

Alle Ressourcen in Experience Platform, einschließlich der Ressourcen, die zu Schema Registry gehören, werden in bestimmte virtuelle Sandboxes isoliert. Bei allen Anfragen an Platform-APIs ist eine Kopfzeile erforderlich, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt werden soll:

  • x-sandbox-name: {SANDBOX_NAME}
NOTE
Weitere Informationen zu Sandboxes in Platform finden Sie in der Sandbox-Übersichtsdokumentation.

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

  • Content-Type: application/json

Validierungsabdeckung

Streaming Validation Service umfasst die Validierung in den folgenden Bereichen:

  • Bereich
  • Präsenz
  • Enum
  • Muster
  • Typ
  • Format

Synchrone Überprüfung

Die synchrone Validierung ist eine Methode zur Validierung, die sofort Rückmeldungen darüber liefert, warum eine Aufnahme fehlgeschlagen ist. Bei einem Fehler werden jedoch die Datensätze, die bei der Validierung fehlschlagen, verworfen und können nicht nachgelagert gesendet 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 über den Grund für das Fehlschlagen informiert, wenn dies fehlgeschlagen ist.

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

NOTE
Der Abfrageparameter syncValidation ist nur für den einzelnen Nachrichtenendpunkt verfügbar und kann nicht für den Batch-Endpunkt verwendet werden.

Wenn eine Nachricht während der synchronen Validierung fehlschlägt, wird sie nicht in die Ausgabeschlange geschrieben, die Benutzern sofortiges Feedback gibt.

NOTE
Schemaänderungen sind möglicherweise nicht sofort verfügbar, da Änderungen zwischengespeichert werden. Die Aktualisierung des Caches dauert bis zu fünfzehn Minuten.

API-Format

POST /collection/{CONNECTION_ID}?syncValidation=true
Parameter
Beschreibung
{CONNECTION_ID}
Der id -Wert der zuvor erstellten Streaming-Verbindung.

Anfrage

Senden Sie die folgende Anfrage zur Aufnahme von Daten an Ihren Daten-Inlet mit synchroner Validierung:

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
  -H "Content-Type: application/json" \
  -d '{JSON_PAYLOAD}'
Parameter
Beschreibung
{JSON_PAYLOAD}
Der JSON-Textkörper einer Daten, die Sie erfassen möchten.

Antwort

Wenn die synchrone Validierung aktiviert ist, enthält eine erfolgreiche Antwort alle aufgetretenen Validierungsfehler in ihrer 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"
                }
            ]
        }
    }
}

In der obigen Antwort wird aufgelistet, wie viele Schemafehlungen gefunden wurden und welche Verstöße aufgetreten sind. Diese Antwort gibt beispielsweise an, dass die Schlüssel workEmail und person im Schema nicht definiert wurden und daher nicht zulässig sind. Außerdem wird der Wert für _id als falsch markiert, da das Schema eine string erwartet hat, stattdessen jedoch eine long eingefügt wurde. Beachten Sie, dass der Validierungsdienst die Verarbeitung dieser Nachricht nach fünf Fehlern stoppt. Andere Nachrichten werden jedoch weiterhin analysiert.

Asynchrone Validierung

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

API-Format

POST /collection/{CONNECTION_ID}
Parameter
Beschreibung
{CONNECTION_ID}
Der id -Wert der zuvor erstellten Streaming-Verbindung.

Anfrage

Senden Sie die folgende Anfrage mit asynchroner Validierung an den Daten-Inlet, um Daten zu erfassen:

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID} \
  -H "Content-Type: application/json" \
  -d '{JSON_PAYLOAD}'
Parameter
Beschreibung
{JSON_PAYLOAD}
Der JSON-Textkörper einer Daten, die Sie erfassen möchten.
NOTE
Es ist kein zusätzlicher Abfrageparameter erforderlich, da die asynchrone Validierung standardmäßig aktiviert ist.

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 zur Aufnahme von Daten bedeuten.

Status-Codes

Status-Code
Was bedeutet es
200
Erfolgreich. Bei der synchronen Validierung bedeutet dies, dass die Validierungsprüfungen bestanden haben. Bei der asynchronen Validierung bedeutet dies, dass die Nachricht nur erfolgreich empfangen wurde. Benutzer können den Status einer Nachricht ermitteln, indem sie den Datensatz beobachten.
400
Fehler. Es stimmt etwas mit deiner Anfrage nicht. Von den Streaming-Validierungsdiensten wird eine Fehlermeldung mit weiteren Details empfangen.
401
Fehler. Ihre Anfrage ist nicht autorisiert - Sie müssen sie mit einem Trägertoken anfordern. Weitere Informationen zum Anfordern des Zugriffs finden Sie in diesem Tutorial oder diesem Blogpost.
500
Fehler. Es gibt einen internen Systemfehler.
501
Fehler. Das bedeutet, dass die synchrone Validierung für diesen Speicherort nicht unterstützt wird.
503
Fehler. Der Dienst ist derzeit nicht verfügbar. Clients sollten es mindestens dreimal mit einer exponentiellen Back-off-Strategie versuchen.
recommendation-more-help
2ee14710-6ba4-4feb-9f79-0aad73102a9a