API de migration vers la prise de décision decisioning-migration-api

Sur cette page : utilisez l’API Decisioning Migration Service pour déplacer les objets de gestion des décisions entre les sandbox avec une analyse des dépendances automatisée et la prise en charge de la restauration, afin que vous puissiez transférer le contenu de prise de décision entre les environnements tout en préservant l’intégrité des données.

L’API Decisioning Migration Service vous permet de migrer des objets de gestion des décisions d’un sandbox à un autre. Le processus de migration s’exécute sous la forme de workflows asynchrones qui incluent l’analyse des dépendances, l’exécution et des fonctionnalités de restauration facultatives.

Cette API vous permet de transférer en toute transparence votre contenu de prise de décision entre les environnements tout en préservant l’intégrité des données et les relations.

Pour en savoir plus sur les avantages et les fonctionnalités de la prise de décision par rapport à la gestion des décisions, consultez cette page.

Fonctionnalités capabilities

L’API Decisioning Migration Service offre les fonctionnalités suivantes :

Conditions préalables prerequisites

Autorisations nécessaires permissions

Pour utiliser l’API Migration, vous avez besoin des autorisations appropriées dans les sandbox source et cible :

Sandbox source : accès en lecture aux objets de gestion des décisions

Sandbox cible : accès permettant de créer et modifier les objets de prise de décision

Parmi les autorisations standard figurent :

Préparer votre sandbox cible target-sandbox-preparation

Avant d’exécuter une migration, vérifiez que votre sandbox cible est correctement configuré :

Pour plus d’informations sur la gestion des sandbox, voir Utiliser et attribuer des sandbox.

Conditions préalables à la migration entre sandbox cross-sandbox-prerequisites

Lorsque le sandbox source est différent du sandbox cible, les éléments suivants sont requis :

Bases d’API api-basics

URL de base base-url

Utilisez l’URL de base suivante :

Authentification authentication

Toutes les requêtes API nécessitent les en-têtes suivants :

Pour obtenir des instructions détaillées sur la configuration de l’authentification, consultez le guide d’authentification de Journey Optimizer.

Workflow de migration migration-workflow

Le processus de migration se compose de deux étapes principales : l’analyse des dépendances et l’exécution de la migration. Pour une migration réussie, procédez comme suit.

Étape 1 : analyser les dépendances analyze-dependencies

Avant la migration, utilisez le workflow de dépendance pour identifier ce qui doit être mappé de la gestion des décisions à la prise de décision dans votre sandbox cible. Cette analyse vous aide à comprendre les relations entre les objets et à préparer les mappages nécessaires.

Créer un workflow de dépendance create-dependency-workflow

Utilisez l’appel API suivant pour créer un workflow d’analyse des dépendances.

Format d’API

POST /workflows/generate-dependencies

Dépendance au niveau du sandbox (à privilégier)

Commencez par une analyse au niveau du sandbox pour obtenir une vue complète de toutes les dépendances :

curl --request POST \
  --url "https://decisioning-migration.adobe.io/workflows/generate-dependencies?request-level=sandbox" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>" \
  --header "Content-Type: application/json" \
  --data '{
    "imsOrgId": "<IMS_ORG_ID>",
    "sourceSandboxDetails": { "sandboxName": "<SOURCE_SANDBOX_NAME>" },
    "targetSandboxDetails": { "sandboxName": "<TARGET_SANDBOX_NAME>" }
  }'

Dépendance au niveau de l’offre

Pour analyser les dépendances uniquement pour des offres spécifiques, appelez le même point d’entrée avec request-level=offer dans la chaîne de requête et fournissez un tableau offersList dans le corps avec les identifiants d’offre que vous souhaitez analyser.

Dépendance au niveau de la décision

Pour analyser les dépendances uniquement pour des décisions spécifiques, utilisez request-level=decision dans la chaîne de requête et fournissez un tableau decisionsList dans le corps avec les identifiants de décision à analyser.

