Show Menu
SUJETS×

Ingestion par lots partielle

L’ingestion par lots partielle permet d’ingérer des données contenant des erreurs jusqu’à un certain seuil. Grâce à cette fonctionnalité, les utilisateurs peuvent ingérer toutes leurs données correctes dans Adobe Experience Platform, alors que toutes leurs données incorrectes sont traitées par lots séparément, avec des détails sur les raisons de leur non-validité.
Ce document fournit un tutoriel pour la gestion de l’ingestion par lots partielle.
En outre, l’ annexe de ce tutoriel contient une référence pour les types d’erreurs d’ingestion par lots partielle.

Prise en main

Ce tutoriel nécessite une connaissance pratique des différents services Adobe Experience Platform impliqués dans l’ingestion par lots partielle. Avant de commencer ce tutoriel, veuillez consulter la documentation relative aux services suivants :
  • Ingestion par lots Platform : méthode d’ingestion et de stockage de données de fichiers, par exemple de type CSV et Parquet, dans
  • Experience Data Model (XDM) : Cadre normalisé selon lequel Platform organiser les données d’expérience client.
The following sections provide additional information that you will need to know in order to successfully make calls to Platform APIs.

Lecture d’exemples d’appels API

Ce guide 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. For information on the conventions used in documentation for sample API calls, see the section on how to read example API calls in the Experience Platform troubleshooting guide.

Collecte des valeurs des en-têtes requis

In order to make calls to Platform APIs, you must first complete the authentication tutorial . Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:
  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:
  • x-sandbox-name: {SANDBOX_NAME}
For more information on sandboxes in Platform, see the sandbox overview documentation .

Enable a batch for partial batch ingestion in the API

Cette section décrit l'activation d'un lot pour l'assimilation partielle de lots à l'aide de l'API. For instructions on using the UI, please read the enable a batch for partial batch ingestion in the UI step.
Vous pouvez créer un nouveau lot avec l'assimilation partielle activée.
Pour créer un nouveau lot, suivez les étapes décrites dans le guide du développeur d'assimilation par lot. Once you reach the Create batch step, add the following field within the request body:
{
    ...
    "enableErrorDiagnostics": true,
    "partialIngestionPercentage": 5
    ...
}

Propriété
Description
enableErrorDiagnostics
Indicateur qui permet Platform de générer des messages d'erreur détaillés sur votre lot.
partialIngestionPercentage
Pourcentage d’erreurs acceptables avant le rejet de l’ensemble du lot. Ainsi, dans cet exemple, un maximum de 5 % du lot peut être une erreur, avant qu’il ne soit endommagé.

Enable a batch for partial batch ingestion in the UI

Cette section décrit l'activation d'un lot pour l'assimilation partielle de lots à l'aide de l'interface utilisateur. Si vous avez déjà activé un lot pour l'assimilation partielle de lots à l'aide de l'API, vous pouvez passer à la section suivante.
Pour activer un lot pour l’assimilation partielle via l’ Platform interface utilisateur, vous pouvez créer un nouveau lot par le biais des connexions source, créer un nouveau lot dans un jeu de données existant ou créer un nouveau lot par le biais du flux"Mapper le fichier CSV au fichier XDM".

Créer une connexion source

Pour créer une connexion à la source, suivez les étapes répertoriées dans l'aperçu des sources. Once you reach the Dataflow detail step, take note of the Partial ingestion and Error diagnostics fields.
Le bouton Ingestion partielle vous permet d’activer ou de désactiver l’utilisation de l’ingestion par lots partielle.
The Error diagnostics toggle only appears when the Partial ingestion toggle is off. This feature allows Platform to generate detailed error messages about your ingested batches. If the Partial ingestion toggle is turned on, enhanced error diagnostics are automatically enforced.
Le seuil d’erreur vous permet de définir le pourcentage d’erreurs acceptables avant le rejet de l’ensemble du lot. Par défaut, cette valeur est définie sur 5 %.

Utilisation d’un jeu de données existant

Pour utiliser un jeu de données existant, début en sélectionnant un jeu de données. La barre latérale droite contient des informations sur le jeu de données.
Le bouton Ingestion partielle vous permet d’activer ou de désactiver l’utilisation de l’ingestion par lots partielle.
The Error diagnostics toggle only appears when the Partial ingestion toggle is off. This feature allows Platform to generate detailed error messages about your ingested batches. If the Partial ingestion toggle is turned on, enhanced error diagnostics are automatically enforced.
Le seuil d’erreur vous permet de définir le pourcentage d’erreurs acceptables avant le rejet de l’ensemble du lot. Par défaut, cette valeur est définie sur 5 %.
Désormais, vous pouvez transférer des données à l’aide du bouton Ajouter les données et elles seront ingérées à l’aide de l’assimilation partielle.

Utilisation du flux "Mapper le fichier CSV au schémaXDM"

