# 连接到 Mailchimp Mailchimp 是一个一体化营销平台，可帮助管理客户和其他利益相关方并与之交谈。该平台的营销方法侧重于健康的联系人管理实践、设计精美的电子邮件、独特的自动化工作流和强大的数据分析。如果您是 Mailchimp 用户，则可以将 AWS Glue 连接到自己的 Mailchimp 账户。然后，可以使用 Mailchimp 作为 ETL 作业中的数据来源。通过运行这些作业，可在 Mailchimp 与 AWS 服务或其他受支持的应用程序之间传输数据。 **Topics** + [AWS Glue 对 Mailchimp 的支持](mailchimp-support.md) + [包含创建和使用连接的 API 操作的策略](mailchimp-configuring-iam-permissions.md) + [配置 Mailchimp](mailchimp-configuring.md) + [配置 Mailchimp 连接](mailchimp-configuring-connections.md) + [从 Mailchimp 实体读取内容](mailchimp-reading-from-entities.md) + [Mailchimp 连接选项](mailchimp-connection-options.md) + [创建 Mailchimp 账户](mailchimp-create-account.md) + [限制](mailchimp-connector-limitations.md) # AWS Glue 对 Mailchimp 的支持 AWS Glue 对 Mailchimp 的支持情况如下： **是否支持作为来源？** 是。可以使用 AWS Glue ETL 作业查询 Mailchimp 中的数据。 **是否支持作为目标？** 否。 **支持的 Mailchimp API 版本** 3.0 # 包含创建和使用连接的 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 控制台的用户。 # 配置 Mailchimp 必须满足以下要求，才能使用 AWS Glue 从 Mailchimp 传输数据： ## 最低要求 + 拥有一个 Mailchimp 账户以及相应的电子邮件地址和密码。有关创建账户的更多信息，请参阅[创建 Mailchimp 账户](mailchimp-create-account.md)。 + 必须创建一个可以访问 AWS Glue 服务的 AWS 账户。 + 确保已创建以下某一项资源：这些资源提供 AWS Glue 在对账户进行身份验证调用时用于安全访问数据的凭证。 + 支持 OAuth 2.0 身份验证的开发人员应用程序。有关创建开发者应用程序的更多信息，请参阅[创建 Mailchimp 账户](mailchimp-create-account.md)。 如果满足这些要求，就可以将 AWS Glue 连接到 Mailchimp 账户。对于常见连接，无需在 Mailchimp 中执行其他操作。 # 配置 Mailchimp 连接 Mailchimp 支持以下两种类型的身份验证机制： + Mailchimp 支持 `AUTHORIZATION_CODE` 授权类型。 + 此授权类型为“三足型”`OAuth`，因其依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。默认情况下，创建连接的用户可以依赖于 AWS Glue 拥有的关联应用程序，在该应用程序中，除了 Mailchimp Client ID 和客户端密钥之外，用户无需提供任何与 `OAuth` 相关的信息。AWS Glue 控制台会将用户重定向到 Mailchimp，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Mailchimp 实例。 + 用户仍然可以选择在 Mailchimp 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Mailchimp，以便登录并授权 AWS Glue 访问其资源。 + 有关为 `AUTHORIZATION_CODE OAuth` 流创建关联应用程序的 Mailchimp 公共文档，请参阅 [ Access Data on Behalf of Other Users with OAuth 2](https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/?msockid=141ebf9ffb4d619525c3ad27fad660d6)。 + **自定义身份验证**：有关生成自定义授权所需 API 密钥的 Mailchimp 公共文档，请参阅 [About API Keys](https://mailchimp.com/en/help/about-api-keys/?msockid=310fd0fe09d16afe034fc5de08d76b01)。 要配置 Mailchimp 连接，请执行以下操作： 1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥： + `OAuth` 身份验证：对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。 + 自定义身份验证：对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将“api\$1key”作为键。 **注意** 必须在 AWS Glue 中为每个连接创建密钥。 1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接： 1. 在**连接**下，选择**创建连接**。 1. 选择**数据来源**时，请选择 Mailchimp。 1. 提供 Mailchimp `instanceUrl`。 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. 选择身份验证类型以连接到 Mailchimp： + `OAuth` 身份验证：提供要连接的 Mailchimp 的令牌 URL 以及用户托管客户端应用程序 ClientId。 + 对于自定义身份验证：选择“自定义”身份验证类型以连接到 Mailchimp。 1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。 1. 如果要使用网络，请选择网络选项。 1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。 1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为附加网络连接。 # 从 Mailchimp 实体读取内容 **先决条件** 要从中读取内容的 Mailchimp 对象。请参阅下面的支持的实体表，查看可用的实体。 **支持的实体** + [Abuse-reports](https://mailchimp.com/developer/marketing/api/campaign-abuse/) + [自动化](https://mailchimp.com/developer/marketing/api/automation/list-automations/) + [活动](https://mailchimp.com/developer/marketing/api/campaigns/list-campaigns/) + [Click-details](https://mailchimp.com/developer/marketing/api/link-clickers/) + [Lists](https://mailchimp.com/developer/marketing/api/link-clickers/) + [成员](https://mailchimp.com/developer/marketing/api/list-segment-members/) + [Open-details](https://mailchimp.com/developer/marketing/api/list-members/) + [Segments](https://mailchimp.com/developer/marketing/api/list-segments/) + [Stores](https://mailchimp.com/developer/marketing/api/ecommerce-stores/list-stores/) + [Unsubscribed](https://mailchimp.com/developer/marketing/api/unsub-reports/) | 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 | | --- | --- | --- | --- | --- | --- | | 自动化 | 支持 | 是 | 是 | 是 | 是 | | 市场活动 | 否 | 否 | 否 | 否 | 否 | | Lists | 支持 | 是 | 否 | 是 | 是 | | Reports Abuse | 否 | 是 | 否 | 是 | 是 | | Reports Open | 否 | 是 | 否 | 是 | 是 | | Reports Click | 支持 | 是 | 否 | 是 | 是 | | Reports Unsubscribe | 否 | 是 | 否 | 是 | 是 | | 分段 | 否 | 是 | 否 | 是 | 是 | | Segment Members | 支持 | 是 | 否 | 是 | 否 | | Stores | 支持 | 是 | 是 | 是 | 否 | **示例** ``` mailchimp_read = glueContext.create_dynamic_frame.from_options( connection_type="mailchimp", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "stores", "INSTANCE_URL": "https://us14.api.mailchimp.com", "API_VERSION": "3.0" }) ``` **Mailchimp 实体和字段详细信息** + [Abuse-reports](https://mailchimp.com/developer/marketing/api/campaign-abuse/) + [自动化](https://mailchimp.com/developer/marketing/api/automation/list-automations/) + [活动](https://mailchimp.com/developer/marketing/api/campaigns/list-campaigns/) + [Click-details](https://mailchimp.com/developer/marketing/api/link-clickers/) + [Lists](https://mailchimp.com/developer/marketing/api/link-clickers/) + [成员](https://mailchimp.com/developer/marketing/api/list-segment-members/) + [Open-details](https://mailchimp.com/developer/marketing/api/list-members/) + [Segments](https://mailchimp.com/developer/marketing/api/list-segments/) + [Stores](https://mailchimp.com/developer/marketing/api/ecommerce-stores/list-stores/) + [Unsubscribed](https://mailchimp.com/developer/marketing/api/unsub-reports/) ## 对查询进行分区 如果您想在 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/mailchimp-reading-from-entities.html) 示例： ``` read_read = glueContext.create_dynamic_frame.from_options( connection_type="mailchimp", connection_options={ "connectionName": "connectionName", "ENTITY_NAME": "automations", "API_VERSION": "3.0", "INSTANCE_URL": "https://us14.api.mailchimp.com", "PARTITION_FIELD": "create_time", "LOWER_BOUND": "2024-02-05T14:09:30.115Z", "UPPER_BOUND": "2024-06-07T13:30:00.134Z", "NUM_PARTITIONS": "3" } ``` # Mailchimp 连接选项 以下是 Mailchimp 的连接选项： + `ENTITY_NAME`（字符串）：（必填）用于读取/写入。Mailchimp 中对象的名称。 + `INSTANCE_URL`（字符串）：（必填）有效的 Mailchimp 实例 URL。 + `API_VERSION`（字符串）：（必填）用于读取。要使用的 Mailchimp Engage Rest API 版本。例如：3.0。 + `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。 + `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。 + `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。 + `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。 + `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。 + `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。 + `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。 # 创建 Mailchimp 账户 1. 导航到 [Mailchimp 登录页面](https://login.mailchimp.com/?locale=en)，输入电子邮件 ID 和密码，然后选择**注册**。 1. 打开来自 Mailchimp 的确认电子邮件，然后选择确认链接验证账户。 **注意** 收到激活电子邮件的实际时间可能有所不同。如果没有收到激活邮件，请检查垃圾邮件文件夹，并阅读我们的激活电子邮件疑难解答提示。Mailchimp 会阻止基于角色的电子邮件地址（例如 [admin@pottedplanter.com](mailto:admin@pottedplanter.com) 或 [security@example.com](mailto:security@example.com)）进行注册。 首次登录账户时，Mailchimp 会要求用户提供所需信息。Mailchimp 将使用这些信息，以确保用户账户符合其使用条款，同时提供与用户及其公司需求相关的指导。 1. 输入用户信息，按照提示完成激活流程，即可开始使用新的 Mailchimp 账户。 **注册 `OAuth2.0` 应用程序** 1. 导航到 [Mailchimp 登录页面](https://login.mailchimp.com/?locale=en)，输入电子邮件 ID 和密码，然后选择**登录**。 1. 选择右上角的**用户**图标，然后从下拉菜单中选择**账户和计费**。 1. 选择**其他**，然后从下拉菜单中选择**已注册的应用程序**。 1. 查找并选择**注册应用程序**。 1. 输入以下详细信息： + **应用程序名称**：应用程序的名称。 + **公司/组织**：您的公司或组织名称。 + **应用程序网站**：应用程序的网站。 + **重定向 URI**：重定向 URI 模式是一个 URI 路径（或以逗号分隔的路径列表）；在登录流程完成后，Mailchimp 可以重定向（如果请求）到此路径。例如，`https://ap-southeast-2\\.console\\.aws\\.amazon\\.com` 1. 选择**创建**。 1. 将会显示**客户端 ID** 和**客户端密钥**。复制并将其保存在安全位置。然后选择**完成**。 **注意** 使用 AppFlow 或 AWS Glue 期间，客户端 ID 和客户端密钥字符串是用于与此连接器建立连接的凭证。 **生成 API 密钥** 1. 导航到 [Mailchimp 登录页面](https://login.mailchimp.com/?locale=en)，输入电子邮件 ID 和密码，然后选择**登录**。 1. 选择右上角的**用户**图标，然后从下拉菜单中选择**账户和计费**。 1. 选择**其他**，然后从下拉菜单中选择 **API 密钥**。 1. 选择**创建密钥**。 1. 输入密钥名称，然后选择**生成密钥**。 下一页面将显示生成的 API 密钥。 1. 复制密钥，将其安全存储，然后选择**完成**。 # 限制 以下是 Mailchimp 连接器的限制： + 仅 `Campaigns`、`Automations`、`Lists`、`Open Details`、`Members` 和 `Segments` 实体支持筛选。 + 对 `DateTime` 数据类型字段应用筛选条件时，必须按以下格式传递值：`yyyy-mm-ddThh:MM:ssZ`