Vérifier le statut du workflow de dépendance poll-dependency-status

Interrogez le workflow de dépendance pour vérifier quand l’analyse est terminée.

Format d’API

GET /workflows/generate-dependencies/{id}

Requête

curl --request GET \
  --url "https://decisioning-migration.adobe.io/workflows/generate-dependencies/<WORKFLOW_ID>" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>"

Lorsque le champ status affiche Completed, l’analyse des dépendances est prête. Utilisez le résultat du workflow pour créer vos mappages de dépendance de migration :

Vous indiquez ces mappages dans l’objet dependency de la demande de migration à l’étape 2.

Étape 2 : exécuter la migration execute-migration

Une fois que vous avez analysé les dépendances et préparé vos mappages, vous pouvez exécuter la migration.

Créer un workflow de migration create-migration-workflow

Utilisez les mappages de dépendance de l’étape 1 pour configurer et exécuter votre migration.

Format d’API

POST /workflows/migration

Migration au niveau des sandbox

Pour migrer tous les objets de prise de décision d’un sandbox à un autre :

curl --request POST \
  --url 'https://decisioning-migration.adobe.io/workflows/migration?request-level=sandbox' \
  --header 'Authorization: Bearer <IMS_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'x-gw-ims-org-id: <IMS_ORG_ID>' \
  --data '{
    "imsOrgId": "<IMS_ORG_ID>",
    "sourceSandboxDetails": { "sandboxName": "<SOURCE_SANDBOX_NAME>" },
    "targetSandboxDetails": { "sandboxName": "<TARGET_SANDBOX_NAME>" },
    "createDataStream": true,
    "dependency": {
      "profileAttributes": {
        "sourceAttr1": "targetAttr1"
      },
      "segments": {
        "sourceSegmentKey1": {
          "namespace": "<TARGET_SEGMENT_NAMESPACE>",
          "id": "<TARGET_SEGMENT_ID>"
        }
      },
      "contextAttributes": {
        "sourceCtx1": "targetCtx1"
      },
      "datasetName": "<TARGET_DATASET_NAME>"
    }
  }'

Migration au niveau des offres

Pour migrer des offres spécifiques uniquement, utilisez request-level=offer dans la chaîne de requête et ajoutez un tableau offersList au corps :

"offersList": ["offer-id-1", "offer-id-2"]

Migration au niveau des décisions

Pour migrer des décisions spécifiques uniquement, utilisez request-level=decision dans la chaîne de requête et ajoutez un tableau decisionsList au corps :

"decisionsList": ["decision-id-1", "decision-id-2"]

Champs de requête

Surveiller le statut de la migration poll-migration-status

Interrogez le workflow de migration pour suivre sa progression.

Format d’API

GET /workflows/migration/{id}

Requête

curl --request GET \
  --url "https://decisioning-migration.adobe.io/workflows/migration/<WORKFLOW_ID>" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>"

Résultats de la migration

Lorsque le champ status affiche Completed, la migration a réussi. Le workflow result comprend :

Lorsque le champ status affiche Failed, consultez le tableau errors[] et le champ result.error pour en savoir plus sur le problème.

Chaque workflow (dépendance, migration et restauration) renvoie les mêmes champs de ressource :

Valider la migration validate-migration

Une fois la migration terminée, vérifiez que tous les objets ont été migrés correctement.

Liste de contrôle de validation validation-checklist

Exemple test-runtime-delivery

Si votre migration a créé un train de données, vous pouvez tester la diffusion de l’offre à l’aide de l’exemple suivant :

curl --request POST \
  --url "https://edge.adobedc.net/ee/or2/v1/interact?configId=<DATASTREAM_ID>" \
  --header "Content-Type: application/json" \
  --header "x-request-id: <uuid>" \
  --data '{ "events": [ ... ] }'

Restaurer une migration rollback

Si vous rencontrez des problèmes lors de la validation, vous pouvez annuler une migration terminée afin de restaurer le sandbox cible à son état précédent.