Pour utiliser le flux "Mapper un fichier CSV au schémaXDM", suivez les étapes répertoriées dans le didacticiel Mappage d’un fichier CSV à un schéma XDM Mapper un fichier CSV. Once you reach the Add data step, take note of the Partial ingestion and Error diagnostics fields.
Le bouton Ingestion partielle vous permet d’activer ou de désactiver l’utilisation de l’ingestion par lots partielle.
The Error diagnostics toggle only appears when the Partial ingestion toggle is off. This feature allows Platform to generate detailed error messages about your ingested batches. If the Partial ingestion toggle is turned on, enhanced error diagnostics are automatically enforced.
Le seuil d’erreur vous permet de définir le pourcentage d’erreurs acceptables avant le rejet de l’ensemble du lot. Par défaut, cette valeur est définie sur 5 %.

Récupération des erreurs d’ingestion par lots partielle

Si les lots contiennent des défaillances, vous devrez récupérer les informations d’erreur les concernant afin de pouvoir ingérer à nouveau les données.

Vérification de l’état

Pour vérifier l’état du lot ingéré, vous devez indiquer l’identifiant du lot dans le chemin d’une requête GET.
Format d’API
GET /catalog/batches/{BATCH_ID}

Paramètre
Description
{BATCH_ID}
Valeur id du lot dont vous voulez vérifier l’état.
Requête
curl -X GET https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID} \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Réponse
Une réponse réussie renvoie un état HTTP 200 avec des informations détaillées sur l’état du lot.
{
    "af838510-2233-11ea-acf0-f3edfcded2d2": {
        "status": "success",
        "tags": {
            ...
            "acp_enableErrorDiagnostics": true,
            "acp_partialIngestionPercent": 5
            ...
        },
        "relatedObjects": [
            {
                "type": "dataSet",
                "id": "5deac2648a19d218a888d2b1"
            }
        ],
        "id": "af838510-2233-11ea-acf0-f3edfcded2d2",
        "externalId": "af838510-2233-11ea-acf0-f3edfcded2d2",
        "inputFormat": {
            "format": "parquet"
        },
        "imsOrg": "{IMS_ORG}",
        "started": 1576741718543,
        "metrics": {
            "inputByteSize": 568,
            "inputFileCount": 4,
            "inputRecordCount": 519,
            "outputRecordCount": 497
        },
        "completed": 1576741722026,
        "created": 1576741597205,
        "createdClient": "{API_KEY}",
        "createdUser": "{USER_ID}",
        "updatedUser": "{USER_ID}",
        "updated": 1576741722644,
        "version": "1.0.5"
    }    
}

Si le lot comporte une erreur et que les diagnostics d’erreur sont activés, l’état indiquera « succès » et davantage d’informations sur l’erreur seront fournies dans un fichier d’erreur téléchargeable.

Étapes suivantes

Ce tutoriel explique comment créer ou modifier un jeu de données pour activer l’ingestion par lots partielle. Pour plus d’informations sur l’ingestion par lots, consultez le guide de développement de l’ingestion par lots .

Types d’erreurs d’ingestion par lots partielle

L’ingestion par lots partielle présente quatre types d’erreurs différents lors de l’ingestion de données.

Fichiers illisibles

Si le lot ingéré contient des fichiers illisibles, les erreurs du lot seront jointes à celui-ci. Vous trouverez plus d’informations sur la récupération du lot rejeté dans le guide sur la récupération des lots rejetés .

Schémas ou en-têtes non valides

Si le lot ingéré comporte un schéma ou des en-têtes non valides, les erreurs du lot seront jointes à celui-ci. Vous trouverez plus d’informations sur la récupération du lot rejeté dans le guide sur la récupération des lots rejetés .

Lignes non analysables

Si le lot ingéré comporte des lignes non analysables, les erreurs du lot seront stockées dans un fichier accessible à l’aide du point de terminaison décrit ci-dessous.
Format d’API
GET /export/batches/{BATCH_ID}/failed?path=parse_errors

Paramètre
Description
{BATCH_ID}
Valeur id du lot dans lequel vous récupérez les informations d’erreur.
Requête
curl -X GET https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/failed?path=parse_errors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Réponse
Une réponse réussie renvoie un état HTTP 200 avec les détails des lignes non analysables.
{
    "_corrupt_record":"{missingQuotes:"v1"}",
    "_errors": [{
         "code":"1401",
         "message":"Row is corrupted and cannot be read, please fix and resend."
    }],
    "_filename": "a1.json"
}

Conversion XDM non valide

Si le lot ingéré comporte des conversions XDM non valides, les erreurs du lot seront stockées dans un fichier accessible à l’aide du point de terminaison suivant.
Format d’API
GET /export/batches/{BATCH_ID}/failed?path=conversion_errors

Paramètre
Description
{BATCH_ID}
Valeur id du lot dans lequel vous récupérez les informations d’erreur.
Requête
curl -X GET https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/failed?path=conversion_errors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Réponse
Une réponse réussie renvoie un état HTTP 200 avec les détails des échecs de la conversion XDM.
{
    "col1":"v1",
    "col2":"v2",
    "col3":[{
        "g1":"h1"
    }],
    "_errors":[{
        "column":"col3",
        "code":"123",
        "message":"Cannot convert array element from Object to String"
    }],
    "_filename":"a1.json"
},
{
    "col1":"v1",
    "col2":"v2",
    "col3":[{
        "g1":"h1"
    }],
    "_errors":[{
        "column":"col1",
        "code":"100",
        "message":"Cannot convert string to float"
    }],
    "_filename":"a2.json"
}