本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 連線至 Salesforce Commerce Cloud B2C Commerce API 是一組用於與 B2C Commerce 執行個體互動的 RESTful API 集合。其包含幾個不同的名稱：Salesforce Commerce API、縮寫 SCAPI，或只是 Commerce API。 API 可讓開發人員建置各種應用程式：從完整店面到自訂商家工具，再到增強 Business Manager。對於所有 B2C Commerce 客戶，均可免費使用該 API。 API 分為兩個主要的 API 群組：Shopper API 和 Admin 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 您必須先符合下列要求，才能使用 從 Salesforce Commerce Cloud AWS Glue 傳輸資料： ## 最低需求 + 您擁有一個具有 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，依照下列步驟在 **Data Connections** 下建立連線： 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. 提供您要連線之 Salesforce Commerce Cloud 的 OAuth 範圍 (選用) 以及使用者管理的用戶端應用程式 ClientId。 1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。 1. 如果想要使用您的網路，請選取網路選項。 1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。 1. 在您的 AWS Glue 任務組態中，提供 `connectionName`做為**其他網路連線**。 # 從 Salesforce Commerce Cloud 實體中讀取 **先決條件** + 您想要從中讀取的 Salesforce Commerce Cloud Object。請參閱以下支援的實體表格，以檢查可用實體。 **支援的實體** | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | 指派 | 是 | 是 | 是 | 是 | 是 | | 行銷活動 | 是 | 是 | 是 | 是 | 是 | | 目錄 | 是 | 是 | 是 | 是 | 是 | | 類別 | 是 | 是 | 是 | 是 | 是 | | 優惠券 | 是 | 是 | 是 | 是 | 是 | | 禮品券 | 是 | 是 | 是 | 是 | 是 | | 產品 | 是 | 是 | 是 | 是 | 是 | | 促銷活動 | 是 | 是 | 是 | 是 | 是 | | 來源碼群組 | 是 | 是 | 是 | 是 | 是 | **範例** ``` 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 實體和欄位詳細資訊** 實體清單： + 指派：[https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments]( https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments) + 行銷活動：[https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns) + 目錄：[https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs) + 類別：[https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories) + 禮品券：[https：//https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates) + 產品：[https://developer.salesforce.com/docs/commerce/commerce-api/references/products](https://developer.salesforce.com/docs/commerce/commerce-api/references/products) + 促銷活動：[https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions) + 原始程式碼群組：[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`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的包含下限值。 對於日期，我們接受 Spark SQL 查詢中使用的 Spark 日期格式。有效值的範例：`"2024-02-06"`。 + `UPPER_BOUND`：所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`：分區數目。 實體分區欄位支援詳細資訊如下表所示： | 實體 | 分區欄位 | DataType | | --- | --- | --- | | 行銷活動 | lastModified | DateTime | | 行銷活動 | startDate | DateTime | | 行銷活動 | endDate | DateTime | | 目錄 | creationDate | DateTime | | 類別 | creatiionDate | DateTime | | 禮品券 | merchantId | String | | 禮品券 | creatiionDate | DateTime | | 產品 | creatiionDate | DateTime | | 產品 | lastModified | DateTime | | 來源碼群組 | creationDate | DateTime | | 來源碼群組 | startTime | DateTime | | 來源碼群組 | endTime | DateTime | **範例** ``` 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`(String) - (必要) 用於讀取。Salesforce Commerce Cloud 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取/寫入。您想要使用的 Salesforce Commerce Cloud Rest API 版本。範例：v1。 + `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。 + `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。 + `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。 + `PARTITION_FIELD`(String) - 用於讀取。用於分區查詢的欄位。 + `LOWER_BOUND`(String) - 用於讀取。所選分區欄位的包含下限值。 + `UPPER_BOUND`(String) - 用於讀取。所選分區欄位的唯一上限值。 + `NUM_PARTITIONS`(Integer) - 預設：1。用於讀取。要讀取的分區數目。 # 限制 以下是 Salesforce Commerce Cloud 連接器的限制： + 分區時，Contains 篩選條件未如預期運作。 + 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 值。如需詳細資訊，請參閱[基本 URL 和請求形成要素](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_tw/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html) + 在某些實體中，擷取時欄位的資料類型與用作可搜尋欄位時不同。因此，這些欄位沒有佈建篩選功能。下表提供有關這些欄位的詳細資訊。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html)