Show Menu
SUJETS×

Utilisation de l’exécution du service de prise de décision à l’aide d’API

Ce document fournit un didacticiel sur l’utilisation des services d’exécution liés à l’ Decisioning Service utilisation des API d’Adobe Experience Platform.

Prise en main

Ce didacticiel nécessite une bonne compréhension des Experience Platform services impliqués dans la prise de décision et la détermination de la prochaine meilleure offre à présenter lors des expériences client. Avant de commencer ce didacticiel, consultez la documentation relative aux éléments suivants :
Les sections suivantes contiennent des informations supplémentaires que vous devez connaître pour pouvoir invoquer les Platform API.

Lecture des exemples d’appels d’API

Ce didacticiel 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 la façon de lire des exemples d’appels d’API dans le guide de Experience Platform dépannage.

Rassembler les valeurs des en-têtes requis

Pour lancer des appels aux Platform API, 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’ Experience Platform API, comme indiqué ci-dessous :
  • Autorisation : Porteur {ACCESS_TOKEN}
  • x-api-key : {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
Toutes les ressources de Experience Platform sont isolées à des sandbox virtuels spécifiques. Toutes les requêtes aux Platform API 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.
Toutes les requêtes qui contiennent une charge utile (POST, PUT, PATCH) nécessitent un en-tête supplémentaire :
  • Content-Type : application/json
Également requis pour les demandes d’exécution :
  • x-request-id : {UUID}
UUID est une chaîne au format UUID unique au niveau mondial et ne doit pas être réutilisée pour différents appels d’API.
Decisioning Service est contrôlée par un certain nombre d’objets commerciaux qui sont liés les uns aux autres. Tous les objets d’entreprise sont stockés dans le référentiel d’objets Platform’s métier, le référentiel d’objets XDM Core. L'une des principales fonctionnalités de ce référentiel est que les API sont orthogonales par rapport au type d'objet métier. Au lieu d'utiliser une API POST, GET, PUT, PATCH ou DELETE qui indique le type de ressource dans son point de terminaison API, il n'y a que 6 points de terminaison génériques, mais ils acceptent ou retournent un paramètre qui indique le type de l'objet lorsque cette désambiguïfication est nécessaire. Le schéma doit être enregistré dans le référentiel, mais au-delà, le référentiel est utilisable pour un ensemble ouvert de types d'objet.
Chemins d’accès aux points de terminaison pour tous les API du référentiel d’objets de base XDM début https://platform.adobe.io/data/core/ode/ .
Le premier élément de chemin suivant le point de terminaison est le containerId . Cet identifiant est obtenu via le point de terminaison racine du référentiel d’objets de base XDM GET https://platform.adobe.io/data/core/xcore/ .

Compilation de modèles de décision

L'activation des entités logiques métier se produit automatiquement et en permanence. Dès qu'une nouvelle option est enregistrée dans le référentiel et qu'elle est marquée comme "approuvée", elle sera candidate à l'inclusion de l'ensemble d'options disponibles. Dès qu'une règle de décision est mise à jour, l'ensemble de règles est réassemblé et préparé pour l'exécution. À cette étape d’activation automatique, toutes les contraintes définies par la logique métier qui ne dépendent pas du contexte d’exécution seront évaluées. Les résultats de cette étape d’activation sont envoyés dans un cache où ils sont disponibles pour l’ Decisioning Service exécution.

Effets des placements, des filtres et des états de cycle de vie

Les Offres sont créées en continu, leur état de cycle de vie change ou elles peuvent obtenir de nouvelles représentations de contenu. Le filtre d’offre d’une activité peut changer, correspondre ou filtrer les offres dont les jeux de balises ont été mis à jour. Ce processus peut être relativement impliqué et les demandes et les services doivent savoir quel sera le groupe de candidats à l'activité qui en résultera. L’exécution de la décision fournit une API activité à offre qui filtres les offres qui ne sont pas approuvées, ne correspondent pas au filtre d’offre ou n’ont pas de représentation pour l’emplacement référencé par l’activité.
Requête
curl -X GET {DECISION_SERVICE_ENDPOINT_PATH}/{CONTAINER_ID}/offers?activityId={ACTIVITY_URI}' \
  -H 'Accept: application/vnd.adobe.xdm+json \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'x-request-id: {NEW_UUID}'

Réponse
Le paramètre activityId peut être répété dans l’url et jusqu’à 30 références d’activité différentes peuvent être données dans une seule requête. La réponse sera utile pour repérer les circonstances inattendues résultant de la configuration et ressemblera à :
{
  "xdm:activityOffers": [
    {
      "xdm:offerActivity": {
        "@id": "{ACTIVITY_URI}",
        "_links": {
          "self": {
            "href": "{repository_endpoint}/{CONTAINER_ID}/instances/{ACTIVITY_INSTANCE_ID}"
          }
        },
        "repo:etag": "1"
      },
      "xdm:offers": [
        {
          "@id": "{OFFER_URI_1}",
          "_links": {
            "self": {
              "href": "{REPOSITORY_ENDPOINT}/{CONTAINER_ID}/instances/{OFFER_INSTANCE_ID_1}"
            }
          },
          "repo:etag": "15"
        },
        {
          "@id": "{OFFER_URI_2}",
          "_links": {
            "self": {
              "href": "{REPOSITORY_ENDPOINT}/{CONTAINER_ID}/instances/{OFFER_INSTANCE_ID_2}"
            }
          },
          "repo:etag": "5"
        }
      ],
      "xdm:fallbackOffer": {
        "@id": "{FALLBACK_URI}",
        "_links": {
          "self": {
            "href": "{REPOSITORY_ENDPOINT}/{CONTAINER_ID}/instances/{FALLBACK_INSTANCE_ID}"
          }
        },
        "repo:etag": "2"
      }
    }
  ]
}

Un léger délai de quelques secondes s’écoule entre le moment où les objets ont été mis à jour et celui où la réponse de l’API reflète le mappage activité-offre. La révision de chaque objet est indiquée dans la réponse afin que les clients puissent vérifier s’il existe une mise à jour des objets qui n’a pas été reflétée.

API de diagnostic et dépannage

Les Activités, offres et règles d'éligibilité sont compilées dans un format interne (catalogue d'offres d’exécution) utilisé par le runtime du service de décision. La compilation peut détecter des erreurs qui n'ont pas été détectées par les vérifications effectuées lorsque les objets ont été stockés et que des liens ont été établis dans le référentiel d'objets de base XDM.
Une API de diagnostic est fournie pour obtenir toutes les erreurs de compilation survenues au cours de cette étape et, au cas où il n’y aurait aucune erreur pour obtenir des informations sur le moment où les règles et les activités ont été recompilées pour la dernière fois.
Requête
curl -X GET {DECISION_SERVICE_ENDPOINT_PATH}/{CONTAINER_ID}/diagnostics \
  -H 'Accept: application/vnd.adobe.xdm+json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'x-request-id: {NEW_UUID}'