Créer un workflow de restauration create-rollback-workflow

Lancez une restauration en créant un workflow de restauration qui fait référence à la migration que vous souhaitez annuler.

Format d’API

POST /workflows/rollback

Requête

curl --request POST \
  --url "https://decisioning-migration.adobe.io/workflows/rollback" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>" \
  --header "Content-Type: application/json" \
  --data '{ "rollbackWorkflowId": "<MIGRATION_WORKFLOW_ID>" }'

Remplacez <MIGRATION_WORKFLOW_ID> par l’identifiant du workflow de migration que vous souhaitez restaurer.

Surveiller le statut de la restauration poll-rollback-status

Interrogez le workflow de restauration pour suivre sa progression.

Format d’API

GET /workflows/rollback/{rollbackWorkflowId}

Requête

curl --request GET \
  --url "https://decisioning-migration.adobe.io/workflows/rollback/<ROLLBACK_WORKFLOW_ID>" \
  --header "Authorization: Bearer <IMS_ACCESS_TOKEN>" \
  --header "x-gw-ims-org-id: <IMS_ORG_ID>"

Gérer des workflows simultanés handle-concurrency

L’API Migration n’autorise l’exécution que d’un seul workflow à la fois par organisation. Si vous tentez de créer un workflow alors qu’un autre est en cours, vous recevrez une réponse d’erreur 409 de conflit (« Un workflow est déjà en cours… »).

Dans ce cas, attendez que le workflow en cours soit terminé ou récupérez l’ID du workflow et interrogez son statut. Une fois le workflow en cours terminé, vous pouvez en créer un nouveau.

Portée et couverture de la migration migration-scope

Comprendre la portée de la migration vous permet de planifier et de valider la transition de la gestion des décisions vers la prise de décision. Cette section décrit ce qui est pris en charge par le processus de migration et ce qui nécessite une intervention manuelle.

Portée : éléments pris en charge in-scope

L’API Migration gère les éléments et fonctionnalités suivants :

Hors portée : éléments non couverts ou qui nécessitent une intervention manuelle. out-of-scope

Les éléments suivants nécessitent une intervention manuelle ou ne sont pas pris en charge par l’outil de migration :

Référence de mappage d’entités entity-mapping

Lors de la migration de la gestion des décisions vers la prise de décision, les entités sont mappées comme indiqué dans le tableau suivant : Les mappages incluent les entités principales de la prise de décision et les entités associées créées ou utilisées lors de la migration.

Mappage des entités entre la gestion des décisions et la prise de décision

Conventions de dénomination

Le processus de migration applique les conventions de dénomination à l’aide du préfixe ExD_ pour garantir la cohérence et éviter les conflits de noms.

Attributs supplémentaires

Modèle de requête et de réponse request-response-model

Lors de la migration de la gestion des décisions vers la prise de décision, le code de votre application doit être mis à jour pour utiliser les nouveaux formats de requête et de réponse. Les deux systèmes utilisent le point d’entrée Edge Network, mais avec des structures de payload et des noms de champ différents.

Requête Edge de la gestion des décisions (actuelle) dm-request

La requête Edge de la gestion des décisions actuelle possède la structure suivante :

Point d’entrée :

POST https://edge.adobedc.net/ee/v2/interact

En-têtes :

Paramètres du corps de la requête :

Exemple de corps de requête :

{
  "xdm": {
    "dryRun": false,
    "propositionRequests": [
      { "activityId": "<ACTIVITY_ID>", "placementId": "<PLACEMENT_ID>", "itemCount": 3 }
    ],
    "profiles": [
      { "identityMap": { "ECID": [ { "id": "<ECID>", "primary": true } ] } }
    ],
    "validateContextData": true,
    "responseFormat": { "includeContent": true }
  }
}

Requête Edge de la prise de décision (après la migration) decisioning-request

Après la migration, utilisez le format de requête de la prise de décision via le même point d’entrée Edge Network.

Point d’entrée :

