Managed Runtime API

使用 Managed Runtime API，即可控制部署至 Commerce Cloud 的 Managed Runtime 上的應用程式。您可建立與 Runtime Admin 網路應用程式具有相同功能的自訂工具，但還能獲得更多管理功能及設定選項。

考量事項

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 標頭中包含 API 金鑰和此值 Bearer $API_KEY。

若要尋找您的 API 金鑰，請登入 Runtime Admin 工具，並前往 Account Settings (帳戶設定) 頁面。

請將您的 API 金鑰視為密碼，因為這能代表您允許指令碼執行操作。

Note

教學

我們將根據一些範例要求進行簡短的教學，為您示範如何使用 API，範例要求的格式為 curl 命令。

在執行命令前，請以實際值取代預留位置。預留位置的格式為：$PLACEHOLDER

在大部分要求中，您必須以實際專案 ID 取代 $PROJECT_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"

Create an Environment (建立環境)

現在，讓我們建立一個名為 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"

修改 Proxy 設定

最後，請呼叫 projects_target_partial_update API 端點來修改 staging 的 Proxy 設定：

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	不適用
POST、PATCH、DELETE	所有其餘端點合計。	100	不適用

下一步驟

現在您已經熟悉 API 的功能，甚至能做出某些範本要求了！

如要進一步瞭解 API，請參考 API 規格。

API 的 Open API 結構描述可在下列位置取得：

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