Le seul paramètre pour cet appel d'API est containerId . Le résultat est toutes les mises à jour de tous les clients qui ont modifié les règles de décision, les offres, les activités ou les filtres d'offre dans ce conteneur. Il y a un léger retard de quelques secondes entre le moment où les objets ont été mis à jour et le moment où la compilation se termine. L'horodatage de la dernière mise à jour et les erreurs éventuelles sont renvoyés dans la réponse à l'appel de diagnostic.
Réponse
{
  "xdm:operations": {
    "xdm:offerCatalogUpdate": {
      "xdm:date": "2019-06-19T23:28:44.855Z",
      "xdm:errors": []
    },
    "xdm:activitiesUpdate": {
      "xdm:date": "2019-06-19T23:28:40.114Z",
      "xdm:errors": []
    }
  }
}

Appels de l'API REST pour exécuter les décisions

L’API REST est l’un des itinéraires pour les applications s’exécutant au-dessus de Platform afin d’obtenir la meilleure expérience possible en fonction des règles, modèles et contraintes définis par l’entreprise pour ses utilisateurs. Les applications envoient l’une des identités du profil (ID de profil et espace de nommage d’identité) qui Decisioning Service recherche le profil et les informations sont utilisées pour appliquer la logique métier. Des données contextuelles supplémentaires peuvent être transmises à la demande et si elles sont spécifiées dans les règles de fonctionnement, elles seront incluses dans les données pour prendre la décision.
Les applications peuvent obtenir de meilleures performances en demandant une décision pour jusqu'à 30 activités à la fois. Les URI des activités sont transmis dans la même requête. L’API REST est synchrone et renvoie les options proposées pour toutes ces activités ou l’option de secours si aucune option de personnalisation ne satisfait aux contraintes.
Il est possible que deux activités différentes proposent la même option que leur "meilleur". Pour éviter de répéter une expérience composée, Decisioning Service arbitre par défaut entre les activités référencées dans la même requête. L'arbitrage signifie que pour chacune des activités, les options du top N sont prises en considération, mais aucune option ne sera proposée à plusieurs reprises dans ces activités. Si deux activités ont la même option classée en tête de liste, l'une d'elles sera élue pour utiliser son deuxième meilleur choix ou son troisième meilleur, etc. Ces règles de déduplication tentent d'éviter que l'une des activités n'utilise son option de secours.
La demande de décision contient les arguments qu'elle contient pour une demande POST. Le corps est formaté en tant que valeur d’ Content-Type en-tête JSON. application/vnd.adobe.xdm+json; schema="{REQUEST_SCHEMA_AND_VERSION}"
Le schéma de demande et la version pris en charge pour l’instant sont https://ns.adobe.com/experience/offer-management/decision-request;version=0.9 . À l’avenir, d’autres schémas ou versions de demande seront fournis.
Requête
curl -X POST {DECISION_SERVICE_ENDPOINT_PATH}/{CONTAINER_ID}/decisions \
  -H 'Accept: application/json, application/problem+json \
  -H '
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'x-request-id: {NEW_UUID}' \
  -d '{
  "xdm:dryRun": {DRY_RUN_TRUE_FALSE},
  "xdm:validateContextData": {VALIDATE_CONTEXT_DATA_TRUE_FALSE},

  "xdm:offerActivities":[
    {
      "xdm:offerActivity": "{ACTIVITY_URI_1}"
    },
  ],
  "xdm:identityMap":{
    "{PROFILE_ID_NAMESPACE_CODE}":[
      {
        "xdm:id":"{PROFILE_ID}"
      }
    ]
  },
  "xdm:profileModel":"{PROFILE_MODEL}",
  "xdm:contextData": [
    {
      "@type": "{CONTEXT_DATASSCHEMA_ID}"
      "xdm:data": { JSON PROPERTIES OF CONTEXT ENTITY }
    }
  ] ,
  "xdm:allowDuplicatePropositions": {
    "xdm:acrossActivities": {DUPLICATE_OFFER_IDS_OF_TRUE_FALSE},
  }
}’

  • xdm:dryRun - Lorsque la valeur de cette propriété facultative est définie sur true, la demande de décision obéira à des contraintes de plafonnement mais ne tirera pas réellement ces compteurs, il est prévu que l'appelant n'a jamais l'intention de présenter la proposition au profil. La proposition Decisioning Service ne sera pas enregistrée comme événement officiel de décision XDM et ne figurera pas dans les ensembles de données de rapports. La valeur par défaut de cette propriété est false et lorsque la propriété est omise, la décision n'est pas considérée comme une série d'essais et doit donc être présentée à l'utilisateur final.
  • xdm:validateContextData - Cette propriété facultative active ou désactive la validation des données contextuelles. Si la validation est activée, pour chaque élément de données contextuelles fourni, le schéma (d’après le @type champ) est extrait du registre XDM et l’ xdm:data objet est validé par rapport à celui-ci.
