Show Menu
SUJETS×

Envoi de plusieurs messages dans une seule requête HTTP

Lors de la diffusion de données en flux continu vers Adobe Experience Platform, effectuer de nombreux appels HTTP peut s’avérer coûteux. Par exemple, au lieu de créer 200 requêtes HTTP avec des charges de 1 Ko, il est beaucoup plus efficace de créer 1 requête HTTP avec 200 messages de 1 Ko chacun, avec une charge utile unique de 200 Ko. Lorsqu’il est utilisé correctement, le regroupement de plusieurs messages au sein d’une même requête constitue un excellent moyen d’optimiser les données envoyées à la plateforme d’expérience.
Ce document fournit un didacticiel pour l’envoi de plusieurs messages à la plateforme Experience Platform dans une seule requête HTTP à l’aide de l’assimilation en flux continu.

Prise en main

Ce didacticiel nécessite une bonne compréhension de la gestion des données de la plateforme Adobe Experience Platform. Avant de commencer ce didacticiel, consultez la documentation suivante :
  • Présentation de l'importation de données : Couvre les concepts de base de la plateforme d’expérience Ingestion des données, y compris les méthodes d’assimilation et les connecteurs de données.
  • Présentation de l'assimilation en flux continu : Flux de travaux et blocs de création d’assimilation de flux continu, tels que les connexions en flux continu, les jeux de données, le Profil individuel XDM et XDM ExperienceEvent.
Ce didacticiel nécessite également que vous ayez suivi le didacticiel Authentication to Adobe Experience Platform (Authentification vers la plate-formeAdobe Experience) pour pouvoir invoquer les API de plateforme. Le didacticiel d'authentification fournit la valeur de l'en-tête d'autorisation requise par tous les appels d'API dans ce didacticiel. L’en-tête s’affiche dans les exemples d’appels comme suit :
  • Autorisation : Porteur {ACCESS_TOKEN}
Toutes les requêtes POST nécessitent un en-tête supplémentaire :
  • Content-Type : application/json

Création d’une connexion en flux continu

Vous devez d’abord créer une connexion de diffusion en continu avant de pouvoir début des données de diffusion en continu sur la plateforme d’expérience. Lisez le guide de création d’une connexion en flux continu pour savoir comment créer une connexion en flux continu.
Après l’enregistrement d’une connexion de diffusion en continu, vous, en tant que producteur de données, disposez d’une URL unique qui peut être utilisée pour diffuser des données vers la plate-forme.

Diffusion en continu vers un jeu de données

L'exemple suivant montre comment envoyer plusieurs messages à un jeu de données spécifique dans une seule requête HTTP. Insérez l’ID de jeu de données dans l’en-tête du message pour que ce message soit directement assimilé à celui-ci.
Vous pouvez obtenir l’ID d’un jeu de données existant à l’aide de l’interface utilisateur de la plate-forme ou à l’aide d’une opération de liste dans l’API. L’ID de jeu de données se trouve sur la plate-forme platform.adobe.com d’expérience en accédant à l’onglet Datasets , en cliquant sur le jeu de données pour lequel vous souhaitez obtenir l’ID et en copiant la chaîne dans le champ ID de jeu de données de l’onglet Info. Pour plus d’informations sur la manière de récupérer des jeux de données à l’aide de l’API, consultez la présentation du service de catalogue.
Au lieu d'utiliser un jeu de données existant, vous pouvez en créer un nouveau. Pour plus d'informations sur la création d'un jeu de données à l'aide d'API , consultez le didacticiel de création d'un jeu de données à l'aide d'API.
Format d’API
POST /collection/batch/{CONNECTION_ID}

