Guide de dépannage de l’ingestion par lots

Cette documentation vous aidera à répondre aux questions fréquentes sur les API Batch Data Ingestion d’Adobe Experience Platform.

Appels API par lots

Les lots sont-ils immédiatement actifs après réception d’un état HTTP 200 OK de l’API CompleteBatch ?

La réponse 200 OK de l’API signifie que le lot a été accepté pour traitement. Il n’est pas actif tant qu’il n’a pas atteint son état final : Actif ou Échec.

Une nouvelle tentative d’appel API CompleteBatch est-elle sans danger après un échec ?

Oui, vous pouvez effectuer une nouvelle tentative d’appel API en toute sécurité. Malgré l’échec, il est possible que l’opération ait effectivement réussi et que le lot ait été accepté. Toutefois, les clients sont censés disposer de mécanismes de nouvelle tentative en cas d’échec de l’API et sont, en réalité, encouragés à effectuer une nouvelle tentative. En cas de réussite de l’opération, l’API renvoie une notification de réussite, même après une nouvelle tentative.

Quand l’API Large File Upload doit-elle être utilisée ?

La taille de fichier recommandée pour l’utilisation de l’API Large File Upload est de 256 Mo ou plus. Vous trouverez plus d’informations sur l’utilisation de l’API Large File Upload ici.

Pourquoi l’appel API Large File Complete échoue-t-il ?

Si des blocs d’un fichier volumineux se chevauchent ou sont manquants, le serveur répond par un état HTTP 400 Bad Request. Cela peut se produire puisqu’il est possible de charger des blocs qui se chevauchent, étant donné que les validations de plage sont effectuées lorsque le fichier est terminé, lors de l’assemblage des blocs de fichier.

Prise en charge de l’ingestion

Quels sont les formats d’ingestion pris en charge ?

Actuellement, Parquet et JSON sont pris en charge. Le format CSV est pris en charge sur une base héritée. Tandis que les données sont promues au format maître et que les vérifications préliminaires sont effectuées, aucune fonctionnalité moderne, telle que la conversion, le partitionnement ou la validation des lignes, n’est prise en charge.

Où faut-il préciser le format d’entrée du lot ?

Le format d’entrée doit être spécifié au moment de la création du lot dans le payload. Vous trouverez ci-dessous un exemple de spécification du format d’entrée du lot :

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
  -d '{
          "datasetId": "{DATASET_ID}",
           "inputFormat": {
                "format": "json"
           }
    }'

Pourquoi les données téléchargées n’apparaissent-elles pas dans le jeu de données ?

Pour que les données apparaissent dans le jeu de données, le lot doit être marqué comme terminé. Tous les fichiers à ingérer doivent être téléchargés avant de marquer le lot comme terminé. Vous trouverez ci-dessous un exemple de marquage d’un lot comme terminé :

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Comment le fichier JSON à plusieurs lignes est-il ingéré ?

Pour ingérer un fichier JSON à plusieurs lignes, l’indicateur isMultiLineJson doit être défini au moment de la création du lot. Voici un exemple :

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
  -d '{
          "datasetId": "{DATASET_ID}",
           "inputFormat": {
                "format": "json",
                "isMultiLineJson": true
           }
      }'

Quelle est la différence entre les lignes JSON (fichier JSON à une seule ligne) et les fichiers JSON à plusieurs lignes ?

Dans le cas des lignes JSON, il existe un objet JSON par ligne. Par exemple :

