Managed Runtime API

Utilizzare Managed Runtime API per controllare le applicazioni distribuite in Managed Runtime di Commerce Cloud. È possibile creare strumenti personalizzati con le stesse funzionalità dell'applicazione web Runtime Admin ma con funzionalità amministrative e opzioni di configurazione ulteriori.

Managed Runtime API è destinata unicamente a scopi amministrativi. Non effettuare richieste all'API nel codice dello storefront.

In questa guida si presuppone la conoscenza di Managed Runtime e dei concetti correlati, quali progetti, ambienti, bundle e distribuzioni. Per ulteriori informazioni, vedere Panoramica di Managed Runtime.

Il nome del brand Mobify compare ancora nel dominio mobify.com nell'URL di base di Managed Runtime API. Sebbene i nuovi domini Salesforce sostituiranno in futuro il dominio Mobify, il supporto per quest'ultimo rimarrà attivo.

Per effettuare richieste API, è necessario includere una chiave API nell'intestazione Authorization della richiesta HTTP con il valore Bearer $API_KEY.

Per individuare la chiave API, accedere allo strumento Runtime Admin e passare alla pagina Account Settings (Impostazioni account).

Poiché la chiave API consente agli script di eseguire le operazioni automaticamente, è necessario considerarla come una password.

Ecco un breve tutorial su come utilizzare l'API con esempi di richieste formattate come comandi curl.

Prima di eseguire i comandi, sostituire i segnaposto con i valori effettivi. I segnaposto sono formattati nel seguente modo: $PLACEHOLDER.

Per la maggior parte delle richieste è necessario sostituire $PROJECT_ID con l'ID di progetto effettivo. Per cercare l'ID di progetto, accedere allo strumento Runtime Admin e passare alla pagina delle impostazioni del progetto.

Gli ID di progetto possono essere composti da un massimo di 20 caratteri e devono essere univoci a livello globale.

La prima richiesta a Managed Runtime API restituisce un elenco di tutti gli ambienti (o "target" come vengono definiti nell'API) che appartengono a un progetto:

Chiamare l' endpoint API projects_target_list per elencare gli ambienti:

A questo punto è possibile creare un ambiente denominato staging da utilizzare per esaminare le modifiche prima di distribuirle a production:

Chiamare dapprima l'endpoint API projects_target_create. Se si sta creando un progetto, è anche possibile chiamare l'endpoint API projects_create per creare anche un ambiente:

Quindi chiamare l'endpoint API cc_b2c_target_info_update per connettere un'istanza di Commerce Cloud e uno o più siti all'ambiente.

Per utilizzare il nuovo ambiente è necessario distribuirvi un bundle.

Chiamiamo l'endpoint API projects_target_retrieve per esaminare i dettagli dell'ambiente staging creato:

Infine, chiamiamo l'endpoint API projects_target_partial_update per modificare la configurazione del proxy per staging:

Con la modifica della configurazione il bundle distribuito viene ri-distribuito in modo che l'aggiornamento abbia effetto.

In caso di problemi con l'utilizzo dell'API, eseguire le seguenti operazioni:

  • Aggiungere l'argomento --fail al comando curl.
  • Controllare la chiave API.
  • Fare clic sull'ID del progetto.

Gli endpoint API funzionano anche in un browser. Accedere allo strumento Runtime Admin, quindi aprire l'endpoint utilizzato direttamente nel browser.

Per supportare l'integrazione e la distribuzione continua utilizzando Managed Runtime API, creare un utente Account Manager per l'automazione:

  • Creare un account utente in Account Manager utilizzando un indirizzo email condiviso come un gruppo Google. Archiviare le credenziali associate e il codice MFA in un gestore di password come LastPass.
  • Assegnare all'utente il ruolo Managed Runtime User.
  • Assegnare all'utente le autorizzazioni necessarie in Runtime Admin. La chiave Managed Runtime API dell'utente può accedere solo a quanto consentito dalle autorizzazioni dell'utente. Mantenere le autorizzazioni specifiche per i progetti con cui CI/CD deve interagire.
  • Creare la chiave API per l'utente e salvarla nel sistema di integrazione continua.

Per mantenere attiva la chiave Managed Runtime API è necessario mantenere attivo l'account Account Manager correlato aggiornandone la password come richiesto dalla configurazione Account Manager dell'organizzazione. Se l'utente è disattivato, riattivarlo reimpostando la password per abilitare nuovamente la chiave API.

Managed Runtime API prevede limiti di frequenza per il numero di richieste consentite per unità di tempo. I limiti di frequenza vengono applicati per singolo utente e garantiscono un accesso equo a tutti gli utenti.

Se la richiesta supera un determinato limite di frequenza, l'API restituisce un errore HTTP 429 Too Many Requests e un'intestazione HTTP Retry-After indicante il numero di secondi di attesa prima di un possibile nuovo tentativo.

I limiti di frequenza non possono essere modificati.

Le tabelle seguenti indicano i limiti di frequenza per le diverse categorie di API.

Per alcuni endpoint i limiti di frequenza sono cumulativi, il che significa che non vengono applicati al singolo endpoint, ma al numero combinato di richieste per più endpoint. Tutte le richieste GET hanno un limite di frequenza cumulativo. Analogamente, tutte le richieste POST, PATCH e DELETE per gli endpoint non richiamati individualmente nelle tabelle seguenti hanno un limite di frequenza cumulativo. Questi limiti sono descritti di seguito.
MetodoEndpoint
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 cumulativo di 1 minutoLimite cumulativo di 1 ora
10100
MetodoEndpointLimite di 5 minutiLimite di 1 ora
POST/api/projects/*/target/*/invalidation/15100
MetodoEndpointLimite di 1 minutoLimite di 1 ora
GETTutti gli endpoint combinati.1000N/D
POST, PATCH, DELETETutti gli endpoint rimanenti combinati.100N/D

In questa guida sono state illustrate le funzionalità di Managed Runtime API con l'aiuto di alcuni esempi di richiesta.

Per ulteriori informazioni, fare riferimento alle specifiche dell'API.

Gli schemi Open API per l'API sono disponibili qui: