本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 連線至 Salesforce Marketing Cloud
Salesforce Marketing Cloud 是一家為電子郵件、行動裝置、社交和線上行銷提供行銷自動化和分析軟體的供應商。其還提供諮詢和實作服務。身為 Salesforce Marketing Cloud 使用者，您可以 AWS Glue 連線至 Salesforce Marketing Cloud 帳戶。然後，您可以在 ETL 任務中使用 Salesforce Marketing Cloud 作為資料來源或目的地。執行這些任務，以在 Salesforce Marketing Cloud AWS 和服務或其他支援的應用程式之間傳輸資料。
**Topics**
+ [AWS Glue 支援 Salesforce Marketing Cloud](salesforce-marketing-cloud-support.md)
+ [包含用於建立和使用連線的 API 操作的政策](salesforce-marketing-cloud-configuring-iam-permissions.md)
+ [設定 Salesforce Marketing Cloud](salesforce-marketing-cloud-configuring.md)
+ [設定 Salesforce Marketing Cloud 連線](salesforce-marketing-cloud-configuring-connections.md)
+ [從 Salesforce Marketing Cloud 實體中讀取](salesforce-marketing-cloud-reading-from-entities.md)
+ [寫入到 Salesforce Marketing Cloud 實體](salesforce-marketing-cloud-writing-to-entities.md)
+ [Salesforce Marketing Cloud 連線選項](salesforce-marketing-cloud-connection-options.md)
+ [Salesforce Marketing Cloud 連接器的限制和備註](salesforce-marketing-cloud-connector-limitations.md)
# AWS Glue 支援 Salesforce Marketing Cloud
AWS Glue 支援 Salesforce Marketing Cloud，如下所示：
**支援作為來源？**
是。您可以使用 AWS Glue ETL 任務從 Salesforce Marketing Cloud 查詢資料。
**支援作為目標？**
否。
**支援的 Salesforce Marketing Cloud API 版本**
支援下列 Salesforce Marketing Cloud API 版本：
+ v1
# 包含用於建立和使用連線的 API 操作的政策
下列範例政策說明建立和使用 連線所需的 AWS IAM 許可。如果您要建立新角色，請建立包含下列項目的政策：
------
#### [ 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 Marketing Cloud
您必須先符合下列要求，才能使用 從 Salesforce Marketing Cloud AWS Glue 傳輸資料：
## 最低需求
以下是最低要求：
+ 您擁有一個 Salesforce Marketing Cloud 帳戶。如需詳細資訊，請參閱[建立 Salesforce Marketing Cloud 帳戶](#salesforce-marketing-cloud-configuring-creating-salesforce-marketing-cloud-account)。
+ 您的 Salesforce Marketing Cloud 帳戶已啟用 API 存取。企業版、無限制版、開發人員版和高效版預設會啟用 API 存取。
如果您符合這些要求，就可以 AWS Glue 連線到 Salesforce Marketing Cloud 帳戶。對於一般連線，您不需要在 Salesforce Marketing Cloud 中執行任何其他操作。
## 建立 Salesforce Marketing Cloud 帳戶
對於 Salesforce Marketing Cloud，您需要聯絡廠商以建立帳戶。如果您或您的公司與 Salesforce 有關聯，請聯絡 Salesforce 客戶經理來請求 Salesforce Marketing Cloud 授權。或者，可以請求聯絡 Salesforce 代表，如下所示：
1. 前往 https://www.salesforce.com/in/products/marketing-cloud/overview/ 並選擇**註冊**。
1. 選取頁面右上角的**聯絡我們**連結。
1. 在表單中輸入必要資訊，然後選擇**聯絡方式**。
Salesforce 代表將與您聯絡，討論您的需求。
## 建立專案和 OAuth 2.0 憑證
若要取得專案和 OAuth 2.0 憑證：
1. 使用您的使用者名稱和密碼登入 [Salesforce Marketing Cloud 執行個體](https://mc.login.exacttarget.com/hub-cas/login)，並使用您註冊的手機號碼進行驗證。
1. 按一下右上角的設定檔，然後前往**設定**。
1. 在**平台工具**下，選擇**應用程式**，然後選擇**已安裝的套件**。
![\[\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/sfmc-platform-tools.png)
1. 在**已安裝的套件**頁面中，按一下右上角的**新增**。提供套件的名稱和說明。
儲存套件。儲存套件之後，可以檢視套件詳細資訊。
1. 在套件的**詳細資訊**頁面的**元件**區段下，選擇**新增元件**。
![\[\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/images/sfmc-add-component.png)
1. 將**元件類型**選取為「API 整合」，然後按一下**下一步**。
1. 將**整合類型**選取為「伺服器到伺服器」(具有用戶端憑證 OAuth 授權類型)，然後按一下**下一步**。
1. 根據您的需求新增範圍，然後按一下**儲存**。
# 設定 Salesforce Marketing Cloud 連線
Salesforce Marketing Cloud 支援 OAuth2 的 CLIENT CREDENTIALS 授權類型。
+ 此授予類型被視為 2 邊 OAuth 2.0，因為用戶端使用它來取得使用者內容外的存取權杖。 AWS Glue 能夠使用用戶端 ID 和用戶端秘密來驗證您定義的自訂服務提供的 Salesforce Marketing Cloud APIs。
+ 每個自訂服務都由一個僅限 API 的使用者擁有，該使用者擁有一組角色和許可，授權服務執行特定動作。存取字符與單一自訂服務關聯。
+ 此授權類型會產生短期存留的存取字符，且可以透過呼叫身分端點來續約。
+ 如需具有用戶端憑證的 OAuth 2.0 的公有 Salesforce Marketing Cloud 文件，請參閱[設定增強型套件的開發環境](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/mc-dev-setup-enhanced.html)。
若要設定 Salesforce Marketing Cloud 連線：
1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密：
1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。
1. 注意：您必須在 中建立連線的秘密 AWS Glue。
1. 在 AWS Glue Glue Studio 中，依照下列步驟在 **Data Connections** 下建立連線：
1. 選取**連線類型**時，請選取 Salesforce Marketing Cloud。
1. 提供您要連線的 Salesforce Marketing Cloud 的 `Subdomain Endpoint`。
1. 選取 AWS Glue 可以擔任並具有下列動作許可的 AWS IAM 角色：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
1. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。
1. 如果想要使用您的網路，請選取網路選項。
1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。
# 從 Salesforce Marketing Cloud 實體中讀取
**必要條件**
您想要從中讀取的 Salesforce Marketing Cloud 物件。您將需要物件名稱，例如 `Activity` 或 `Campaigns`。下表顯示支援的實體。
**來源的支援實體**：
| 實體 | 介面 | 可以篩選 | 支援限制 | 支援排序依據 | 支援 SELECT \$1 | 支援分區 |
| --- | --- | --- | --- | --- | --- | --- |
| 事件通知回呼 | REST | 否 | 否 | 否 | 是 | 否 |
| Seed-List | REST | 否 | 是 | 否 | 是 | 否 |
| 設定 | REST | 是 | 是 | 否 | 是 | 否 |
| 網域驗證 | REST | 是 | 是 | 是 | 是 | 否 |
| 物件巢狀標籤 | REST | 是 | 否 | 否 | 是 | 否 |
| 聯絡 | REST | 否 | 是 | 否 | 是 | 否 |
| 事件通知訂閱 | REST | 否 | 否 | 否 | 是 | 否 |
| 簡訊 | REST | 否 | 是 | 否 | 是 | 否 |
| 活動 | SOAP | 否 | 否 | 否 | 是 | 是 |
| Bounce Event | SOAP | 否 | 否 | 否 | 是 | 是 |
| Click Event | SOAP | 否 | 否 | 否 | 是 | 是 |
| Content Area | SOAP | 否 | 否 | 否 | 是 | 是 |
| Data Extension | SOAP | 否 | 是 | 否 | 是 | 是 |
| Email | SOAP | 否 | 是 | 否 | 是 | 是 |
| Forwarded Email Event | SOAP | 否 | 是 | 否 | 是 | 是 |
| Forward Email OptInEvent | SOAP | 否 | 是 | 否 | 是 | 是 |
| 連結 | SOAP | 否 | 是 | 否 | 是 | 是 |
| Link Send | SOAP | 否 | 是 | 否 | 是 | 是 |
| 清單 | SOAP | 否 | 是 | 否 | 是 | 是 |
| List Subscriber | SOAP | 否 | 是 | 否 | 是 | 是 |
| Not Sent Event | SOAP | 否 | 是 | 否 | 是 | 是 |
| Open Event | SOAP | 否 | 是 | 否 | 是 | 是 |
| 傳送 | SOAP | 否 | 是 | 否 | 是 | 是 |
| Sent Event | SOAP | 否 | 是 | 否 | 是 | 是 |
| Subscriber | SOAP | 否 | 是 | 否 | 是 | 是 |
| Survey Event | SOAP | 否 | 是 | 否 | 是 | 是 |
| Unsub Event | SOAP | 否 | 是 | 否 | 是 | 是 |
| 稽核事件 | REST | 否 | 是 | 是 | 是 | 否 |
| 行銷活動 | REST | 否 | 是 | 是 | 是 | 否 |
| 互動 | REST | 否 | 是 | 是 | 是 | 否 |
| 內容資產 | REST | 否 | 是 | 是 | 是 | 否 |
**REST 的範例**：
```
salesforcemarketingcloud_read = glueContext.create_dynamic_frame.from_options(
connection_type="salesforcemarketingcloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Campaigns",
"API_VERSION": "v1",
"INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com"
}
)
```
**SOAP 的範例**：
```
salesforcemarketingcloud_read = glueContext.create_dynamic_frame.from_options(
connection_type="salesforcemarketingcloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Activity",
"API_VERSION": "v1",
"INSTANCE_URL": "https://**********************.soap.marketingcloudapis.com"
}
)
```
**Salesforce Marketing Cloud 實體和欄位詳細資訊**：
下表說明 Salesforce Marketing Cloud 實體。存在具有靜態中繼資料的 REST 實體和具有動態中繼資料的 SOAP 實體。
**具有靜態中繼資料的 REST 實體**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/salesforce-marketing-cloud-reading-from-entities.html)
**具有動態中繼資料的 SOAP 實體**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/salesforce-marketing-cloud-reading-from-entities.html)
## 分區查詢
在 Salesforce Marketing Cloud 中，Integer 和 DateTime 資料類型欄位支援欄位型分區。
如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。
+ `PARTITION_FIELD`：用來分區查詢的欄位名稱。
+ `LOWER_BOUND`：所選分區欄位的**包含**下限值。
對於時間戳記欄位，接受 Spark SQL 查詢中使用的 Spark 時間戳記格式。
有效值的範例：
```
“2024-05-07T02:03:00.00Z"
```
+ `UPPER_BOUND`：所選分區欄位的**唯一**上限值。
+ `NUM_PARTITIONS`：分區數目。
範例：
```
salesforcemarketingcloud_read = glueContext.create_dynamic_frame.from_options(
connection_type="salesforcemarketingcloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "ListSubscriber",
"API_VERSION": "v1",
"PARTITION_FIELD": "CreatedDate",
"LOWER_BOUND": "2023-09-07T02:03:00.000Z",
"UPPER_BOUND": "2024-05-07T02:03:00.000Z",
"NUM_PARTITIONS": "10"
}
)
```
# 寫入到 Salesforce Marketing Cloud 實體
**先決條件**
+ 您想要寫入到的 Salesforce Marketing 物件。需要指定物件的名稱，例如 `List`、`Campaigns` 或下表中列出的任何其他實體。
+ Salesforce Marketing Cloud 連接器支援三種寫入操作：
+ INSERT
+ UPSERT (更新插入)
+ UPDATE
使用 `UPDATE` 和 `UPSERT` 寫入操作時，必須提供 `ID_FIELD_NAMES` 選項，以指定記錄的外部 ID 欄位。
**目的地支援的實體**：
| 實體 | Priority | 介面 (REST、SOAP 等） | 可以插入 | 可以更新 | 可以更新插入 |
| --- | --- | --- | --- | --- | --- |
| 行銷活動 | P0 | REST | Y- 單一 | Y- 單一 | N |
| 內容資產 | P0 | REST | Y- 單一、大量 | Y- 單一 | N |
| 聯絡 | P1 | REST | Y- 單一 | Y- 單一 | N |
| 網域驗證 | P1 | REST | Y- 單一 | Y- 單一、大量 | N |
| 事件通知回呼 | P1 | REST | Y- 單一 | Y- 單一 | N |
| 事件通知訂閱 | P1 | REST | Y- 單一 | Y- 單一 | N |
| 簡訊 | P1 | REST | Y- 單一 | N | N |
| 物件巢狀標籤 | P2 | REST | Y- 單一 | Y- 單一 | N |
| Seed-List | P1 | REST | Y- 單一 | Y- 單一 | N |
| 設定 | P1 | REST | Y- 單一 | Y- 單一 | N |
| Data Extension | P0 | SOAP | Y- 單一 | Y- 單一 | Y- 單一 |
| Email | P0 | SOAP | Y- 單一 | Y- 單一 | N |
| 清單 | P0 | SOAP | Y- 單一 | Y- 單一 | N |
| 傳送 | P0 | SOAP | Y- 單一 | N | N |
| Subscriber | P0 | SOAP | Y- 單一 | Y- 單一 | N |
**REST 的 INSERT 操作範例**：
```
salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options(
connection_type="salesforcemarketingcloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Campaigns",
"API_VERSION": "v1",
"writeOperation" : "INSERT",
"INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com"
}
)
```
**SOAP 的 INSERT 操作範例**：
```
salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options(
connection_type="salesforcemarketingcloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "List",
"API_VERSION": "v1",
"writeOperation" : "INSERT",
"INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com"
}
)
```
**REST 的 UPDATE 操作範例**：
```
salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options(
connection_type="salesforcemarketingcloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Campaigns",
"API_VERSION": "v1",
"writeOperation" : "UPDATE",
"ID_FIELD_NAMES": "id",
"INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com"
}
)
```
**SOAP 的 UPDATE 操作範例**：
```
salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options(
connection_type="salesforcemarketingcloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "List",
"API_VERSION": "v1",
"writeOperation" : "UPDATE",
"ID_FIELD_NAMES": "id",
"INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com"
}
)
```
**SOAP 的 UPSERT 操作範例**：
```
salesforcemarketingcloud_write = glueContext.write_dynamic_frame.from_options(
connection_type="salesforcemarketingcloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "DataExtension/Insert-***E/6*******3",
"API_VERSION": "v1",
"writeOperation" : "UPSERT",
"INSTANCE_URL": "https://**********************.rest.marketingcloudapis.com"
}
)
```
# Salesforce Marketing Cloud 連線選項
以下是 Salesforce Marketing Cloud 的連線選項：
+ `ENTITY_NAME`(String) - (必要) 用於讀取。Salesforce Marketing Cloud 中的物件名稱。
+ `API_VERSION`(String) - (必要) 用於讀取。您想要使用的 Salesforce Marketing Cloud Rest 和 SOAP API 版本。
+ `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。用於讀取。要讀取的分區數目。
+ `WRITE_OPERATION`(String) - 預設：INSERT。用於寫入。值應為 INSERT、UPDATE、UPSERT。
+ `ID_FIELD_NAMES`(String) - 預設：null。UPDATE 和 UPSERT 是必要項目。
# Salesforce Marketing Cloud 連接器的限制和備註
以下是 Salesforce Marketing Cloud 連接器的限制或備註：
+ 在 DateTime 資料類型欄位中使用篩選條件時，需要傳遞格式為 "yyyy-mm-ddThh：MM：ssZ" 的值。
+ 在「資料預覽」中，「布林資料類型」值為空白。
+ 對於 SOAP 實體，最多可以定義兩個篩選條件，對於 REST 實體，只能定義一個篩選條件，這會限制使用篩選條件測試分區。
+ 從 SaaS 端觀察到多種非預期行為：`linksend` 實體中的 `Link.Alias` 欄位不支援 CONTAINS 運算子 (例如 `Link.Alias CONTAINS "ViewPrivacyPolicy"`)，且資料延伸實體 (例如 EQUALS 和 GREATER THAN) 的篩選運算子不會傳回預期結果。
+ SFMC ClickEvent SOAP API 在反映新建立的記錄方面存在延遲，因此最近建立的記錄可能無法立即在 API 回應中使用。
範例：如果您於 **2025-01-10T14:30:00** 建立了 5 筆新的 ClickEvent 記錄，並立即使用 SOAP API 對其進行擷取，則回應可能不會包含所有 5 筆記錄。新建立的記錄最多可能需要 5 分鐘才會出現在 API 回應中。此延遲也會影響資料擷取和排程執行。
+ 執行寫入操作時，支援兩種不同的 DateTime 格式：**2025-03-11T04：46：00** （不含毫秒） 和 **2025-03-11T04：46：00.000Z** AWS Glue （含毫秒）。
+ 對於事件通知訂閱實體，只能為已驗證的回呼 URL 建立訂閱，而且每個回呼最多可有 200 個訂閱。
+ 對於事件通知回呼實體，每個帳戶最多可建立 50 筆記錄。