[Ultimate]{class="badge positive"}

Connexion API HTTP

Présentation overview

La destination de l’API HTTP est une destination en flux continu Adobe Experience Platform qui vous aide à envoyer des données de profil à des points d’entrée HTTP tiers.

Pour envoyer des données de profil à des points d’entrée HTTP, vous devez d’abord vous connecter à la destination dans Adobe Experience Platform.

Cas d’utilisation use-cases

La destination de l’API HTTP vous permet d’exporter les données de profil XDM et les audiences vers des points de terminaison HTTP génériques. Vous pouvez y lancer vos propres analyses ou effectuer toute autre opération dont vous pourriez avoir besoin sur les données de profil exportées hors d’Experience Platform.

Les points d’entrée HTTP peuvent être les systèmes des client(e)s ou des solutions tierces.

Audiences prises en charge supported-audiences

Cette section décrit les types d’audiences que vous pouvez exporter vers cette destination.

Type et fréquence d’exportation export-type-frequency

Reportez-vous au tableau ci-dessous pour plus d’informations sur le type et la fréquence d’exportation des destinations.

Conditions préalables prerequisites

Pour utiliser la destination d’API HTTP pour exporter des données en dehors d’Experience Platform, vous devez respecter les conditions préalables suivantes :

Prise en charge et certificat du protocole mTLS mtls-protocol-support

Vous pouvez utiliser Mutual Transport Layer Security (mTLS) pour garantir une sécurité renforcée dans les connexions sortantes à vos connexions de destination d’API HTTP.

mTLS est une méthode de sécurité de bout en bout pour l’authentification mutuelle qui garantit que les deux parties partageant des informations sont celles qu’elles prétendent être avant que les données ne soient partagées. mTLS comprend une étape supplémentaire par rapport à TLS, dans laquelle le serveur demande également le certificat du client et le vérifie à sa fin.

Si vous souhaitez utiliser mTLS avec des destinations HTTP API, l’adresse du serveur que vous avez indiquée dans la page détails de destination doit avoir TLS protocoles désactivés et seulement mTLS activé. Si le protocole TLS 1.2 est toujours activé sur le point de terminaison , aucun certificat n’est envoyé pour l’authentification du client. Cela signifie que pour utiliser mTLS avec votre destination HTTP API, votre point d’entrée de serveur "récepteur" doit être un point d’entrée de connexion activé uniquement mTLS.

Télécharger le certificat certificate

Si vous souhaitez vérifier que Common Name (CN) et Subject Alternative Names (SAN) effectuent une validation tierce supplémentaire, vous pouvez télécharger le certificat ci-dessous :

Vous pouvez également récupérer les certificats publics en toute sécurité en effectuant une requête GET sur le point de terminaison MTLS. Pour plus d’informations, consultez la documentation du point d’entrée de certificat public .

Liste autorisée d’adresses IP ip-address-allowlist

Pour répondre aux exigences de sécurité et de conformité des clients, Experience Platform fournit une liste des adresses IP statiques que vous pouvez inscrire sur la liste autorisée pour la destination de l’API HTTP. Reportez-vous à la liste autorisée d’adresses IP pour les destinations de diffusion en continu pour obtenir la liste complète des adresses IP à placer sur la liste autorisée.

Types d’authentification pris en charge supported-authentication-types

La destination API HTTP prend en charge plusieurs types d’authentification à votre point d’entrée HTTP :

curl --location --request POST '<YOUR_API_ENDPOINT>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<CLIENT_ID>' \
--data-urlencode 'client_secret=<CLIENT_SECRET>'

curl --location --request POST 'https://some-api.com/token' \
--header 'Authorization: Basic base64(clientId:clientSecret)' \
--header 'Content-type: application/x-www-form-urlencoded; charset=UTF-8' \
--data-urlencode 'grant_type=client_credentials'

Se connecter à la destination connect-destination

Pour vous connecter à cette destination, procédez comme décrit dans le tutoriel sur la configuration des destinations. Lors de la connexion à cette destination, vous devez fournir les informations suivantes :

