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: {IMS_ORG}

Alle Ressourcen in Experience Platform, einschließlich der Ressourcen, die zu Schema Registry gehören, werden 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:

  • x-sandbox-name: {SANDBOX_NAME}
HINWEIS

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 Validierungen 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.

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

HINWEIS

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 weist beispielsweise darauf hin, 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 einen string erwartet hat, stattdessen aber ein long eingefügt wurde. Beachten Sie, dass der Validierungsdienst stop 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.
HINWEIS

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 Bedeutung
200 Erfolg. 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. Mit deiner Anfrage stimmt etwas 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 von Zugriff 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.

Auf dieser Seite