POST https://edge.adobedc.net/ee/v2/interact

Champs de requête clés :

Exemple de corps de requête (côté serveur) :

{
  "events": [
    {
      "query": {
        "identity": { "fetch": ["ECID"] },
        "personalization": {
          "surfaces": ["web://my-web/IP_NLI_HP_GET_LOAN_WIDGET"],
          "schemas": [
            "https://ns.adobe.com/personalization/json-content-item",
            "https://ns.adobe.com/personalization/html-content-item"
          ]
        }
      },
      "xdm": {
        "eventType": "decisioning.propositionFetch",
        "environment": {
          "type": "browser",
          "browserDetails": { "viewportWidth": 1280, "viewportHeight": 900, "userAgent": "<USER_AGENT>" }
        },
        "identityMap": {
          "ECID": [ { "id": "<ECID>", "authenticatedState": "ambiguous", "primary": true } ]
        },
        "timestamp": "2025-09-08T12:00:00.000Z"
      },
      "data": {
        "__adobe": { "ajo": { "allowDuplicateDecisionItems": false } }
      }
    }
  ],
  "meta": {
    "state": {
      "domain": "my-web",
      "cookiesEnabled": true,
      "entries": [
        { "key": "kndctr_<ORG>_AdobeOrg_identity", "value": "<identity-cookie>" },
        { "key": "kndctr_<ORG>_AdobeOrg_cluster", "value": "<cluster-cookie>" }
      ]
    }
  }
}

Réponse Edge de la prise de décision decisioning-response

La réponse de la prise de décision contient plusieurs descripteurs organisés par type de préoccupation : personalization:decisions (les offres), locationHint:result et state:store (les cookies à conserver).

Structure de réponse :

{
  "requestId": "<REQUEST_ID>",
  "handle": [
    {
      "type": "personalization:decisions",
      "eventIndex": 0,
      "payload": [
        {
          "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
          "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
          "scopeDetails": {
            "decisionProvider": "AJO",
            "correlationID": "<CORRELATION_ID>",
            "characteristics": {
              "eventToken": "<base64 message-level event token>",
              "subPropositions": "<base64-encoded array of decision items>"
            },
            "rank": 1,
            "activity": {
              "id": "<campaignId>#<actionId>",
              "priority": 0,
              "matchedSurfaces": ["web://my-web/IP_NLI_HP_GET_LOAN_WIDGET"]
            }
          },
          "items": [
            {
              "id": "36646bab-af1b-44c6-b632-bbfb9c357919",
              "schema": "https://ns.adobe.com/personalization/json-content-item",
              "data": { "content": "{ ...offer JSON... }" }
            }
          ]
        }
      ]
    },
    {
      "type": "locationHint:result",
      "payload": [
        { "scope": "EdgeNetwork", "hint": "ind1", "ttlSeconds": 1800 }
      ]
    },
    {
      "type": "state:store",
      "payload": [
        { "key": "kndctr_<ORG>_AdobeOrg_cluster", "value": "<cluster-cookie>", "maxAge": 1800 },
        { "key": "kndctr_<ORG>_AdobeOrg_identity", "value": "<identity-cookie>", "maxAge": 34128000 }
      ]
    }
  ]
}

Champs de réponse clés :

La chaîne characteristics.subPropositions est décodée en base64 pour obtenir le tableau des éléments diffusés, chacun avec son token par élément :

[
  {
    "id": "1ae75277-8832-4c23-bbbc-09f01cfe6c8b",
    "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
    "scopeDetails": { "decisionProvider": "EXD", "correlationID": "<CORRELATION_ID>-0", "rank": 1 },
    "items": [
      { "id": "dps:<schema>:1be64ff83a612488", "name": "ExD_Personal Loan Offer", "score": 997.0, "token": "CLaefQnVLcLbCtzEXV3Jeg" },
      { "id": "dps:<schema>:1be6516838e1248c", "name": "ExD_Home Loan Offer",     "score": 995.0, "token": "ALlB5KV1B0e+CpHoahi7Ew" },
      { "id": "dps:<schema>:1be650da3cd06e98", "name": "ExD_Auto Loan Offer",     "score": 994.0, "token": "koJTRQcwFkR92AqbZ88ytQ" },
      { "id": "dps:<schema>:1be65612d5a1248d", "name": "ExD_Fallback Offer",      "itemSelection": { "selectionDetail": { "selectionType": "fallback" } }, "token": "GHo4ow7h6iCzBOhYR1+6jg" }
    ]
  }
]

