Managed Runtime API

Verwenden Sie die Managed Runtime API, um die in Managed Runtime von Commerce Cloud bereitgestellten Anwendungen zu kontrollieren. Sie können benutzerdefinierte Tools erstellen, die über die gleichen Funktionalitäten wie die Runtime Admin-Webanwendung verfügen, erhalten darüber hinaus aber noch mehr Administrationsfähigkeiten und Konfigurationsoptionen.

Die Managed Runtime API ist ausschließlich für Administrationszwecke gedacht. Stellen Sie in Ihrem Storefront-Code keine Anfragen an diese API.

In dieser Anleitung wird davon ausgegangen, dass Sie bereits mit Managed Runtime und verwandten Konzepten wie Projekten, Umgebungen, Bündeln und Bereitstellungen vertraut sind. Näheres dazu finden Sie in der Übersicht über Managed Runtime.

Der Markenname Mobify wird noch in der Domain mobify.com in der Basis-URL für die Managed Runtime API verwendet. Obwohl die neuen Salesforce-Domains letztendlich die Mobify-Domain ersetzen werden, wird die Mobify-Domain weiterhin unterstützt.

Um Anfragen an die API zu senden, müssen Sie im Header Authorization der HTTP-Anfrage einen API-Schlüssel mit dem Wert Bearer $API_KEY einfügen.

Um Ihren API-Schlüssel zu finden, melden Sie sich beim Tool Runtime Admin an und rufen Sie die Seite Account Settings (Kontoeinstellungen) auf.

Behandeln Sie Ihren API-Schlüssel wie ein Passwort, denn damit können Skripte Vorgänge in Ihrem Namen ausführen.

Wir zeigen Ihnen gleich in einem kurzen Tutorial anhand einiger als curl-Befehle formatierten Beispielanfragen, wie Sie die API verwenden.

Ersetzen Sie vor der Ausführung der Befehle alle Platzhalter mit den tatsächlichen Werten. Platzhalter haben das folgende Format: $PLACEHOLDER.

Bei den meisten Anfragen müssen Sie $PROJECT_ID mit Ihrer tatsächlichen Projekt-ID ersetzen. Um Ihre Projekt-ID zu finden, melden Sie sich beim Tool Runtime Admin an und rufen Sie die Seite mit den Einstellungen Ihres Projekts auf.

Project-IDs können aus bis zu 20 Zeichen bestehen und müssen allgemein eindeutig sein.

Unsere erste Anfrage an die Managed Runtime API listet alle Umgebungen (oder "Ziele", wie sie in der API genannt werden) auf, die zu einem Projekt gehören:

Rufen Sie den API-Endpunkt projects_target_list auf, um die Umgebungen aufzulisten:

Jetzt erstellen wir eine Umgebung namens staging, mit der wir Änderungen vor ihrer Bereitstellung in production verifizieren können:

Rufen Sie zuerst den API-Endpunkt projects_target_create auf. Wenn Sie ein Projekt erstellen, können Sie den API-Endpunkt projects_create aufrufen, um auch eine Umgebung zu erstellen:

Rufen Sie dann den API-Endpunkt cc_b2c_target_info_update auf, um eine Commerce Cloud-Instanz und eine oder mehrere Websites mit der Umgebung zu verbinden.

Um Ihre neue Umgebung zu nutzen, müssen Sie ein Bündel darin bereitstellen.

Rufen wir jetzt den API-Endpunkt projects_target_retrieve auf, um die Details der von uns erstellten staging-Umgebung zu überprüfen:

Zum Schluss rufen wir den API-Endpunkt projects_target_partial_update auf, um die Proxy-Konfiguration für staging zu ändern:

Durch eine Konfigurationsänderung wird das bereitgestellte Bündel erneut bereitgestellt, damit die Konfigurationsaktualisierung wirksam wird.

Wenn Sie bei der Verwendung der API auf Probleme stoßen, versuchen Sie die folgenden Schritte zur Fehlerbehebung:

Fügen Sie Ihrem curl-Befehl das Argument --fail hinzu.
Überprüfen Sie Ihren API-Schlüssel.
Überprüfen Sie die ID Ihres Projekts.