Informations d’authentification authentication-information

Authentification par jeton porteur bearer-token-authentication

Si vous sélectionnez le type d’authentification Jeton porteur pour vous connecter à votre point d’entrée HTTP, saisissez les champs ci-dessous et sélectionnez Se connecter à la destination  :

Aucune authentification no-authentication

Si vous sélectionnez le type d’authentification Aucune pour vous connecter à votre point d’entrée HTTP :

Lorsque vous sélectionnez cette ouverture d’authentification, il vous suffit de sélectionner Se connecter à la destination et la connexion à votre point d’entrée est établie.

Authentification par mot de passe OAuth 2 oauth-2-password-authentication

Si vous sélectionnez le type d’authentification Mot de passe OAuth 2 pour vous connecter à votre point d’entrée HTTP, saisissez les champs ci-dessous et sélectionnez Se connecter à la destination  :

Authentification avec informations d’identification du client OAuth 2 oauth-2-client-credentials-authentication

Si vous sélectionnez le type d’authentification Informations d’identification du client OAuth 2 pour vous connecter à votre point d’entrée HTTP, saisissez les champs ci-dessous et sélectionnez Se connecter à la destination  :

Renseigner les détails de la destination destination-details

Pour configurer les détails de la destination, renseignez les champs obligatoires et facultatifs ci-dessous. Un astérisque situé en regard d’un champ de l’interface utilisateur indique que le champ est obligatoire.

Activer les alertes enable-alerts

Vous pouvez activer les alertes pour recevoir des notifications sur le statut de votre flux de données vers votre destination. Sélectionnez une alerte dans la liste et abonnez-vous à des notifications concernant le statut de votre flux de données. Pour plus d’informations sur les alertes, consultez le guide sur l’abonnement aux alertes des destinations dans l’interface utilisateur.

Lorsque vous avez terminé de renseigner les détails sur votre connexion de destination, sélectionnez Suivant.

Activer des audiences vers cette destination activate

Pour obtenir des instructions sur l’activation des audiences vers cette destination, reportez-vous à la section Activation des données d’audience vers des destinations d’exportation de profils en continu .

Attributs de destination attributes

Lors de l’étape Sélectionner des attributs, Adobe recommande de sélectionner un identifiant unique dans votre schéma d’union. Sélectionnez l’identifiant unique et tout autre champ XDM que vous souhaitez exporter vers la destination.

Comportement d’exportation de profils profile-export-behavior

Experience Platform optimise le comportement d’exportation de profils vers votre destination d’API HTTP, afin de n’exporter les données vers votre point de terminaison d’API que lorsque des mises à jour pertinentes d’un profil se sont produites à la suite de la qualification de l’audience ou d’autres événements significatifs. Les profils sont exportés vers votre destination dans les situations suivantes :

Dans tous les cas décrits ci-dessus, seuls les profils pour lesquels des mises à jour pertinentes se sont produites sont exportés vers votre destination. Par exemple, si une audience mappée au flux de destination comporte cent membres et que cinq nouveaux profils sont éligibles à ce segment, l’exportation vers votre destination est incrémentielle et inclut uniquement les cinq nouveaux profils.

Notez que tous les attributs mappés sont exportés pour un profil, quel que soit l’emplacement des modifications. Ainsi, dans l’exemple ci-dessus, tous les attributs mappés pour ces cinq nouveaux profils seront exportés même si les attributs eux-mêmes restent inchangés.

Ce qui détermine une exportation de données et ce qui est inclus dans l’exportation what-determines-export-what-is-included

Concernant les données exportées pour un profil donné, il est important de comprendre les deux concepts différents entre ce qui détermine l’exportation de données vers votre destination d’API HTTP et les données incluses dans l’exportation.

Prenons l’exemple d’un flux de données vers une destination HTTP dans lequel trois audiences sont sélectionnées et quatre attributs sont mappés à la destination.