La demande par ce schéma contient un tableau d'URI référençant les activités d'offre, une identité de profil et un tableau d'éléments de données contextuelles :
  • xdm:offerActivities - Cette propriété obligatoire est un tableau d'objets où chaque élément contient des données sur l'activité d'offre. L’activité d’offre possède les propriétés suivantes :
    • xdm:offerActivity - L'identificateur unique (URI) de l'activité. Il s’agit de la valeur de la @id propriété de l’activité d’offre.
  • xdm:identityMap - Propriété obligatoire contenant un objet JSON conforme au schéma XDM https://ns.adobe.com/xdm/context/identitymap . La propriété définit un mappage où la clé est un code d’espace de nommage d’identité et la valeur est une liste d’identifiants d’utilisateur final dans l’espace de nommage donné. Si m.
  • xdm:contextData - Propriété facultative contenant des éléments décrits par une référence à leur schéma. Chaque élément de données contextuelles du tableau doit avoir les propriétés suivantes :
    • @type - Propriété obligatoire référençant le schéma XDM de l'objet dans cet élément.
    • xdm:data - Propriété obligatoire contenant les propriétés d'objet selon le schéma XDM indiqué dans la @type propriété.

Données contextuelles dynamiques dans les demandes de décision

La section précédente indique comment les objets XDM peuvent être transmis à une demande de décision. Voici un exemple de ce tableau d’objets contextuels :
"xdm:contextData": [
  {
    "@type":" https://ns.adobe.com/{TENANT_ID_OF_ORG}/schemas/{NUMERIC_SCHEMA_ID};version=1",
    "xdm:data":{ 
      "{TENANT_ID_OF_ORG}": {
        "productDetails":{ 
          "xdm:gender":      "unisex",
          "xdm:fabrication": "leather",
          "xdm:category":    "wallets",
        }
      }
    }
  }
]