Die API-Endpunkte funktionieren auch in einem Browser. Melden Sie sich im Runtime Admin-Tool an und öffnen Sie den verwendeten Endpunkt direkt in Ihrem Browser.

Erstellen Sie einen Account Manager-Benutzer für die Automatisierung, um die kontinuierliche Integration und Bereitstellung über die Managed Runtime API zu unterstützen:

Erstellen Sie im Account Manager ein Benutzerkonto mit einer gemeinsam genutzten E-Mail-Adresse wie die einer Google-Gruppe. Speichern Sie die zugehörigen Anmeldedaten und den MFA-Code in einem Passwortmanager wie LastPass.
Geben Sie dem Benutzer die Rolle Managed Runtime User.
Weisen Sie dem Benutzer in Runtime Admin die erforderlichen Zugriffsrechte zu. Der Managed Runtime API-Schlüssel des Benutzers kann nur auf das zugreifen, was die Zugriffsrechte des Benutzers zulassen. Beschränken Sie die Zugriffsrechte spezifisch auf die Projekte, mit denen CI/CD interagieren muss.
Erstellen Sie den API-Schlüssel für den Benutzer und speichern Sie ihn in Ihrem System für die kontinuierliche Integration.

Damit der Managed Runtime API-Schlüssel aktiv bleibt, müssen Sie das zugehörige Account Manager-Konto aktiv halten, indem Sie das Kontopasswort entsprechend der Account Manager-Konfiguration Ihrer Organisation aktualisieren. Wenn der Benutzer deaktiviert ist, reaktivieren Sie ihn, indem Sie zur Reaktivierung des API-Schlüssels das Passwort zurücksetzen.

Für die Managed Runtime API gibt es Durchsatzbeschränkungen für die Anzahl von Anfragen, die pro Zeiteinheit zulässig sind. Diese Beschränkungen werden pro Benutzer durchgesetzt und gewährleisten allen Benutzern einen fairen Zugriff.

Wenn Ihre Anfrage eine Durchsatzbeschränkung überschreitet, gibt die API den HTTP-Fehler 429 Too Many Requests zurück und der HTTP-Header Retry-After zeigt die Wartezeit bis zum nächsten Versuch in Sekunden an.

Durchsatzbeschränkungen können nicht angepasst werden.

Die nachstehenden Tabellen zeigen die Durchsatzbeschränkungen der verschiedenen API-Familien an.

Für einige Endpunkte gibt es kumulative Durchsatzbeschränkungen, d. h. sie werden nicht an jedem Endpunkt separat gedrosselt. Stattdessen drosseln kumulative Durchsatzbeschränkungen die kombinierte Anzahl von Anfragen über mehrere Endpunkte hinweg. Für alle GET-Anfragen gilt eine kumulative Durchsatzbeschränkung. Ähnlich gilt auch für alle POST-, PATCH- und DELETE-Anfragen auf Endpunkten, die in den nachfolgenden Tabellen nicht individual aufgeführt sind, eine kumulative Durchsatzbeschränkung. Diese Beschränkungen werden unten beschrieben.

Methode	Endpunkt
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/`

kum. Beschränkung pro Minute	kum. Beschränkung pro Stunde
10	100

Methode	Endpunkt	5-Min-Beschr.	1-Std-Beschr.
POST	`/api/projects//target//invalidation/`	15	100

Methode	Endpunkt	Beschr. pro Min.	Beschr. pro Std.
GET	alle Endpunkte kombiniert	1000	n. zutr.
POST, PATCH, DELETE	alle verbleibenden Endpunkte kombiniert	100	n. zutr.

Jetzt wissen Sie, was die API alles kann. Sie können nun selbst einige Beispielanfragen stellen!

In der API-Spezifikation erfahren Sie mehr zur API.

Die Open API-Schemata für die API sind verfügbar unter:

MRT Admin: https://cloud.mobify.com/api/schema.json
MRT B2C-Konfiguration: https://cloud.mobify.com/api/cc/b2c/schema.json