Une exportation de profil vers la destination peut être déterminée par un profil éligible ou sortant de l’un des trois segments mappés. Cependant, dans l’exportation des données, dans l’objet segmentMembership (voir la section Données exportées ci-dessous), d’autres audiences non mappées peuvent apparaître, si ce profil particulier en est membre et si elles partagent la même stratégie de fusion que l’audience qui a déclenché l’exportation. Si un profil est admissible pour le segment Customer with DeLorean Cars, mais qu’il est également membre du film Watched "Back to the Future" et des segments Science fiction fan, ces deux autres audiences seront également présentes dans l’objet segmentMembership de l’exportation de données, même si elles ne sont pas mappées dans le flux de données, si elles partagent la même stratégie de fusion Client avec des DeLorean Cars.

Du point de vue des attributs de profil, toute modification apportée aux quatre attributs mappés ci-dessus déterminera une exportation de destination et chacun de ces quatre attributs mappés et présents sur le profil sera présent dans l’exportation des données.

Renvoyer des données historiques historical-data-backfill

Lorsque vous ajoutez une nouvelle audience à une destination existante, ou lorsque vous créez une destination et que vous mappez des audiences avec celle-ci, l’Experience Platform exporte les données historiques de qualification des audiences vers la destination. Les profils qui remplissent les critères de l’audience avant l’audience a été ajoutée à la destination sont exportés vers la destination dans un délai d’environ une heure.

Données exportées exported-data

Les données Experience Platform exportées arrivent dans votre destination HTTP au format JSON. Par exemple, l’exportation ci-dessous contient un profil qualifié pour un certain segment, qui est membre de deux autres segments et qui a quitté un autre segment. L’exportation inclut également le prénom, le nom, la date de naissance et l’adresse e-mail personnelle de l’attribut de profil. Les identités de ce profil sont ECID et e-mail.

{
  "person": {
    "birthDate": "YYYY-MM-DD",
    "name": {
      "firstName": "John",
      "lastName": "Doe"
    }
  },
  "personalEmail": {
    "address": "john.doe@acme.com"
  },
  "segmentMembership": {
   "ups":{
      "7841ba61-23c1-4bb3-a495-00d3g5fe1e93":{
         "lastQualificationTime":"2022-01-11T21:24:39Z",
         "status":"exited"
      },
      "59bd2fkd-3c48-4b18-bf56-4f5c5e6967ae":{
         "lastQualificationTime":"2022-01-02T23:37:33Z",
         "status":"realized"
      },
      "947c1c46-008d-40b0-92ec-3af86eaf41c1":{
         "lastQualificationTime":"2021-08-25T23:37:33Z",
         "status":"realized"
      },
      "5114d758-ce71-43ba-b53e-e2a91d67b67f":{
         "lastQualificationTime":"2022-01-11T23:37:33Z",
         "status":"realized"
      }
   }
},
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

Vous trouverez ci-dessous d’autres exemples de données exportées, en fonction des paramètres de l’interface utilisateur que vous sélectionnez dans le flux de connexion à la destination pour les options Inclure les noms de segment et Inclure la date et l’heure de segment  :

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
            "name": "First name equals John"
          }
        }
      }

"segmentMembership": {
        "ups": {
          "5b998cb9-9488-4ec3-8d95-fa8338ced490": {
            "lastQualificationTime": "2019-04-15T02:41:50+0000",
            "status": "realized",
            "createdAt": 1648553325000,
            "updatedAt": 1648553330000,
            "mappingCreatedAt": 1649856570000,
            "mappingUpdatedAt": 1649856570000,
          }
        }
      }

Politique de limitation et de reprise limits-retry-policy

Dans 95 % des cas, Experience Platform tente d’offrir une latence de débit inférieure à 10 minutes pour les messages envoyés avec succès, avec un taux de moins de 10 000 demandes par seconde pour chaque flux de données vers une destination HTTP.

En cas d’échec des requêtes vers la destination API HTTP, Experience Platform stocke les requêtes ayant échoué et tente à deux reprises d’envoyer les requêtes à votre point d’entrée.