Le schéma doit avoir été construit par votre organisation. Pour en savoir plus sur la construction de schémas, consultez le didacticiel de l'éditeur de Schémas. Votre schéma sera dans un espace de nommage https://ns.adobe.com/{TENANT_ID}/schemas .
Le guide du développeur de l'API Schéma Registry explique comment accéder aux schémas par programmation et comment un développeur obtient l'ID de client et l'identifiant numérique de votre schéma. Le numéro de version est requis et est également fourni par les API du Registre du schéma.
Un schéma défini par une organisation a généralement une propriété racine nommée _{TENANT_ID} , également appelée chaîne d'espace de nommage du client. Notez que les propriétés utilisées à partir d’un composant de schéma global tel que _ https://ns.adobe.com/xdm/context/product ont un préfixe d’espace de nommage xdm: . Dans ce cas, la propriété définie par l’organisation productDetails a été construite avec ce type de données. Bien que les propriétés du client soient imbriquées dans une propriété nommée d’après l’espace de nommage du client, les types de données disponibles dans le monde entier utilisent le préfixe réservé xdm: pour empêcher les collisions de noms de propriété.
Plusieurs objets de données peuvent être répertoriés dans la xdm:contextData propriété. Chaque objet doit identifier son type via la @type propriété. Les valeurs des objets de données contextuelles peuvent être utilisées dans des expressions PQL, par exemple dans la condition d’une règle d'éligibilité. L'objet de données contextuelles doit être traité par l'expression spéciale de référence de chemin @{schemaId} . Les expressions qui suivent cette expression de référence sont des expressions de chemin d’accès régulières qui accèdent aux propriétés de l’objet de données :
{
  "xdm:name": "Eligible for a free gender-specific item of interest",
  "xdm:condition": {
    "xdm:value":
      "gender in (\"female\",\"non-specific\")  
       and (
         select p from
           @{https://ns.adobe.com/{TENANT_ID}/schemas/{NUMERIC_SCHEMA_ID}}._{TENANT_ID}
         select e from xEvent 
            where e.type = \"productSearch\" 
              and e.category = p.category 
              and p.gender in (\"female\",\"unisex\")
       )",
    "xdm:format": "pql/text",
    "xdm:type": "PQL"
  }
}

Dans l’exemple ci-dessus, la variable p effectue une itération sur le tableau des objets marqués avec le @type = https://ns.adobe.com/{TENANT_ID}/schemas/{NUMERIC_SCHEMA_ID}} .
Notez que la syntaxe PQL n’utilise pas de préfixes dans les noms de propriété. Par défaut, les propriétés globales sont simplement référencées sans le xdm: préfixe. Les propriétés définies par votre organisation sont imbriquées dans une propriété supplémentaire nommée d’après l’espace de nommage locataire (dans l’exemple indiqué par la variable {TENANT_ID} ). Pour pouvoir référencer directement les propriétés personnalisées, la variable p est liée au résultat du chemin qui déréférence la propriété d’imbrication supplémentaire.

Utilisation des enregistrements de profil

Tous les enregistrements des entités de événement de profil et d’expérience sont déjà gérés dans le magasin de profils. En transmettant une ou plusieurs identités de profil à la demande, le profil de ces identités sera identifié et consulté à partir du magasin. Les données sont alors automatiquement disponibles pour les règles de décision et les modèles évalués par la stratégie de décision.
Pour récupérer les enregistrements de profil et d’expérience, la stratégie de fusion par défaut est appliquée. Notez qu’après avoir téléchargé des enregistrements de profil dans la Platform base de données, il y a un léger retard jusqu’à ce que les enregistrements de profil puissent être recherchés. Il en va de même pour l’assimilation d’enregistrements de profil et d’expérience via les API de diffusion en continu, et ce n’est qu’après quelques secondes que les données seront disponibles pour l’évaluation des règles de décision qui évaluent les données du événement de profil et d’expérience.