Abrufen fehlgeschlagener Batches mit der Data Access API

Adobe Experience Platform bietet für den Upload und die Aufnahme von Daten zwei Methoden. Sie können entweder die Batch-Erfassung verwenden, um ihre Daten mit verschiedenen Dateitypen (z. B. CSV-Dateien) einzufügen, oder die Streaming-Erfassung, mit der Sie ihre Daten mithilfe von Streaming-Endpunkten in Echtzeit in Platform einfügen können.

In diesem Tutorial werden die Schritte zum Abrufen von Informationen zu einem fehlgeschlagenen Batch mithilfe von Data Ingestion -APIs beschrieben.

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:

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:

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

Beispiel für fehlgeschlagenen Batch

In diesem Tutorial werden Beispieldaten mit einem fehlerhaft formatierten Zeitstempel verwendet, der für den Monat den Wert 00 festlegt, wie unten dargestellt:

{
    "body": {
        "xdmEntity": {
            "id": "c8d11988-6b56-4571-a123-b6ce74236036",
            "timestamp": "2018-00-10T22:07:56Z",
            "environment": {
                "browserDetails": {
                    "userAgent": "Mozilla\/5.0 (Windows NT 5.1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/29.0.1547.57 Safari\/537.36 OPR\/16.0.1196.62",
                    "acceptLanguage": "en-US",
                    "cookiesEnabled": true,
                    "javaScriptVersion": "1.6",
                    "javaEnabled": true
                },
                "colorDepth": 32,
                "viewportHeight": 799,
                "viewportWidth": 414
            }
        }
    }
}

Die obige Payload wird aufgrund des fehlerhaften Zeitstempels nicht ordnungsgemäß mit dem XDM-Schema validiert.

Abrufen des fehlgeschlagenen Batches

API-Format

GET /batches/{BATCH_ID}/failed

Anfrage

curl -X GET 'https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/failed' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Cache-Control: no-cache' \
  -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

{
    "data": [
        {
            "name": "_SUCCESS",
            "length": "0",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/export/batches/{BATCH_ID}/failed?path=_SUCCESS"
                }
            }
        },
        {
            "name": "part-00000-44c7b669-5e38-43fb-b56c-a0686dabb982-c000.json",
            "length": "1800",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/export/batches/{BATCH_ID}/failed?path=part-00000-44c7b669-5e38-43fb-b56c-a0686dabb982-c000.json"
                }
            }
        }
    ],
    "_page": {
        "limit": 100,
        "count": 2
    }
}

Aus der Antwort oben ist ersichtlich, bei welchen Blöcken aus dem Batch die Aufnahme erfolgreich war und bei welchen sie fehlschlug. Diese Antwort hier zeigt, dass die Datei part-00000-44c7b669-5e38-43fb-b56c-a0686dabb982-c000.json den fehlgeschlagenen Batch enthält.

Herunterladen des fehlgeschlagenen Batches

Sobald Sie wissen, welche Datei aus dem Batch fehlschlug, können Sie die entsprechende Datei herunterladen und sich die Fehlermeldung anzeigen lassen.

API-Format

GET /batches/{BATCH_ID}/failed?path={FAILED_FILE}

Anfrage

Mit der nachfolgenden Anfrage können Sie die Datei herunterladen, bei der Fehler bei der Aufnahme aufgetreten sind.

curl -X GET 'https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/failed?path={FAILED_FILE}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Antwort

Da der zuvor aufgenommene Batch einen ungültigen Wert für Datum/Zeit aufwies, wird der folgende Validierungsfehler angezeigt.

{
    "_validationErrors": [
        {
            "causingExceptions": [],
            "keyword": "format",
            "message": "[2018-00-23T22:07:01Z] is not a valid date-time. Expected [yyyy-MM-dd'T'HH:mm:ssZ, yyyy-MM-dd'T'HH:mm:ss.[0-9]{1-9}Z, yyyy-MM-dd'T'HH:mm:ss[+-]HH:mm, yyyy-MM-dd'T'HH:mm:ss.[0-9]{1,9}[+-]HH:mm]",
            "pointerToViolation": "#/timestamp",
            "schemaLocation": "#/properties/timestamp"
        }
    ]
}

Nächste Schritte

Mit Abschluss dieses Tutorials haben Sie gelernt, wie Fehler aus fehlgeschlagenen Batches abgerufen werden. Weitere Informationen finden Sie zur Aufnahme von Batches finden Sie im Entwicklerhandbuch zur Batch-Erfassung. Weitere Informationen zur Streaming-Erfassung finden Sie im Tutorial zur Erstellung einer Streaming-Verbindung.

Anhang

Dieser Abschnitt enthält Informationen zu anderen möglichen Fehlern bei der Aufnahme.

Fehlerhaft formatiertes XDM

Wie der Zeitstempel-Fehler im Beispiel zuvor sind auch diese Fehler auf ein falsch formatiertes XDM zurückzuführen. Die Fehlermeldungen sind je nach Art des Problems unterschiedlich. Daher kann an dieser Stelle kein Beispiel für einen spezifischen Fehler angegeben werden.

Fehlende oder ungültige Organisations-ID

Dieser Fehler wird angezeigt, wenn die Organisations-ID in der Payload fehlt oder ungültig ist.

{
    "type": "http://ns.adobe.com/adobecloud/problem/data-collection-service/inlet",
    "status": 400,
    "title": "Invalid XDM Message Format",
    "report": {
        "message": "inletId: [{INLET_ID}] imsOrgId: [{ORG_ID}@AdobeOrg] Message has an absent or wrong ims org in the header"
    }
}

Fehlendes XDM-Schema

Dieser Fehler wird angezeigt, wenn schemaRef für xdmMeta fehlt.

{
    "type": "http://ns.adobe.com/adobecloud/problem/data-collection-service/inlet",
    "status": 400,
    "title": "Invalid XDM Message Format",
    "report": {
        "message": "inletId: [{INLET_ID}] imsOrgId: [{ORG_ID}@AdobeOrg] Message has unknown xdm format"
    }
}

Fehlender Quellname

Dieser Fehler wird angezeigt, wenn für die source in der Kopfzeile der name fehlt.

{
    "_errors":{
        "_streamingValidation": [
            {
                "message": "Payload header is missing Source Name"
            }
        ]
    }
}

Fehlende XDM-Entität

Dieser Fehler wird angezeigt, wenn xdmEntity nicht vorhanden ist.

{
    "_validationErrors": [
        {
            "message": "Payload body is missing xdmEntity"
        }
    ]
}