API Managed Runtime

Utilisez l’API Managed Runtime pour contrôler les applications déployées sur le Managed Runtime de Commerce Cloud. Vous pouvez créer des outils personnalisés avec les mêmes fonctionnalités que l’application web Runtime Admin, mais qui bénéficient d’options d’administration et de configuration supplémentaires.

L'API Managed Runtime est destinée à des fins d'administration uniquement. Ne lancez surtout pas de request à l'API dans le code de votre boutique.

Ce guide suppose que vous connaissez déjà Managed Runtime et ses concepts associés, tels que les projets, les environnements, les paquets et les déploiements. Pour en savoir plus, consultez le document Présentation de Managed Runtime.

La marque Mobify apparaît encore dans le domaine mobify.com dans l'URL de base de l'API Managed Runtime. Même si de nouveaux domaines Salesforce remplaceront à terme le domaine Mobify, la prise en charge de ce dernier sera maintenue.

Pour lancer des requests API, vous devez inclure une clé API dans l’en-tête Authorization de la request HTTP avec la valeur Bearer $API_KEY.

Pour trouver votre clé d'API, connectez-vous à l'outil Runtime Admin et accédez à la page Account Settings.

Considérez votre clé API comme un mot de passe, car elle permet aux scripts d'effectuer des opérations en votre nom.

Nous allons vous montrer comment utiliser l'API avec un bref tutoriel et quelques exemples de requests, qui sont formatées comme des commandes curl.

Avant d'exécuter les commandes, indiquez des valeurs réelles dans les espaces réservés. Les espaces réservés sont mis en forme comme ceci : $PLACEHOLDER.

Pour la plupart des requests, vous devez remplacer $PROJECT_ID par votre identifiant de projet réel. Pour trouver l'identifiant de votre projet, connectez-vous à l'outil Runtime Admin et accédez à la page des paramètres de votre projet.

Les identifiants de projet peuvent comporter jusqu’à 20 caractères et doivent être uniques à l’échelle mondiale.

Notre première request à l'API Managed Runtime répertorie tous les environnements (ou « targets », soit cibles, comme on les appelle dans l'API) qui appartiennent à un projet :

Appelez le point de terminaison d’API projects_target_list pour répertorier les environnements :

Créons maintenant un environnement appelé staging que nous pourrons utiliser pour contrôler les changements avant de les déployer vers l'instance production :

Appelez d’abord le point de terminaison d’API projects_target_create . Si vous créez un projet, vous pouvez appeler le point de terminaison d’API projects_create pour créer également un environnement :

Appelez ensuite le point de terminaison d’API cc_b2c_target_info_update pour connecter une instance Commerce Cloud et un ou plusieurs sites à l’environnement.

Pour utiliser votre nouvel environnement, vous devez y déployer un paquet.

Appelons le point de terminaison d’API projects_target_retrieve pour passer en revue les détails de l’environnement staging que nous avons créé :

Pour finir, appelons le point de terminaison d’API projects_target_partial_update pour modifier la configuration du proxy pour staging :

La modification de la configuration redéploie le paquet actuel afin que la mise à jour de la configuration prenne effet.

Si vous rencontrez des difficultés à utiliser l’API, essayez ces étapes de dépannage :

  • Ajoutez l'argument --fail à votre commande curl.
  • Vérifiez votre clé API.
  • Vérifiez l'identifiant de votre projet.

Les points de terminaison de l'API fonctionnent également dans un navigateur. Connectez-vous à l'outil Runtime Admin, puis ouvrez le point de terminaison que vous utilisez directement dans votre navigateur.

Pour prendre en charge l’intégration et le déploiement continus à l’aide de l’API Managed Runtime, créez un utilisateur Account Manager pour l’automatisation :

  • Créez un compte utilisateur dans Account Manager en utilisant une adresse e-mail partagée, par exemple un groupe Google. Stockez les informations d’identification associées et le code MFA dans un gestionnaire de mots de passe comme LastPass.
  • Donnez à l’utilisateur le rôle Managed Runtime User.
  • Attribuez les autorisations requises à l’utilisateur dans Runtime Admin. La clé API Managed Runtime de l’utilisateur ne peut accéder qu’à ce qui est explicitement autorisé à l’utilisateur. Ces autorisations doivent rester spécifiques aux projets avec lesquels la CI/CD doit interagir.
  • Créez la clé API pour l’utilisateur et enregistrez-la dans votre système d’intégration continue.

Pour conserver la clé API Managed Runtime active, vous devez conserver le compte Account Manager associé actif en mettant à jour son mot de passe comme l’exige la configuration Account Manager de votre organisation. Si l’utilisateur est désactivé, réactivez-le en réinitialisant le mot de passe afin de réactiver la clé API.

L’API Managed Runtime a mis en place des limites de débit portant sur le nombre de requests autorisées par unité de temps. Les limites de débit sont appliquées par utilisateur et contribuent à l’équité de l’accès pour tous les utilisateurs.

Si votre request dépasse une limite de débit, l’API renvoie une erreur HTTP 429 Too Many Requests et un en-tête HTTP Retry-After qui indique le nombre de secondes à attendre avant de pouvoir réessayer.

Les limites de débit ne peuvent pas être ajustées.

Les tableaux ci-dessous indiquent les limites de débit pour les différentes familles d’API.

Certains points de terminaison comportent des limites de débit cumulées ; ils ne sont donc pas limités par point de terminaison. Au lieu de cela, les limites de débit cumulées limitent le nombre combiné de requests sur plusieurs points de terminaison. Toutes les requests GET ont une limite de débit cumulée. De même, toutes les requests POST, PATCH et DELETE pour les points de terminaison qui ne sont pas consignées individuellement dans les tableaux suivants ont une limite de débit cumulée. Ces limites sont indiquées ci-dessous.

MéthodePoint de terminaison
POST/api/projects/
PATCH/api/projects/*/
DELETE/api/projects/*/
POST/api/projects/*/builds/*/
POST/api/projects/*/target/
PATCH/api/projects/*/target/*/
DELETE/api/projects/*/target/*/
POST/api/projects/*/target/*/deploy/
Limite cumulée de 1 minuteLimite cumulée de 1 heure
10100
MéthodePoint de terminaisonLimite de 5 minuteLimite de 1 heure
POST/api/projects/*/target/*/invalidation/15100
MéthodePoint de terminaisonLimite de 1 minuteLimite de 1 heure
GETCombinaison de tous les points de terminaison.1000N/A
POST, PATCH, DELETECombinaison de tous les points de terminaison restants.100N/A

Vous connaissez maintenant les possibilités de l'API, et vous avez même lancé quelques requests !

Pour en savoir plus sur l'API, consultez la spécification d'API.

Les schémas Open API de l’API sont disponibles à ces adresses :