本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 連線至 Adobe Marketo Engage Adobe Marketo Engage 是一種行銷自動化平台，可讓行銷人員管理面向潛在客戶和客戶的個人化多管道計畫和行銷活動。 **Topics** + [AWS Glue 支援 Adobe Marketo Engage](adobe-marketo-engage-support.md) + [包含用於建立和使用連線的 API 操作的政策](adobe-marketo-engage-configuring-iam-permissions.md) + [設定 Adobe Marketo Engage](adobe-marketo-engage-configuring.md) + [設定 Adobe Marketo Engage 連線](adobe-marketo-engage-configuring-connections.md) + [從 Adobe Marketo Engage 實體讀取](adobe-marketo-engage-reading-from-entities.md) + [寫入 Adobe Marketo Engage 實體](adobe-marketo-engage-writing-to-entities.md) + [Adobe Marketo Engage 連線選項](adobe-marketo-engage-connection-options.md) + [Adobe Marketo Engage 連接器的限制和備註](adobe-marketo-engage-connector-limitations.md) # AWS Glue 支援 Adobe Marketo Engage AWS Glue 支援 Adobe Marketo Engage，如下所示： **支援作為來源？** 是。您可以使用 AWS Glue ETL 任務從 Adobe Marketo Engage 查詢資料。 **支援作為目標？** 是。您可以使用 AWS Glue ETL 任務將資料寫入 Adobe Marketo。 **支援的 Adobe Marketo Engage API 版本** 支援下列 Adobe Marketo Engage 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 主控台的使用者。 # 設定 Adobe Marketo Engage 您必須先符合下列要求，才能使用 從 Adobe Marketo Engage AWS Glue 傳輸資料： ## 最低需求 以下是最低要求： + 您具有包含用戶端憑證的 Adobe Marketo Engage 帳戶。 + 您的 Adobe Marketo Engage 帳戶具有包含有效授權的 API 存取。 如果您符合這些要求，就可以 AWS Glue 連線到 Adobe Marketo Engage 帳戶。對於一般連線，不需要在 Adobe Marketo Engage 中執行任何其他操作。 ## 取得 OAuth 2.0 憑證 若要取得 API 憑證以對執行個體進行已驗證的呼叫，請參閱 [Adobe Marketo Rest API](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/rest-api) # 設定 Adobe Marketo Engage 連線 Adobe Marketo Engage 支援 CLIENT CREDENTIALS 授權類型。 + 此授予類型會被視為 2 字長度的 OAuth 2.0，因為用戶端使用它來取得使用者內容外的存取權杖。 AWS Glue 能夠使用用戶端 ID 和用戶端秘密來驗證您定義的自訂服務所提供的 Adobe Marketo Engage APIs。 + 每個自訂服務都由一個僅限 API 的使用者擁有，該使用者擁有一組角色和許可，授權服務執行特定動作。存取字符與單一自訂服務關聯。 + 此授權類型會產生短期存留的存取字符，且可以透過呼叫身分端點來續約。 + 如需具有用戶端認證的 OAuth 2.0 的公有 Adobe Marketo Engage 文件，請參閱《Adobe Marketo Engage 開發人員指南》中的[身分驗證](https://developers.adobe-marketo-engage.com/rest-api/authentication/)。 設定 Adobe Marketo Engage 連線： 1. 在 AWS Secrets Manager 中，使用下列詳細資訊建立秘密： 1. 對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。 1. 注意：您必須在 AWS Glue中為每個連線建立機密。 1. 在 AWS Glue Glue Studio 中，依照下列步驟在**資料連線下建立連線**： 1. 在選取**連線類型**時，選取 Adobe Marketo Engage。 1. 提供您要連線的 Adobe Marketo Engage 執行個體的 `INSTANCE_URL`。 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`。 # 從 Adobe Marketo Engage 實體讀取 **必要條件** 您想要從中讀取的 Adobe Marketo Engage 物件。您將需要物件名稱，例如潛在客戶、活動或自訂物件。下表顯示支援的實體。 **來源 (同步) 支援的實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | leads | 是 | 是 | 否 | 是 | 否 | | 活動 | 是 | 是 | 否 | 是 | 否 | | customobjects | 是 | 是 | 否 | 是 | 否 | **來源 (非同步) 支援的實體**： | 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$1 | 支援分區 | | --- | --- | --- | --- | --- | --- | | leads | 是 | 否 | 否 | 是 | 是 | | 活動 | 是 | 否 | 否 | 是 | 否 | | customobjects | 是 | 否 | 否 | 是 | 是 | **範例**： ``` adobe-marketo-engage_read = glueContext.create_dynamic_frame.from_options( connection_type="adobe-marketo-engage", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v2", "INSTANCE_URL": "https://539-t**-6**.mktorest.com" } ``` **Adobe Marketo Engage 實體和欄位詳細資訊**： **具有靜態中繼資料的實體**： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) **具有動態中繼資料的實體**： 對於下列實體，Adobe Marketo Engage 會提供端點來動態擷取中繼資料，以便在每個實體的資料類型層級擷取運算子支援。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) ## 分區查詢 如果想要在 Spark 中使用並行，可以提供其他 Spark 選項 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用這些參數，原始查詢會分區為可由 Spark 任務並行執行的子查詢的 `NUM_PARTITIONS` 數目。 + `PARTITION_FIELD`：用來分區查詢的欄位名稱。 + `LOWER_BOUND`：所選分區欄位的**包含**下限值。 對於 DateTime 欄位，接受 ISO 格式的值。 有效值範例： ``` "2024-07-01T00:00:00.000Z" ``` + `UPPER_BOUND`：所選分區欄位的**唯一**上限值。 + `NUM_PARTITIONS`：分區數目。 下表說明實體分區欄位支援詳細資訊： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) 範例： ``` adobe-marketo-engage_read = glueContext.create_dynamic_frame.from_options( connection_type="adobe-marketo-engage", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "PARTITION_FIELD": "createdAt" "LOWER_BOUND": "2024-07-01T00:00:00.000Z" "UPPER_BOUND": "2024-07-02T00:00:00.000Z" "NUM_PARTITIONS": "10" } ``` # 寫入 Adobe Marketo Engage 實體 **先決條件** + 您想要寫入的 Adobe Marketo 物件。您將需要物件名稱，例如 `leads` 或 `customobjects`。 + Adobe Marketo 連接器支援三種寫入操作： + INSERT + UPSERT (更新插入) + UPDATE + 對於 `UPSERT`和 `UPDATE` 寫入操作，您必須提供 `ID_FIELD_NAMES` 選項，以指定記錄的 ID 欄位。使用 `leads` 實體時，使用 `email` 作為 `ID_FIELD_NAMES` 進行 `UPSERT` 操作，使用 `id` 進行 `UPDATE` 操作。對於 `customobjects` 實體，使用 `marketoGUID` 作為 `ID_FIELD_NAMES` 同時進行 `UPDATE` 和 `UPSERT` 操作。 **目的地支援的實體 (同步)** | 實體名稱 | 將支援為目的地連接器 | 可以插入 | 可以更新 | 可以更新插入 | | --- | --- | --- | --- | --- | | leads | 是 | 是 (大量) | 是 (大量) | 是 (大量) | | customobjects | 是 | 是 (大量) | 是 (大量) | 是 (大量) | **範例**： **INSERT 操作：** ``` marketo_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="marketo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "WRITE_OPERATION": "INSERT" } ``` **UPDATE 操作：** ``` marketo_write = glueContext.write_dynamic_frame.from_options( frame=frameToWrite, connection_type="marketo", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "leads", "API_VERSION": "v1", "WRITE_OPERATION": "UPDATE", "ID_FIELD_NAMES": "id" } ``` **注意** 對於 `leads` 和 `customobjects` 實體，Adobe Marketo 會提供端點來動態擷取中繼資料，以便從 Marketo API 回應中識別可寫入欄位。 # Adobe Marketo Engage 連線選項 以下是 Adobe Marketo Engage 的連線選項： + `ENTITY_NAME`(String) - (必要) 用於讀取。Adobe Marketo Engage 中的物件名稱。 + `API_VERSION`(String) - (必要) 用於讀取。您要使用的 Adobe Marketo Engage 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。用於讀取。要讀取的分區數目。 + `TRANSFER_MODE`(String) - 預設：SYNC。用於非同步讀取。 + `WRITE_OPERATION`(String) - 預設：INSERT。用於寫入。值應為 INSERT、UPDATE、UPSERT。 + `ID_FIELD_NAMES`(String) - 預設：null。UPDATE 和 UPSERT 的必要項目。 # Adobe Marketo Engage 連接器的限制和備註 以下是 Adobe Marketo Engage 連接器的限制或備註： + 'sinceDatetime' 和 'activityTypeId' 是 Sync Activities 實體的必要篩選條件參數。 + 訂閱每天分配 5 萬個 API 呼叫 (每天在中部標準時間上午 12：00 重設)。您可以在 Adobe Marketo Engage 訂閱中購買額外的每日容量。如需參考，請參閱 [Adobe Marketo Rest API](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/rest-api)。 + 日期範圍篩選條件 (`createdAt` 或 `updatedAt`) 的時間範圍上限為 31 天。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 在任何指定時間內，訂閱在佇列中最多分配 10 個大量擷取任務。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 依預設，擷取任務每天限制為 500 MB (每天在中部標準時間上午 12：00 重設)。您可以在 Adobe Marketo Engage 訂閱中購買額外的每日容量。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 並行匯出任務的數目上限為 2。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 已排入佇列的匯出任務數目上限 (包括目前匯出的任務) 為 10。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 允許的最大檔案大小為 1 GB，可從大量任務中擷取。 + 建立非同步任務後，檔案將保留 7 天才到期。如需參考，請參閱[大量擷取 - Marketo 開發人員](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + `createdAt` 或 `updatedAt` 是 Async Leads 實體的必要篩選條件參數。 + `createdAt` 是 Async Activities 實體的必要篩選條件參數。 + `updatedAt` 是 Async Custom Object 實體的必要篩選條件參數。 + 使用 AWS Glue SaaS 連接器時，使用者無法識別在寫入目的地 SaaS 平台期間發生部分故障時，哪些特定記錄失敗。 + 使用同步寫入操作時，輸入檔案中具有 null 值的任何欄位都會自動捨棄，而不會傳送至 SaaS 平台。 + 您可以在批次中建立或更新最多 300 個記錄以進行同步寫入。 如需詳細資訊，請參閱 [Adobe Marketo Engage 整合最佳實務](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/marketo-integration-best-practices)和[大量擷取](https://https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-activity-extract)。