Propriété
Description
{CONNECTION_ID}
ID de la connexion de flux continu créée.
Requête
curl -X POST https://dcs.adobedc.net/collection/batch/{CONNECTION_ID} \
  -H 'Content-Type: application/json' \
  -d '{
  "messages": [
    {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
        },
        "imsOrgId": "{IMS_ORG}",
        "source": {
          "name": "GettingStarted"
        },
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
          "timestamp": "2019-02-23T22:07:01Z",
          "environment": {
            "browserDetails": {
              "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
              "acceptLanguage": "en-US",
              "cookiesEnabled": true,
              "javaScriptVersion": "1.6",
              "javaEnabled": true
            },
            "colorDepth": 32,
            "viewportHeight": 799,
            "viewportWidth": 414
          },
          "productListItems": [
            {
              "SKU": "CC",
              "name": "Fernie Snow",
              "quantity": 30,
              "priceTotal": 7.8
            }
          ],
          "commerce": {
            "productViews": {
              "value": 1
            }
          },
          "_experience": {
            "campaign": {
              "message": {
                "profileSnapshot": {
                  "workEmail": {
                    "address": "gregdorcey@example.com"
                  }
                }
              }
            }
          }
        }
      }
    },
    {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
        },
        "imsOrgId": "{IMS_ORG}",
        "source": {
          "name": "GettingStarted"
        },
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "7af6adcc-dc9e-4692-b826-55d2abe68c11",
          "timestamp": "2019-02-23T22:07:31Z",
          "environment": {
            "browserDetails": {
              "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
              "acceptLanguage": "en-US",
              "cookiesEnabled": true,
              "javaScriptVersion": "1.6",
              "javaEnabled": true
            },
            "colorDepth": 32,
            "viewportHeight": 799,
            "viewportWidth": 414
          },
          "productListItems": [
            {
              "SKU": "CC",
              "name": "Carmine Santiago",
              "quantity": 10,
              "priceTotal": 5.5
            }
          ],
          "commerce": {
            "productViews": {
              "value": 1
            }
          },
          "_experience": {
            "campaign": {
              "message": {
                "profileSnapshot": {
                  "workEmail": {
                    "address": "emilyong@example.com"
                  }
                }
              }
            }
          }
        }
      }
    }
  ]
}'

Réponse
Une réponse réussie renvoie un état HTTP 207 (multi-état). L’examen du corps de la réponse fournit plus de détails sur la réussite ou l’échec de chaque méthode exécutée dans la requête. Une réponse est renvoyée pour chaque élément du tableau des messages de requête. Vous trouverez ci-dessous un exemple de réponse positive sans échec de message :
{
    "inletId": "9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5",
    "batchId": "1565628583792:1485:153",
    "receivedTimeMs": 1565628583854,
    "responses": [
        {
            "xactionId": "1565628583792:1485:153:0"
        },
        {
            "xactionId": "1565628583792:1485:153:1"
        }
    ]
}

Pour plus d'informations sur les codes d'état, consultez le tableau des codes de réponse dans l'annexe de ce didacticiel.

Identifier les messages qui ont échoué

Par rapport à l’envoi d’une requête avec un seul message, lors de l’envoi d’une requête HTTP avec plusieurs messages, d’autres facteurs peuvent être pris en compte, tels que : comment identifier le moment où l'envoi des données a échoué, quels messages spécifiques n'ont pas pu être envoyés et comment ils peuvent être récupérés, et ce qui arrive aux données qui réussissent lorsque d'autres messages dans la même requête échouent.
Avant de poursuivre l'utilisation de ce didacticiel, il est recommandé de consulter d'abord le guide de récupération des lots ayant échoué.

Envoyer la charge utile de demande avec des messages valides et non valides

L'exemple suivant montre ce qui se produit lorsque le lot inclut des messages valides et non valides.
La charge utile de requête est un tableau d’objets JSON représentant le événement dans le schéma XDM. Notez que les conditions suivantes doivent être remplies pour que la validation du message soit réussie :
  • Le imsOrgId champ de l’en-tête de message doit correspondre à la définition d’entrée. Si la charge utile de la demande n’inclut pas de imsOrgId champ, le service principal de collecte de données (DCCS) ajoute automatiquement le champ.
  • L’en-tête du message doit faire référence à un schéma XDM existant créé dans l’interface utilisateur de la plate-forme.
  • Le datasetId champ doit référencer un jeu de données existant dans Platform et son schéma doit correspondre au schéma fourni dans l’objet header dans chaque message inclus dans le corps de la requête.
Format d’API
POST /collection/batch/{CONNECTION_ID}

