用于混合实施的 CDN API

分阶段无头部署是一种使用 Storefront Reference Architecture (SFRA) 和 Composable Storefront 等多种网店技术提供单一购物体验的技术。

嵌入式 CDN (eCDN) 区域可以同时将流量路由到 SFRA 和 Managed Runtime，从而允许您逐步部署 Composable Storefront。

本指南介绍如何使用 Commerce API CDN 区域将流量路由到 Managed Runtime。您还可以使用 Business Manager 将流量路由到 Managed Runtime。在 Business Manager 中配置 MRT 路由规则

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

在本指南中，我们使用带有生产 URL https://www.example.com的示例网店。

只有现有客户才能访问此页面上的某些链接。请访问 Salesforce Commerce Cloud GitHub 存储库和访问权限，了解有关如何访问 Commerce Cloud 存储库的信息。

Tip

前提条件

您要熟悉 Admin API 授权
您必须拥有具有范围 sfcc.cdn-zones.rw 的 Account Manager API 客户端。
您必须知道要与 Managed Runtime 一起使用的 eCDN 区域的区域 ID。要获取此信息，请使用 CDN 区域 API 的 getZonesInfo 端点。
使用 updateSecuritySettings以在区域中启用 alwaysUseHttps。_ Managed Runtime 仅支持通过 HTTPS 的流量。_
设置您的 SLAS API 客户端的 redirect_uri 以包含该区域。
如果您限制了允许访问 Managed Runtime 环境的 IP 集，请将 eCDN 使用的 CloudFlare IPs 添加到允许的 IP 集。

将流量路由到 Managed Runtime

使用 createMrtRules 端点，您可以创建将流量路由到 Managed Runtime 环境的规则：

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
2  --header "Authorization: Bearer $TOKEN" \
3  --header 'Content-Type: application/json' \
4  --data '{
5    "mrtHostname": "example-production.mobify-storefront.com",
6    "expressions": [
7      "http.host eq \"www.example.com\" and http.request.uri.path matches \"^/products\""
8    ]
9  }'

我们来检查一下请求正文中提供的数据。

mrtHostname 的值是用于流量路由的 Managed Runtime 环境的域。它必须引用 mobify-storefront.com 域上托管的 Managed Runtime 环境。如果现有规则使用提供的值，则请求将失败。

Managed Runtime 是唯一受支持的路由目标。

Note

expressions 的值是 Cloudflare 规则表达式的数组，用于控制将哪些请求路由到 Managed Runtime。对于大多数实施，单个路由表达式便已足够。

除了提供的表达式之外，还使用以下默认路由规则：

1(
2  http.request.uri.path matches "^/callback.*" or
3  http.request.uri.path matches "^/mobify.*" or
4  http.request.uri.path matches "^/worker\.js.*"
5)

路由更改会立即应用，导航到与表达式匹配的 URL 会返回从 Managed Runtime 检索的内容。

路由方案

支持以下路由方案：
- 映射到单个 MRT 环境的单个主机名：
  - 例如， http.host eq \"www.example.com\" → example-production.mobify-storefront.com
- 多个主机名映射到单个 MRT 环境：
  - 例如， http.host in {\"www.example.com\" \"prod.example.com\" \"us.example.com\"}→ example-production.mobify-storefront.com
目前 不支持 以下路由方案：
- 根据不同路径映射到多个MRT环境的单个主机名

表达式约束

表达式根据以下标准进行验证：

http.host 必须恰好出现一次，并且后面必须跟着 eq OR in 运算符。有关使用示例，请参阅上文。
主机名必须与区域匹配。换言之，eCDN 区域必须具有涵盖所提供主机名的有效证书。
支持以下字段：
- http.host
- http.request.uri.path
- http.request.uri
- http.cookie
表达式的最大长度为 3072 个字符。
一个区域最多可以关联 100 个表达式。

修改路由配置

当您继续分阶段部署时，您可以将更多请求路由到 Managed Runtime。

要修改路由表达式，请使用 getMrtRule 获取与要更新的表达式关联的规则集和规则的 ID：

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
2--header "Authorization: Bearer $TOKEN"

接下来使用 updateMrtRule 更新表达式：

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules/$RULESET/rules/$RULE" \
2--request 'PATCH' \
3--header "Authorization: Bearer $TOKEN" \
4--header 'Content-Type: application/json' \
5--data '{
6    "expression": "http.host eq \"www.example.com\" and (http.request.uri.path matches \"^/products\" or http.request.uri.path matches \"^/categories\")"
7  }'

添加更多路由配置

若要向现有托管运行时环境添加更多路由规则，请使用 updateMrtRuleset 并提供 mrtHostname 和其他路由表达式：

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
2  --request 'PATCH' \
3  --header "Authorization: Bearer $TOKEN" \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "mrtHostname": "example-production.mobify-storefront.com",
7    "expressions": ["http.host eq \"www.example.com\" and http.request.uri.path matches \"^/home\""]
8  }'

若要为新的托管运行时环境添加路由规则，请使用 createMrtRules 端点并提供新 mrtHostname 值：

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
2--header "Authorization: Bearer $TOKEN" \
3--header 'Content-Type: application/json' \
4--data '{
5    "mrtHostname": "example-development.mobify-storefront.com",
6    "expressions": [
7      "http.host eq \"dev.example.com\" and http.request.uri.path matches \"^/products\""
8    ]
9  }'

修改托管运行时环境

若要更新现有规则以路由到其他托管运行时环境，请使用 updateMrtRuleset 并提供 oldMrtHostname 要路由到的和（new）： mrtHostname

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
2  --request 'PATCH' \
3  --header "Authorization: Bearer $TOKEN" \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "oldMrtHostname": "example-old.mobify-storefront.com",
7    "mrtHostname": "example-new.mobify-storefront.com"
8  }'

禁用路由

如果您要切换到第三方 CDN，或者您不想再将特定路径从 eCDN 路由到 MRT，您可以禁用路由。

若要禁用路由，请使用 getMrtRules 获取要删除的配置的 ID：

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
2--header "Authorization: Bearer $TOKEN"

然后，若要删除 Managed Runtime 路由规则，请使用 deleteMrtRule 并传入 getMrtRules 返回的适用 ID：

1curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules/$RULESET/rules/$RULE" \
2--request 'DELETE' \
3--header "Authorization: Bearer $TOKEN"

如果要删除所有托管运行时路由规则，请使用 deleteMrtRuleset：

1`curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules/$RULESET" \`
2--request 'DELETE' \
3--header "Authorization: Bearer $TOKEN"

将所有流量路由到 Managed Runtime

完成分阶段部署或启动新站点时，您可以选择使用单个表达式将区域的所有流量路由到 Managed Runtime：

1http.host eq \"www.example.com\"

模拟 eCDN 路由

在 eCDN 不可用的环境中，使用 composable-hybrid-dev-server 来模拟 eCDN 路由。