Présentation de l’API d’ingestion par lots

L’API Batch Ingestion de Adobe Experience Platform vous permet d’ingérer des données dans Experience Platform sous forme de fichiers de lots. Les données ingérées peuvent être des données de profil d’un fichier plat (tel qu’un fichier Parquet) ou des données conformes à un schéma connu dans le registre Experience Data Model (XDM).

La Référence de l’API Batch Ingestionfournit des informations supplémentaires sur ces appels API.

Le diagramme suivant décrit le processus d’ingestion par lots :

Commencer

Les points d’entrée d’API utilisés dans ce guide font partie de l’API Batch Ingestion. Avant de continuer, consultez le guide de prise en main pour obtenir des liens vers la documentation associée, un guide de lecture des exemples d’appels API dans ce document et des informations importantes sur les en-têtes requis pour réussir des appels vers n’importe quelle API d’Experience Platform.

Conditions préalables de Data Ingestion

Bonnes pratiques d’ingestion par lots

Contraintes d’ingestion par lots

L’ingestion de données par lots présente certaines contraintes :

Types

Lors de l’ingestion de données, il est important de comprendre le fonctionnement des schémas Experience Data Model (XDM). Pour plus d’informations sur la façon dont les types de champs XDM sont associés à différents formats, reportez-vous au guide de développement du registre des schémas.

Il existe une certaine flexibilité lors de l’ingestion de données : si un type ne correspond pas à ce qui se trouve dans le schéma cible, les données seront converties en type cible exprimé. Si cette conversion est impossible, le lot échouera avec TypeCompatibilityException.

Par exemple, ni JSON ni CSV n’ont de type date ou date-time. Par conséquent, ces valeurs sont exprimées à l’aide de chaînes au format ISO 8601 (« 2018-07-10T15:05:59.000-08:00 ») ou d’une heure Unix au format millisecondes (1531263959000) et sont converties au moment de l’ingestion en type XDM cible.

Le tableau ci-dessous illustre les conversions prises en charge lors de l’ingestion de données.

Utilisation de l’API

L’API Data Ingestion vous permet d’ingérer des données sous forme de lots (une unité de données composée d’un ou de plusieurs fichiers à ingérer en une seule unité) en Experience Platform en trois étapes de base :

Création d’un lot

Avant de pouvoir ajouter des données à un jeu de données, elles doivent être liées à un lot, qui sera ensuite chargé dans un jeu de données spécifié.

POST /batches

Requête

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

Réponse

{
    "id": "{BATCH_ID}",
    "imsOrg": "{ORG_ID}",
    "updated": 0,
    "status": "loading",
    "created": 0,
    "relatedObjects": [
        {
            "type": "dataSet",
            "id": "{DATASET_ID}"
        }
    ],
    "version": "1.0.0",
    "tags": {},
    "createdUser": "{USER_ID}",
    "updatedUser": "{USER_ID}"
}

Chargement des fichiers

Une fois le nouveau lot créé avec succès pour le chargement, les fichiers peuvent désormais être chargés dans le jeu de données spécifique.

Vous pouvez charger des fichiers à l’aide de l’API Small File Upload. Cependant, si vos fichiers sont trop volumineux et que la limite de la passerelle est dépassée (tels que des délais d’expiration étendus, des requêtes pour la taille du corps dépassées et d’autres restrictions), vous pouvez passer à l’API de chargement de fichiers volumineux. Cette API charge le fichier en blocs et regroupe les données à l’aide de l’appel API Chargement du fichier volumineux terminé .

Chargement de petits fichiers

Une fois un lot créé, les données peuvent être chargées vers un jeu de données préexistant. Le fichier en cours de chargement doit correspondre à son schéma XDM référencé.

PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}

Requête

curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Réponse

#Status 200 OK, with empty response body

Chargement de fichiers volumineux - création d’un fichier

Pour charger un fichier volumineux, le fichier doit être divisé en petits blocs qui seront chargés un par un.

POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}?action=initialize

Requête

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet?action=initialize" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Réponse

#Status 201 CREATED, with empty response body

Chargement de fichiers volumineux - chargement des parties suivantes

Une fois le fichier créé, tous les blocs suivants peuvent être chargés en exécutant des requêtes PATCH répétées, une pour chaque section du fichier.

PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}

Requête

curl -X PATCH "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "Content-Range: bytes {CONTENT_RANGE}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Réponse

#Status 200 OK, with empty response

Signalement de la fin du lot

Une fois que tous les fichiers ont été chargés dans le lot, il peut être marqué comme étant terminé. Ce faisant, les entrées DataSetFile Catalog sont créées pour les fichiers terminés et associées au lot généré ci-dessus. Le lot de Catalog est marqué comme réussi, ce qui déclenche les flux en aval afin d’ingérer les données disponibles.

Requête

POST /batches/{BATCH_ID}?action=COMPLETE

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

Réponse

#Status 200 OK, with empty response

Vérifier l’état du lot

En attendant que les fichiers soient chargés dans le lot, vous pouvez vérifier l’état du lot pour voir sa progression.

Format d’API

GET /batch/{BATCH_ID}

Requête

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

Réponse

{
    "{BATCH_ID}": {
        "imsOrg": "{ORG_ID}",
        "created": 1494349962314,
        "createdClient": "MCDPCatalogService",
        "createdUser": "{USER_ID}",
        "updatedUser": "{USER_ID}",
        "updated": 1494349963467,
        "externalId": "{EXTERNAL_ID}",
        "status": "success",
        "errors": [
            {
                "code": "err-1494349963436"
            }
        ],
        "version": "1.0.3",
        "availableDates": {
            "startDate": 1337,
            "endDate": 4000
        },
        "relatedObjects": [
            {
                "type": "batch",
                "id": "foo_batch"
            },
            {
                "type": "connection",
                "id": "foo_connection"
            },
            {
                "type": "connector",
                "id": "foo_connector"
            },
            {
                "type": "dataSet",
                "id": "foo_dataSet"
            },
            {
                "type": "dataSetView",
                "id": "foo_dataSetView"
            },
            {
                "type": "dataSetFile",
                "id": "foo_dataSetFile"
            },
            {
                "type": "expressionBlock",
                "id": "foo_expressionBlock"
            },
            {
                "type": "service",
                "id": "foo_service"
            },
            {
                "type": "serviceDefinition",
                "id": "foo_serviceDefinition"
            }
        ],
        "metrics": {
            "foo": 1337
        },
        "tags": {
            "foo_bar": [
                "stuff"
            ],
            "bar_foo": [
                "woo",
                "baz"
            ],
            "foo/bar/foo-bar": [
                "weehaw",
                "wee:haw"
            ]
        },
        "inputFormat": {
            "format": "parquet",
            "delimiter": ".",
            "quote": "`",
            "escape": "\\",
            "nullMarker": "",
            "header": "true",
            "charset": "UTF-8"
        }
    }
}

Le champ "status" indique l’état actuel du lot demandé. Les lots peuvent avoir l’un des états suivants :

États de l’ingestion par lot