Propriété
Description
{CONNECTION_ID}
ID de l'entrée de données créée.
Requête
curl -X POST https://dcs.adobedc.net/collection/batch/{CONNECTION_ID} \
  -H 'Content-Type: application/json' \
  -d '{
  "messages": [
    {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
        },
        "imsOrgId": "{IMS_ORG}",
        "source": {
          "name": "GettingStarted"
        },
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
          "timestamp": "2019-02-23T22:07:01Z",
          "environment": {
            "browserDetails": {
              "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
              "acceptLanguage": "en-US",
              "cookiesEnabled": true,
              "javaScriptVersion": "1.6",
              "javaEnabled": true
            },
            "colorDepth": 32,
            "viewportHeight": 799,
            "viewportWidth": 414
          },
          "productListItems": [
            {
              "SKU": "CC",
              "name": "Tip Top Collection",
              "quantity": 15,
              "priceTotal": 9.5
            }
          ],
          "commerce": {
            "productViews": {
              "value": 1
            }
          },
          "_experience": {
            "campaign": {
              "message": {
                "profileSnapshot": {
                  "workEmail": {
                    "address": "rogerkanagawa@example.com"
                  }
                }
              }
            }
          }
        }
      }
    },
    {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
        },
        "imsOrgId": "{IMS_ORG}",
        "source": {
          "name": "GettingStarted"
        },
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      }
    },
    {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
        },
        "imsOrgId": "invalidIMSOrg@AdobeOrg",
        "source": {
          "name": "GettingStarted"
        },
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
          "timestamp": "2019-02-23T22:07:01Z",
          "environment": {
            "browserDetails": {
              "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
              "acceptLanguage": "en-US",
              "cookiesEnabled": true,
              "javaScriptVersion": "1.6",
              "javaEnabled": true
            },
            "colorDepth": 32,
            "viewportHeight": 799,
            "viewportWidth": 414
          },
          "productListItems": [
            {
              "SKU": "CC",
              "name": "Carmine Santiago",
              "quantity": 10,
              "priceTotal": 5.5
            }
          ],
          "commerce": {
            "productViews": {
              "value": 1
            }
          },
          "_experience": {
            "campaign": {
              "message": {
                "profileSnapshot": {
                  "workEmail": {
                    "address": "mohandeewar@example.com"
                  }
                }
              }
            }
          }
        }
      }
    },
   {
      "header": {
        "schemaRef": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
          "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
        },
        "imsOrgId": "{IMS_ORG}",
        "source": {
          "name": "GettingStarted"
        },
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
          "timestamp": "2019-02-23T22:07:01Z",
          "environment": {
            "browserDetails": {
              "userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
              "acceptLanguage": "en-US",
              "cookiesEnabled": true,
              "javaScriptVersion": "1.6",
              "javaEnabled": true
            },
            "colorDepth": 32,
            "viewportHeight": 799,
            "viewportWidth": 414
          },
          "productListItems": [
            {
              "SKU": "CC",
              "name": "Tip Top Collection",
              "quantity": 15,
              "priceTotal": 9.5
            }
          ],
          "commerce": {
            "productViews": {
              "value": 1
            }
          }
        }
      }
    },
    {
      "header": {
        "msgType": "xdmEntityCreate",
        "msgId": "79d2e715-f25f-4c36",
        "xdmSchema": {
          "name": "_xdm.context.experienceevent"
        },
        "imsOrgId": "{IMS_ORG}",
        "source": {
          "name": "GettingStarted"
        },
        "datasetId": "{DATASET_ID}",
        "createdAt": 1526283801869
      },
      "body": {
        "xdmMeta": {
          "xdmSchema": {
            "name": "_xdm.context.experienceevent"
          }
        },
        "xdmEntity": {
          "_id": "abc",
          "dataSource": {
            "_id": "http://abc.com/abc"
          },
          "timestamp": "2018-05-18T15:28:25Z",
          "endUserIDs": {
            "_vendor": {
              "adobe": {
                "experience": {
                  "mcId": {
                    "id": "http://abc.com/abc"
                  }
                }
              }
            }
          }
        }
      }
    }
  ]
}'

Réponse
La charge utile de réponse inclut un état pour chaque message, ainsi qu’un GUID dans le xactionId qui peut être utilisé pour le suivi.
{
    "inletId": "9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5",
    "batchId": "1565638336649:1750:244",
    "receivedTimeMs": 1565638336705,
    "responses": [
        {
            "xactionId": "1565650704337:2124:92:3"
        },
        {
            "statusCode": 400,
            "message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{IMS_ORG}] Message has unknown xdm format"
        },
        {
            "statusCode": 400,
            "message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{IMS_ORG}] Message has an absent or wrong ims org in the header"
        },
        {
            "statusCode": 400,
            "message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{IMS_ORG}] Message has unknown xdm format"
        }
    ]
}

L’exemple de réponse ci-dessus affiche des messages d’erreur pour la requête précédente. En comparant cette réponse à la réponse valide précédente, vous pouvez constater que la demande a abouti à un succès partiel, avec un message correctement ingéré et trois messages qui ont abouti à un échec. Notez que les deux réponses renvoient un code d’état "207". Pour plus d'informations sur les codes d'état, consultez le tableau des codes de réponse dans l'annexe de ce didacticiel.
Le premier message a été envoyé avec succès à Plateforme et n'est pas affecté par les résultats des autres messages. Par conséquent, lorsque vous tentez de renvoyer les messages ayant échoué, vous n’avez pas besoin de réinclure ce message.
Le second message a échoué car il manquait de corps de message. La demande de collection attend des éléments de message qu’ils comportent des sections d’en-tête et de contenu valides. L’ajout du code suivant après l’en-tête du deuxième message corrige la demande, ce qui permet au deuxième message de réussir la validation :
      "body": {
        "xdmMeta": {
          "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
          }
        },
        "xdmEntity": {
          "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
          "timestamp": "2019-02-23T22:07:01Z",
        }
    },