Modèles d’implémentation implementation-patterns

La prise de décision prend en charge trois approches d’implémentation :

Implémentation côté client (SDK web/SDK mobile) client-side

Le SDK web ou mobile gère automatiquement toutes les requêtes et la gestion des cookies. Le SDK stocke et transfère des cookies d’identité et de cluster avec chaque requête.

Gestion des cookies : automatique. Le SDK web gère les cookies kndctr_<OrgId>_identity et kndctr_<OrgId>_cluster.

Implémentation côté serveur (API Edge Network) server-side

Le serveur d’applications envoie une requête POST directement à Edge Network et doit gérer manuellement le transfert des cookies. Le serveur extrait les cookies de navigateur des requêtes entrantes et les transfère à Edge Network via meta.state.entries[], puis renvoie les cookies dans la réponse.

Gestion des cookies : manuelle : le serveur d’applications doit extraire les cookies de la requête du navigateur, les transférer à Edge Network dans le corps de la requête, puis les définir dans la réponse. Les cookies doivent être explicitement transférés dans meta.state.entries pour assurer la cohérence des identités.

Implémentation hybride hybrid

Associe le rendu côté serveur (chargement initial de la page) au SDK côté client (interactions suivantes). Le serveur effectue le rendu du contenu initial via Edge Network, puis le SDK web prend le relais pour les requêtes de personnalisation suivantes.

Gestion des cookies : mixte : côté serveur, la transmission des cookies à Edge Network doit être effectuée manuellement ; côté client, elle est gérée automatiquement par le SDK web. Assurez-vous que les jetons d’identité du rendu côté serveur sont disponibles pour le SDK côté client pour garantir une résolution cohérente des identités.

Suivi des événements et collecte de données event-tracking

Pour attribuer correctement les résultats de la prise de décision, activer le capping de la fréquence et bénéficier l’optimisation du classement basée sur l’IA, vous devez implémenter le suivi des événements à l’aide du schéma d’événement de prise de décision.

Champs d’événement obligatoires event-fields

eventType et _experience.decisioning.propositionEventType sont requis. Si l’un des deux est omis, le compteur d’affichage/d’interaction correspondant n’augmente pas.

Exigences relatives au schéma schema-requirements

Associez le groupe de champs de la prise de décision à votre schéma de jeu de données d’événement avant la migration :

Gestion du jeton de suivi tracking-token

La gestion du jeton de suivi doit respecter les exigences suivantes :

Exemples d’événements de prise de décision event-examples

Chaque exemple renvoie la proposition diffusée (y compris ses scopeDetails, qui transportent des characteristics.subPropositions) et définit à la fois eventType et propositionEventType. Les compteurs augmentent pour les éléments dans subPropositions ; propositionAction.tokens sélectionne lesquels.

Événements d’affichage

Les événements d’affichage informent la prise de décision lorsqu’une offre est présentée à un utilisateur ou une utilisatrice. Fournissez le ou les jetons du ou des éléments affichés, ou omettez les tokens pour augmenter le compteur d’affichage pour tous les éléments de subPropositions :