{"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}}
{"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}}
{"string":"string3","int":3,"array":[3,6,9],"dict": {"key": "value3", "extra_key": "extra_value3"}}

Dans le cas d’un fichier JSON à plusieurs lignes, un objet peut occuper plusieurs lignes, tandis que tous les objets sont placés dans un tableau JSON. Par exemple :

[
    {"string":"string1","int":1,"array":[1,2,3],"dict": {"key": "value1"}},
    {"string":"string2","int":2,"array":[2,4,6],"dict": {"key": "value2"}},
    {
        "string": "string3",
        "int": 3,
        "array": [
            3,
            6,
            9
        ],
        "dict": {
            "key": "value3",
            "extra_key": "extra_value3"
        }
    }
]

Par défaut, Batch Data Ingestion utilise le format JSON à une seule ligne.

L’ingestion au format CSV est-elle prise en charge ?

L’ingestion au format CSV est uniquement prise en charge pour les schémas plats. Actuellement, l’ingestion de données hiérarchiques au format CSV n’est pas prise en charge.

Pour obtenir toutes les fonctionnalités d’ingestion de données, vous devez utiliser les formats JSON ou Parquet.

Quels types de validation sont effectués sur les données ?

Trois niveaux de validation sont effectués sur les données :

Comment remplacer un lot déjà ingéré ?

Un lot déjà ingéré peut être remplacé à l’aide de la fonctionnalité Relecture de lot. Vous trouverez plus d’informations sur la fonctionnalité Relecture de lot ici.

Comment surveiller l’ingestion par lots ?

Une fois qu’un lot a été signalé en vue d’une promotion, la progression de l’ingestion par lots peut être surveillée à l’aide de la requête suivante :

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Cette requête vous permettra d’obtenir une réponse similaire à celle-ci :

200 OK

{
    "{BATCH_ID}":{
        "imsOrg":"{ORG_ID}",
        "created":1494349962314,
        "createdClient":"{API_KEY}",
        "createdUser":"{USER_ID}",
        "updatedUser":"{USER_ID}",
        "completed":1494349963467,
        "externalId":"{EXTERNAL_ID}",
        "status":"staging",
        "errors":[],
    }
}

États de lot

Quels sont les états de lot possibles ?

Au cours de son cycle de vie, un lot peut passer par les états suivants :

En quoi consiste l’état « Évaluation » des lots ?

Lorsqu’un lot se trouve dans l’état « Évaluation », cela signifie que le lot a été signalé en vue d’une promotion et que les données sont évaluées pour la consommation en aval.

En quoi consiste l’état « Nouvelle tentative » d’un lot ?

Lorsqu’un lot se trouve dans l’état « Nouvelle tentative », cela signifie que l’ingestion des données du lot a été temporairement interrompue en raison de problèmes intermittents. Dans ce cas, aucune intervention du client n’est nécessaire.

En quoi consiste l’état « Bloqué » d’un lot ?

Lorsqu’un lot se trouve dans l’état « Bloqué », cela signifie que Data Ingestion Services rencontre des difficultés à ingérer le lot et que toutes les nouvelles tentatives sont épuisées.

En quoi consiste l’état « Chargement » d’un lot ?

Lorsqu’un lot se trouve dans l’état « Chargement », cela signifie que l’API CompleteBatch n’a pas été appelée pour promouvoir le lot.

Existe-t-il un moyen de savoir si un lot a bien été ingéré ?

Oui, une fois que l’état du lot est "Actif", le lot a été ingéré avec succès. Pour connaître l’état du lot, suivez les étapes décrites plus haut.

Que se passe-t-il après l’échec d’un lot ? what-if-a-batch-fails

Lorsqu’un lot échoue, le processus s’arrête et renvoie un état Failure. La raison de son échec peut être identifiée dans la section errors du payload. Vous trouverez ci-dessous des exemples d’erreurs :

    "errors":[
        {
            "code":"106",
            "description":"Dataset file is empty. Please upload file with data.",
            "rows":[]
        },
        {
            "code":"118",
            "description":"CSV file contains empty header row.",
            "rows":[]
        }
    ]

Une fois les erreurs corrigées, le lot peut à nouveau être chargé.

Prise en charge des lots

Comment supprimer les lots ?

Au lieu de les supprimer directement de Catalog, les lots doivent être supprimés à l’aide de l’une des méthodes fournies ci-dessous :

Quelles sont les mesures disponibles au niveau des lots ?

Les mesures suivantes sont disponibles pour les lots à l’état Actif/Réussite :

Pourquoi les mesures ne sont-elles pas disponibles pour certains lots ?

Deux raisons peuvent expliquer que les mesures ne soient pas disponibles pour votre lot :

Que signifient les différents codes d’état ?