# 连接到 Adobe Marketo Eng Adobe Marketo Engage 是一个营销自动化平台，让营销人员能够管理面向潜在客户和现有客户的个性化多渠道推广计划和推广活动。 **Topics** + [AWS Glue 支持 Adobe Marketo Enage](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 Enage 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 您必须满足以下要求，才能使用 AWS Glue 从 Adobe Marketo Engage 传出数据： ## 最低要求 以下是最低要求： + 您拥有一个 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 支持 OAuth2 的客户端凭证授权类型。 + 此授权类型被视为双足型 OAuth 2.0，因为客户端将其用于在用户环境之外获取访问令牌。AWS Glue 能够使用客户端 ID 和客户端密钥对由您定义的自定义服务提供的 Adobe Marketo Engage API 进行身份验证。 + 每项自定义服务均归仅限 API 的用户所有，该用户拥有一组角色和权限，可授权该服务执行特定操作。访问令牌与单项自定义服务相关联。 + 这种授权类型会生成一个短期有效的访问令牌，并且可以通过调用身份端点来续订。 + 有关包含客户端凭证的 OAuth 2.0 的 Adobe Marketo Engage 公共文档，请参阅《Adobe Marketo Engage 开发人员指南》中的 [Authentication](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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。 1. 如果要使用网络，请选择网络选项。 1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。 # 从 Adobe Marketo Engage 实体中读取 **先决条件** 您要从中读取内容的 Adobe Marketo Engage 对象。您将需要潜在客户、活动或自定义对象等对象名称。下表显示支持的实体。 **源支持的实体（同步）**： | 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 | | --- | --- | --- | --- | --- | --- | | 潜在客户 | 是 | 是 | 否 | 是 | 否 | | 活动 | 是 | 是 | 否 | 是 | 否 | | 自定义对象 | 是 | 是 | 否 | 是 | 否 | **源支持的实体（异步）**： | 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 | | --- | --- | --- | --- | --- | --- | | 潜在客户 | 是 | 否 | 否 | 是 | 是 | | 活动 | 是 | 否 | 否 | 是 | 否 | | 自定义对象 | 是 | 否 | 否 | 是 | 是 | **示例：** ``` 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_cn/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_cn/glue/latest/dg/adobe-marketo-engage-reading-from-entities.html) ## 对查询进行分区 如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。 + `PARTITION_FIELD`：用于对查询进行分区的字段的名称。 + `LOWER_BOUND`：所选分区字段的**包含**下限值。 对于日期时间字段，我们接受 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_cn/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` 实体时，对于 `UPSERT` 操作，需将 `email` 用作 `ID_FIELD_NAMES`；对于 `UPDATE` 操作，则用作 `id`。对于 `customobjects` 实体，无论是 `UPDATE` 还是 `UPSERT` 操作，均需将 `marketoGUID` 用作 `ID_FIELD_NAMES`。 **目的地（同步）支持的实体** | 实体名称 | 是否支持作为目的地连接器 | 是否可以插入 | 是否可以更新 | 是否可以更新插入 | | --- | --- | --- | --- | --- | | 潜在客户 | 是 | 是（批量） | 是（批量） | 是（批量） | | 自定义对象 | 是 | 是（批量） | 是（批量） | 是（批量） | **示例：** **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`（字符串）：（必填）用于读取。Adobe Marketo Engage 中对象的名称。 + `API_VERSION`（字符串）：（必填）用于读取。要使用的 Adobe Marketo Engage Rest API 版本。例如：v1。 + `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。 + `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。 + `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。 + `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。 + `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。 + `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。 + `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。 + `TRANSFER_MODE`（字符串）：默认值：SYNC。用于异步读取。 + `WRITE_OPERATION`（字符串）– 默认：INSERT。用于写入。值应为 INSERT、UPDATE、UPSERT。 + `ID_FIELD_NAMES`（字符串）– 默认：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 天。有关参考，请参阅 [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 在任意给定时间，订阅在队列中最多可分配 10 个批量提取作业。有关参考，请参阅 [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 默认情况下，数据提取作业限制为每天 500 MB（每天于北美中部标准时间中午 12:00 重置）。额外的每日容量可以作为 Adobe Marketo Engage 订阅的一部分购买。有关参考，请参阅 [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 并发导出作业的最大数量为 2。有关参考，请参阅 [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 排队导出作业（包括当前正在导出的作业）的最大数量为 10。有关参考，请参阅 [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + 允许从批量作业提取的最大文件大小为 1 GB。 + 创建异步作业后，到文件过期之前，文件会保留 7 天。有关参考，请参阅 [Bulk Extract - Marketo Developers](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-extract)。 + `createdAt` 或 `updatedAt` 是“异步线索”实体的必要筛选条件参数。 + `createdAt` 是“异步活动”实体的必要筛选条件参数。 + `updatedAt` 是“异步自定义对象”实体的必要筛选条件参数。 + 使用 AWS Glue SaaS 连接器时，如果出现部分写入失败的情况，用户无法确定在向目的地 SaaS 平台执行写入操作期间哪些特定记录发生了失败。 + 使用同步写入操作时，输入文件中任何值为空的字段都会被自动删除，也不会被发送到 SaaS 平台。 + 在同步写入操作中，最多可​​以批量创建或更新 300 条记录。 有关更多信息，请参阅 [Marketo 集成最佳实践](https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/marketo-integration-best-practices)和 [Bulk Extract](https://https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/rest/bulk-extract/bulk-activity-extract)。