Le troisième message a échoué en raison d'un ID d'organisation IMS non valide utilisé dans l'en-tête. L’organisation IMS doit correspondre à à laquelle vous essayez de publier du contenu. Pour déterminer l'ID d'organisation IMS correspondant à la connexion de flux continu que vous utilisez, vous pouvez exécuter une GET inlet requête à l'aide de l'API d'importation de données. Voir récupération d’une connexion de flux continu pour obtenir un exemple de récupération des connexions de flux continu précédemment créées.
Le quatrième message a échoué car il ne suivait pas le schéma XDM attendu. Les xdmSchema éléments inclus dans l’en-tête et le corps de la requête ne correspondent pas au schéma XDM du {DATASET_ID} . La correction du schéma dans l’en-tête et le corps du message lui permet de transmettre la validation DCCS et d’être envoyé avec succès à la plateforme. Le corps du message doit également être mis à jour pour correspondre au schéma XDM du {DATASET_ID} pour qu’il puisse transmettre la validation en flux continu sur la plate-forme. Pour plus d'informations sur ce qui arrive aux messages qui arrivent à être diffusés sur Plate-forme, consultez la section Confirmer les messages assimilés de ce didacticiel.

Récupérer les messages ayant échoué à partir de la plate-forme

Les messages en échec sont identifiés par un code d'état d'erreur dans le tableau de réponses. Les messages non valides sont collectés et stockés dans un lot "erreur" dans le jeu de données spécifié par {DATASET_ID} .
Pour plus d'informations sur la récupération des messages de lots ayant échoué, consultez le guide de récupération des lots ayant échoué.

Confirmer les messages ingérés

Les messages qui réussissent la validation DCCS sont diffusés en continu sur la plateforme. Sur Plate-forme, les messages de lot sont testés par validation en flux continu avant d'être ingérés dans le lac de données. L'état des lots, qu'ils réussissent ou non, s'affiche dans le jeu de données spécifié par {DATASET_ID} .
Vous pouvez vue l’état des messages par lot qui sont diffusés sur la plateforme à l’aide de l’interface utilisateur de la plateforme d’expérience en accédant à l’onglet Datasets , en cliquant sur le jeu de données auquel vous diffusez en continu et en cochant l’onglet Activité du jeu de données.
Les messages par lots qui passent la validation en flux continu sur la plateforme sont assimilés dans le lac de données. Les messages sont alors disponibles pour analyse ou exportation.

Étapes suivantes

Maintenant que vous savez comment envoyer plusieurs messages dans une seule requête et vérifier quand les messages sont correctement assimilés dans le jeu de données de cible, vous pouvez début de diffuser vos propres données vers Platform. Pour un aperçu de la façon de requête et de récupérer les données assimilées à partir de la plateforme, voir le guide d'accès aux données.

Annexe

Cette section contient des informations supplémentaires pour le didacticiel.

Codes de réponse :

Le tableau suivant affiche les codes d’état renvoyés par les messages de réponse réussis et non réussis.
Code d'état
Description
207
Bien que '207' soit utilisé comme code d'état global de la réponse, le destinataire doit consulter le contenu de l'organisme de réponse à plusieurs états pour plus d'informations sur la réussite ou l'échec de l'exécution de la méthode. Le code de réponse est utilisé en cas de succès, de succès partiel et également en cas d’échec.
400
Il y a eu un problème avec la demande. Consultez le corps de la réponse pour obtenir un message d’erreur plus spécifique (par exemple, les champs obligatoires manquaient pour la charge du message ou le format xdm du message était inconnu).
401
Non autorisé : en-tête d'autorisation valide manquante pour la demande. Ceci est renvoyé uniquement pour les entrées pour lesquelles l’authentification est activée.
403
Non autorisé : Le jeton d'autorisation fourni n'est pas valide ou a expiré. Ceci est renvoyé uniquement pour les entrées pour lesquelles l’authentification est activée.
413
Charge utile trop importante - envoyée lorsque la demande de charge totale est supérieure à 1 Mo.
429
Trop de requêtes dans une durée spécifiée.
500
Erreur lors du traitement de la charge utile. Consultez le corps de la réponse pour obtenir un message d’erreur plus spécifique (par exemple, schéma de charge utile de message non spécifié, ou ne correspond pas à la définition XDM dans Platform).
503
Le service n'est pas disponible actuellement. Les clients doivent réessayer au moins 3 fois en utilisant une stratégie de sauvegarde exponentielle.