Managed Runtime API

使用 Managed Runtime API 来控制部署到 Commerce Cloud Managed Runtime 的应用程序。您可以创建与 Runtime Admin Web 应用程序具有相同功能的自定义工具，但您可以获得更多的管理能力和配置选项。

注意事项

Managed Runtime API 仅用于管理目的。 请_勿_在网店代码中向 API 发出请求。超过速率限制的请求将被阻止。

Warning

要从网店读取环境变量，请使用 process.env。
要读取和加载重定向，请使用托管终结点 /mobify/redirects/$path。

在您开始之前

本指南假设您已经了解 Managed Runtime 和相关概念，例如：项目、环境、捆绑包和部署。要了解更多信息，请参阅 Managed Runtime 概述。

Mobify 品牌名称仍出现在 Managed Runtime API 的基本 URL 的 mobify.com 域中。尽管新的 Salesforce 域最终将取代这 Mobify 域，但目前将继续支持 Mobify 域。

Note

要想发出 API 请求，您必须在 HTTP 请求 Authorization 标头中包含值为 Bearer $API_KEY 的 API 密钥。

要查找您的 API 密钥，请登录 Runtime Admin 工具并转到帐户设置页面。

请将您的 API 密钥视为密码，因为它允许脚本代表您执行操作。

Note

教程

我们将通过一个简短教程向您展示如何使用 API，该教程基于一些格式化为 curl 命令的示例请求。

在运行命令之前，将所有占位符替换为实际值。占位符的格式如 $PLACEHOLDER。

对于大多数请求，您必须将 $PROJECT_ID 替换为您的实际项目 ID。要查找您的项目 ID，请登录 Runtime Admin 工具并转到项目的设置页面。

项目 ID 最长可达 20 个字符，并且是全局唯一的。

列出环境

我们对 Managed Runtime API 的第一个请求列出了属于项目的所有环境（在 API 中也称为“目标”）：

调用 projects_target_list API 端点以列出环境：

1curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/" \
2  --header "Authorization: Bearer $API_KEY"

创建环境

现在我们创建一个名为 staging 的环境，可以用于验证更改，然后将其部署到 production：

首先调用 projects_target_create API 端点。如果要创建项目，则可以调用 projects_create API 端点来创建环境：

1curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/" \
2  --request 'POST' \
3  --header "Authorization: Bearer $API_KEY" \
4  --header 'Content-Type: application/json' \
5  --data '{"name": "staging"}'

然后调用 cc_b2c_target_info_update API 端点，以将 Commerce Cloud 实例和一个或多个站点连接到环境。

1curl "https://cloud.mobify.com/api/cc/b2c/projects/$PROJECT_ID/b2c-target-info/staging/" \
2  --request 'PUT' \
3  --header "Authorization: Bearer $API_KEY" \
4  --header 'Content-Type: application/json' \
5  --data '{"instance_id": "aaaa_stg", "sites": ["DemoSite1", "DemoSite2"]}'

要使用您的新环境，您必须在其中部署一个捆绑包。

让我们调用 projects_target_retrieve API 端点来查看我们创建的 staging 环境的详细信息：

1curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/staging/" \
2  --header "Authorization: Bearer $API_KEY"

修改代理配置

最后，让我们调用 projects_target_partial_update API 端点来修改以下 staging 的代理配置：

1curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/staging/" \
2  --request 'PATCH'  \
3  --header "Authorization: Bearer $API_KEY" \
4  --header 'Content-Type: application/json' \
5  --data '{"ssr_proxy_configs": [{"path": "api", "host": "kv7kzm78.api.commercecloud.salesforce.com"}]}'

更改配置会重新部署已部署的捆绑包，以便配置更新生效。

疑难解答

如果您在使用 API 时遇到问题，请尝试这些疑难解答步骤。

将 --fail 参数添加到 curl 命令中。
检查 API 密钥。
检查项目 ID。

API 端点也可以在浏览器中工作。登录到 Runtime Admin 工具，然后直接在浏览器中打开您正在使用的端点。

自动化用户🤖

要使用 Managed Runtime API 支持持续集成和部署，请创建 Account Manager 用户以实现自动化：

使用共享电子邮件地址（例如 Google Group）在 Account Manager 中创建用户帐户。将关联的登录信息和 MFA 代码存储在 LastPass 等密码管理器中。
赋予用户 Managed Runtime User 角色。
在 Runtime Admin 中为用户分配所需的权限。_用户的 Managed Runtime API 密钥只能访问用户权限允许的内容。使这些密钥专门针对 CI/CD 需要与 _ 交互的项目。
为用户创建 API 密钥并将其保存在您的持续集成系统中。

要使 Managed Runtime API 密钥保持启用状态，您必须按照组织 Account Manager 配置的要求更新其密码，从而使相关的 Account Manager 帐户保持启用状态。如果用户被停用，请通过重置密码来重新激活用户以重新启用 API 密钥。

速率限制

Managed Runtime API 对每单位时间允许的请求数量设置了速率限制。速率限制的使用基于每个用户，有助于确保所有用户的公平访问。

如果您的请求超出速率限制，API 将返回 HTTP 429 Too Many Requests 错误以及指示您可以重试之前需要等待秒数的 Retry-After HTTP 标头。

速率限制无法调整。

如何读取数字

下表显示了不同 API 系列的速率限制。

某些端点具有累积速率限制，这意味着它们不会针对每个端点进行限制。相反，累积速率限制会限制多个端点的请求总数。所有 GET 请求都有累积速率限制。同样，下表中未单独标注端点的所有 POST、PATCH 和 DELETE 请求都有累积速率限制。这些限制如下所述。

Important

项目和环境

方法	端点
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/`

累计 1 分钟限制	累计 1 小时限制
10	100

缓存废止

方法	端点	5 分钟限制	1 小时限制
POST	`/api/projects//target//invalidation/`	15	100

默认速率限制

方法	端点	1 分钟限制	1 小时限制
GET	所有端点合并。	1000	N/A
POST, PATCH, DELETE	所有剩余端点组合。	100	N/A

接下来的步骤

现在您已了解 API 的功能，甚至还发出了一些示例请求！

要了解有关 API 的更多信息，请参阅 API Specification（API 规范）。

API 的开放式 API 架构可在以下位置获得：

MRT Admin： https://cloud.mobify.com/api/schema.json
MRT B2C Config： https://cloud.mobify.com/api/cc/b2c/schema.json