Show Menu
SUJETS×

Récupération partielle par lot (bêta)

L'assimilation partielle par lot permet d'assimiler des données contenant des erreurs, jusqu'à un certain seuil. Grâce à cette fonctionnalité, les utilisateurs peuvent intégrer toutes leurs données correctes dans Adobe Experience Platform, tandis que toutes leurs données incorrectes sont mises en lots séparément, ainsi que les raisons pour lesquelles elles ne sont pas valides.
Ce document fournit un didacticiel pour la gestion de l'assimilation partielle des lots.
En outre, l' annexe de ce didacticiel fournit une référence pour les types d'erreur d'assimilation par lot partielle.
Cette fonctionnalité n'existe qu'à l'aide de l'API. Veuillez contacter votre équipe pour accéder à cette fonction.

Prise en main

Ce didacticiel nécessite une connaissance approfondie des différents services Adobe Experience Platform impliqués dans l’assimilation partielle de lots. Avant de commencer ce didacticiel, consultez la documentation relative aux services suivants :
  • Importation par lot : Méthode par laquelle la plate-forme ingère et stocke des données à partir de fichiers de données, tels que CSV et Parquet.
  • Modèle de données d’expérience (XDM) : Cadre normalisé selon lequel la plate-forme organise les données d’expérience client.
Les sections suivantes contiennent des informations supplémentaires que vous devez connaître pour pouvoir invoquer les API de plateforme.

Lecture des exemples d’appels d’API

Ce guide fournit des exemples d’appels d’API pour montrer comment formater vos requêtes. Il s’agit notamment des chemins d’accès, des en-têtes requis et des charges de requête correctement formatées. 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 sur comment lire des exemples d’appels d’API dans le guide de dépannage d’Experience Platform.

Rassembler les valeurs des en-têtes requis

Pour lancer des appels aux API de plateforme, vous devez d’abord suivre le didacticiel d’ authentification. Le didacticiel d’authentification fournit les valeurs de chacun des en-têtes requis dans tous les appels d’API de plateforme d’expérience, comme indiqué ci-dessous :
  • Autorisation : Porteur {ACCESS_TOKEN}
  • x-api-key : {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
Toutes les ressources de la plate-forme d’expérience sont isolées dans des sandbox virtuels spécifiques. Toutes les requêtes d’API de plateforme nécessitent un en-tête spécifiant le nom du sandbox dans lequel l’opération aura lieu :
  • x-sandbox-name : {SANDBOX_NAME}
Pour plus d’informations sur les sandbox dans Platform, voir la documentation d’aperçu de sandbox.

Activation d’un jeu de données pour l’assimilation par lots partielle dans l’API

Vous pouvez créer un nouveau jeu de données ou modifier un jeu de données existant avec l'assimilation partielle activée.
Pour créer un nouveau jeu de données, suivez les étapes du didacticiel Création d’un jeu de données Création d’un jeu de données. Une fois que vous avez atteint l’étape Créer un jeu de données , ajoutez le champ suivant dans le corps de la requête :
{
    ...
    "tags" : {
        "partialBatchIngestion":["errorThresholdPercentage:5"]
    },
    ...
}

Propriété
Description
errorThresholdPercentage
Le pourcentage d'erreurs acceptables avant l'ensemble du lot échoue.
De même, pour modifier un jeu de données existant, suivez les étapes du guide de développement Catalogue.
Dans le jeu de données, vous devrez ajouter la balise décrite ci-dessus.

Récupérer les erreurs d'assimilation partielle des lots

Si les lots contiennent des échecs, vous devrez récupérer les informations d'erreur sur ces échecs afin de pouvoir réingérer les données.

Vérifier l'état

Pour vérifier l'état du lot assimilé, 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 souhaitez 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 l’état HTTP 200 avec des informations détaillées sur l’état du lot.
{
    "af838510-2233-11ea-acf0-f3edfcded2d2": {
        "status": "success",
        "tags": {
            ...
        },
        "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 est "réussite" et contient plus d'informations sur l'erreur fournie dans un fichier d'erreur téléchargeable.

Étapes suivantes

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

Types d'erreur d'assimilation par lots partiels

L'assimilation partielle par lot comporte quatre types d'erreur différents lors de l'assimilation de données.

Fichiers illisibles

Si le lot ingéré contient des fichiers illisibles, les erreurs du lot sont jointes au lot lui-même. Pour plus d'informations sur la récupération du lot en échec, consultez le guide Récupération de lots ayant échoué à l’aide de l’API Récupération des lots en échec.

schémas ou en-têtes non valides

Si le lot assimilé comporte un schéma non valide ou des en-têtes non valides, les erreurs du lot sont jointes au lot lui-même. Pour plus d'informations sur la récupération du lot en échec, consultez le guide Récupération de lots ayant échoué à l’aide de l’API Récupération des lots en échec.

Lignes non analysables

Si le lot ingéré contient des lignes non analysables, les erreurs du lot sont 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 à partir duquel 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 l’é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 assimilé a des conversions XDM non valides, les erreurs du lot sont 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 à partir duquel 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 l’état HTTP 200 avec les détails des échecs de 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"
}