# 连接到 Salesforce Commerce Cloud B2C Commerce API 是一系列 RESTful API，用于与 B2C Commerce 实例进行交互。该类 API 还有几个别的名字：Salesforce Commerce API、SCAPI（首字母缩写词）或者 Commerce API。 该类 API 让开发者能够构建各种各样的应用程序：从完整的店面到自定义商家工具，再到增强业务管理器。所有 B2C Commerce 客户均可免费使用该类 API。 该类 API 分为两大类 API：Shopper API 和 Admin API。在每个组中，该类 API 分为 API 系列，又分入专注于相关功能的小组。 **Topics** + [AWS Glue 对 Salesforce Commerce Cloud 的支持](salesforce-commerce-cloud-support.md) + [包含创建和使用连接的 API 操作的策略](salesforce-commerce-cloud-configuring-iam-permissions.md) + [配置 Salesforce Commerce Cloud](salesforce-commerce-cloud-configuring.md) + [配置 Salesforce Commerce Cloud 连接](salesforce-commerce-cloud-configuring-connections.md) + [从 Salesforce Commerce Cloud 实体中读取](salesforce-commerce-cloud-reading-from-entities.md) + [Salesforce Commerce Cloud 连接选项参考](salesforce-commerce-cloud-connection-options.md) + [限制](salesforce-commerce-cloud-connector-limitations.md) # AWS Glue 对 Salesforce Commerce Cloud 的支持 AWS Glue 对 Salesforce Commerce Cloud 的支持如下所示： **是否支持作为来源？** 是。可以使用 AWS Glue ETL 作业查询 Salesforce Commerce Cloud 中的数据。 **是否支持作为目标？** 否。 **支持的 Salesforce Commerce Cloud API 版本** v1。 # 包含创建和使用连接的 API 操作的策略 以下示例策略描述了创建和使用连接所需的 AWS 权限。如果您要创建新角色，请创建包含以下内容的策略： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:ListConnectionTypes", "glue:DescribeConnectionType", "glue:RefreshOAuth2Tokens", "glue:ListEntities", "glue:DescribeEntity" ], "Resource": "*" } ] } ``` ------ 您还可以使用以下托管 IAM 策略允许访问权限： + [AWSGlueServiceRole](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/service-role/AWSGlueServiceRole)：授予对各种 AWS Glue 进程代表您运行所需的资源的访问权限。这些资源包括 AWS Glue、Amazon S3、IAM、CloudWatch Logs 和 Amazon EC2。如果您遵循此策略中指定的资源的命名约定，则 AWS Glue 进程具有所需的权限。此策略通常附加到在定义爬网程序、作业和开发终端节点时指定的角色。 + [AWSGlueConsoleFullAccess](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/AWSGlueConsoleFullAccess)：当策略所附加到的身份使用 AWS 管理控制台时，授予对 AWS Glue 资源的完全访问权限。如果遵循此策略中指定的资源的命名约定，则用户具有完全控制台功能。此策略通常附加到 AWS Glue 控制台的用户。 # 配置 Salesforce Commerce Cloud 您必须满足以下要求，才能使用 AWS Glue 从 Salesforce Commerce Cloud 传输数据： ## 最低要求 + 拥有带 clientId 和 clientSecret 的 Salesforce Commerce Cloud 客户端。 + Salesforce Commerce Cloud 账户已启用 API 访问权限。 如果满足这些要求，就可以将 AWS Glue 连接到 Salesforce Commerce Cloud 账户。对于常见连接，无需在 Salesforce Commerce Cloud 中执行任何其他操作。 # 配置 Salesforce Commerce Cloud 连接 Salesforce Commerce Cloud 支持 OAuth2 的 CLIENT CREDENTIALS 的客户端凭证授权类型。 + 此授权类型被视为双足型 OAuth 2.0，因为客户端将其用于在用户环境之外获取访问令牌。AWS Glue 能够使用客户端 ID 和客户端密钥对由您定义的自定义服务提供的 Salesforce Commerce Cloud API 进行身份验证。 + 每项自定义服务均归仅限 API 的用户所有，该用户拥有一组角色和权限，可授权该服务执行特定操作。访问令牌与单项自定义服务相关联。 + 这种授权类型会生成一个短期有效的访问令牌，并且可以通过调用身份端点来续订。 + 有关生成客户端凭证的 Salesforce Commerce Cloud 文档的更多信息，请参阅 [Salesforce 文档](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html)。 要配置 Salesforce Commerce Cloud 连接，请执行以下操作： 1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。 1. 对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET 作为键。 1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接： 1. 在“数据连接”下，选择**创建连接**。 1. 选择**数据来源**时，请选择 Salesforce Commerce Cloud。 1. 请提供 Salesforce Commerce Cloud **短代码**、**组织 ID** 和**站点 ID**。 1. 选择 Salesforce Commerce Cloud 账户的 Salesforce Commerce Cloud 域 URL。 1. 选择 AWS Glue 可以代入并有权执行以下操作的 IAM 角色： ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue", "secretsmanager:PutSecretValue", "ec2:CreateNetworkInterface", "ec2:DescribeNetworkInterfaces", "ec2:DeleteNetworkInterface" ], "Resource": "*" } ] } ``` ------ 1. 提供 OAuth 范围（可选），以及要连接的 Salesforce Commerce Cloud 的用户托管客户端应用程序 ClientId。 1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。 1. 如果要使用网络，请选择网络选项。 1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。 1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。 # 从 Salesforce Commerce Cloud 实体中读取 **先决条件** + 要从中读取内容的 Salesforce Commerce Cloud 对象。请参阅下面的支持的实体表，查看可用的实体。 **支持的实体** | 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 | | --- | --- | --- | --- | --- | --- | | 分配 | 支持 | 是 | 是 | 是 | 是 | | 市场活动 | 支持 | 是 | 是 | 是 | 是 | | 目录 | 支持 | 是 | 是 | 是 | 是 | | 类别 | 支持 | 是 | 是 | 是 | 是 | | 优惠券 | 支持 | 是 | 是 | 是 | 是 | | Gift Certificates | 支持 | 是 | 是 | 是 | 是 | | 产品 | 支持 | 是 | 是 | 是 | 是 | | Promotions | 支持 | 是 | 是 | 是 | 是 | | Source Code Groups | 支持 | 是 | 是 | 是 | 是 | **示例** ``` salesforce_commerce_cloud_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforceCommerceCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "campaign", "API_VERSION": "v1" } ) ``` **Salesforce Commerce Cloud 实体和字段详细信息** 实体列表： + Assignments：[https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments]( https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments) + Campaigns：[https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns) + Catalogs：[https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs) + Categories：[https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories) + Gift Certificates：[https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates) + Products：[https://developer.salesforce.com/docs/commerce/commerce-api/references/products](https://developer.salesforce.com/docs/commerce/commerce-api/references/products) + Promotions：[https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions) + Source Code Groups：[https://developer.salesforce.com/docs/commerce/commerce-api/references/source-code-groups](https://developer.salesforce.com/docs/commerce/commerce-api/references/source-code-groups) **对查询进行分区** 如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。 + `PARTITION_FIELD`：用于对查询进行分区的字段的名称。 + `LOWER_BOUND`：所选分区字段的包含下限值。 对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-02-06"`。 + `UPPER_BOUND`：所选分区字段的排除上限值。 + `NUM_PARTITIONS`：分区的数量。 基于实体的分区字段支持详细信息如下表中所示： | 实体 | 分区字段 | DataType | | --- | --- | --- | | 市场活动 | lastModified | 日期时间 | | 市场活动 | startDate | 日期时间 | | 市场活动 | endDate | 日期时间 | | 目录 | creationDate | 日期时间 | | 类别 | creatiionDate | 日期时间 | | Gift Certificates | merchantId | 字符串 | | Gift Certificates | creatiionDate | 日期时间 | | 产品 | creatiionDate | 日期时间 | | 产品 | lastModified | 日期时间 | | Source Code Groups | creationDate | 日期时间 | | Source Code Groups | startTime | 日期时间 | | Source Code Groups | endTime | 日期时间 | **示例** ``` salesforceCommerceCloud_read = glueContext.create_dynamic_frame.from_options( connection_type="SalesforceCommerceCloud", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "coupons", "API_VERSION": "v1", "PARTITION_FIELD": "creationDate", "LOWER_BOUND": "2020-05-01T20:55:02.000Z", "UPPER_BOUND": "2024-07-11T20:55:02.000Z", "NUM_PARTITIONS": "10" } ) ``` # Salesforce Commerce Cloud 连接选项参考 以下是 Salesforce Commerce Cloud 的连接选项： + `ENTITY_NAME`（字符串）：（必填）用于读取。Salesforce Commerce Cloud 中对象的名称。 + `API_VERSION`（字符串）–（必填）用于读/写。要使用的 Salesforce Commerce Cloud Rest API 版本。示例：v1。 + `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。 + `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。 + `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。 + `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。 + `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。 + `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。 + `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。 # 限制 以下是 Salesforce Commerce Cloud 连接器的限制： + 分区时，“包含”筛选条件未按预期工作。 + CDN Zones 的实体不支持沙盒实例，仅支持开发和生产实例类型。有关更多信息，请参阅 [https://help.salesforce.com/s/articleView?id=cc.b2c\$1embedded\$1cdn\$1overview.htm](https://help.salesforce.com/s/articleView?id=cc.b2c_embedded_cdn_overview.htm)。 + 在 Salesforce Commerce Cloud，没有可用于获取动态元数据的 API 端点。因此，没有提供支持“产品”和“类别”实体中的自定义字段。 + 站点 ID 是必填的查询参数。必须通过“自定义连接器设置”传递“站点 ID”值。有关更多信息，请参阅 [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)。 + 可以在单个 API 请求中对最多两个字段（如果存在，则不包括“级别”）应用筛选条件，并使用下表中提到的不同运算符组合： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html) + 在某些实体中，检索时的字段数据类型与用作可搜索字段时的数据类型不同。因此，没有为这些字段提供筛选功能。下表提供了有关此类字段的详细信息。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html)