{
  "header": {
    "imsOrgId": "YOUR_ORG_ID",
    "sandboxId": "sandbox-id",
    "sandboxName": "sandbox-name",
    "source": { "name": "ajo-inbound" }
  },
  "body": {
    "xdmEntity": {
      "identityMap": {
        "ECID": [ { "id": "ecid-123", "primary": true } ]
      },
      "eventType": "decisioning.propositionDisplay",
      "_experience": {
        "decisioning": {
          "propositionEventType": { "display": 1 },
          "propositionAction": {
            "id": "b96f842b-5dd9-4c55-9dae-647d96250028",
            "tokens": ["CLaefQnVLcLbCtzEXV3Jeg", "ALlB5KV1B0e+CpHoahi7Ew"]
          },
          "propositions": [
            {
              "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
              "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
              "scopeDetails": {
                "decisionProvider": "AJO",
                "characteristics": {
                  "eventToken": "<base64 eventToken from response>",
                  "subPropositions": "<base64 subPropositions from response>"
                }
              }
            }
          ]
        }
      }
    }
  }
}

Événements d’interaction (clic)

Les événements d’interaction effectuent le suivi des clics et des interactions des utilisateurs et utilisatrices avec une offre qui leur est présentée. Vous devez fournir exactement un jeton identifiant l’élément sur lequel la personne a cliqué :

{
  "header": {
    "imsOrgId": "YOUR_ORG_ID",
    "sandboxId": "sandbox-id",
    "sandboxName": "sandbox-name",
    "source": { "name": "ajo-inbound" }
  },
  "body": {
    "xdmEntity": {
      "identityMap": {
        "ECID": [ { "id": "ecid-123", "primary": true } ]
      },
      "eventType": "decisioning.propositionInteract",
      "_experience": {
        "decisioning": {
          "propositionEventType": { "interact": 1 },
          "propositionAction": {
            "id": "b96f842b-5dd9-4c55-9dae-647d96250028",
            "tokens": ["CLaefQnVLcLbCtzEXV3Jeg"]
          },
          "propositions": [
            {
              "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
              "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
              "scopeDetails": {
                "decisionProvider": "AJO",
                "characteristics": {
                  "eventToken": "<base64 eventToken from response>",
                  "subPropositions": "<base64 subPropositions from response>"
                }
              }
            }
          ]
        }
      }
    }
  }
}

Événements personnalisés

Les événements personnalisés utilisent un eventType défini par le client ou la cliente (toute valeur autre que decisioning.proposition<Display|Interact|Dismiss>) et définit tous les display/interact/dismiss sur 0 dans propositionEventType (classé comme OTHER). Les événements personnalisés sont décodés comme des événements d’affichage (filtrage multi-jetons) par rapport aux subPropositions et sont évalués via le PQL configuré :

{
  "header": {
    "imsOrgId": "YOUR_ORG_ID",
    "sandboxId": "sandbox-id",
    "sandboxName": "sandbox-name",
    "originalTimestamp": 1700000
  },
  "body": {
    "xdmEntity": {
      "identityMap": {
        "ECID": [ { "id": "ecid-123", "primary": true } ]
      },
      "eventType": "add-to-cart",
      "_experience": {
        "decisioning": {
          "propositionEventType": { "display": 0, "interact": 0, "dismiss": 0 },
          "propositionAction": {
            "id": "b96f842b-5dd9-4c55-9dae-647d96250028",
            "tokens": ["CLaefQnVLcLbCtzEXV3Jeg"]
          },
          "propositions": [
            {
              "id": "103ae599-e6d8-4631-baf3-51dd8c6ed4c1",
              "scope": "web://my-web/IP_NLI_HP_GET_LOAN_WIDGET",
              "scopeDetails": {
                "decisionProvider": "AJO",
                "characteristics": {
                  "eventToken": "<base64 eventToken from response>",
                  "subPropositions": "<base64 subPropositions from response>"
                }
              }
            }
          ]
        }
      }
    }
  }
}

Ces événements incluent le capping de la fréquence, les rapports prêts à l’emploi et l’optimisation du classement basée sur l’IA dans la prise de décision. Pour envoyer des événements de proposition avec le SDK web, consultez Expérience basée sur du code : implémentations de la prise de décision.

Processus de migration de bout en bout migration-process

Rubriques connexes related-topics