Validation de l’ingestion par flux

L’ingestion par flux vous permet de charger vos données vers Adobe Experience Platform à l’aide de points de terminaison en continu en temps réel. Les API d’ingestion par flux prennent en charge deux modes de validation : synchrone et asynchrone.

Prise en main

Ce guide nécessite une compréhension professionnelle des composants suivants d’Adobe Experience Platform :

Lecture d’exemples d’appels API

Ce tutoriel fournit des exemples d’appels API pour démontrer comment formater vos requêtes. Il s’agit notamment de chemins d’accès, d’en-têtes requis et de payloads de requêtes correctement formatés. L’exemple JSON renvoyé dans les réponses de l’API est également fourni. Pour plus d’informations sur les conventions utilisées dans la documentation pour les exemples d’appels d’API, voir la section concernant la lecture d’exemples d’appels d’API dans le guide de dépannage Experience Platform.

Collecte des valeurs des en-têtes requis

Pour lancer des appels aux API Platform, vous devez d’abord suivre le tutoriel d’authentification. Le tutoriel d’authentification fournit les valeurs de chacun des en-têtes requis dans tous les appels d’API Experience Platform, comme indiqué ci-dessous :

Toutes les ressources dans Experience Platform, y compris ceux appartenant à la variable Schema Registry, sont isolés dans des environnements de test virtuels spécifiques. Toutes les requêtes envoyées aux API Platform nécessitent un en-tête spécifiant le nom du sandbox dans lequel l’opération sera effectuée :

Toutes les requêtes contenant un payload (POST, PUT, PATCH) requièrent un en-tête supplémentaire :

Couverture de validation

Streaming Validation Service couvre la validation dans les domaines suivants :

Validation synchrone

La validation synchrone est une méthode de validation qui fournit des commentaires immédiats sur les raisons de l’échec d’une ingestion. Toutefois, en cas d’échec, les enregistrements dont la validation échoue sont ignorés et le système empêche leur envoi en aval. Par conséquent, la validation synchrone ne doit être utilisée que pendant le processus de développement. Lors d’une validation synchrone, les appelants sont informés du résultat de la validation et en cas d’échec, des raisons de cet échec.

La validation synchrone n’est pas activée par défaut. Pour l’activer, vous devez transmettre le paramètre de requête facultatif syncValidation=true lorsque vous effectuez des appels API. De plus, la validation synchrone est actuellement disponible uniquement si le point d’entrée de votre flux se trouve sur le centre de données VA7.

Si un message échoue au cours de la validation synchrone, le message ne sera pas écrit vers la file d’attente de sortie, qui fournit des commentaires immédiats pour les utilisateurs.

Format d’API

POST /collection/{CONNECTION_ID}?syncValidation=true

Requête

Envoyez la requête suivante pour ingérer des données vers votre inlet de données grâce à la validation synchrone :

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

Réponse

Lorsque la validation synchrone est activée, une réponse réussie inclut toutes les erreurs de validation survenues dans le 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"
                }
            ]
        }
    }
}

La réponse ci-dessus répertorie le nombre de violations de schéma et en quoi elles consistaient. Par exemple, cette réponse indique que les clés workEmail et person n’étaient pas définies dans le schéma et donc non autorisées. Elle marque également la valeur _id comme incorrecte, puisque le schéma attendait un string, mais qu’un long a été inséré à la place. Notez qu’une fois que cinq erreurs sont rencontrées, le service de validation arrêtera le traitement de ce message. Les autres messages continueront toutefois à être analysés.

Validation asynchrone

La validation asynchrone est une méthode de validation qui ne fournit aucun commentaire immédiat. Au lieu de cela, les données sont envoyées à un lot en échec dans Data Lake pour éviter toute perte de données. Ces données en échec peuvent être récupérées par la suite pour une analyse et une relecture plus approfondies. Cette méthode est celle qui doit être utilisée en production. Sauf requête contraire, l’ingestion par flux fonctionne avec le mode de validation asynchrone.

Format d’API

POST /collection/{CONNECTION_ID}

Requête

Envoyez la requête suivante pour ingérer des données vers votre inlet de données grâce à la validation asynchrone :

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

Réponse

Lorsque la validation asynchrone est activée, une réponse réussie renvoie les éléments suivants :

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

Veuillez noter que la réponse indique que la validation synchrone a été ignorée, car elle n’a pas été explicitement demandée.

Annexe

Cette section contient des informations relatives à la signification des différents codes d’état pour les réponses d’ingestion de données.

Codes d’état