# 连接到数据
AWS Glue *连接*是一个 Data Catalog 对象，用于存储特定数据存储的登录凭证、URI 字符串、虚拟私有云（VPC）信息等。AWS Glue 爬网程序、作业和开发端点使用连接方可访问特定类型的数据存储。您可以将连接用于源和目标，并在多个爬网程序或提取、转换、加载（ETL）作业中重复使用相同的连接。
最新版本的 AWS Glue 连接架构提供了一种统一的方式来跨 AWS 服务和应用程序（例如 AWS Glue、Amazon Athena 和 Amazon SageMaker AI Unified Studio）管理数据连接。
## 连接器和连接使用概览
*连接*包含连接到特定数据存储所需的属性。当您创建连接时，它将存储于 AWS Glue Data Catalog 中。选择一个连接器，然后创建基于该连接器的连接。
您可以为 AWS Marketplace 中非本地支持的数据存储订阅连接器，然后在创建连接时使用这些连接器。开发人员还可以创建自己的连接器，您可以在创建连接时使用它们。
**注意**
在 AWS Glue Studio 中使用自定义或 AWS Marketplace 连接器创建的连接不会在类型设置为 `UNKNOWN` 的 AWS Glue 控制台中显示。
以下步骤介绍了 AWS Glue Studio 中连接器的总体使用流程。
1. 订阅 AWS Marketplace 中的连接器，或者开发自己的连接器并将其上载到 AWS Glue Studio。有关更多信息，请参阅 [将连接器添加到 AWS Glue Studio](creating-custom-connectors.md#creating-connectors)。
1. 查看连接器使用信息。您可以在连接器产品页面上的 **Usage (使用)** 选项卡上找到此类信息。例如，如果您在此[适用于 Google BigQuery 的 AWS Glue 连接器](https://aws.amazon.com/marketplace/pp/prodview-w2ranrogj3xmm?ref_=beagle&applicationId=GlueStudio)产品页面上单击 **Usage** (使用) 选项卡，则可以在 **Additional Resources** (其他资源) 部分查看关于此连接器的使用博客的链接。
1. 创建连接。您可以选择要使用的连接器并为连接提供附加信息，例如登录凭证、URI 字符串和 Virtual Private Cloud（VPC）信息。有关更多信息，请参阅 [为连接器创建连接](creating-connections.md)。
1. 为您的任务创建 IAM 角色。作业代入您在创建它时指定的 IAM 角色的权限。此 IAM 角色必须具有对数据存储进行身份验证、从中提取数据和向其写入数据所需的权限。
1. 创建 ETL 任务并配置 ETL 任务的数据源属性。按照自定义连接器提供程序的指示提供连接选项和身份验证信息。有关更多信息，请参阅 [使用自定义连接器编写任务](job-authoring-custom-connectors.md)。
1. 添加转换或其他数据存储以自定义 ETL 任务，如[在 AWS Glue Studio 中启动视觉 ETL 作业](edit-nodes-chapter.md)中所示。
1. 如果为数据目标使用连接器，请为 ETL 任务配置数据目标属性。按照自定义连接器提供程序的指示提供连接选项和身份验证信息。有关更多信息，请参阅 [使用自定义连接器编写任务](job-authoring-custom-connectors.md)。
1. 配置任务属性以自定义任务运行环境，如[修改任务属性](managing-jobs-chapter.md#edit-jobs-properties)中所示。
1. 运行作业。
# 统一连接
AWS 最近推出了一项名为“SageMaker LakeHouse 连接”或“AWS Glue 统一连接”的新功能。使用此功能创建的连接可供多项 AWS 服务（例如 AWS Glue 和 Amazon Athena）使用。在 Amazon Athena 中创建数据来源时，我们会看到一个提及 AWS Glue 连接输入的部分。此时，Amazon Athena 将为您创建 AWS Glue 连接，包括连接的“AthenaProperties”部分中的任何 Amazon Athena 特定属性。
另一方面，如果您直接在 AWS Glue 中创建连接，则只会提示您输入 AWS Glue 和 Apache Spark 特定的属性；这些属性将存储在连接的“ConnectionProperties”和“SparkProperties”部分中。
这两种情况都会导致创建“统一连接”，但 Amazon Athena 中创建的连接仅配置为在 Amazon Athena 中使用，而在 AWS Glue 中创建的连接仅配置为在 AWS Glue 中使用。不过，可以用缺少的属性（Amazon Athena 或 Spark 属性）更新这些连接，以便两项服务都可以使用连接。Amazon SageMaker AIUnified Studio 通过在 AWS Glue 连接上填写所有必要的属性（“ConnectionProperties”“AthenaProperties”和“SparkProperties”）来自动解决这个问题，确保 AWS Glue 和 Amazon Athena 都可以使用连接。
值得注意的是，尽管我们将这些连接称为“统一连接”，但在 AWS Glue 或 Amazon Athena 中单独创建的连接并不是真正统一的连接，除非对它们进行了适当的配置，可供两项服务使用。只有通过 SageMaker Unified Studio 创建的并且可直接供多项服务使用的连接，才是真正统一的连接。
此外，在 AWS Glue 中创建的连接在 Amazon Athena 中不可见，因为 Amazon Athena 显示的数据来源包括对 AWS Glue 连接的引用，而不是 AWS Glue 连接本身。同理，在 Amazon Athena 中创建的连接在 AWS Glue Studio 中不可见，因为 AWS Glue Studio 会过滤掉所有未配置必要 AWS Glue 设置的连接。
AWS Glue Studio 默认创建统一连接。在 AWS Glue 控制台中，您可以在连接页面上的连接表、连接详细信息页面和作业详细信息页面中的连接表中查看连接的版本。
连接版本在“连接详细信息”上可见：
![\[屏幕截图显示有关 v2 连接的连接详细信息。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/connections-v2-connection-details-2.png)
查看所有连接时也可以看到连接版本。
![\[屏幕截图显示有关 v2 连接的连接详细信息。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/connections-list-view-v2-2.png)
最后，可以在作业的“作业详细信息”选项卡中查看连接版本。
![\[屏幕截图显示有关 v2 连接的连接详细信息。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/connections-v2-job-details-tab.png)
使用版本 2 连接，您可以获得以下扩展的数据连接功能：
+ **连接类型发现**：支持使用标准化模板创建连接。AWS Glue 自动发现您可以访问的连接类型以及给定连接类型的必需和可选输入。
+ **可重复使用性**：可在 AWS 数据处理引擎和工具（如 AWS Glue、Amazon Athena 和 Amazon SageMaker AI）中重复使用的连接定义。连接现在包含 AthenaProperties、SparkProperties、PythonProperties，除了存储在 ConnectionProperties 中的通用属性之外，它们还允许指定计算环境/服务特定的连接属性。现在，Athena 通过在 AthenaProperties 属性映射中指定特定于 Athena 的属性来在 AWS Glue 中创建连接。
+ **数据预览**：能够浏览元数据并预览来自连接的源的数据。
+ **连接器元数据**：可以使用可重复使用的连接来发现表元数据。
+ **服务相关密钥**：用户可以在 `CreateConnection` 请求中提供必要的 OAuth、基本或自定义身份验证凭证。CreateConnection API 会在您的账户中创建一个服务相关密钥并代表您存储凭证。
## 支持的身份验证类型
统一连接支持以下身份验证类型：
+ **BASIC**：大多数数据库连接类型和现有 AWS Glue 连接类型都支持基本身份验证，即通过用户名和密码进行验证。以前，SecretsManager 中的密钥命名方式与具体连接器相关，例如，可能采用 user、username、userName、opensearch.net.http.auth.user 等形式。统一连接的作用正是根据 USERNAME 和 PASSWORD 密钥，对基本身份验证连接类型进行标准化。
+ **OAUTH2**：大多数新推出的 SaaS 连接类型都支持 OAuth2 协议。
+ **自定义**：少数连接类型还会使用一些其他身份验证机制，例如 Google BigQuery，用户需要提供其从 Google BigQuery 获取的 JSON。
## 注意事项
在创建数据来源的统一连接时，请考虑以下区别：
+ 通过 AWS Glue Studio 创建统一连接时，用户凭证存储在 AWS Secrets Manager 中，而不是连接本身中。这意味着作业现在需要访问 Secrets Manager。
+ 如果任务在 VPC 中运行，则需要 VPC 端点或 NAT 网关才能访问 AWS Secrets Manager 和 Secure Token Service（STS），这会产生额外费用。
+ 对于某些数据来源（Redshift、SQL Server、MySQL、Oracle、PostgreSQL），通过 AWS Glue Studio 创建统一连接需要访问 AWS STS 和 AWS Secrets Manager。对于建立安全连接和检索访问虚拟私有云（VPC）内的这些数据来源所需的凭证而言，此操作必不可少。
+ 通过 AWS Glue Studio 创建统一连接需要具有访问 AWS Secrets Manager 和管理 VPC 资源权限的 IAM 角色（如果使用 VPC）：
+ secretsmanager:GetSecretValue
+ secretsmanager:PutSecretValue
+ secretsmanager:DescribeSecret
+ ec2:CreateNetworkInterface
+ ec2:DeleteNetworkInterface
+ ec2:DescribeNetworkInterfaces
+ ec2:DescribeSubnets
# 可用连接
AWS Glue 支持以下连接类型：
+ Adobe Analytics
+ Adobe Marketo Engage
+ Amazon Aurora（如果使用原生 JDBC 驱动程序则支持。并非所有驱动程序功能都可以利用）
+ Amazon DocumentDB
+ Amazon DynamoDB
+ Amazon OpenSearch Service，用于与 AWS Glue for Spark 结合使用。
+ Amazon Redshift
+ Asana
+ Azure Cosmos，用于将 Azure Cosmos DB for NoSQL 与 AWS Glue ETL 作业结合使用
+ Azure SQL，用于与 AWS Glue for Spark 结合使用。
+ Blackbaud
+ CircleCI
+ Datadog
+ Docusign Monitor
+ Domo
+ Dynatrace
+ Facebook Ads
+ Facebook Page Insights
+ Freshdesk
+ Freshsales
+ Google Ads
+ Google Analytics 4
+ Google BigQuery，用于与 AWS Glue for Spark 结合使用。
+ Google Search Console
+ Google Sheets
+ HubSpot
+ Instagram Ads
+ Intercom
+ JDBC
+ Jira Cloud
+ Kafka
+ Kustomer
+ LinkedIn
+ Mailchimp
+ Microsoft Dynamics 365 CRM
+ Microsoft Teams
+ Mixpanel
+ Monday
+ MongoDB
+ MongoDB Atlas
+ Okta
+ Oracle NetSuite
+ Paypal
+ Pendo
+ Pipedrive
+ Productboard
+ QuickBooks
+ REST API（需要设置连接类型，请参阅 [REST API 连接](https://docs.aws.amazon.com/glue/latest/dg/rest-api-connections.html)）
+ Salesforce
+ Salesforce Commerce Cloud
+ Salesforce Marketing Cloud
+ Salesforce Marketing Cloud Account Engagement（以前称为 Salesforce Pardot）
+ SAP HANA，用于与 AWS Glue for Spark 结合使用。
+ SAP OData
+ SendGrid
+ ServiceNow
+ Slack
+ Smartsheet
+ Snapchat Ads
+ Stripe
+ Snowflake，用于与 AWS Glue for Spark 结合使用。
+ Teradata Vantage，用于与 AWS Glue for Spark 结合使用。
+ Twilio
+ Vertica，用于与 AWS Glue for Spark 结合使用。
+ WooCommerce
+ Zendesk
+ Zoho CRM
+ Zoom Meetings
+ 各种 Amazon Relational Database Service（Amazon RDS）产品。
+ 网络（指定到 Amazon Virtual Private Cloud（Amazon VPC）中数据来源的连接）
使用 AWS Glue Studio，您还可以创建*连接器*的连接。连接器是一个可选代码包，可帮助访问 AWS Glue Studio 中的数据存储。有关更多信息，请参阅 [在 AWS Glue Studio 中使用连接器和连接](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html)
有关如何连接本地数据库的信息，请参阅 AWS 大数据博客网站上的 [How to access and analyze on-premises data stores using AWS Glue](https://aws.amazon.com/blogs/big-data/how-to-access-and-analyze-on-premises-data-stores-using-aws-glue/)。
要使用自定义 IAM 角色创建具有 VPC 配置的连接，它必须具有以下 VPC 访问操作：
+ secretsmanager:GetSecretValue
+ secretsmanager:PutSecretValue
+ secretsmanager:DescribeSecret
+ ec2:CreateNetworkInterface
+ ec2:DeleteNetworkInterface
+ ec2:DescribeNetworkInterfaces
+ ec2:DescribeSubnets
## 限制
+ 如果使用 AWS Glue API 创建了 v2 连接，则无法通过 AWS Glue 控制台编辑连接：
+ Amazon DocumentDB
+ Amazon Aurora
+ MariaDB
+ MongoDB Atlas
+ MongoDB
# REST API 连接
AWS Glue 连接器涵盖了 AWS 和外部的各种数据来源。但是，可能存在一些原生 AWS Glue 连接器不支持的专有系统或新兴平台。AWS Glue REST 连接器提供了一种机制来为任何具有基于 REST 的 API 的数据来源配置自定义连接器，其工作方式与原生支持的 AWS Glue 连接器相同。此功能最大限度地减少了构建自定义库或 ETL 脚本来访问这些数据来源的需求。
为了启用 REST API 连接器，引入AWS Glue了一个新AWS资源—— **连接类型**。下面的操作可用于管理与基于 REST API 的数据来源的连接：
+ **RegisterConnectionType**：根据提供的配置在 AWS Glue 中注册连接类型。有关请求结构，请参阅 [RegisterConnectionType](https://docs.aws.amazon.com/glue/latest/webapi/API_RegisterConnectionType.html)。
+ **DeleteConnectionType**：删除 AWS Glue 中的连接类型配置。请参阅 [DeleteConnectionType](https://docs.aws.amazon.com/glue/latest/webapi/API_DeleteConnectionType.html)。
+ **DescribeConnectionType**：提供 AWS Glue 中给定连接类型支持的选项的完整详细信息。请参阅 [DescribeConnectionType](https://docs.aws.amazon.com/glue/latest/webapi/API_DescribeConnectionType.html)。
+ **ListConnectionTypes**：返回连接类型列表以及每种 AWS Glue 连接类型支持的内容的高级详细信息。请参阅 [ListConnectionTypes](https://docs.aws.amazon.com/glue/latest/webapi/API_ListConnectionTypes.html)。
## 在 AWS Glue 中创建 REST 连接类型
要创建 REST 连接类型，请使用 AWS CLI、AWS SDK 或 AWS API 调用 RegisterConnectionType API。配置详细信息是基于所连接的 REST API 提供的。
**注意**
无法使用 AWS Glue 控制台创建 REST 连接
### 先决条件
在尝试配置 AWS Glue REST API 连接器之前，您需要熟悉 REST API 的内部工作方式。如果您拥有数据来源的 REST API 文档以及用于检查请求/响应结构的工具，将会很有帮助。
应确定 REST API 的下列属性：
+ 用于对 REST 端点发出的调用的身份验证机制。AWS GlueREST API 连接器支持：**基本身份验证、OAuth2 - ClientCredentials、OAuth2 - 授权码、OAuth2 - JWT 和自定义身份验证**。
+ 可通过 REST 端点传输的实体（数据对象）和相关元数据（如字段名称和数据类型）。
+ HTTP 请求和响应结构。此结构包括 HTTP 方法、端点 URL、标头、查询参数以及请求正文和响应有效载荷的格式。
+ 分页架构。AWS GlueREST API 连接器支持两种分页架构：`cursor-based` 和 `offset-based` 分页。
### RegisterConnectionType
根据提供的配置在 AWS Glue 中注册 ConnectionType。ConnectionType 资源是一种新的 AWS Glue 资源，用于存储有关数据来源如何解释请求和响应的详细信息。目前仅支持 REST 协议。它封装了有关 REST API 源的详细信息，例如：
+ **连接属性**：定义连接到 REST API 的 BaseUrl 以及在 AWS Glue CreateConnection 期间进行输入所需的任何其他请求参数。
+ **身份验证配置**：定义如何对 REST API 请求进行身份验证。在为连接类型创建 AWS Glue 连接时，将使用此配置。
+ **REST 配置**：定义用于从 REST API 源读取数据的 HTTP 请求和响应配置。需要在**全局**或**实体**级别配置下面的属性：
+ **请求方法**：定义 REST HTTP 方法。
+ **响应配置**：定义应如何解释 API 响应（包括正文中的记录或错误位置）。
+ **分页配置**：定义 REST API 用于对结果记录进行分页的策略以及如何发送/检索分页属性。
+ **验证端点配置**：定义验证 AWS Glue 连接时要调用的端点。
+ **实体配置**：定义连接器支持的 REST 实体及其架构。
### RegisterConnectionType 请求语法
请参阅 [RegisterConnectionType](https://docs.aws.amazon.com/glue/latest/webapi/API_RegisterConnectionType.html)
注册 REST API 连接类型后，即可用于创建与已配置数据来源的连接。有关详细说明，请参阅[连接到 REST API](https://docs.aws.amazon.com/glue/latest/dg/connecting-to-data-rest-api.html)。
# AWS Glue 连接属性
本主题包含有关 AWS Glue 连接属性的信息。
**Topics**
+ [必需的连接属性](#connection-properties-required)
+ [AWS Glue JDBC 连接属性](#connection-properties-jdbc)
+ [AWS Glue MongoDB 和 MongoDB Atlas 连接属性](#connection-properties-mongodb)
+ [Salesforce 连接属性](#connection-properties-salesforce)
+ [Snowflake 连接](#connection-properties-snowflake)
+ [Vertica 连接](#connection-properties-vertica)
+ [SAP HANA 连接](#connection-properties-saphana)
+ [Azure SQL 连接](#connection-properties-azuresql)
+ [Teradata Vantage 连接](#connection-properties-teradata)
+ [OpenSearch Service 连接](#connection-properties-opensearch)
+ [Azure Cosmos 连接](#connection-properties-azurecosmos)
+ [AWS Glue SSL 连接属性](#connection-properties-SSL)
+ [适用于客户端身份验证的 Apache Kafka 连接属性](#connection-properties-authentication)
+ [Google BigQuery 连接](#connection-properties-bigquery)
+ [Vertica 连接](#connection-properties-vertica)
## 必需的连接属性
在 AWS Glue 控制台上定义连接时，您必须提供以下属性值：
**连接名称**
为连接输入一个唯一名称。
**连接类型**
选择 **JDBC** 或特定的连接类型之一。
有关 JDBC 连接类型的详细信息，请参阅[AWS Glue JDBC 连接属性](#connection-properties-jdbc)
选择 **Network (网络)** 以连接到 Amazon Virtual Private Cloud 环境（Amazon VPC）中的数据源。
根据您选择的类型，AWS Glue 控制台会显示其他必需字段。例如，如果选择 **Amazon RDS**，则必须选择数据库引擎。
**需要 SSL 连接**
选择此选项时，AWS Glue 必须验证数据存储连接是通过受信任的安全套接字层（SSL）进行连接的。
有关更多信息（包括选择此选项时可用的其他选项），请参阅[AWS Glue SSL 连接属性](#connection-properties-SSL)。
**选择 MSK 集群（仅适用于 Amazon managed streaming for Apache Kafka（MSK））**
指定来自另一个 AWS 账户的 MSK 集群。
**Kafka 引导启动服务器 URL（仅限 Kafka）**
指定引导服务器 URL 的逗号分隔的列表。包括端口号。例如：b-1.vpc-test-2.o4q88o.c6.kafka.us-east-1.amazonaws.com:9094, b-2.vpc-test-2.o4q88o.c6.kafka.us-east-1.amazonaws.com:9094, b-3.vpc-test-2.o4q88o.c6.kafka.us-east-1.amazonaws.com:9094
## AWS Glue JDBC 连接属性
AWS Glue Studio 现在可以为 MySQL、Oracle、PostgresSQL、Redshift 和 SQL Server 数据来源创建统一连接。这需要额外的步骤才能访问 Secrets Manager 和 VPC 资源，可能会产生额外费用。可以通过为相应连接选择连接名称，在 AWS Glue Studio 中访问这些连接。
有关更多信息，请参阅 [注意事项](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。
AWS Glue 可通过 JDBC 连接来连接到以下数据存储：
+ Amazon Redshift
+ Amazon Aurora
+ Microsoft SQL Server
+ MySQL
+ Oracle
+ PostgreSQL
+ Snowflake，使用 AWS Glue 爬网程序时。
+ Aurora（如果使用原生 JDBC 驱动程序，则支持。并非所有驱动程序功能都可以利用）
+ Amazon RDS for MariaDB
**重要**
目前，ETL 任务只能在一个子网内使用 JDBC 连接。如果一个作业中有多个数据存储，则它们必须在同一子网，或者可以从该子网访问。
如果您选择为 AWS Glue 爬网程序引入自己的 JDBC 驱动程序版本，则您的爬网程序将消耗 AWS Glue 作业 和 Amazon S3 中的资源，以确保您提供的驱动程序在您的环境中运行。额外的资源使用量将反映在您的账户中。此外，提供自己的 JDBC 驱动程序并不意味着爬网程序能够利用该驱动程序的所有功能。驱动程序仅限于[在 Data Catalog 中定义连接](https://docs.aws.amazon.com/glue/latest/dg/glue-connections.html)中描述的属性。
以下是适用于 JDBC 连接类型的其他属性。
**JDBC URL**
输入 JDBC 数据存储的 URL。对于大多数数据库引擎，此字段将采用以下格式。在此格式中，将 *protocol*、*host*、*port* 和 *db\$1name* 替换为您自己的信息。
` jdbc:protocol://host:port/db_name `
根据数据库引擎，可能需要不同的 JDBC URL 格式。此格式可能稍微不同地使用冒号 (:) 和斜杠 (/) 或不同的关键字来指定数据库。
要让 JDBC 连接到数据存储，数据存储中需要 `db_name`。`db_name` 用于与提供的 `username` 和 `password` 建立网络连接。当连接时，AWS Glue 可以访问数据存储中的其他数据库以运行爬网程序或运行 ETL 作业。
以下 JDBC URL 示例显示了多个数据库引擎的语法。
+ 要连接到具有 `dev` 数据库的 Amazon Redshift 群集数据存储：
`jdbc:redshift://xxx.us-east-1.redshift.amazonaws.com:8192/dev`
+ 要连接到具有 `employee` 数据库的 Amazon RDS for MySQL 数据存储：
`jdbc:mysql://xxx-cluster.cluster-xxx.us-east-1.rds.amazonaws.com:3306/employee`
+ 要连接到具有 `employee` 数据库的 Amazon RDS for PostgreSQL 数据存储：
`jdbc:postgresql://xxx-cluster.cluster-xxx.us-east-1.rds.amazonaws.com:5432/employee`
+ 要连接到具有 `employee` 服务名称的 Amazon RDS for Oracle 数据存储：
`jdbc:oracle:thin://@xxx-cluster.cluster-xxx.us-east-1.rds.amazonaws.com:1521/employee`
Amazon RDS for Oracle 的语法可以遵循以下模式。在这些模式中，将 *host*、*port*、*service\$1name* 和 *SID* 替换为您自己的信息。
+ `jdbc:oracle:thin://@host:port/service_name`
+ `jdbc:oracle:thin://@host:port:SID`
+ 要连接到具有 `employee` 数据库的 Amazon RDS for Microsoft SQL Server 数据存储：
`jdbc:sqlserver://xxx-cluster.cluster-xxx.us-east-1.rds.amazonaws.com:1433;databaseName=employee`
Amazon RDS for SQL Server 的语法可以遵循以下模式：在这些模式中，将 *server\$1name*、*port* 和 *db\$1name* 替换为您自己的信息。
+ `jdbc:sqlserver://server_name:port;database=db_name`
+ `jdbc:sqlserver://server_name:port;databaseName=db_name`
+ 要连接到 `employee` 数据库的 Amazon Aurora PostgreSQL 实例，请指定数据库实例的终端节点、端口和数据库名称：
`jdbc:postgresql://employee_instance_1.xxxxxxxxxxxx.us-east-2.rds.amazonaws.com:5432/employee`
+ 要连接到有 `employee` 数据库的 Amazon RDS for MariaDB 数据存储，请指定数据库实例的端点、端口和数据库名称：
`jdbc:mysql://xxx-cluster.cluster-xxx.aws-region.rds.amazonaws.com:3306/employee`
+
**警告**
只有 AWS Glue 爬网程序支持 Snowflake JDBC 连接。在 AWS Glue 作业中使用 Snowflake 连接器时，请使用 Snowflake 连接类型。
要连接到 `sample` 数据库的 Snowflake 实例，请指定 Snowflake实例的端点、用户、数据库名称和角色名称。您可以选择添加 `warehouse` 参数。
`jdbc:snowflake://account_name.snowflakecomputing.com/?user=user_name&db=sample&role=role_name&warehouse=warehouse_name`
**重要**
对于通过 JDBC 进行的 Snowflake 连接，将强制执行 URL 中参数的顺序，并且必须按照 `user`、`db`、`role_name` 和 `warehouse` 进行排序。
+ 要使用 AWS 私有链接连接到 `sample` 数据库的 Snowflake 实例，请按如下方式指定 Snowflake JDBC URL：
`jdbc:snowflake://account_name.region.privatelink.snowflakecomputing.com/?user=user_name&db=sample&role=role_name&warehouse=warehouse_name`
**用户名**
我们建议您使用 AWS 密钥存储连接凭证，而不是直接提供用户名和密码。有关更多信息，请参阅 [在 AWS Secrets Manager 中存储连接凭证](connection-properties-secrets-manager.md)。
提供有权访问 JDBC 数据存储的用户名。
**密码**
输入对 JDBC 数据存储具有访问权限的用户名的密码。
**端口：**
输入 JDBC URL 中使用的端口以连接到 Amazon RDS Oracle 实例。只有在为 Amazon RDS Oracle 实例选择 **Require SSL connection (需要 SSL 连接)** 时会显示此字段。
**VPC**
选择包含您的数据存储的 Amazon Virtual Private Cloud (VPC) 的名称。AWS Glue 控制台会列出当前区域的所有 VPC。
在使用托管 AWS 的 JDBC 连接（例如来自 Snowflake 的数据）时，您的 VPC 应该有一个 NAT 网关，用于将流量分成公有子网和私有子网。公有子网用于连接外部源，内部子网用于 AWS Glue 处理。有关为外部连接配置 Amazon VPC 的信息，请阅读[使用 NAT 设备连接到互联网或其他网络](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat.html)以及 [设置 Amazon VPC 以建立从 AWS Glue 到 Amazon RDS 数据存储的 JDBC 连接](setup-vpc-for-glue-access.md)。
**子网**
选择包含您的数据存储的 VPC 内的子网。AWS Glue 控制台列出了您的 VPC 中的数据存储的所有子网。
**安全组**
选择与您的数据存储关联的安全组。AWS Glue 需要一个或多个安全组且其入站源规则允许 AWS Glue 进行连接。AWS Glue 控制台列出了所有被授权对您的 VPC 进行入站访问的安全组。AWS Glue 将这些安全组与连接到您的 VPC 的子网的弹性网络接口关联。
**JDBC 驱动程序类名 - 可选**
提供自定义 JDBC 驱动程序类名：
+ Postgres – org.postgresql.Driver
+
MySQL – com.mysql.jdbc.Driver, com.mysql.cj.jdbc.Driver
+
Redshift – com.amazon.redshift.jdbc.Driver, com.amazon.redshift.jdbc42.Driver
+
Oracle – oracle.jdbc.driver.OracleDriver
+
SQL Server – com.microsoft.sqlserver.jdbc.SQLServerDriver
**JDBC 驱动程序 S3 路径 - 可选**
向自定义 JDBC 驱动程序提供 Amazon S3 位置。这是 .jar 文件的绝对路径。如果您想提供自己的 JDBC 驱动程序，连接到您的爬网程序支持的数据库的数据源，则可以为参数 `customJdbcDriverS3Path` 和 `customJdbcDriverClassName` 指定值。
使用客户提供的 JDBC 驱动程序仅限于所需的 [必需的连接属性](#connection-properties-required)。
## AWS Glue MongoDB 和 MongoDB Atlas 连接属性
以下是适用于 MongoDB 或 MongoDB Atlas 连接类型的其他属性。
**MongoDB URL**
输入 MongoDB 或 MongoDB Atlas 数据存储的 URL：
+ 对于 MongoDB：mongodb://host:port/database。主机可以是主机名、IP 地址或 UNIX 域套接字。如果连接字符串未指定端口，则使用默认的 MongoDB 端口 27017。
+ 对于 MongoDB Atlas：mongodb\$1srv://server.example.com/database。主机可以是后面对应于 DNS SRV 记录的主机名。SRV 格式不需要端口，将使用默认的 MongoDB 端口 27017。
**用户名**
我们建议您使用 AWS 密钥存储连接凭证，而不是直接提供用户名和密码。有关更多信息，请参阅 [在 AWS Secrets Manager 中存储连接凭证](connection-properties-secrets-manager.md)。
提供有权访问 JDBC 数据存储的用户名。
**密码**
输入具有 MongoDB 或 MongoDB Atlas 数据存储访问权限的用户名的密码。
## Salesforce 连接属性
以下是 Salesforce 连接类型的附加属性。
+ `ENTITY_NAME`（字符串）–（必填）用于读/写。您在 Salesforce 中的对象的名称。
+ `API_VERSION`（字符串）–（必填）用于读/写。您想要使用的 Salesforce Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `IMPORT_DELETED_RECORDS`（字符串）– 默认：FALSE。用于读取。在查询时获取删除记录。
+ `WRITE_OPERATION`（字符串）– 默认：INSERT。用于写入。值应为 INSERT、UPDATE、UPSERT、DELETE。
+ `ID_FIELD_NAMES`（字符串）– 默认：null。仅用于 UPSERT。
## Snowflake 连接
以下属性用于设置在 AWS Glue ETL 作业中使用的 Snowflake 连接。爬取 Snowflake 时，请使用 JDBC 连接。
**Snowflake URL**
Snowflake 端点的 URL。有关 Snowflake 端点 URL 的更多信息，请参阅 Snowflake 文档中的 [Connecting to Your Accounts](https://docs.snowflake.com/en/user-guide/organizations-connect)。
**AWS 密钥**
AWS Secrets Manager 中密钥的**密钥名称**。AWS Glue 将使用密钥的 `sfUser` 和 `sfPassword` 连接到 Snowflake。
**Snowflake 角色（可选）**
连接时 AWS Glue 将使用的 Snowflake 安全角色。
配置与托管在 Amazon VPC 中的 Snowflake 端点的连接时，请使用以下属性。AWS PrivateLink
**VPC**
选择包含您的数据存储的 Amazon Virtual Private Cloud (VPC) 的名称。AWS Glue 控制台会列出当前区域的所有 VPC。
**子网**
选择包含您的数据存储的 VPC 内的子网。AWS Glue 控制台列出了您的 VPC 中的数据存储的所有子网。
**安全组**
选择与您的数据存储关联的安全组。AWS Glue 需要一个或多个安全组且其入站源规则允许 AWS Glue 进行连接。AWS Glue 控制台列出了所有被授权对您的 VPC 进行入站访问的安全组。AWS Glue 将这些安全组与连接到您的 VPC 的子网的弹性网络接口关联。
## Vertica 连接
使用以下属性设置 AWS Glue ETL 作业的 Vertica 连接。
**Vertica 主机**
Vertica 安装的主机名。
**Vertica 端口**
可用于访问 Vertica 安装的端口。
**AWS 密钥**
AWS Secrets Manager 中密钥的**密钥名称**。AWS Glue 将使用密钥的键连接到 Vertica。
配置与 Amazon VPC 中的 Vertica 端点的连接时，请使用以下属性。
**VPC**
选择包含您的数据存储的 Amazon Virtual Private Cloud (VPC) 的名称。AWS Glue 控制台会列出当前区域的所有 VPC。
**子网**
选择包含您的数据存储的 VPC 内的子网。AWS Glue 控制台列出了您的 VPC 中的数据存储的所有子网。
**安全组**
选择与您的数据存储关联的安全组。AWS Glue 需要一个或多个安全组且其入站源规则允许 AWS Glue 进行连接。AWS Glue 控制台列出了所有被授权对您的 VPC 进行入站访问的安全组。AWS Glue 将这些安全组与连接到您的 VPC 的子网的弹性网络接口关联。
## SAP HANA 连接
使用以下属性设置 AWS Glue ETL 作业的 SAP HANA 连接。
**SAP HANA URL**
一个 SAP JDBC URL。
SAP HANA JDBC URL 的格式为 `jdbc:sap://saphanaHostname:saphanaPort/?databaseName=saphanaDBname,ParameterName=ParameterValue`
AWS Glue 需要以下 JDBC URL 参数：
+ `databaseName` – SAP HANA 中要连接的默认数据库。
**AWS 密钥**
AWS Secrets Manager 中密钥的**密钥名称**。AWS Glue 将使用密钥的键连接到 SAP HANA。
配置与托管在 Amazon VPC 中的 SAP HANA 端点的连接时，请使用以下属性：
**VPC**
选择包含您的数据存储的 Amazon Virtual Private Cloud (VPC) 的名称。AWS Glue 控制台会列出当前区域的所有 VPC。
**子网**
选择包含您的数据存储的 VPC 内的子网。AWS Glue 控制台列出了您的 VPC 中的数据存储的所有子网。
**安全组**
选择与您的数据存储关联的安全组。AWS Glue 需要一个或多个安全组且其入站源规则允许 AWS Glue 进行连接。AWS Glue 控制台列出了所有被授权对您的 VPC 进行入站访问的安全组。AWS Glue 将这些安全组与连接到您的 VPC 的子网的弹性网络接口关联。
## Azure SQL 连接
使用以下属性设置 AWS Glue ETL 作业的 Azure SQL 连接。
**Azure SQL URL**
Azure SQL 端点的 JDBC URL。
该 URL 必须为以下格式：`jdbc:sqlserver://databaseServerName:databasePort;databaseName=azuresqlDBname;`。
AWS Glue 需要以下 URL 属性：
+ `databaseName` – Azure SQL 中要连接的默认数据库。
有关 Azure SQL 托管实例的 JDBC URL 的更多信息，请参阅 [Microsoft 文档](https://learn.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=azuresqldb-mi-current)。
**AWS 密钥**
AWS Secrets Manager 中密钥的**密钥名称**。AWS Glue 将使用密钥的键连接到 Azure SQL。
## Teradata Vantage 连接
使用以下属性设置 AWS Glue ETL 作业的 Teradata Vantage 连接。
**Teradata URL**
要连接到 Teradata 实例，请指定数据库实例的主机名和相关的 Teradata 参数：
`jdbc:teradata://teradataHostname/ParameterName=ParameterValue,ParameterName=ParameterValue`.
AWS Glue 支持以下 JDBC URL 参数：
+ `DATABASE_NAME`— Teradata 中要连接的默认数据库。
+ `DBS_PORT` – 如果属于非标准端口，则请指定 Teradata 端口。
**AWS 密钥**
AWS Secrets Manager 中密钥的**密钥名称**。AWS Glue 将使用密钥的键连接到 Teradata Vantage。
配置与托管在 Amazon VPC 中的 Teradata Vantage 端点的连接时，请使用以下属性：
**VPC**
选择包含您的数据存储的 Amazon Virtual Private Cloud (VPC) 的名称。AWS Glue 控制台会列出当前区域的所有 VPC。
**子网**
选择包含您的数据存储的 VPC 内的子网。AWS Glue 控制台列出了您的 VPC 中的数据存储的所有子网。
**安全组**
选择与您的数据存储关联的安全组。AWS Glue 需要一个或多个安全组且其入站源规则允许 AWS Glue 进行连接。AWS Glue 控制台列出了所有被授权对您的 VPC 进行入站访问的安全组。AWS Glue 将这些安全组与连接到您的 VPC 的子网的弹性网络接口关联。
## OpenSearch Service 连接
使用以下属性设置 AWS Glue ETL 作业的 OpenSearch Service 连接。
**域端点**
Amazon OpenSearch Service 域端点的默认格式为 https://search-*domainName*-*unstructuredIdContent*.*region*.es.amazonaws.com。有关如何确定域端点的更多信息，请参阅《Amazon OpenSearch Service 开发人员指南》中的 [Creating and managing Amazon OpenSearch Service domains](https://docs.aws.amazon.com//opensearch-service/latest/developerguide/createupdatedomains.html)。
**端口：**
端点上的端口已打开。
**AWS 密钥**
AWS Secrets Manager 中密钥的**密钥名称**。AWS Glue 将使用密钥的键连接到 OpenSearch Service。
配置与托管在 Amazon VPC 中的 OpenSearch Service 端点的连接时，请使用以下属性：
**VPC**
选择包含您的数据存储的 Amazon Virtual Private Cloud (VPC) 的名称。AWS Glue 控制台会列出当前区域的所有 VPC。
**子网**
选择包含您的数据存储的 VPC 内的子网。AWS Glue 控制台列出了您的 VPC 中的数据存储的所有子网。
**安全组**
选择与您的数据存储关联的安全组。AWS Glue 需要一个或多个安全组且其入站源规则允许 AWS Glue 进行连接。AWS Glue 控制台列出了所有被授权对您的 VPC 进行入站访问的安全组。AWS Glue 将这些安全组与连接到您的 VPC 的子网的弹性网络接口关联。
## Azure Cosmos 连接
使用以下属性设置 AWS Glue ETL 作业的 Azure Cosmos 连接。
**Azure Cosmos DB 账户端点 URI**
用于连接到 Azure Cosmos 的端点。有关更多信息，请参阅 [Azure 文档](https://learn.microsoft.com/en-us/rest/api/cosmos-db/cosmosdb-resource-uri-syntax-for-rest)。
**AWS 密钥**
AWS Secrets Manager 中密钥的**密钥名称**。AWS Glue 将使用密钥的键连接到 Azure Cosmos。
## AWS Glue SSL 连接属性
下面是有关 **Require SSL connection**（需要 SSL 连接）属性的详细信息。
如果不需要 SSL 连接，则 AWS Glue 在使用 SSL 加密与数据存储的连接时会忽略失败。有关配置说明，请参阅数据存储的文档。当您选择此选项时，如果 AWS Glue 无法连接，则开发端点中的作业运行、爬网程序或 ETL 语句将失败。
**注意**
Snowflake 默认支持 SSL 连接，因此此属性不适用于 Snowflake。
此选项在 AWS Glue 客户端进行验证。对于 JDBC 连接，AWS Glue 仅通过 SSL 连接并进行证书和主机名验证。SSL 连接支持适用于：
+ Oracle 数据库
+ Microsoft SQL Server
+ PostgreSQL
+ Amazon Redshift
+ MySQL（仅限 Amazon RDS 实例）
+ Amazon Aurora MySQL（仅限 Amazon RDS 实例）
+ Amazon Aurora PostgreSQL（仅限 Amazon RDS 实例）
+ Kafka，其中包括 Amazon Managed Streaming for Apache Kafka
+ MongoDB
**注意**
要使 **Amazon RDS Oracle** 数据存储能够使用 **Require SSL connection (需要 SSL 连接)**，您必须创建一个选项组并将其附加到 Oracle 实例。
登录 AWS 管理控制台，然后通过以下网址打开 Amazon RDS 控制台：[https://console.aws.amazon.com/rds/](https://console.aws.amazon.com/rds/)。
将 **Option group (选项组)** 添加到 Amazon RDS Oracle 实例。有关如何在 Amazon RDS 控制台上添加选项组的更多信息，请参阅[创建选项组](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithOptionGroups.html#USER_WorkingWithOptionGroups.Create)
将 **Option (选项)** 添加到 **SSL** 的选项组。您为 SSL 指定的**端口**稍后在您为 Amazon RDS Oracle 实例创建 AWS Glue JDBC 连接 URL 时使用。有关如何在 Amazon RDS 控制台上添加选项的更多信息，请参阅 *Amazon RDS 用户指南*中的[向选项组添加选项](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithOptionGroups.html#USER_WorkingWithOptionGroups.AddOption)。有关 Oracle SSL 选项的更多信息，请参阅 *Amazon RDS 用户指南*中的 [Oracle SSL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.Oracle.Options.SSL.html)。
在 AWS Glue 控制台中，创建到 Amazon RDS Oracle 实例的连接。在连接定义中，选择 **Require SSL connection (需要 SSL 连接)**。在请求时，输入您在 Amazon RDS Oracle SSL 选项中使用的**端口**。
当为连接选择了 **Require SSL connection (需要 SSL 连接)** 时，可使用以下其他可选属性。
**S3 中的自定义 JDBC 证书**
如果您的证书当前用于与本地或云数据库进行 SSL 通信，则可以将该证书用于与 AWS Glue 数据源或目标的 SSL 连接。输入包含自定义根证书的 Amazon Simple Storage Service（Amazon S3）位置。AWS Glue 使用此证书建立与数据库的 SSL 连接。AWS Glue 仅处理 X.509 证书。该证书必须经过 DER 编码，并以 base64 编码 PEM 格式提供。
如果将此字段留空，则使用默认证书。
**自定义 JDBC 证书字符串**
输入 JDBC 数据库特定的证书信息。此字符串用于域匹配或可分辨名称 (DN) 匹配。对于 Oracle 数据库，此字符串会映射到 `tnsnames.ora` 文件中安全性部分中的 `SSL_SERVER_CERT_DN` 参数。对于 Microsoft SQL Server，此字符串将用作 `hostNameInCertificate`。
下面是适用于 Oracle 数据库 `SSL_SERVER_CERT_DN` 参数的示例。
```
cn=sales,cn=OracleContext,dc=us,dc=example,dc=com
```
**Kafka 私有 CA 证书位置**
如果您拥有当前用于与 Kafka 数据存储进行 SSL 通信的证书，则可以在 AWS Glue 连接中使用该证书。此选项对于 Kafka 数据存储是必需的，对于 Amazon Managed Streaming for Apache Kafka 数据存储是可选的。输入包含自定义根证书的 Amazon Simple Storage Service（Amazon S3）位置。AWS Glue 使用此证书建立与 Kafka 数据存储的 SSL 连接。AWS Glue 仅处理 X.509 证书。该证书必须经过 DER 编码，并以 base64 编码 PEM 格式提供。
**Skip certificate validation (跳过证书验证)**
选中 **Skip certificate validation (跳过证书验证)** 复选框，可跳过 AWS Glue 对自定义证书的验证。如果您选择验证，则 AWS Glue 会验证证书的签名算法和主题公有密钥算法。如果证书验证失败，则使用该连接的任何 ETL 作业或爬网程序都将失败。
唯一允许的签名算法是 SHA256withRSA、SHA384withRSA 或 SHA512withRSA。对于主题公有密钥算法，密钥长度必须至少为 2048 位。
**Kafka 客户端密钥库位置**
用于 Kafka 客户端身份验证的客户端密钥库文件的 Amazon S3 位置。路径必须采用 s3://bucket/prefix/filename.jks 的形式。它必须以文件名和 .jks 扩展名结尾。
**Kafka 客户端密钥库密码（可选）**
用于访问提供的密钥库的密码。
**Kafka 客户端密钥密码（可选）**
密钥库可以由多个密钥组成，因此这是访问要与 Kafka 服务器端密钥一起使用的客户端密钥的密码。
## 适用于客户端身份验证的 Apache Kafka 连接属性
AWS Glue 支持简单身份验证和安全层（SASL）框架，用于在创建 Apache Kafka 连接时进行身份验证。SASL 框架支持各种身份验证机制，且 AWS Glue 提供 SCRAM（用户名和密码）、GSSAPI（Kerberos 协议）和 PLAIN 协议。
使用 AWS Glue Studio 配置下面的一种客户端身份认证方法。有关更多信息，请参阅《AWS Glue Studio 用户指南》中的 [Creating connections for connectors](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#creating-connections)。
+ 无 – 不进行身份验证。如果是为进行测试而创建连接，这非常有用。
+ SASL/SCRAM-SHA-512 – 选择此身份验证方法将允许您指定身份验证凭证。有两个可用的选项：
+ 使用 AWS Secrets Manager（推荐）- 如果选择此选项，则可以将用户名和密码存储在 AWS Secrets Manager 中，然后让 AWS Glue 在需要时进行访问。指定存储 SSL 或 SASL 身份验证凭证的密钥。有关更多信息，请参阅 [在 AWS Secrets Manager 中存储连接凭证](connection-properties-secrets-manager.md)。
+ 直接提供用户名和密码。
+ SASL/GSSAPI (Kerberos) – 如果选择此选项，则可以选择 keytab 文件、krb5.conf 文件的位置，然后输入 Kerberos 主体名称和 Kerberos 服务名称。keytab 文件和 krb5.conf 文件的位置必须位于 Amazon S3 位置。由于 MSK 尚不支持 SASL/GSSAPI，所以此选项仅适用于客户管理的 Apache Kafka 集群。有关更多信息，请参阅 [MIT Kerberos 文档：keytab](https://web.mit.edu/kerberos/krb5-latest/doc/basic/keytab_def.html)。
+ SASL/PLAIN - 选择此身份验证方法以指定身份验证凭证。有两个可用的选项：
+ 使用 AWS Secrets Manager（推荐）- 如果选择此选项，则可以将凭证存储在 AWS Secrets Manager 中，然后让 AWS Glue 在需要时访问该信息。指定存储 SSL 或 SASL 身份验证凭证的密钥。
+ 直接提供用户名和密码。
+ SSL 客户端身份验证 – 如果选择此选项，则可以通过浏览 Amazon S3 来选择 Kafka 客户端密钥库的位置。或者，您可以输入 Kafka 客户端密钥库密码和 Kafka 客户端密钥密码。
## Google BigQuery 连接
以下属性用于设置在 AWS Glue ETL 作业中使用的 Google BigQuery 连接。有关更多信息，请参阅 [BigQuery 连接](aws-glue-programming-etl-connect-bigquery-home.md)。
AWS 密钥
AWS Secrets Manager 中的密钥的**秘密名称**。AWS GlueETL 作业将使用您的秘密的 `credentials` 密钥连接到 Google BigQuery。
## Vertica 连接
以下属性用于设置在 AWS Glue ETL 作业中使用的 Azure Cosmos 连接。有关更多信息，请参阅 [Vertica 连接](aws-glue-programming-etl-connect-vertica-home.md)。
# 在 AWS Secrets Manager 中存储连接凭证
我们建议您使用 AWS Secrets Manager 提供数据存储的连接凭证。以这种方式使用 Secrets Manager 可让 AWS Glue 在运行时访问您的密钥，以运行 ETL 任务和爬网程序，并帮助确保您的凭证安全。
**先决条件**
要将 Secrets Manager 与 AWS Glue 一起使用，您必须授予 [AWS Glue 的 IAM 角色](create-an-iam-role.md)权限才能检索密钥值。AWS 托管策略 `AWSGlueServiceRole` 不包含 AWS Secrets Manager 权限。有关示例 IAM 策略，请参阅《AWS Secrets Manager 用户指南》中的 [Example: Permission to retrieve secret values](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_examples.html#auth-and-access_examples_read)（示例：检索密钥值的权限）。
根据网络设置，您可能还需要创建一个 VPC 端点，以在 VPC 与 Secrets Manager 之间建立私有连接。有关更多信息，请参阅[使用 AWS Secrets Manager VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)。
**为 AWS Glue 创建密钥**
1. 请遵循《*AWS Secrets Manager 用户指南*》中的[创建和管理密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html)中的说明。以下示例 JSON 展示了在为 AWS Glue 创建密钥时如何在 **Plaintext**（明文）选项卡中指定凭证。
```
{
"username": "EXAMPLE-USERNAME",
"password": "EXAMPLE-PASSWORD"
}
```
1. 使用 AWS Glue Studio 界面将密钥与连接相关联。有关详细信息，请参阅《AWS Glue Studio 用户指南》**中的 [Creating connections for connectors](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#creating-connections)。
# 添加 AWS Glue 连接
您可以通过编程方式连接到 AWS Glue for Spark 中的数据来源。有关更多信息，请参阅 [AWS Glue for Spark 中适用于 ETL 的连接类型和选项](aws-glue-programming-etl-connect.md)。
您还可以使用 AWS Glue 控制台来添加、编辑、删除和测试连接。有关 AWS Glue 连接的信息，请参阅[连接到数据](glue-connections.md)。
**Topics**
+ [连接到 Adobe Analytics](connecting-to-adobe-analytics.md)
+ [连接到 Adobe Marketo Eng](connecting-to-data-adobe-marketo-engage.md)
+ [连接到 AWS Glue Studio 中的 Amazon Redshift](connecting-to-data-redshift.md)
+ [连接到 Asana](connecting-to-asana.md)
+ [在 AWS Glue Studio 中连接到 Azure Cosmos DB](connecting-to-data-azurecosmos.md)
+ [在 AWS Glue Studio 中连接到 Azure SQL](connecting-to-data-azuresql.md)
+ [连接到 Blackbaud Raiser Edge NXT](connecting-to-data-blackbaud.md)
+ [连接到 CircleCI](connecting-to-data-circleci.md)
+ [连接到 Datadog](connecting-to-datadog.md)
+ [连接到 Docusign Monitor](connecting-to-data-docusign-monitor.md)
+ [连接到 Domo](connecting-to-data-domo.md)
+ [连接到 Dynatrace](connecting-to-data-dynatrace.md)
+ [连接到 Facebook Ads](connecting-to-data-facebook-ads.md)
+ [连接到 Facebook Page Insights](connecting-to-data-facebook-page-insights.md)
+ [连接到 Freshdesk](connecting-to-data-freshdesk.md)
+ [连接到 Freshsales](connecting-to-data-freshsales.md)
+ [连接到 Google Ads](connecting-to-googleads.md)
+ [连接到 Google Analytics 4](connecting-to-googleanalytics.md)
+ [连接到 AWS Glue Studio 中的 Google BigQuery](connecting-to-data-bigquery.md)
+ [连接到 Google Search Console](connecting-to-data-google-search-console.md)
+ [连接到 Google Sheets](connecting-to-googlesheets.md)
+ [连接到 HubSpot](connecting-to-data-hubspot.md)
+ [连接到 Instagram Ads](connecting-to-data-instagram-ads.md)
+ [在 AWS Glue Studio 中连接到 Intercom](connecting-to-data-intercom.md)
+ [连接到 Jira Cloud](connecting-to-data-jira-cloud.md)
+ [连接到 Kustomer](connecting-to-data-kustomer.md)
+ [连接到 LinkedIn](connecting-to-linkedin.md)
+ [连接到 Mailchimp](connecting-to-mailchimp.md)
+ [连接到 Microsoft Dynamics 365 CRM](connecting-to-microsoft-dynamics-365.md)
+ [连接到 Microsoft Teams](connecting-to-microsoft-teams.md)
+ [连接到 Mixpanel](connecting-to-mixpanel.md)
+ [连接到 Monday](connecting-to-monday.md)
+ [在 AWS Glue Studio 中连接到 MongoDB](connecting-to-data-mongodb.md)
+ [连接到 Oracle NetSuite](connecting-to-data-oracle-netsuite.md)
+ [在 AWS Glue Studio 中连接到 OpenSearch Service](connecting-to-data-opensearch.md)
+ [连接到 Okta](connecting-to-okta.md)
+ [连接到 PayPal](connecting-to-data-paypal.md)
+ [连接到 Pendo](connecting-to-pendo.md)
+ [连接到 Pipedrive](connecting-to-pipedrive.md)
+ [连接到 Productboard](connecting-to-productboard.md)
+ [连接到 QuickBooks](connecting-to-data-quickbooks.md)
+ [连接到 REST API](connecting-to-data-rest-api.md)
+ [连接到 Salesforce](connecting-to-data-salesforce.md)
+ [连接到 Salesforce Marketing Cloud](connecting-to-data-salesforce-marketing-cloud.md)
+ [连接到 Salesforce Commerce Cloud](connecting-to-salesforce-commerce-cloud.md)
+ [连接到 Salesforce Marketing Cloud Account Engagement](connecting-to-data-salesforce-marketing-cloud-account-engagement.md)
+ [在 AWS Glue Studio 中连接到 SAP HANA](connecting-to-data-saphana.md)
+ [连接到 SAP OData](connecting-to-data-sap-odata.md)
+ [连接到 SendGrid](connecting-to-data-sendgrid.md)
+ [连接到 ServiceNow](connecting-to-data-servicenow.md)
+ [在 AWS Glue Studio 中连接到 Slack](connecting-to-data-slack.md)
+ [连接到 Smartsheet](connecting-to-smartsheet.md)
+ [在 AWS Glue Studio 中连接到 Snapchat Ads](connecting-to-data-snapchat-ads.md)
+ [在 AWS Glue Studio 连接到 Snowflake](connecting-to-data-snowflake.md)
+ [在 AWS Glue Studio 中连接到 Stripe](connecting-to-data-stripe.md)
+ [在 AWS Glue Studio 中连接到 Teradata Vantage](connecting-to-data-teradata.md)
+ [连接到 Twilio](connecting-to-data-twilio.md)
+ [在 AWS Glue Studio 中连接到 Vertica](connecting-to-data-vertica.md)
+ [连接到 WooCommerce](connecting-to-data-woocommerce.md)
+ [连接到 Zendesk](connecting-to-data-zendesk.md)
+ [连接到 Zoho CRM](connecting-to-data-zoho-crm.md)
+ [连接到 Zoom Meeting](connecting-to-data-zoom-meetings.md)
+ [使用您自己的 JDBC 驱动程序添加 JDBC 连接](console-connections-jdbc-drivers.md)
# 连接到 Adobe Analytics
Adobe Analytics 是一个强大的数据分析平台，从支持客户旅程的多渠道数字体验中收集数据，并提供分析数据的工具。营销人员和业务分析师通常使用此平台进行业务分析。如果是 Adobe Analytics 用户，则可将 AWS Glue 连接到 Adobe Analytics 账户。然后，可以使用 Adobe Analytics 作为 ETL 作业中的数据来源。通过运行这些作业，可在 Adobe Analytics 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 支持 Adobe Analytics](adobe-analytics-support.md)
+ [包含创建和使用连接的 API 操作的策略](adobeanalytics-configuring-iam-permissions.md)
+ [配置 Adobe Analytics](adobeanalytics-configuring.md)
+ [配置 Adobe Analytics 连接](adobeanalytics-configuring-connections.md)
+ [从 Adobe Analytics 实体读取内容](adobeanalytics-reading-from-entities.md)
+ [Adobe Analytics 连接选项](adobeanalytics-connection-options.md)
+ [创建 Adobe Analytics 账户](adobeanalytics-create-account.md)
+ [限制](adobeanalytics-connector-limitations.md)
# AWS Glue 支持 Adobe Analytics
AWS Glue 对 Adobe Analytics 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Adobe Analytics 中的数据。
**是否支持作为目标？**
否。
**支持的 Adobe Analytics API 版本**
v2.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 控制台的用户。
# 配置 Adobe Analytics
必须满足以下要求，才能使用 AWS Glue 从 Adobe Analytics 传输数据：
## 最低要求
+ 拥有一个 Adobe Analytics 账户以及相应的电子邮件地址和密码。有关创建账户的更多信息，请参阅[创建 Adobe Analytics 账户](adobeanalytics-create-account.md)。
+ Adobe Analytics 账户已启用 API 访问权限。Select、Prime 和 Ultimate 版本都默认启用 API 访问权限。
如果满足这些要求，就可以将 AWS Glue 连接到 Adobe Analytics 账户。对于常见连接，无需在 Adobe Analytics 中执行其他操作。
# 配置 Adobe Analytics 连接
Adobe Analytics 支持 `OAuth2` 的 `AUTHORIZATION_CODE` 授权类型。
此授权类型被视为“三足型”`OAuth`，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。用户可以选择在 Adobe Analytics 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Adobe Analytics，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
有关为 AUTHORIZATION\$1CODE OAuth 流创建关联应用程序的 Adobe Analytics 公共文档，请参阅 [Adobe Analytics API](https://adobedocs.github.io/analytics-2.0-apis/)。
要配置 Adobe Analytics 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
**注意**
必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在选择**连接类型**时，请选择 Adobe Analytics。
1. 提供想要连接到的 Adobe Analytics 的 `x_api_key, 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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Adobe Analytics 实体读取内容
**先决条件**
要从中读取内容的 Adobe Analytics 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 注释 | 支持 | 是 | 是 | 是 | 否 |
| 测算指标 | 支持 | 是 | 是 | 是 | 否 |
| 测算指标函数 | 是 | 否 | 否 | 是 | 否 |
| 组件元数据共享 | 支持 | 是 | 否 | 是 | 否 |
| 日期范围 | 支持 | 是 | 否 | 是 | 否 |
| Dimensions | 是 | 否 | 否 | 是 | 否 |
| 指标 | 是 | 否 | 否 | 是 | 否 |
| Projects | 是 | 否 | 否 | 是 | 否 |
| 报告顶级项 | 支持 | 是 | 否 | 是 | 否 |
| Segments | 支持 | 是 | 是 | 是 | 否 |
| 使用日志 | 支持 | 是 | 否 | 是 | 否 |
**示例**
```
adobeAnalytics_read = glueContext.create_dynamic_frame.from_options(
connection_type="adobeanalytics",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "annotation/ex*****",
"API_VERSION": "v2.0"
})
```
**Adobe Analytics 实体和字段详细信息**
+ [Annotations](https://adobedocs.github.io/analytics-2.0-apis/#/Annotations)
+ [Calculated Metrics](https://adobedocs.github.io/analytics-2.0-apis/#/Calculated%20Metrics)
+ [Component Meta Data](https://adobedocs.github.io/analytics-2.0-apis/#/Component%20Meta%20Data)
+ [Date Ranges](https://adobedocs.github.io/analytics-2.0-apis/#/Date%20Ranges)
+ [Dimensions](https://adobedocs.github.io/analytics-2.0-apis/#/Dimensions)
+ [Metrics](https://adobedocs.github.io/analytics-2.0-apis/#/Metrics)
+ [Projects](https://adobedocs.github.io/analytics-2.0-apis/#/Projects)
+ [Reports](https://adobedocs.github.io/analytics-2.0-apis/#/Reports)
+ [Segments](https://adobedocs.github.io/analytics-2.0-apis/#/Segments)
+ [Users](https://adobedocs.github.io/analytics-2.0-apis/#/Users)
+ [Usage Logs](https://adobedocs.github.io/analytics-2.0-apis/#/Usage%20Logs)
# Adobe Analytics 连接选项
以下是 Adobe Analytics 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取/写入。Adobe Analytics 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取/写入。要使用的 Adobe Analytics Rest API 版本。例如：V2.0。
+ `X_API_KEY`（字符串）：（必填）用于读取/写入。对发出 API 请求的开发人员或应用程序进行身份验证时需要用到该项。
+ `SELECTED_FIELDS`（列表<字符串>）– 默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# 创建 Adobe Analytics 账户
1. 访问 [Adobe 合作伙伴计划](https://partners.adobe.com/exchangeprogram/creativecloud.html)，注册交换合作伙伴计划。
1. 选择**加入交换计划**。
1. 使用公司电子邮件地址注册或创建账户。
1. 在建议框中，选择订阅了 Adobe Analytics 产品的相应公司。
1. 确保该账户使用具有 Adobe Analytics 有效订阅的有效组织（从可用列表中）进行注册。
1. 获得公司管理部门批准后，点击批准电子邮件中的链接激活账户。
**验证所创建的账户是否有权访问 Adobe Analytics 服务**
1. 登录 [Adobe 管理控制台](https://adminconsole.adobe.com/)。
1. 检查页面右上角的组织名称，确保登录了正确的公司。
1. 选择**产品**，验证 Adobe Analytics 是否可用。
**注意**
如果没有可用的组织，或者 Adobe Analytics 产品显示为灰色或不可用，则表明账户可能未与组织关联且/或并无 Adobe Analytics 有效订阅。请与系统管理员联系，为账户申请该服务的访问权限。
**创建项目和 `OAuth2.0` 凭证**
1. 登录要在其中创建 [OAuth 2.0 应用程序](https://developer.adobe.com/developer-console/docs/guides/services/services-add-api-oauth/)的 Adobe Analytics 账户。
1. 选择**项目**，然后选择**创建新项目**。
1. 要添加项目，请选择**添加到项目**，然后选择**API**。
1. 选择 **Adobe Analytics API**。
1. 选择 **OAUTH** 作为用户身份验证。
1. 选择 **Web** 作为 `OAUTH`，并提供重定向 URI。
有关重定向 URI 及其模式，请参阅以下内容：
+ `OAuth 2.0` 默认重定向 URI：默认重定向 URI 是 Adobe 会在身份验证过程中访问的页面 URL。例如，`https://ap-southeast-2.console.aws.amazon.com/appflow/oauth`
+ OAuth 2.0 重定向 URI 模式：重定向 URI 模式是一个 URI 路径（或以逗号分隔的路径列表）；在登录流程完成后，Adobe 可以重定向（如果请求）到此路径。例如，`https://ap-southeast-2\\.console\\.aws\\.amazon\\.com`
1. 添加以下范围：
+ `openid`
+ `read_organizations`
+ `additional_info.projectedProductContext`
+ `additional_info.job_function`
1. 选择**保存凭证**。
1. 创建应用程序后，将 `Client ID` 和 `Client Secret` 值复制到文本文件中。
# 限制
以下是 Adobe Analytics 连接器的限制：
+ Adobe Analytics 不支持基于字段和基于记录的分区。由于无法查询分区的字段，因此不支持基于字段的分区。由于未要求为分页提供“偏移量”，因此不支持基于记录的分区。
+ 在 `Report Top Item` 实体中，`startDate` 和 `endDate` 查询参数未按预期运行。未根据这些参数对响应进行筛选，导致该实体的筛选器和增量流出现问题。
+ 对于 `Annotation`、`Calculated Metrics`、`Calculated Metrics Function`、`Date Ranges`、`Dimension`、`Metric`、`Project`、`Report Top Items` 和 `Segment` 实体，`locale` 查询参数会指定响应的本地化部分要使用哪种语言，并且不会筛选记录。例如，`locale="ja_JP"` 会以日语显示数据。
+ `Report Top Item` 实体：`dateRange` 和 `lookupNoneValues` 字段上的筛选器目前不起作用。
+ `Segment` 实体：如果筛选器值为 `includeType=“templates”`，其他字段上的筛选器不起作用。
+ `Date Range` 实体：`curatedRsid` 字段上的筛选器件不起作用。
+ `Metric entity` 实体：对具有 false 值的可分段字段进行筛选，可得出 true 和 false 值的结果。
# 连接到 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)。
# 连接到 AWS Glue Studio 中的 Amazon Redshift
**注意**
您可以使用 AWS Glue for Spark 在 AWS Glue Studio 以外读取和写入 Amazon Redshift 数据库中的表。要以编程方式为 Amazon Redshift 配置 AWS Glue 作业，请参阅 [Redshift 连接](aws-glue-programming-etl-connect-redshift-home.md)。
AWS Glue 提供对 Amazon Redshift 的内置支持。AWS Glue Studio 提供一个可视化界面，用于连接到 Amazon Redshift、创作数据集成作业并在 AWS Glue Studio 无服务器 Spark 运行时上运行这些作业。
**Topics**
+ [创建 Amazon Redshift 连接](creating-redshift-connection.md)
+ [创建 Amazon Redshift 源节点](creating-redshift-source-node.md)
+ [创建 Amazon Redshift 目标节点](creating-redshift-target-node.md)
+ [高级选项](creating-redshift-connection-advanced-options.md)
# 创建 Amazon Redshift 连接
## 所需权限
使用 Amazon Redshift 集群和 Amazon Redshift 无服务器环境需要额外的权限。有关如何为 ETL 作业添加权限的更多信息，请参阅 [Review IAM permissions needed for ETL jobs](https://docs.aws.amazon.com/glue/latest/ug/setting-up.html#getting-started-min-privs-job)。
+ redshift:DescribeClusters
+ redshift-serverless:ListWorkgroups
+ redshift-serverless:ListNamespaces
## 概述
添加 Amazon Redshift 连接时，您可以选择现有 Amazon Redshift 连接，也可以在 AWS Glue Studio 中添加**数据来源 - Redshift** 节点时创建新连接。
AWS Glue 同时支持 Amazon Redshift 集群和 Amazon Redshift 无服务器环境。创建连接时，Amazon Redshift 无服务器环境会在连接选项旁边显示**无服务器**标签。
有关如何创建 Amazon Redshift 连接的更多信息，请参阅 [Moving data to and from Amazon Redshift](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-redshift.html#aws-glue-programming-etl-redshift-using)。
# 创建 Amazon Redshift 源节点
## 所需权限
使用 Amazon Redshift 数据来源的 AWS Glue Studio 作业需要额外的权限。有关如何为 ETL 作业添加权限的更多信息，请参阅 [Review IAM permissions needed for ETL jobs](https://docs.aws.amazon.com/glue/latest/ug/setting-up.html#getting-started-min-privs-job)。
要使用 Amazon Redshift 连接，需要以下权限。
+ redshift-data:ListSchemas
+ redshift-data:ListTables
+ redshift-data:DescribeTable
+ redshift-data:ExecuteStatement
+ redshift-data:DescribeStatement
+ redshift-data:GetStatementResult
## 添加 Amazon Redshift 数据来源
**要添加**数据来源 - Amazon Redshift** 节点，请执行以下操作：**
1. 选择 Amazon Redshift 访问类型：
+ 直接数据连接（推荐）- 如果您想直接访问 Amazon Redshift 数据，请选择此选项。这是推荐的选项，也是默认选项。
+ Data Catalog tables - 如果您有要使用的 Data Catalog 表，请选择此选项。
1. 如果您选择直接数据连接，请为 Amazon Redshift 数据来源选择连接。这假设该连接已经存在，并且您可以从现有连接中进行选择。如果需要创建连接，请选择**创建 Redshift 连接**。有关更多信息，请参阅 [Overview of using connectors and connections](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#using-connectors-overview)。
选择连接后，您可以通过单击**查看属性**来查看连接属性。可以看到有关连接的信息，包括 URL、安全组、子网、可用区、描述以及创建时间（UTC）和上次更新时间（UTC）时间戳。
1. 选择 Amazon Redshift 来源选项：
+ **选择单个表** - 该表包含您要从单个 Amazon Redshift 表中访问的数据。
+ **输入自定义查询** - 允许您根据自定义查询访问多个 Amazon Redshift 表中的数据集。
1. 如果您选择了单个表，请选择 Amazon Redshift 架构。可供选择的可用架构列表由所选表决定。
或者，选择**输入自定义查询**。选择此选项可访问多个 Amazon Redshift 表中的自定义数据集。选择此选项后，输入 Amazon Redshift 查询。
连接到 Amazon Redshift 无服务器环境时，请向自定义查询添加以下权限：
```
GRANT SELECT ON ALL TABLES IN TO PUBLIC
```
您可以选择**推断架构**，根据您输入的查询来读取架构。您也可以选择**打开 Redshift 查询编辑器**来输入 Amazon Redshift 查询。有关更多信息，请参阅 [Querying a database using the query editor](https://docs.aws.amazon.com/redshift/latest/mgmt/query-editor.html)。
1. 在**性能和安全**中，选择 Amazon S3 暂存目录和 IAM 角色。
+ **Amazon S3 暂存目录** — 选择用于临时暂存数据的 Amazon S3 位置。
+ **IAM 角色** - 选择可以写入您选择的 Amazon S3 位置的 IAM 角色。
1. 在**自定义 Redshift 参数 - 可选**中，输入参数和值。
# 创建 Amazon Redshift 目标节点
## 所需权限
使用 Amazon Redshift 数据目标的 AWS Glue Studio 作业需要额外的权限。有关如何为 ETL 作业添加权限的更多信息，请参阅 [Review IAM permissions needed for ETL jobs](https://docs.aws.amazon.com/glue/latest/ug/setting-up.html#getting-started-min-privs-job)。
要使用 Amazon Redshift 连接，需要以下权限。
+ redshift-data:ListSchemas
+ redshift-data:ListTables
## 添加 Amazon Redshift 目标节点
**要创建 Amazon Redshift 目标节点，请执行以下操作：**
1. 选择现有 Amazon Redshift 表作为目标，或输入新的表名。
1. 使用**数据目标 - Redshift** 目标节点时，可以从以下选项中进行选择：
+ **附加** - 如果表已经存在，则将所有新数据作为插入内容转储到表中。如果表不存在，请创建表并插入所有新数据。
此外，如果要更新（更新插入）目标表中的现有记录，请选中该复选框。该表必须先存在，否则操作将失败。
+ **合并** - AWS Glue 将根据您指定的条件更新数据或将数据附加到目标表。
**注意**
要在 AWS Glue 中使用合并操作，必须启用 Amazon Redshift 合并功能。有关如何为您的 Amazon Redshift 实例启用合并的说明，请参阅 [MERGE (preview)](https://docs.aws.amazon.com/redshift/latest/dg/r_MERGE.html)。
选择选项：
+ **选择键和简单操作** - 选择要用作源数据和目标数据集之间匹配键的列。
匹配时指定以下选项：
+ 使用源数据更新目标数据集中的记录。
+ 删除目标数据集中的记录。
如果不匹配，请指定以下选项：
+ 将源数据作为新行插入目标数据集。
+ 不执行任何操作。
+ **输入自定义 MERGE 语句** - 然后，您可以选择**验证合并语句**来验证该语句是有效还是无效。
+ **截断** - 如果表已经存在，请先清除目标表的内容，从而截断表数据。如果截断成功，则插入所有数据。如果表不存在，请创建表并插入所有数据。如果截断不成功，操作将失败。
+ **丢弃** - 如果表已存在，则删除表的元数据和数据。如果删除成功，则插入所有数据。如果表不存在，请创建表并插入所有数据。如果丢失不成功，操作将失败。
+ **创建** - 使用默认名称创建新表。如果表名已经存在，请创建一个名称后缀为 `job_datetime` 的新表以保持唯一性。这会将所有数据插入到新表中。如果该表存在，则最终的表名将附加后缀。如果该表不存在，则将创建一个表。无论哪种情况，都将创建一个新表。
# 高级选项
请参阅 [Using the Amazon Redshift Spark connector on AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-redshift.html#aws-glue-programming-etl-redshift-using)。
# 连接到 Asana
Asana 是一款基于云的团队协作解决方案，旨在帮助团队组织、计划和完成任务及项目。如果是 Asana 用户，则账户包含有关工作空间、项目、任务、团队等的数据。可以将数据从 Asana 传输到某些 AWS 服务或其他受支持的应用程序。
**Topics**
+ [AWS Glue 支持 Asana](asana-support.md)
+ [包含创建和使用连接的 API 操作的策略](asana-configuring-iam-permissions.md)
+ [配置 Asana](asana-configuring.md)
+ [配置 Asana 连接](asana-configuring-connections.md)
+ [从 Asana 实体读取内容](asana-reading-from-entities.md)
+ [Asana 连接选项](asana-connection-options.md)
+ [创建 Asana 账户](asana-create-account.md)
+ [限制](asana-connector-limitations.md)
# AWS Glue 支持 Asana
AWS Glue 对 Asana 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Asana 中的数据。
**是否支持作为目标？**
否。
**支持的 Asana API 版本**
1.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 控制台的用户。
# 配置 Asana
必须满足以下要求，才能使用 AWS Glue 从 Asana 传输数据：
## 最低要求
+ 拥有一个包含电子邮件和密码的 Asana 账户。有关创建账户的更多信息，请参阅[创建 Asana 账户](asana-create-account.md)。
+ 必须创建一个可以访问 AWS Glue 服务的 AWS 账户。
+ 确保已在 Asana 账户中创建以下某一项资源：
+ 支持 `OAuth 2.0` 身份验证的开发人员应用程序。有关更多说明，请参阅 Asana 开发人员文档中的 [OAuth](https://developers.asana.com/docs/oauth)。或者，请参阅 [创建 Asana 账户](asana-create-account.md)。
+ 个人访问令牌。有关更多信息，请参见 Asana 开发人员文档中的个人访问令牌[https://developers.asana.com/docs/personal-access-token](https://developers.asana.com/docs/personal-access-token)。
如果满足这些要求，就可以将 AWS Glue 连接到 Adobe Analytics 账户。对于常见连接，无需在 Adobe Analytics 中执行其他操作。
# 配置 Asana 连接
Asana 支持 `OAuth2` 的 `AUTHORIZATION_CODE` 授权类型。
此授权类型被视为“三足型”`OAuth`，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。用户可以选择在 Asana 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Asana，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
有关为 `AUTHORIZATION_CODE OAuth` 流创建关联应用程序的 Asana 公共文档，请参阅 [Asana API](https://developers.asana.com/docs/oauth)。
要配置 Asana 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
+
**注意**
必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Asana。
1. 提供 Asana 环境。
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. 在 AWS Glue 中选择要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Asana 实体读取内容
**先决条件**
要从中读取内容的 Asana 对象。请参阅下面的支持的实体表，查看可用的实体。
**源支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| Workspace | 否 | 是 | 否 | 是 | 否 |
| Tag | 否 | 是 | 否 | 是 | 否 |
| 用户 | 否 | 是 | 否 | 是 | 否 |
| 项目组合 | 否 | 是 | 否 | 是 | 否 |
| Team | 否 | 是 | 否 | 是 | 否 |
| Project | 支持 | 是 | 否 | 是 | 否 |
| 板块 | 否 | 是 | 否 | 是 | 否 |
| 任务 | 是 | 否 | 否 | 是 | 是 |
| Goal | 支持 | 是 | 否 | 是 | 否 |
| AuditLogEvent | 支持 | 是 | 否 | 是 | 否 |
| 状态更新 | 支持 | 是 | 否 | 是 | 否 |
| 自定义字段 | 否 | 是 | 否 | 是 | 否 |
| 项目简介 | 是 | 否 | 否 | 是 | 是 |
**示例**
```
read_read = glueContext.create_dynamic_frame.from_options(
connection_type="Asana",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "task/workspace:xxxx",
"API_VERSION": "1.0",
"PARTITION_FIELD": "created_at",
"LOWER_BOUND": "2024-02-05T14:09:30.115Z",
"UPPER_BOUND": "2024-06-07T13:30:00.134Z",
"NUM_PARTITIONS": "3"
}
```
**Asana 实体和字段详细信息**
+ [Workspace](https://developers.asana.com/docs/workspaces)
+ [Tag](https://developers.asana.com/docs/tags)
+ [User](https://developers.asana.com/docs/users)
+ [Portfolio](https://developers.asana.com/docs/portfolios)
+ [Team](https://developers.asana.com/docs/teams)
+ [Project](https://developers.asana.com/docs/get-all-projects-in-a-workspace)
+ [Section](https://developers.asana.com/docs/get-sections-in-a-project)
+ [Task](https://developers.asana.com/docs/search-tasks-in-a-workspace)
+ [Goal](https://developers.asana.com/docs/get-goals)
+ [AuditLogEvent](https://developers.asana.com/docs/audit-log-api)
+ [Status Update](https://developers.asana.com/reference/status-updates)
+ [Custom Field](https://developers.asana.com/reference/custom-fields)
+ [Project Brief](https://developers.asana.com/reference/project-briefs)
**对查询进行分区**
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`2024-06-07T13:30:00.134Z`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
基于实体的分区字段支持详细信息如下表中所示。
| 实体名称 | 分区字段 | 数据类型 |
| --- | --- | --- |
| Task | created\$1at | 日期时间 |
| Task | modified\$1at | 日期时间 |
**示例**
```
read_read = glueContext.create_dynamic_frame.from_options(
connection_type="Asana",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "task/workspace:xxxx",
"API_VERSION": "1.0",
"PARTITION_FIELD": "created_at",
"LOWER_BOUND": "2024-02-05T14:09:30.115Z",
"UPPER_BOUND": "2024-06-07T13:30:00.134Z",
"NUM_PARTITIONS": "3"
}
```
# Asana 连接选项
以下是 Asana 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取/写入。Asana 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取/写入。要使用的 Asana Rest API 版本。例如：1.0。
+ `SELECTED_FIELDS`（列表<字符串>）– 默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# 创建 Asana 账户
1. 注册 [Asana 账户](https://asana.com/create-account)，然后选择**注册**。
1. 登录后，将重定向到[账户设置](https://app.asana.com/0/account_setup)页面。完成以下步骤：
+ 查看账户设置表。
+ 填写所有相关详细信息来创建 Asana 账户。
+ 仔细检查信息是否准确。
1. 选择**创建账户**或**提交**（确切的按钮文本可能有所不同）完成账户设置。
**在 Asana 中为 `OAuth2.0` 创建应用程序**
1. 使用 [Asana 客户凭证](https://app.asana.com/-/login)登录 Asana 账户。
1. 选择右上角的用户配置文件图标，然后从下拉菜单中选择**我的设置**。
1. 选择**应用程序**选项卡，然后选择**管理开发人员应用程序**。
1. 选择**创建新应用程序**，然后输入相关详细信息。
1. 选择**创建应用程序**。
1. 在**我的应用程序**页面上，执行以下操作：
1. 选择 **OAuth**，然后记下**应用程序凭证**部分中的客户端 ID 和客户端密钥。
1. 在**重定向 URL** 部分中，添加所需的重定向 URL。
**注意**
使用以下格式输入重定向 URI：`https://{aws-region-code}.console.aws.amazon.com/gluestudio/oauth`。例如，对于美国东部（弗吉尼亚州北部）区域，使用：`https://us-east-1.console.aws.amazon.com/gluestudio/oauth`
**在 Asana 中为 `PAT` 令牌创建应用程序**
1. 使用 [Asana 客户凭证](https://app.asana.com/-/login)登录 Asana 账户。
1. 选择右上角的用户配置文件图标，然后从下拉菜单中选择**我的配置文件设置**。
1. 选择**应用程序**选项卡，然后选择**服务账户**。
1. 选择**创建新应用程序**，然后输入相关详细信息。
1. 选择**添加服务账户**。
1. 下一页会显示令牌，请复制并安全存储令牌。
**重要**
此令牌只会显示一次。务必复制此令牌并安全存储。
# 限制
以下是 Asana 连接器的限制：
+ 企业域中的服务账户只能访问审核日志 API 端点。需要使用服务账户的个人访问令牌进行身份验证后才能访问这些端点。
+ 只有高级方案或更高方案的用户账户才能访问“目标”实体。
+ `Audit Log Event Entity`：在连接器中，`start_at` 和 `end_at` 字段合并为一个字段（即 start\$1end\$1at）来支持筛选和增量传输。
+ `Date` 字段不支持分区，尽管它支持“大于或等于”和“小于或等于”运算符。场景：创建一个作业，其中 `partitionField` 为 `due_on`（数据类型：日期）、`lowerBound` 为 `2019-09-14`、`upperBound` 为 `2019-09-16` 且 `numPartition` 为 `2`。端点 URL 的筛选条件部分按如下方式创建：
+ partition1：due\$1on.before=2019-09-14&due\$1on.after=2019-09-14
+ partition2：due\$1on.before=2019-09-15&due\$1on.after=2019-09-15 Output:
+ 在 partition1 中，得到 due\$1date 为 2019-09-14 和 2019-09-15 的数据
+ 在 partition2 中，得到与 due\$1date 为 2019-09-15（partition1 中）相同的数据以及其他数据，导致数据重复。
+ 由于 SaaS 端引发了不正确的请求错误，无法在同一字段上支持筛选和分区。
+ “任务”实体要求筛选条件中至少有 1 个字段。Asana 存在一个限制，即如果不根据基于时间的字段对记录进行排序，则无法识别分页。因此，Created\$1at 字段与分页一起用于区分下一组记录。Created\$1at 字段在筛选条件中标记为必填项，如果未提供此值，则默认值为 2000-01-01T00:00:00Z。有关分页的更多信息，请参阅 [Tasks in a workspace](https://developers.asana.com/reference/searchtasksforworkspace)。
# 在 AWS Glue Studio 中连接到 Azure Cosmos DB
AWS Glue 提供了对 Azure Cosmos DB 的内置支持。AWS Glue Studio 提供了直观的界面，以用于连接到 Azure Cosmos DB for NoSQL、编写数据集成作业以及在 AWS Glue Studio 无服务器 Spark 运行时系统上运行这些作业。
**Topics**
+ [创建 Azure Cosmos DB 连接](creating-azurecosmos-connection.md)
+ [创建 Azure Cosmos DB 源节点](creating-azurecosmos-source-node.md)
+ [创建 Azure Cosmos DB 目标节点](creating-azurecosmos-target-node.md)
+ [高级选项](#creating-azurecosmos-connection-advanced-options)
# 创建 Azure Cosmos DB 连接
**先决条件**
+ 在 Azure 中，您需要确定或生成一个 Azure Cosmos DB 密钥 `cosmosKey`，以供 AWS Glue 使用。有关更多信息，请参阅 Azure 文档中的 [保护对 Azure Cosmos DB 中数据的访问](https://learn.microsoft.com/en-us/azure/cosmos-db/secure-access-to-data?tabs=using-primary-key)。
**配置 Azure Cosmos DB 连接：**
1. 在 AWS Secrets Manager 中，使用您的 Azure Cosmos DB 密钥创建一个密钥。要在 Secrets Manager 中创建密钥，请按照 AWS Secrets Manager 文档中[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中的教程进行操作。创建密钥后，保留密钥名称 *secretName*，以供下一步使用。
+ 在选择**键/值对**时，请使用键 `spark.cosmos.accountKey` 和值 *cosmosKey* 创建一个键值对。
1. 在 AWS Glue 控制台中，按照 [添加 AWS Glue 连接](console-connections.md) 中的步骤创建一个连接。创建连接后，保留连接名为 *connectionName*，以供未来在 AWS Glue 中使用。
+ 选择**连接类型**时，请选择 Azure Cosmos DB。
+ 选择 **AWS 密钥**时，请提供 *secretName*。
# 创建 Azure Cosmos DB 源节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue Azure Cosmos DB 连接，如上一节“[创建 Azure Cosmos DB 连接](creating-azurecosmos-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要读取的 Azure Cosmos DB for NoSQL 容器。您将需要该容器的标识信息。
Azure Cosmos DB for NoSQL 容器由其数据库和容器来标识。在连接到 Azure Cosmos for NoSQL API 时，您必须提供数据库 *cosmosDBName* 和容器 *cosmosContainerName* 的名称。
## 添加 Azure Cosmos DB 数据来源
**添加**数据来源 – Azure Cosmos DB** 节点：**
1. 选择 Azure Cosmos DB 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 Azure Cosmos DB 连接**。有关更多信息，请参阅之前的 [创建 Azure Cosmos DB 连接](creating-azurecosmos-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 选择 **Cosmos DB 数据库名称** – 提供您要读取的数据库的名称 *cosmosDBName*。
1. 选择 **Azure Cosmos DB 容器** – 提供您要读取的容器的名称 *cosmosContainerName*。
1. 或者，选择 **Azure Cosmos DB 自定义查询** – 提供 SQL SELECT 查询以检索 Azure Cosmos 数据库中的特定信息。
1. 在**自定义 Azure Cosmos 属性**中，根据需要输入相关参数和值。
# 创建 Azure Cosmos DB 目标节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue Azure Cosmos DB 连接，如上一节“[创建 Azure Cosmos DB 连接](creating-azurecosmos-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要写入的 Azure Cosmos DB 表。您将需要该容器的标识信息。**必须首先创建容器，然后才能调用连接方法。**
Azure Cosmos DB for NoSQL 容器由其数据库和容器来标识。在连接到 Azure Cosmos for NoSQL API 时，您必须提供数据库 *cosmosDBName* 和容器 *cosmosContainerName* 的名称。
## 添加 Azure Cosmos DB 数据目标
**添加**数据目标 – Azure Cosmos DB** 节点：**
1. 选择 Azure Cosmos DB 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 Azure Cosmos DB 连接**。有关更多信息，请参阅之前的 [创建 Azure Cosmos DB 连接](creating-azurecosmos-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 选择 **Cosmos DB 数据库名称** – 提供您要读取的数据库的名称 *cosmosDBName*。
1. 选择 **Azure Cosmos DB 容器** – 提供您要读取的容器的名称 *cosmosContainerName*。
1. 在**自定义 Azure Cosmos 属性**中，根据需要输入相关参数和值。
## 高级选项
您可以在创建 Azure Cosmos DB 节点时提供高级选项。这些选项与编程 Spark 脚本的 AWS Glue 时可用的选项相同。
请参阅[Azure Cosmos DB 连接](aws-glue-programming-etl-connect-azurecosmos-home.md)。
# 在 AWS Glue Studio 中连接到 Azure SQL
AWS Glue 提供了对 Azure SQL 的内置支持。AWS Glue Studio 提供了直观的界面，以用于连接到 Azure SQL、编写数据集成作业以及在 AWS Glue Studio 无服务器 Spark 运行时系统上运行这些作业。
**Topics**
+ [创建 Azure SQL 连接](creating-azuresql-connection.md)
+ [创建 Azure SQL 源节点](creating-azuresql-source-node.md)
+ [创建 Azure SQL 目标节点](creating-azuresql-target-node.md)
+ [高级选项](#creating-azuresql-connection-advanced-options)
# 创建 Azure SQL 连接
要从 AWS Glue 连接到 Azure SQL，您需要创建 Azure SQL 凭证并将其存储在一个 AWS Secrets Manager 密钥中，然后将该密钥关联到某个 Azure SQL AWS Glue 连接。
**配置 Azure SQL 连接：**
1. 在 AWS Secrets Manager 中，使用您的 Azure SQL 凭证创建密钥。要在 Secrets Manager 中创建密钥，请按照 AWS Secrets Manager 文档中[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中的教程进行操作。创建密钥后，保留密钥名称 *secretName*，以供下一步使用。
+ 在选择**键/值对**时，请使用键 `user` 和值 *azuresqlUsername* 创建一个键值对。
+ 在选择**键/值对**时，请使用键 `password` 和值 *azuresqlPassword* 创建一个键值对。
1. 在 AWS Glue 控制台中，按照 [添加 AWS Glue 连接](console-connections.md) 中的步骤创建一个连接。创建连接后，保留连接名为 *connectionName*，以供未来在 AWS Glue 中使用。
+ 选择**连接类型**时，请选择 Azure SQL。
+ 在提供 **Azure SQL URL** 时，请提供 JDBC 端点的 URL。
该 URL 必须为以下格式：`jdbc:sqlserver://databaseServerName:databasePort;databaseName=azuresqlDBname;`。
AWS Glue 需要以下 URL 属性：
+ `databaseName` – Azure SQL 中要连接的默认数据库。
有关 Azure SQL 托管实例的 JDBC URL 的更多信息，请参阅 [Microsoft 文档](https://learn.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=azuresqldb-mi-current)。
+ 选择 **AWS 密钥**时，请提供 *secretName*。
# 创建 Azure SQL 源节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue Azure SQL 连接，如上一节“[创建 Azure SQL 连接](creating-azuresql-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要读取的 Azure SQL 表 *tableName*。
Azure SQL 表由其数据库、Schema 和表名来标识。连接到 Azure SQL 时，必须提供数据库名和表名。如果 Schema 不是默认值“public”，则还必须提供 Schema。数据库通过 *connectionName* 中的 URL 属性来提供，Schema 和表名通过 `dbtable` 来提供。
## 添加 Azure SQL 数据来源
**添加**数据来源 – Azure SQL** 节点：**
1. 选择 Azure SQL 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 Azure SQL 连接**。有关更多信息，请参阅之前的 [创建 Azure SQL 连接](creating-azuresql-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 选择 **Azure SQL 源**选项：
+ **选择单个表** – 访问单个表中的所有数据。
+ **输入自定义查询** - 允许您根据自定义查询访问多个表中的数据集。
1. 如果您选择单个表，请输入 *tableName*。
如果选择**输入自定义查询**，请输入一个 TransactSQL SELECT 查询。
1. 在**自定义 Azure SQL 属性**中，根据需要输入相关参数和值。
# 创建 Azure SQL 目标节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue Azure SQL 连接，如上一节“[创建 Azure SQL 连接](creating-azuresql-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要写入的 Azure SQL 表 *tableName*。
Azure SQL 表由其数据库、Schema 和表名来标识。连接到 Azure SQL 时，必须提供数据库名和表名。如果 Schema 不是默认值“public”，则还必须提供 Schema。数据库通过 *connectionName* 中的 URL 属性来提供，Schema 和表名通过 `dbtable` 来提供。
## 添加 Azure SQL 数据目标
**添加**数据目标 – Azure SQL** 节点：**
1. 选择 Azure SQL 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 Azure SQL 连接**。有关更多信息，请参阅之前的 [创建 Azure SQL 连接](creating-azuresql-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 要配置**表名**，请提供 *tableName*。
1. 在**自定义 Azure SQL 属性**中，根据需要输入相关参数和值。
## 高级选项
您可以在创建 Azure SQL 节点时提供高级选项。这些选项与编程 Spark 脚本的 AWS Glue 时可用的选项相同。
请参阅[Azure SQL 连接](aws-glue-programming-etl-connect-azuresql-home.md)。
# 连接到 Blackbaud Raiser Edge NXT
Blackbaud Raiser Edge NXT 是一款全面的基于云的筹款和捐赠者管理软件解决方案，专为非营利组织和整个社会公益社区打造。该连接器依托 Blackbaud Raiser Edge NXT 的 SKY API 建立，提供操作来帮助管理 Raisers Edge NXT 中的实体。
**Topics**
+ [AWS Glue 对 Blackbaud Raiser Edge NXT 的支持](blackbaud-support.md)
+ [包含创建和使用连接的 API 操作的策略](blackbaud-configuring-iam-permissions.md)
+ [配置 Blackbaud Raiser Edge NXT](blackbaud-configuring.md)
+ [配置 Blackbaud Raiser Edge NXT 连接](blackbaud-configuring-connections.md)
+ [从 Blackbaud Raiser Edge NXT 实体中读取内容](blackbaud-reading-from-entities.md)
+ [Blackbaud Raiser Edge NXT 连接选项](blackbaud-connection-options.md)
+ [Blackbaud Raiser Edge NXT 限制](blackbaud-connection-limitations.md)
# AWS Glue 对 Blackbaud Raiser Edge NXT 的支持
AWS Glue 对 Blackbaud Raiser Edge NXT 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Blackbaud Raiser Edge NXT 中的数据。
**是否支持作为目标？**
否。
**支持的 Blackbaud Raiser Edge NXT API 版本**
支持以下 Blackbaud Raiser Edge NXT 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 控制台的用户。
# 配置 Blackbaud Raiser Edge NXT
必须满足以下要求，才能使用 AWS Glue 从 Blackbaud Raiser Edge NXT 传输数据：
## 最低要求
以下是最低要求：
+ 拥有 Blackbaud Raiser Edge NXT 账户。
+ 已在 Blackbaud Raiser Edge NXT 账户中生成访问令牌，且分配了可访问 API 的相应读/写范围。有关更多信息，请参阅 [Authorization](https://developer.blackbaud.com/skyapi/docs/authorization)。
如果满足这些要求，就可以将 AWS Glue 连接到您的 Blackbaud Raiser Edge NXT 账户。
# 配置 Blackbaud Raiser Edge NXT 连接
Blackbaud Raiser Edge NXT 支持 OAuth2 的 AUTHORIZATION\$1CODE 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Blackbaud Raiser Edge NXT，用户必须登录并向 AWS Glue 授予所请求的权限，以便其访问自己的 Blackbaud Raiser Edge NXT 实例。
+ 用户可以选择在 Blackbaud Raiser Edge NXT 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID、订阅密钥和实例 URL。在这种情况下，用户仍会被重定向到 Blackbaud Raiser Edge NXT，以便登录并授权 AWS Glue 访问自己的资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 Blackbaud Raiser Edge NXT 公共文档，请参阅 [Authorization](https://developer.blackbaud.com/skyapi/docs/authorization)。
要配置 Blackbaud Raiser Edge NXT 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的 API 密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**数据来源**时，选择 Blackbaud Raiser Edge NXT。
1. 提供要连接的 Blackbaud Raiser Edge NXT 账户的 `INSTANCE_URL`。
1. 提供用户托管客户端应用程序 `clientId`。
1. 提供与账户关联的订阅密钥。
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` 的权限。
# 从 Blackbaud Raiser Edge NXT 实体中读取内容
**先决条件**
要从中读取内容的 Blackbaud Raiser Edge NXT 对象。您将需要对象名称。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| Constituent Address | 支持 | 是 | 否 | 是 | 是 |
| Constituent Education | 支持 | 是 | 否 | 是 | 是 |
| Constituent Email address | 支持 | 是 | 否 | 是 | 是 |
| Constituent Phone | 支持 | 是 | 否 | 是 | 是 |
| Constituent Note | 支持 | 是 | 否 | 是 | 是 |
| Constituent Relationship | 支持 | 是 | 否 | 是 | 是 |
| Constituent Online presence | 支持 | 是 | 否 | 是 | 是 |
| Opportunity | 支持 | 是 | 否 | 是 | 是 |
| Appeal | 支持 | 是 | 否 | 是 | 是 |
| 活动 | 支持 | 是 | 否 | 是 | 是 |
| Fund | 支持 | 是 | 否 | 是 | 是 |
| 软件包 | 支持 | 是 | 否 | 是 | 是 |
| Gift Batch | 支持 | 是 | 否 | 是 | 否 |
| Event Participant | 支持 | 是 | 是 | 是 | 是 |
| Constituent Fundraiser Assignment | 否 | 否 | 否 | 是 | 否 |
| Gift | 支持 | 是 | 是 | 是 | 是 |
| 成员身份 | 支持 | 是 | 否 | 是 | 是 |
| 操作 | 支持 | 是 | 否 | 是 | 否 |
| Constituent | 支持 | 是 | 是 | 是 | 是 |
| Constituent Goods | 支持 | 是 | 否 | 是 | 是 |
| 事件 | 支持 | 是 | 是 | 是 | 是 |
| Gift custom field | 支持 | 是 | 否 | 是 | 是 |
**示例：**
```
blackbaud_read = glueContext.create_dynamic_frame.from_options(
connection_type="BLACKBAUD",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v1",
"SUBSCRIPTION_KEY":
}
```
## Blackbaud Raiser Edge NXT 实体和字段详细信息
有关实体和字段详细信息的更多信息，请参阅：
+ [操作](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Action)
+ [Constituent](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Constituent)
+ [Constituent Address](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Address)
+ [Constituent Membership](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Membership)
+ [Constituent Fundraiser Assignment](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#FundraiserAssignment)
+ [Constituent Education](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Education)
+ [Constituent Email Address](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#EmailAddress)
+ [Constituent Phone](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Phone)
+ [Constituent Note](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Note)
+ [Constituent Online Presence](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#OnlinePresence)
+ [Constituent Relationship](https://developer.blackbaud.com/skyapi/renxt/constituent/entities#Relationship)
+ [Event (事件)](https://developer.blackbaud.com/skyapi/renxt/event/entities#Event)
+ [Event Participant](https://developer.blackbaud.com/skyapi/renxt/event/entities#Participant)
+ [Appeal](https://developer.blackbaud.com/skyapi/renxt/fundraising/entities#Appeal)
+ [活动](https://developer.blackbaud.com/skyapi/renxt/fundraising/entities#Campaign)
+ [Fund](https://developer.blackbaud.com/skyapi/renxt/fundraising/entities#Fund)
+ [包](https://developer.blackbaud.com/skyapi/renxt/fundraising/entities#Package)
+ [Gift](https://developer.blackbaud.com/skyapi/renxt/gift/entities#Gift)
+ [Gift Custom Field](https://developer.blackbaud.com/skyapi/renxt/gift/entities#CustomField)
+ [Gift Batch](https://developer.blackbaud.com/skyapi/renxt/gift-batch/entities#GiftBatch)
+ [Opportunity](https://developer.blackbaud.com/skyapi/renxt/opportunity/entities#Opportunity)
+ [Constituent Codes](https://developer.sky.blackbaud.com/api#api=56b76470069a0509c8f1c5b3)
**注意**
在连接器的响应中，“结构体”和“列表”数据类型将转换为“字符串”数据类型，“日期时间”数据类型将转换为“时间戳”数据类型。
## 对查询进行分区
**基于字段的分区**：
Blackbaud Raiser Edge NXT 不支持基于字段的分区或基于记录的分区。
**基于记录的分区**：
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `NUM_PARTITIONS`。使用此参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
在基于记录的分区中，从 Blackbaud Raiser Edge NXT API 查询存在的记录总数，然后将其除以提供的 `NUM_PARTITIONS` 数字。然后，每个子查询会同时获取生成的记录数。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
blackbaud_read = glueContext.create_dynamic_frame.from_options(
connection_type="BLACKBAUD",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v1",
"NUM_PARTITIONS": "2",
"SUBSCRIPTION_KEY":
}
```
# Blackbaud Raiser Edge NXT 连接选项
以下是 Blackbaud Raiser Edge NXT 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Blackbaud Raiser Edge NXT 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Blackbaud Raiser Edge NXT Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。示例值：10。
+ `SUBSCRIPTION_KEY`（字符串）：（必填）默认：空。用于读取。与开发者账户关联的订阅密钥。
# Blackbaud Raiser Edge NXT 限制
以下是 Blackbaud Raiser Edge NXT 的限制或注意事项：
+ SaaS 仅支持 `EQUAL_TO` 运算符，该运算符返回在指定日期当天或之后创建或修改的结果。此外，“id”字段是字符串数据类型字段。也没有对非空字段的标识。因此，不支持基于字段的分区。
+ 只有具有每日、每月和每周频率的 `Event` 实体才支持增量拉取。
+ Constituent Fundraiser Assignment 实体最多返回 20 条记录。
+ 基于记录的分区：
+ `Action`、`Constituent Fundraiser Assignment` 或 `Gift Batch` 实体都不支持。
+ 只有 `Event` 和 `Event Participant` 实体支持使用筛选谓词的基于记录的分区。如果筛选谓词与任何其他基于记录的支持实体一起使用，则会引发异常。
+ 在 `Gift Custom Field` 实体中，“值”字段必须与“类别”字段结合使用，否则会产生未经筛选的响应。因此，为了强制用户在使用“值”字段进行筛选时插入“类别”字段，如果未满足上述要求，则会引发异常。
+ 所有适用实体的 `date_added` 和 `last_modified` 字段不支持任何比较运算符。这些字段仅支持 equal to 运算符。此外，没有可与上述字段配对来提供众多记录的字段。因此，这些字段仅可查询，不能支持增量传输。
+ `Gift Batch` 实体中的 `added_by` 字段不会被视为可筛选字段，因为该字段可能不会发出正确的结果。
+ 在 `Gift` 实体中插入数据后，通过 `/GET Gift List` 端点检索记录的延迟约为 30 分钟。
+ 由于数据来源端的限制，Gift 实体已放弃对增量传输的支持。
+ Opportunity 实体中的状态字段有 10 分钟的延迟。
+ `Fundraiser Assignment` 实体以 `Constituent` 作为依赖实体。连接器最多可加载 5000 个 ID 供选择，避免响应大小超过允许的最大有效载荷大小。
# 连接到 CircleCI
CircleCI 是一个持续集成和持续交付平台。CircleCI 账户包含有关您项目、管线、工作流等的数据。如果您是 CircleCI 用户，则可以将 AWS Glue 连接到自己的 CircleCI 账户。然后，可以使用 CircleCI 作为 ETL 作业中的数据来源。通过运行这些作业，可在 CircleCI 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 对 CircleCI 的支持](circleci-support.md)
+ [包含创建和使用连接的 API 操作的策略](circleci-configuring-iam-permissions.md)
+ [配置 CircleCI](circleci-configuring.md)
+ [配置 CircleCI 连接](circleci-configuring-connections.md)
+ [从 CircleCI 实体中读取内容](circleci-reading-from-entities.md)
+ [CircleCI 连接选项](circleci-connection-options.md)
+ [CircleCI 限制](circleci-connection-limitations.md)
# AWS Glue 对 CircleCI 的支持
AWS Glue 对 CircleCI 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 CircleCI 中的数据。
**是否支持作为目标？**
否。
**支持的 CircleCI API 版本**
支持以下 CircleCI API 版本：
+ v2
# 包含创建和使用连接的 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 控制台的用户。
# 配置 CircleCI
必须满足以下要求，才能使用 AWS Glue 从 CircleCI 传输数据：
## 最低要求
以下是最低要求：
+ 拥有 CircleCI 账户，且其中包含要传输的数据。
+ 在账户的用户设置中创建了个人 API 令牌。有关更多信息，请参阅 [Creating a personal API token](https://circleci.com/docs/managing-api-tokens/#creating-a-personal-api-token)。
+ 在创建连接时向 AWS Glue 提供个人 API 密钥。
如果满足这些要求，就可以将 AWS Glue 连接到 CircleCI 账户。
# 配置 CircleCI 连接
CircleCI 支持自定义身份验证。
要配置 CircleCI 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的 API 密钥，且以 `Circle-Token` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**数据来源**时，请选择 CircleCI。
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` 的权限。
# 从 CircleCI 实体中读取内容
**先决条件**
要从中读取内容的 CircleCI 对象。您将需要对象名称。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 上下文 | 是 | 否 | 否 | 是 | 否 |
| Organization Summary Metric | 是 | 否 | 否 | 是 | 否 |
| 管道 | 否 | 否 | 否 | 是 | 否 |
| 管道工作流 | 是 | 否 | 否 | 是 | 否 |
| Project Branch | 是 | 否 | 否 | 是 | 否 |
| Project Flaky Test | 否 | 否 | 否 | 是 | 否 |
| Project Summary Metric | 是 | 否 | 否 | 是 | 否 |
| 计划 | 否 | 否 | 否 | 是 | 否 |
| Workflow Job Timeseries | 是 | 否 | 否 | 是 | 否 |
| Workflow Metric And Trend | 是 | 否 | 否 | 是 | 否 |
| Workflow Recent Run | 是 | 否 | 否 | 是 | 否 |
| Workflow Summary Metric | 是 | 否 | 否 | 是 | 否 |
| Workflow Test Metric | 是 | 否 | 否 | 是 | 否 |
**示例：**
```
circleci_read = glueContext.create_dynamic_frame.from_options(
connection_type="circleci",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "context/e7ea2945-dccb-4205-b673-8391fe1b3a4c",
"API_VERSION": "v2"
}
```
## CircleCI 实体和字段详细信息
有关实体和字段详细信息的更多信息，请参阅：
+ [Contexts](https://circleci.com/docs/api/v2/#operation/listContexts)
+ [Project Summary Metrics](https://circleci.com/docs/api/v2/#operation/getProjectWorkflowsPageData)
+ [Workflow Job Timeseries](https://circleci.com/docs/api/v2/#operation/getJobTimeseries)
+ [Organization Summary Metrics](https://circleci.com/docs/api/v2/#operation/getOrgSummaryData)
+ [Project Branches](https://circleci.com/docs/api/v2/#operation/getAllInsightsBranches)
+ [Project Flaky Tests](https://circleci.com/docs/api/v2/#operation/getFlakyTests)
+ [Workflow Recent Runs](https://circleci.com/docs/api/v2/#operation/getProjectWorkflowRuns)
+ [Workflow Summary Metrics](https://circleci.com/docs/api/v2/#operation/getProjectWorkflowMetrics)
+ [Workflow Metrics and Trends](https://circleci.com/docs/api/v2/#operation/getWorkflowSummary)
+ [Workflow Test Metrics](https://circleci.com/docs/api/v2/#operation/getProjectWorkflowTestMetrics)
+ [Pipelines](https://circleci.com/docs/api/v2/#operation/listPipelinesForProject)
+ [Pipeline Workflows](https://circleci.com/docs/api/v2/#operation/listWorkflowsByPipelineId)
+ [Schedules](https://circleci.com/docs/api/v2/#operation/listSchedulesForProject)
具有静态元数据的实体：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/circleci-reading-from-entities.html)
**注意**
在连接器的响应中，结构和列表数据类型将转换为字符串数据类型。
**对查询进行分区**
CircleCI 不支持基于字段的分区或基于记录的分区。
# CircleCI 连接选项
以下是 CircleCI 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。CircleCI 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 CircleCI Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# CircleCI 限制
以下是 CircleCI 的限制或注意事项：
+ CircleCI 不支持基于字段的分区或基于记录的分区。
+ 包含“-”（连字符）的筛选字段只有在用反引号括起来时才有效。例如：`workflow-name` = "abc"
+ 不支持 GitLab VCS 类型，因为没有编程方法可以检索 GitLab VCS 实体路径所需的“项目 ID”。
# 连接到 Datadog
Datadog 是一种适用于云规模应用程序的监控和分析平台，包括基础架构、应用程序、服务和工具。
**Topics**
+ [AWS Glue 支持 Datadog](datadog-support.md)
+ [包含创建和使用连接的 API 操作的策略](datadog-configuring-iam-permissions.md)
+ [配置 Datadog](datadog-configuring.md)
+ [配置 Datadog 连接](datadog-configuring-connections.md)
+ [从 Datadog 实体读取内容](datadog-reading-from-entities.md)
+ [Datadog 连接选项](datadog-connection-options.md)
+ [创建 Datadog 账户](datadog-create-account.md)
+ [限制](datadog-connector-limitations.md)
# AWS Glue 支持 Datadog
AWS Glue 对 Datadog 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Datadog 中的数据。
**是否支持作为目标？**
否。
**支持的 Datadog API 版本**
+ v1
+ v2
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Datadog
必须满足以下要求，才能使用 AWS Glue 从 Datadog 传输数据：
## 最低要求
+ 拥有 Datadog 账户以及 DD-API-KEY 和 DD-APPLICATION-KEY。有关创建账户的更多信息，请参阅[创建 Datadog 账户](datadog-create-account.md)。
+ Datadog 账户拥有 API 访问权限和有效许可证。
Datadog 支持以下六个 URL。默认情况下，所有 Datadog API 客户端都配置为使用 Datadog US1 网站 API。如果位于 Datadog EU 网站上，则必须选择带有 Datadog EU 网站 `DD-API-KEY` 和 `DD-APPLICATION-KEY` 的 https://api.datadoghq.eu URL 来访问 API。同理，若位于其他网站上，则应选择带有相应网站 `DD-API-KEY and DD-APPLICATION-KEY` 的相应 URL。
+ US1 API URL：[https://api.datadoghq.com](https://api.datadoghq.com)https://api.datadoghq.com
+ EU API URL：[https://api.datadoghq.eu](https://api.datadoghq.eu)
+ US3 API URL：[https://api.us3.datadoghq.com](https://api.us3.datadoghq.com)
+ US5 API URL：[https://api.us5.datadoghq.com](https://api.us5.datadoghq.com)
+ S1-FED API URL：[https://api.ddog-gov.com](https://api.ddog-gov.com)
+ Japan API UR：[https://api.ap1.datadoghq.com](https://api.ap1.datadoghq.com)
如果满足这些要求，就可以将 AWS Glue 连接到 Datadog 账户。
# 配置 Datadog 连接
Datadog 支持自定义身份验证。以下是配置 Datadog 连接的步骤：
要配置 Datadog 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
对于客户管理型关联应用程序：密钥应包含关联应用程序的消费者密钥，且以 `API_KEY` 和 `APPLICATION_KEY` 为键。
**注意**
必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Datadog。
1. 提供想要连接到的 Datadog 的 `Instance_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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Datadog 实体读取内容
**先决条件**
要从中读取内容的 Datadog 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 指标时间序列 | 是 | 否 | 否 | 是 | 否 |
| 日志查询 | 支持 | 是 | 是 | 是 | 否 |
**示例**
```
Datadog_read = glueContext.create_dynamic_frame.from_options(
connection_type="datadog",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "log-queries",
"API_VERSION": "v2",
"INSTANCE_URL": "https://api.datadoghq.com",
"FILTER_PREDICATE": "from = `2023-10-03T09:00:26Z`"
}
```
**Datadog 实体和字段详细信息**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/datadog-reading-from-entities.html)
# Datadog 连接选项
以下是 Datadog 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取/写入。Datadog 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取/写入。要使用的 Datadog Rest API 版本。`v1` 版本支持 `metrics-timeseries` 实体，而 `v2` 版本支持 `log-queries` 实体。
+ `INSTANCE_URL`（字符串）：（必填）用于读取。Datadog 实例 URL。Datadog 实例 URL 因地区而异。
+ `SELECTED_FIELDS`（列表<字符串>）– 默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# 创建 Datadog 账户
1. 前往 [https://www.datadoghq.com/](https://api.datadoghq.com)。
1. 选择**开始免费使用**。
1. 输入所需信息，然后注册。
1. 按照建议安装 **Datadog Agent 安装程序**。
1. 确保该账户使用具有 Datadog 有效订阅的有效组织（从可用列表中）进行注册。
1. 登录 Datadog 账户后，将鼠标悬停在右上角的用户名上方，查看**密钥**详细信息：
1. 要获取 API 密钥，请选择 **API 密钥**。
1. 要获取应用程序密钥，请选择**应用程序密钥**。
# 限制
以下是 Datadog 连接器的限制：
+ Datadog 不支持基于字段的分区或基于记录的分区。
+ `from` 是 `Log Queries` 实体的必要筛选条件参数。
+ `from_to_date` 和 `query` 是 `Metrics Timeseries` 实体的必要筛选条件参数。
# 连接到 Docusign Monitor
Docusign Monitor 借助全天候的活动跟踪功能帮助组织保护自己的协议。Monitor API 将此活动跟踪信息直接提供给现有的安全堆栈或数据可视化工具，让团队能够检测未经授权的活动、调查事件以及快速响应经过验证的威胁。该 API 还提供了安全团队自定义控制面板和警报的所需的灵活性，以满足特定业务需求。
**Topics**
+ [AWS Glue 对 Docusign Monitor 的支持](docusign-monitor-support.md)
+ [包含创建和使用连接的 API 操作的策略](docusign-monitor-configuring-iam-permissions.md)
+ [配置 Docusign Monitor](docusign-monitor-configuring.md)
+ [配置 Docusign Monitor 连接](docusign-monitor-configuring-connections.md)
+ [从 Docusign Monitor 中实体读取](docusign-monitor-reading-from-entities.md)
+ [Docusign Monitor 连接选项](docusign-monitor-connection-options.md)
+ [Docusign Monitor 限制](docusign-monitor-connection-limitations.md)
# AWS Glue 对 Docusign Monitor 的支持
AWS Glue 对 Docusign Monitor 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Docusign Monitor 中的数据。
**是否支持作为目标？**
否。
**支持的 Docusign Monitor API 版本**
支持以下 Docusign Monitor API 版本：
+ v2.0
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Docusign Monitor
必须满足以下要求，才能使用 AWS Glue 将数据从 Docusign Monitor 传输到支持的目标：
## 最低要求
以下是最低要求：
+ 拥有 Docusign 账户，以便在 Docusign Monitor 中使用 Docusign 软件产品。
+ 在 Docusign 账户的开发者控制台中，已经为 AWS Glue 创建了一个 OAuth 2.0 集成应用程序。
此应用程序提供 AWS Glue 在对账户进行身份验证调用时，用于安全访问数据的客户端凭证。有关更多信息，请参阅 Docusign Monitor 文档中的 [OAuth 2.0](https://developers.docusign.com/platform/webhooks/connect/validation-and-security/oauth-connect/)。
如果满足这些要求，就可以将 AWS Glue 连接到 Docusign Monitory 账户。
# 配置 Docusign Monitor 连接
Docusign Monitor 支持 AUTHORIZATION\$1CODE 授权类型。
+ 此授权类型被视为三足型 OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。
+ 用户可以选择在 Docusign Monitor 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，用户仍会被重定向到 Docusign Monitor，以便登录并授权 AWS Glue 访问自己的资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 Docusign Monitor 公共文档，请参阅 [OAuth for Docusign Connect](https://developers.docusign.com/platform/webhooks/connect/validation-and-security/oauth-connect/)。
要配置 Docusign Monitor 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的 API 密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在**连接**下，选择**创建连接**。
1. 选择**数据来源**时，请选择 Docusign Monitor。
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. 提供 Docusign Monitor 应用程序的**用户托管客户端应用程序 ClientId**。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Docusign Monitor 中实体读取
**先决条件**
要从中读取内容的 Docusign Monitor 对象。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 监控数据 | 支持 | 是 | 否 | 是 | 否 |
**示例：**
```
docusignmonitor_read = glueContext.create_dynamic_frame.from_options(
connection_type="docusign_monitor",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "monitoring-data",
"API_VERSION": "v2.0"
}
```
## Docusign Monitor 实体和字段详细信息
具有静态元数据的实体：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/docusign-monitor-reading-from-entities.html)
**对查询进行分区**
Docusign Monitor 不支持基于字段的分区或基于记录的分区。
# Docusign Monitor 连接选项
以下是 Docusign Monitor 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Docusign Monitor 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Docusign Monitor Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
# Docusign Monitor 限制
以下是 Docusign Monitor 的限制或注意事项：
+ 使用 `cursor` 字段应用筛选条件时，API 会检索从指定日期开始的接下来七天的记录。
+ 若未提供筛选条件，则 API 会检索自 API 请求的当前日期起过去七天的记录。
+ Docusign Monitor 不支持基于字段的分区或基于记录的分区。
+ Docusign Monitor 不支持“排序依据”功能。
# 连接到 Domo
Domo 是一款基于云的控制面板制作工具。借助 Domo 的企业应用程序平台，扩展 Domo 所需的基础已经到位，可以更快地构建自定义解决方案。
**Topics**
+ [AWS Glue 对 Domo 的支持](domo-support.md)
+ [包含创建和使用连接的 API 操作的策略](domo-configuring-iam-permissions.md)
+ [配置 Domo](domo-configuring.md)
+ [配置 Domo 连接](domo-configuring-connections.md)
+ [从 Domo 实体中读取内容](domo-reading-from-entities.md)
+ [Domo 连接选项](domo-connection-options.md)
+ [Domo 限制](domo-connection-limitations.md)
# AWS Glue 对 Domo 的支持
AWS Glue 对 Domo 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Domo 中的数据。
**是否支持作为目标？**
否。
**支持的 Domo API 版本**
支持以下 Domo 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 控制台的用户。
# 配置 Domo
必须满足以下要求，才能使用 AWS Glue 将数据从 Domo 传输到支持的目标：
## 最低要求
以下是最低要求：
+ 拥有已启用 API 访问权限的 Domo 账户。
+ 在 Domo 开发者账户下创建应用程序，提供 AWS Glue 在对账户进行身份验证调用时用于安全访问数据的客户端凭证。有关更多信息，请参阅 [创建 Domo 开发者应用程序](#domo-configuring-creating-developer-app)。
如果满足这些要求，就可以将 AWS Glue 连接到 Domo 账户。
## 创建 Domo 开发者应用程序
要获取客户端 ID 和客户端密钥，必须创建一个开发者账户。
1. 前往 [Domo 开发者登录页面](https://developer.domo.com/manage-clients)。
1. 选择**登录**。
1. 提供域名并点击**继续**。
1. 将鼠标悬停在**我的账户**上，然后选择**新客户端**。
1. 提供名称和描述并选择范围（数据），然后选择**创建**。
1. 从创建的新客户端中检索生成的**客户端 ID** 和**客户端密钥**。
# 配置 Domo 连接
Domo 支持 OAuth2 的 CLIENT\$1CREDENTIALS 授权类型。
+ 这种授权类型被认为是双足型 OAuth，因为只有客户端应用程序向服务器进行身份验证，无需用户参与。
+ 用户可以选择在 Domo 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。
+ 有关为授权码 OAuth 流创建关联应用程序的 Domo 公共文档，请参阅 [OAuth Authentication](https://developer.domo.com/portal/1845fc11bbe5d-api-authentication)。
要配置 Domo 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的访问令牌，且以 `client_id` 和 `client_secret` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在**连接**下，选择**创建连接**。
1. 选择**数据来源**时，请选择 Domo。
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` 的权限。
# 从 Domo 实体中读取内容
**先决条件**
要从中读取内容的 Domo 对象。您会用到“数据集”或“数据权限策略”等对象名称。下表显示支持的实体。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 数据集 | 支持 | 是 | 是 | 是 | 是 |
| 数据权限策略 | 否 | 否 | 否 | 是 | 否 |
**示例：**
```
Domo_read = glueContext.create_dynamic_frame.from_options(
connection_type="domo",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "dataset",
"API_VERSION": "v1"
}
```
## Domo 实体和字段详细信息
具有静态元数据的实体：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/domo-reading-from-entities.html)
对于以下实体，Domo 提供用于动态获取元数据的端点，以便在实体的数据类型级别捕获运算符支持。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/domo-reading-from-entities.html)
## 对查询进行分区
**基于字段的分区**
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于日期时间字段，我们接受 ISO 格式的值。
有效值示例：
```
"2023-01-15T11:18:39.205Z"
```
对于“日期”字段，我们接受 ISO 格式的值。
有效值示例：
```
"2023-01-15"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
有效值示例：
```
"2023-02-15T11:18:39.205Z"
```
+ `NUM_PARTITIONS`：分区的数量。
基于实体的分区字段支持详细信息如下表中所示：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/domo-reading-from-entities.html)
示例：
```
Domo_read = glueContext.create_dynamic_frame.from_options(
connection_type="domo",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "dataset",
"API_VERSION": "v1",
"PARTITION_FIELD": "permissionTime"
"LOWER_BOUND": "2023-01-15T11:18:39.205Z"
"UPPER_BOUND": "2023-02-15T11:18:39.205Z"
"NUM_PARTITIONS": "2"
}
```
**基于记录的分区**
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `NUM_PARTITIONS`。使用此参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
在基于记录的分区中，从 Domo 查询存在的记录总数，然后将其除以提供的 `NUM_PARTITIONS` 数字。然后，每个子查询会同时获取生成的记录数。
示例：
```
Domo_read = glueContext.create_dynamic_frame.from_options(
connection_type="domo",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "dataset",
"API_VERSION": "v1",
"NUM_PARTITIONS": "2"
}
```
# Domo 连接选项
以下是 Domo 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Domo 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Domo Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）：用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）：用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）：用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# Domo 限制
以下是 Domo 的限制或注意事项：
+ 由于 SDK 的限制，对于以“\$1”开头的可查询字段（例如：\$1BATCH\$1ID），筛选无法按预期生效。
+ 由于 API 的限制，筛选会在提供日期之前的日期生效。这也会影响增量拉取。要克服此限制，请根据时区（UTC）选择一个日期，获取所需日期的数据。
# 连接到 Dynatrace
Dynatrace 是一个提供分析和自动化服务的平台，可实现全面的可观测性和安全性。该平台专门监控和优化应用程序性能、基础设施和用户体验。
**Topics**
+ [AWS Glue 对 Dynatrace 的支持](dynatrace-support.md)
+ [包含创建和使用连接的 API 操作的策略](dynatrace-configuring-iam-permissions.md)
+ [配置 Dynatrace](dynatrace-configuring.md)
+ [配置 Dynatrace 连接](dynatrace-configuring-connections.md)
+ [从 Dynatrace 实体读取内容](dynatrace-reading-from-entities.md)
+ [Dynatrace 连接选项](dynatrace-connection-options.md)
+ [Dynatrace 限制](dynatrace-connection-limitations.md)
# AWS Glue 对 Dynatrace 的支持
AWS Glue 对 Dynatrace 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Dynatrace 中的数据。
**是否支持作为目标？**
否。
**支持的 Dynatrace API 版本**
支持以下 Dynatrace API 版本：
+ v2
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Dynatrace
必须满足以下要求，才能使用 AWS Glue 从 Dynatrace 传输数据：
## 最低要求
以下是最低要求：
+ 拥有 Dynatrace 账户。
+ 已在 Dynatrace 账户中生成访问令牌，并分配了相应的读/写范围用以访问 API。有关更多信息，请参阅[生成令牌](https://docs.dynatrace.com/docs/discover-dynatrace/references/dynatrace-api/basics/dynatrace-api-authentication#create-token)。
如果满足这些要求，就可以将 AWS Glue 连接到 Dynatrace 账户。
# 配置 Dynatrace 连接
Dynatrace 支持自定义身份验证。
要配置 Dynatrace 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的 API 密钥，且以 `apiToken` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**数据来源**时，请选择 Dynatrace。
1. 提供想要连接到的 Dynatrace 账户的 `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` 的权限。
# 从 Dynatrace 实体读取内容
**先决条件**
要从中读取内容的 Dynatrace 对象。需要“problem”等对象名称。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 问题 | 支持 | 是 | 是 | 是 | 否 |
**示例：**
```
Dynatrace_read = glueContext.create_dynamic_frame.from_options(
connection_type="Dynatrace",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "problem",
"API_VERSION": "v2",
"INSTANCE_URL": "https://[instanceName].live.dynatrace.com"
}
```
**Dynatrace 实体和字段详细信息**：
Dynatrace 提供用于动态获取所支持实体元数据的端点。因此，可在数据类型级别捕获运算符支持。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/dynatrace-reading-from-entities.html)
## 对查询进行分区
Dynatrace 不支持基于字段的分区或基于记录的分区。
# Dynatrace 连接选项
以下是 Dynatrace 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Dynatrace 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Dynatrace Rest API 版本。
+ `INSTANCE_URL`（字符串）– 用于读取。有效的 Dynatrace 实例 URL。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# Dynatrace 限制
以下是 Dynatrace 的限制或说明：
+ Dynatrace 不支持基于字段的分区或基于记录的分区。
+ 对于“全选”功能，若在筛选条件中提供“字段”，则每页将获取最多 10 条记录。
+ 支持的最大页面大小为 500 条。如果在创建流时选择任一 [`evidenceDetails, impactAnalysis, recentComments`] 字段，则每页获取的记录数将默认为 10 条。
# 连接到 Facebook Ads
Facebook Ads 是一个功能强大的数字广告平台，各种规模的企业都使用它来吸引目标受众，实现各种营销目标。该平台允许广告商制作量身定制的广告，这些广告可以在 Facebook 的一系列应用程序和服务（包括 Facebook 和 Messenger）中展示。凭借其先进的定位功能，Facebook Ads 使企业能够接触特定人口统计、兴趣、行为和地点的受众。
**Topics**
+ [AWS Glue 对 Facebook Ads 的支持](facebook-ads-support.md)
+ [包含创建和使用连接的 API 操作的策略](facebook-ads-configuring-iam-permissions.md)
+ [配置 Facebook Ads](facebook-ads-configuring.md)
+ [配置 Facebook Ads 连接](facebook-ads-configuring-connections.md)
+ [从 Facebook Ads 实体中读取](facebook-ads-reading-from-entities.md)
+ [Facebook Ads 连接选项](facebook-ads-connection-options.md)
+ [Facebook Ads 连接器的限制和说明](facebook-ads-connector-limitations.md)
# AWS Glue 对 Facebook Ads 的支持
AWS Glue 对 Facebook Ads 的支持如下：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业查询 Facebook Ads 中的数据。
**是否支持作为目标？**
否。
**支持的 Facebook Ads API 版本**
支持以下 Facebook Ads API 版本：
+ v17.0
+ v18.0
+ v19.0
+ v20.0
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Facebook Ads
您必须满足以下要求，才能使用 AWS Glue 从 Facebook Ads 传输数据：
## 最低要求
以下是最低要求：
+ 可通过 Facebook 直接访问 Facebook 标准账户。
+ 需要进行用户身份验证才能生成访问令牌。
+ Facebook Ads SDK 连接器将实现*用户访问令牌 OAuth* 流程。
+ 我们使用 OAuth2.0 对 Facebook Ads 的 API 请求进行身份验证。这种基于 Web 的身份验证属于多重身份验证（MFA）架构，是 2FA 的超集。
+ 用户需要授予访问端点的权限。为了访问用户的数据，端点授权是通过[权限](https://developers.facebook.com/docs/permissions)和[功能](https://developers.facebook.com/docs/features-reference)来处理的。
## 获取 OAuth 2.0 凭证
要获取 API 凭证以便可对实例进行经过身份验证的调用，请参阅《Facebook Ads Developer Guide》中的 [REST API](https://developers.facebook-ads.com/rest-api/)。
# 配置 Facebook Ads 连接
Facebook Ads 支持 OAuth2 的 AUTHIZATION\$1CODE 授权类型。
+ 此授权类型被视为三足型 OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。
+ 用户仍然可以选择在 Facebook Ads 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Facebook Ads，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成访问令牌。即将到期的系统用户令牌自生成或刷新之日起 60 天内有效。为保持连续性，开发者应在 60 天内刷新访问令牌。否则访问令牌将失效，并且需要开发者获取新访问令牌才能重新获得 API 访问权限。请参阅 [Refresh Access Token](https://developers.facebook.com/docs/marketing-api/system-users/install-apps-and-generate-tokens/)。
+ 有关为授权码 OAuth 流程创建关联应用程序的信息，请参阅《Google for Developers guide》中的 [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/oauth2)。
配置 Facebook Ads 连接：
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Facebook Ads。
1. 提供您想要连接到的 Facebook Ads 实例的 `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` 的权限。
# 从 Facebook Ads 实体中读取
**先决条件**
您要从中读取内容的 Facebook Ads 对象。您将需要对象名称。下表显示支持的实体。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 活动 | 支持 | 是 | 否 | 是 | 是 |
| 广告集 | 支持 | 是 | 否 | 是 | 是 |
| 广告 | 支持 | 是 | 否 | 是 | 是 |
| 广告创意 | 否 | 是 | 否 | 是 | 否 |
| 洞察 – 账户 | 否 | 是 | 否 | 是 | 否 |
| 广告账户 | 支持 | 是 | 否 | 是 | 否 |
| 洞察 – 广告 | 支持 | 是 | 否 | 是 | 是 |
| 洞察 – 广告组 | 支持 | 是 | 否 | 是 | 是 |
| 洞察 – 活动 | 支持 | 是 | 否 | 是 | 是 |
**示例：**
```
FacebookAds_read = glueContext.create_dynamic_frame.from_options(
connection_type="FacebookAds",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v20.0"
}
```
## Facebook Ads 实体和字段详细信息
有关实体和字段详细信息的更多信息，请参阅：
+ [广告账户](https://developers.facebook.com/docs/marketing-api/reference/ad-account)
+ [活动](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group)
+ [广告集](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign)
+ [广告](https://developers.facebook.com/docs/marketing-api/reference/adgroup)
+ [广告创意](https://developers.facebook.com/docs/marketing-api/reference/ad-creative)
+ [洞察广告账户](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights)
+ [洞察广告](https://developers.facebook.com/docs/marketing-api/reference/adgroup/insights/)
+ [洞察广告组](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/insights)
+ [洞察活动](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group/insights)
有关更多信息，请参阅 [Marketing API](https://developers.facebook.com/docs/marketing-api/reference/v21.0)。
**注意**
在连接器的响应中，结构和列表数据类型将转换为字符串数据类型。
## 对查询进行分区
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于日期时间字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"2022-01-01"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
FacebookADs_read = glueContext.create_dynamic_frame.from_options(
connection_type="FacebookAds",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v20.0",
"PARTITION_FIELD": "created_time"
"LOWER_BOUND": "2022-01-01"
"UPPER_BOUND": "2024-01-02"
"NUM_PARTITIONS": "10"
}
```
# Facebook Ads 连接选项
以下是 Facebook Ads 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Facebook Ads 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。您想要使用的 Facebook Ads 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。用于异步读取。
# Facebook Ads 连接器的限制和说明
以下是 Facebook Ads 连接器的限制或说明：
+ 由于 Facebook Ads 支持动态元数据，因此所有字段均可查询。所有字段都支持筛选，如果数据可用，则会提取记录，否则 Facebook 会返回错误请求（400）响应并显示相应的错误消息。
+ 应用程序的调用次数是用户在滚动的一小时窗口内可以调用次数 200 乘以用户数。有关速率限制的详细信息，请参阅 [Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/) 和 [Business Use Case Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#buc-rate-limits)。
# 连接到 Facebook Page Insights
Facebook Page 允许公司和其他利益团体为 Facebook.com 社交网络创建页面。公司使用这些页面来共享营业时间、发布公告以及与客户进行在线互动。如果是 Facebook Page Insights 用户，则可将 AWS Glue 连接到 Facebook Page Insights 账户。可以使用 Facebook Page Insights 作为 ETL 作业中的数据来源。通过运行这些作业，可将数据从 Facebook Page Insights 传输到 AWS 服务或其他受支持的应用程序。
**Topics**
+ [AWS Glue 支持 Facebook Page Insights](facebook-page-insights-support.md)
+ [包含创建和使用连接的 API 操作的策略](facebook-page-insights-configuring-iam-permissions.md)
+ [配置 Facebook Page Insights](facebook-page-insights-configuring.md)
+ [配置 Facebook Page Insights 连接](facebook-page-insights-configuring-connections.md)
+ [从 Facebook Page Insight 读取内容](facebook-page-insights-reading-from-entities.md)
+ [Facebook Page Insights 连接选项](facebook-page-insights-connection-options.md)
+ [Facebook Page Insights 连接器的限制和说明](facebook-page-insights-connector-limitations.md)
# AWS Glue 支持 Facebook Page Insights
AWS Glue 对 Facebook Page Insights 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Facebook Page Insights 中的数据。
**是否支持作为目标？**
否。
**支持的 Facebook Page Insight API 版本**
支持以下 Facebook Page Insights API 版本：
+ v17
+ v18
+ v19
+ v20
+ v21
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Facebook Page Insights
必须满足以下要求，才能使用 AWS Glue 从 Facebook Page Insights 传输数据：
## 最低要求
以下是最低要求：
+ 可通过 Facebook 直接访问 Facebook 标准账户。
+ 需要进行用户身份验证才能生成访问令牌。
+ Facebook Page Insights 连接器将实现用户访问令牌 OAuth 流。
+ 连接器使用 OAuth2.0 来验证我们向 Facebook Page Insights 发送的 API 请求。这属于多重身份验证（MFA）架构，是双重身份验证（2FA）的超集。它是基于 Web 的身份验证。
+ 用户需要授予访问端点的权限。为了访问用户的数据，端点授权是通过权限和功能来处理的。
# 配置 Facebook Page Insights 连接
要配置 Facebook Page Insights 连接，请执行以下操作：
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Facebook Page Insights。
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. 选择授权码 URL。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Facebook Page Insight 读取内容
**先决条件**
要从中读取内容的 Facebook Page Insights 对象。您将需要对象名称。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 页面内容 | 是 | 否 | 是 | 是 | 是 |
| 页面 CTA 点击次数 | 是 | 否 | 否 | 是 | 是 |
| 页面互动量 | 是 | 否 | 否 | 是 | 是 |
| 页面展示量 | 是 | 否 | 否 | 是 | 是 |
| 页面文章数 | 是 | 否 | 否 | 是 | 是 |
| 页面文章互动量 | 否 | 否 | 否 | 是 | 否 |
| 页面文章反应量 | 否 | 否 | 否 | 是 | 否 |
| 页面反应量 | 是 | 否 | 否 | 是 | 是 |
| 故事 | 是 | 否 | 否 | 是 | 是 |
| 页面用户人口统计数据 | 是 | 否 | 否 | 是 | 是 |
| 页面视频观看量 | 是 | 否 | 否 | 是 | 是 |
| 页面浏览量 | 是 | 否 | 否 | 是 | 是 |
| 页面视频文章量 | 是 | 否 | 否 | 是 | 是 |
| 页面 | 否 | 是 | 否 | 是 | 否 |
| 动态 | 支持 | 是 | 否 | 是 | 是 |
**示例：**
```
facebookPageInsights_read = glueContext.create_dynamic_frame. from options(
connection_type="facebookpageinsights",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v21"
}
```
**Facebook Page Insights 字段详细信息**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/facebook-page-insights-reading-from-entities.html)
## 对查询进行分区
**基于筛选器的分区**：
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于“日期时间”字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"2024-09-30T01:01:01.000Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
facebookPageInsights_read = glueContext.create_dynamic_frame.from_options(
connection_type="facebookpageinsights",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v21",
"PARTITION_FIELD": "created_Time"
"LOWER_BOUND": "2024-10-27T07:00:00+0000"
"UPPER_BOUND": "2024-10-27T07:00:00+0000"
"NUM_PARTITIONS": "10"
}
```
# Facebook Page Insights 连接选项
以下是 Facebook Page Insights 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Facebook Page Insights 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Facebook Page Insights Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（字符串）：（必填）用于读取。有效的 Facebook Page Insights 实例 URL。
# Facebook Page Insights 连接器的限制和说明
以下是 Facebook Page Insights 连接器的限制或说明：
+ 大多数指标每 24 小时更新一次。
+ 仅提供最近两年的见解数据。
+ 使用 `since` 和 `until` 参数时，一次只能查看 90 天的见解数据。
# 连接到 Freshdesk
Freshdesk 是一款基于云的客户支持软件，功能丰富，易于使用。借助实时聊天、电子邮件、电话和社交媒体等多种支持渠道，即可通过客户的首选沟通方式为他们提供帮助。如果是 Freshdesk 用户，则可将 AWS Glue 连接到 Freshdesk 账户。可以使用 Freshdesk 作为 ETL 作业中的数据来源。通过运行这些作业，可将数据从 Freshdesk 传输到 AWS 服务或其他受支持的应用程序。
**Topics**
+ [AWS Glue 支持 Freshdesk](freshdesk-support.md)
+ [包含创建和使用连接的 API 操作的策略](freshdesk-configuring-iam-permissions.md)
+ [配置 Freshdesk](freshdesk-configuring.md)
+ [配置 Freshdesk 连接](freshdesk-configuring-connections.md)
+ [从 Freshdesk 实体读取内容](freshdesk-reading-from-entities.md)
+ [Freshdesk 连接选项](freshdesk-connection-options.md)
+ [Freshdesk 连接器的限制和说明](freshdesk-connector-limitations.md)
# AWS Glue 支持 Freshdesk
AWS Glue 对 Freshdesk 的支持情况如下：
**是否支持作为来源？**
是，支持同步和异步。可以使用 AWS Glue ETL 作业查询 Freshdesk 中的数据。
**是否支持作为目标？**
否。
**支持的 Freshdesk API 版本**
支持以下 Freshdesk API 版本：
+ v2
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Freshdesk
必须满足以下要求，才能使用 AWS Glue 从 Freshdesk 传输数据：
## 最低要求
以下是最低要求：
+ 一个 Freshdesk 账户。可以选择免费版、成长版、专业版或企业版。
+ Freshdesk 用户的 API 密钥。
# 配置 Freshdesk 连接
Freshdesk 支持自定义身份验证。
有关生成自定义身份验证所需 API 密钥的 Freshdesk 公共文档，请参阅 [Freshdesk authentication](https://developer.freshdesk.com/api/#authentication)。
以下是配置 Freshdesk 连接的步骤：
+ 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
+ 如果是客户管理的连接应用程序，密钥应包含所连应用程序的 API 密钥，且以 `apiKey` 为键。注意：必须在 AWS Glue 中为每个连接创建密钥。
+ 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
+ 选择**数据来源**时，请选择 Freshdesk。
+ 提供想要连接到的 Freshdesk 实例的 `INSTANCE_URL`。
+ 选择 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": "*"
}
]
}
```
------
+ 在 AWS Glue 中选择要用于此连接的 `secretName`，然后放置令牌。
+ 如果要使用网络，请选择网络选项。
+ 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
+ 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 Freshdesk 实体读取内容
**先决条件**
要从中读取内容的 Freshdesk 对象。您将需要对象名称。
**同步源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 座席 | 支持 | 是 | 否 | 是 | 是 |
| 工作时间 | 否 | 是 | 否 | 是 | 是 |
| 公司 | 支持 | 是 | 否 | 是 | 是 |
| 联系人 | 支持 | 是 | 否 | 是 | 是 |
| 对话 | 否 | 是 | 否 | 是 | 否 |
| 电子邮件配置 | 否 | 是 | 否 | 是 | 否 |
| 电子邮件收件箱 | 支持 | 是 | 是 | 是 | 否 |
| 论坛类别 | 否 | 是 | 否 | 是 | 否 |
| 论坛 | 否 | 是 | 否 | 是 | 否 |
| 组 | 否 | 是 | 否 | 是 | 否 |
| 产品 | 否 | 是 | 否 | 是 | 否 |
| 角色 | 否 | 是 | 否 | 是 | 否 |
| 满意度评分 | 支持 | 是 | 否 | 是 | 否 |
| 技能 | 否 | 是 | 否 | 是 | 否 |
| 解决方案 | 支持 | 是 | 否 | 是 | 否 |
| 调查 | 否 | 是 | 否 | 是 | 否 |
| 票证 | 支持 | 是 | 是 | 是 | 是 |
| 时间条目 | 支持 | 是 | 否 | 是 | 否 |
| 主题 | 否 | 是 | 否 | 是 | 否 |
| 主题评论 | 否 | 是 | 否 | 是 | 否 |
**异步源支持的实体**：
| 实体 | API 版本 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- | --- |
| 公司 | v2 | 否 | 否 | 否 | 否 | 否 |
| 联系人 | v2 | 否 | 否 | 否 | 否 | 否 |
**示例：**
```
freshdesk_read = glueContext.create_dynamic_frame.from_options(
connection_type="freshdesk",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v2"
}
```
**Freshdesk 实体和字段详细信息**：
| 实体 | 字段 |
| --- | --- |
| 座席 | https://developers.freshdesk.com/api/\$1list\$1all\$1agents |
| 工作时间 | https://developers.freshdesk.com/api/\$1list\$1all\$1business\$1hours |
| 评论 | https://developers.freshdesk.com/api/\$1comment\$1attributess |
| 公司 | https://developers.freshdesk.com/api/\$1companies |
| 联系人 | https://developers.freshdesk.com/api/\$1list\$1all\$1contacts |
| 对话 | https://developers.freshdesk.com/api/\$1list\$1all\$1ticket\$1notes |
| 电子邮件配置 | https://developers.freshdesk.com/api/\$1list\$1all\$1email\$1configs |
| 电子邮件收件箱 | https://developers.freshdesk.com/api/\$1list\$1all\$1email\$1mailboxes |
| 论坛类别 | https://developers.freshdesk.com/api/\$1category\$1attributes |
| 论坛 | https://developers.freshdesk.com/api/\$1forum\$1attributes |
| 组 | https://developers.freshdesk.com/api/\$1list\$1all\$1groups |
| 产品 | https://developers.freshdesk.com/api/\$1list\$1all\$1products |
| 角色 | https://developers.freshdesk.com/api/\$1list\$1all\$1roles |
| 满意度评分 | https://developers.freshdesk.com/api/\$1view\$1all\$1satisfaction\$1ratingss |
| 技能 | https://developers.freshdesk.com/api/\$1list\$1all\$1skills |
| 解决方案 | https://developers.freshdesk.com/api/\$1solution\$1content |
| 调查 | https://developers.freshdesk.com/api/\$1list\$1all\$1survey |
| 票证 | https://developers.freshdesk.com/api/\$1list\$1all\$1tickets |
| 时间条目 | https://developers.freshdesk.com/api/\$1list\$1all\$1time\$1entries |
| 主题 | https://developers.freshdesk.com/api/\$1topic\$1attributes |
## 对查询进行分区
**基于筛选器的分区**：
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于“日期时间”字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"2024-09-30T01:01:01.000Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
freshDesk_read = glueContext.create_dynamic_frame.from_options(
connection_type="freshdesk",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v2",
"PARTITION_FIELD": "Created_Time"
"LOWER_BOUND": " 2024-10-27T23:16:08Z“
"UPPER_BOUND": " 2024-10-27T23:16:08Z"
"NUM_PARTITIONS": "10"
}
```
# Freshdesk 连接选项
以下是 Freshdesk 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Freshdesk 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Freshdesk Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（字符串）：（必填）用于读取。有效的 Freshdesk 实例 URL。
+ `TRANSFER_MODE`（字符串）– 用于指示 `SYNC` 或 `ASYNC` 等处理类型是否默认设置为 `SYNC`。（可选）
# Freshdesk 连接器的限制和说明
以下是 Freshdesk 连接器的限制或说明：
+ 具有筛选功能的 `Company`、`Contacts` 和 `Tickets` 实体有分页限制。这些实体每页仅返回 30 条记录，且页数值最多可设置为 10（最多可获取 300 条记录）。
+ `Tickets` 实体不会获取超过 30 天的记录。
+ `Company`、`Contacts` 和 `Tickets` 实体在筛选功能中支持“日期”数据类型。应该为这三个实体选择“每日”向前触发频率。选择“分钟”或“每小时”可能会导致数据重复。此外，在为筛选功能选择这些字段时，只应选择日期值，因为筛选时只会考虑所选时间戳的日期部分。
+ 每分钟 API 调用次数取决于所用套餐。无论调用方使用的座席数量或 IP 地址等因素如何，此限制均适用于整个账户。所有试用版用户的默认 API 调用限制次数为每分钟 50 次。有关更多详细信息，请参阅 [Freshdesk](https://developer.freshdesk.com/api/#ratelimit)
+ 无论是何实体，一次仅可以处理一个导出/异步作业。只有在现有作业成功完成或失败后，才会处理新作业。有关更多详细信息，请参阅 [Freshdesk](https://developers.freshdesk.com/api/#export_contact)
+ 同步 API 调用支持以下字段，但在异步 API 请求正文中，不支持/不允许传递这些字段。
+ id
+ created\$1at
+ updated\$1at
+ updated\$1since
+ active
+ company\$1id
+ other\$1companies
+ avatar
+ view\$1all\$1tickets
+ 已删除
+ other\$1emails
+ 状态
+ 标签
+ tags
# 连接到 Freshsales
Freshsales 是一款直观的 CRM 系统，可帮助销售代表消除销售过程中的猜测工作。借助内置电话和电子邮件、任务、预约和笔记，销售代表无需在选项卡之间切换即可跟进潜在客户。可以借助管道视图更好地管理交易，促成更多交易。如果是 Freshsales 用户，则可将 AWS Glue 连接到 Freshsales 账户。可以使用 Freshsales 作为 ETL 作业中的数据来源。通过运行这些作业，可将数据从 Freshsales 传输到 AWS 服务或其他受支持的应用程序。
**Topics**
+ [AWS Glue 支持 Freshsales](freshsales-support.md)
+ [包含创建和使用连接的 API 操作的策略](freshsales-configuring-iam-permissions.md)
+ [配置 Freshsales](freshsales-configuring.md)
+ [配置 Freshsales 连接](freshsales-configuring-connections.md)
+ [从 Freshsales 实体读取内容](freshsales-reading-from-entities.md)
+ [Fressales 连接选项](freshsales-connection-options.md)
+ [Freshsales 的限制](freshsales-connection-limitations.md)
# AWS Glue 支持 Freshsales
AWS Glue 对 Freshsales 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Freshsales 中的数据。
**是否支持作为目标？**
否。
**支持的 Freshsales API 版本**
支持以下 Freshsales API 版本：
+ v1.0
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Freshsales
必须满足以下要求，才能使用 AWS Glue 从 Freshsales 传输数据：
## 最低要求
以下是最低要求：
+ 拥有一个 Fressales 账户。
+ 拥有一个用户 API 密钥。
如果满足这些要求，就可以将 AWS Glue 连接到 Freshsales 账户。对于常见连接，无需在 Freshsales 中执行其他操作。
# 配置 Freshsales 连接
Freshsales 支持自定义身份验证。
有关生成自定义身份验证所需 API 密钥的 Freshsales 公共文档，请参阅 [Authentication](https://developer.freshsales.io/api/#authentication)。
要配置 Freshsales 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的 API 密钥，且以 `apiSecretKey` 为键。密钥还需要包含另一个键值对：以 `apiKey` 为键，以 `token` 为值。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**数据来源**时，请选择 Freshsales。
1. 提供想要连接到的 Freshsales 账户的 `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` 的权限。
# 从 Freshsales 实体读取内容
**先决条件**
要从中读取内容的 Freshsales 对象。您将需要对象名称。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 账户 | 支持 | 是 | 是 | 是 | 是 |
| 联系人 | 支持 | 是 | 是 | 是 | 是 |
**示例：**
```
freshSales_read = glueContext.create_dynamic_frame.from_options(
connection_type="freshsales",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v1.0"
}
```
**Freshsales 实体和字段详细信息**：
Freshsales 提供了端点，用于为所支持实体动态获取元数据。因此，可在数据类型级别捕获运算符支持。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/freshsales-reading-from-entities.html)
## 对查询进行分区
**基于筛选器的分区**：
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于“日期时间”字段，我们接受 ISO 格式的值。
有效值示例：
```
"2024-09-30T01:01:01.000Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
freshSales_read = glueContext.create_dynamic_frame.from_options(
connection_type="freshsales",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v1",
"PARTITION_FIELD": "Created_Time"
"LOWER_BOUND": " 2024-10-15T21:16:25Z"
"UPPER_BOUND": " 2024-10-20T21:25:50Z"
"NUM_PARTITIONS": "10"
}
```
# Fressales 连接选项
以下是 Freshsales 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Freshsales 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Freshsales Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（字符串）– 用于读取。有效的 Freshsales 实例 URL。
# Freshsales 的限制
以下是 Freshsales 的限制或说明：
+ 在 Freshsales 中，API 速率限制为每个账户每小时 1000 个 API 请求（请参阅 [Errors](https://developer.freshsales.io/api/#error)）。但此限制可通过企业版订阅方案延长（请参阅 [plan comparison](https://www.freshworks.com/crm/pricing-compare/)）。
# 连接到 Google Ads
Google Ads API 是 Google Ads 的编程接口，用于管理大型或复杂的 Google Ads 账户和广告活动。如果是 Google Ads 用户，则可将 AWS Glue 连接到 Google Ads 账户。然后，可以使用 Google Ads 作为 ETL 作业中的数据来源。通过运行这些作业，可在 Google Ads 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 对 Google Ads 的支持](googleads-support.md)
+ [包含创建和使用连接的 API 操作的策略](googleads-configuring-iam-permissions.md)
+ [配置 Google Ads](googleads-configuring.md)
+ [配置 Google Ads 连接](googleads-configuring-connections.md)
+ [从 Google Ads 实体中读取](googleads-reading-from-entities.md)
+ [Google Ads 连接选项](googleads-connection-options.md)
+ [创建 Google Ads 账户](googleads-create-account.md)
+ [限制](googleads-connector-limitations.md)
# AWS Glue 对 Google Ads 的支持
AWS Glue 对 Google Ads 的支持如下：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业查询 Google Ads 中的数据。
**是否支持作为目标？**
否。
**支持的 Google Ads API 版本**
v18
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Google Ads
您必须满足以下要求，才能使用 AWS Glue 从 Google Ads 传出数据：
## 最低要求
+ 您拥有一个 Google Ads 账户，以及电子邮件地址和密码。有关创建账户的更多信息，请参阅 [Creating a Google Ads account](googleads-create-account.md)。
+ 您的 Google Ads 账户已启用 API 访问权限。对 Google Ads API 的所有使用均无需额外付费。
+ 您的 Google Ads 账户允许您安装连接的应用程序。如果您无法使用此功能，请联系您的 Google Ads 管理员。
如果满足这些要求，就可以将 AWS Glue 连接到 Google Ads 账户。
# 配置 Google Ads 连接
Google Ads 支持 OAuth2 的 `AUTHORIZATION_CODE` 授权类型。
此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Google Ads，用户必须登录并向 AWS Glue 授予所请求的权限，以便访问其 Google Ads 实例。
用户可以选择在 Google Ads 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Google Ads，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
有关为授权码 OAuth 流创建关联应用程序的公共 Google Ads 文档，请参阅[创建访问凭据](https://developers.google.com/workspace/guides/create-credentials)。
要配置 Google Ads 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。
1. 对于 AuthorizationCode 授权类型：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在选择**连接类型**时，请选择 Google Ads。
1. 提供想要连接到的 Google Ads 的 `developer token`。
1. 如果想以管理员身份登录，请提供 Google Ads 的 `MANAGER ID`。
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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Google Ads 实体中读取
**先决条件**
+ 您要从中读取内容的 Google Ads 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 广告组广告 | 支持 | 是 | 是 | 否 | 是 |
| 广告组 | 支持 | 是 | 是 | 否 | 是 |
| 活动预算 | 支持 | 是 | 是 | 是 | 是 |
| 账户预算 | 是 | 否 | 是 | 是 | 否 |
| 活动 | 支持 | 是 | 是 | 是 | 是 |
| Account | 是 | 否 | 是 | 否 | 否 |
**示例**
```
googleAds_read = glueContext.create_dynamic_frame.from_options(
connection_type="googleads",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "campaign-3467***",
"API_VERSION": "v16"
}
```
**Google Ads 实体和字段详细信息**
| 实体 | 字段 | 数据类型 | 支持的运算符 |
| --- | --- | --- | --- |
| Account | resourceName | 字符串 | \$1=, = |
| Account | callReportingEnabled | 布尔值 | \$1=, = |
| Account | callConversionReportingEnabled | 布尔值 | \$1=, = |
| Account | callConversionAction | 字符串 | \$1=, = |
| Account | conversionTrackingId | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| Account | crossAccountConversionTrackingId | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| Account | payPerConversionEligibilityFailureReasons | 列表 | |
| Account | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| Account | currencyCode | 字符串 | \$1=, =, LIKE |
| Account | timeZone | 字符串 | \$1=, =, LIKE |
| Account | autoTaggingEnabled | 布尔值 | \$1=, = |
| Account | hasPartnersBadge | 布尔值 | \$1=, = |
| Account | manager | 布尔值 | \$1=, = |
| Account | testAccount | 布尔值 | \$1=, = |
| Account | date | 日期 | BETWEEN, =, <, >, <=, >= |
| Account | costMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| Account | acceptedCustomerDataTerms | 布尔值 | |
| Account | conversionTrackingStatus | 字符串 | \$1=, =, LIKE |
| Account | enhancedConversionsForLeadsEnabled | 布尔值 | |
| Account | googleAdsConversionCustomer | 字符串 | |
| Account | 状态 | 字符串 | \$1=, = |
| Account | allConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| Account | allConversionsValueByConversionDate | 双精度 | \$1=, =, <, > |
| Account | conversionsByConversionDate | 双精度 | \$1=, =, <, > |
| Account | conversionsValueByConversionDate | 双精度 | \$1=, =, <, > |
| Account | valuePerAllConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| Account | videoViews | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| Account | clicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| Account | invalidClicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| Account | costPerAllConversions | 双精度 | \$1=, =, <, > |
| Account | costPerConversion | 双精度 | \$1=, =, <, > |
| Account | conversions | 双精度 | \$1=, =, <, > |
| Account | absoluteTopImpressionPercentage | 双精度 | \$1=, =, <, > |
| Account | 展示 | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| Account | topImpressionPercentage | 双精度 | \$1=, =, <, > |
| Account | averageCpc | 双精度 | \$1=, =, <, > |
| Account | activeViewMeasurableCostMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| Account | averageCost | 双精度 | \$1=, =, <, > |
| Account | ctr | 双精度 | \$1=, =, <, > |
| Account | activeViewCtr | 双精度 | \$1=, =, <, > |
| Account | searchImpressionShare | 双精度 | \$1=, =, <, > |
| Account | conversionAction | 字符串 | \$1=, = |
| Account | conversionActionCategory | 字符串 | \$1=, = |
| Account | conversionActionName | 字符串 | \$1=, =, LIKE |
| 账户预算 | resourceName | 字符串 | \$1=, = |
| 账户预算 | 状态 | 字符串 | \$1=, = |
| 账户预算 | proposedEndTimeType | 字符串 | \$1=, = |
| 账户预算 | approvedEndTimeType | 字符串 | \$1=, = |
| 账户预算 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 账户预算 | billingSetup | 字符串 | \$1=, = |
| 账户预算 | 名称 | 字符串 | \$1=, =, LIKE |
| 账户预算 | approvedStartDateTime | 日期时间 | BETWEEN, =, <, >, <=, >= |
| 账户预算 | proposedSpendingLimitMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 账户预算 | approvedSpendingLimitMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 账户预算 | adjustedSpendingLimitMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 账户预算 | amountServedMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | resourceName | 字符串 | \$1=, =, LIKE |
| 广告组 | 状态 | 字符串 | \$1=, =, LIKE |
| 广告组 | type | 字符串 | \$1=, =, LIKE |
| 广告组 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | 名称 | 字符串 | \$1=, =, LIKE |
| 广告组 | 市场活动 | 字符串 | \$1=, = |
| 广告组 | cpcBidMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | targetCpaMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | cpmBidMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | cpvBidMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | targetCpmMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | effectiveTargetCpaMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | date | 日期 | BETWEEN, =, <, >, <=, >= |
| 广告组 | costMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | useAudienceGrouped | 布尔值 | \$1=, = |
| 广告组 | effectiveCpcBidMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | allConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组 | allConversionsValueByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组 | conversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组 | conversionsValueByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组 | valuePerAllConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组 | valuePerConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组 | averageCost | 双精度 | \$1=, =, <, > |
| 广告组 | costPerAllConversions | 双精度 | \$1=, =, <, > |
| 广告组 | costPerConversion | 双精度 | \$1=, =, <, > |
| 广告组 | averagePageViews | 双精度 | \$1=, =, <, > |
| 广告组 | videoViews | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | clicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | allConversions | 双精度 | \$1=, =, <, > |
| 广告组 | averageCpc | 双精度 | \$1=, =, <, > |
| 广告组 | absoluteTopImpressionPercentage | 双精度 | \$1=, =, <, > |
| 广告组 | 展示 | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组 | topImpressionPercentage | 双精度 | \$1=, =, <, > |
| 广告组 | activeViewCtr | 双精度 | \$1=, =, <, > |
| 广告组 | ctr | 双精度 | \$1=, =, <, > |
| 广告组 | searchTopImpressionShare | 双精度 | \$1=, =, <, > |
| 广告组 | searchImpressionShare | 双精度 | \$1=, =, <, > |
| 广告组 | searchAbsoluteTopImpressionShare | 双精度 | \$1=, =, <, > |
| 广告组 | relativeCtr | 双精度 | \$1=, =, <, > |
| 广告组 | conversionAction | 字符串 | \$1=, = |
| 广告组 | conversionActionCategory | 字符串 | \$1=, = |
| 广告组 | conversionActionName | 字符串 | \$1=, =, LIKE |
| 广告组 | updateMask | 字符串 | |
| 广告组 | 创建 | 结构体 | |
| 广告组 | 更新 | 结构体 | |
| 广告组 | primaryStatus | 字符串 | \$1=, = |
| 广告组 | primaryStatusReasons | 列表 | |
| 广告组广告 | resourceName | 字符串 | \$1=, = |
| 广告组广告 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组广告 | 状态 | 字符串 | \$1=, = |
| 广告组广告 | labels | 列表 | |
| 广告组广告 | adGroup | 字符串 | \$1=, = |
| 广告组广告 | costMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组广告 | approvalStatus | 字符串 | \$1=, = |
| 广告组广告 | reviewStatus | 字符串 | \$1=, = |
| 广告组广告 | adStrength | 字符串 | \$1=, = |
| 广告组广告 | type | 字符串 | \$1=, = |
| 广告组广告 | businessName | 字符串 | \$1=, =, LIKE |
| 广告组广告 | date | 日期 | BETWEEN, =, <, >, <=, >= |
| 广告组广告 | allConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组广告 | allConversionsValueByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组广告 | conversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组广告 | conversionsValueByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组广告 | valuePerAllConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组广告 | valuePerConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 广告组广告 | activeViewMeasurableCostMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组广告 | averageCost | 双精度 | \$1=, =, <, > |
| 广告组广告 | costPerAllConversions | 双精度 | \$1=, =, <, > |
| 广告组广告 | costPerConversion | 双精度 | \$1=, =, <, > |
| 广告组广告 | clicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组广告 | averagePageViews | 双精度 | \$1=, =, <, > |
| 广告组广告 | videoViews | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组广告 | allConversions | 双精度 | \$1=, =, <, > |
| 广告组广告 | averageCpc | 双精度 | \$1=, =, <, > |
| 广告组广告 | topImpressionPercentage | 双精度 | \$1=, =, <, > |
| 广告组广告 | 展示 | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 广告组广告 | absoluteTopImpressionPercentage | 双精度 | \$1=, =, <, > |
| 广告组广告 | activeViewCtr | 双精度 | \$1=, =, <, > |
| 广告组广告 | ctr | 双精度 | \$1=, =, <, > |
| 广告组广告 | conversionAction | 字符串 | \$1=, = |
| 广告组广告 | conversionActionCategory | 字符串 | \$1=, = |
| 广告组广告 | conversionActionName | 字符串 | \$1=, =, LIKE |
| 广告组广告 | updateMask | 字符串 | |
| 广告组广告 | 创建 | 结构体 | |
| 广告组广告 | 更新 | 结构体 | |
| 广告组广告 | policyValidationParameter | 结构体 | |
| 广告组广告 | primaryStatus | 字符串 | \$1=, = |
| 广告组广告 | primaryStatusReasons | 列表 | |
| 活动 | resourceName | 字符串 | \$1=, = |
| 活动 | 状态 | 字符串 | \$1=, = |
| 活动 | baseCampaign | 字符串 | \$1=, = |
| 活动 | 名称 | 字符串 | \$1=, =, LIKE |
| 活动 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动 | campaignBudget | 字符串 | \$1=, =, LIKE |
| 活动 | startDate | 日期 | BETWEEN, =, <, >, <=, >= |
| 活动 | endDate | 日期 | BETWEEN, =, <, >, <=, >= |
| 活动 | adServingOptimizationStatus | 字符串 | \$1=, = |
| 活动 | advertisingChannelType | 字符串 | \$1=, = |
| 活动 | advertisingChannelSubType | 字符串 | \$1=, = |
| 活动 | experimentType | 字符串 | \$1=, = |
| 活动 | servingStatus | 字符串 | \$1=, = |
| 活动 | biddingStrategyType | 字符串 | \$1=, = |
| 活动 | domainName | 字符串 | \$1=, =, LIKE |
| 活动 | languageCode | 字符串 | \$1=, =, LIKE |
| 活动 | useSuppliedUrlsOnly | 布尔值 | \$1=, = |
| 活动 | positiveGeoTargetType | 字符串 | \$1=, = |
| 活动 | negativeGeoTargetType | 字符串 | \$1=, = |
| 活动 | paymentMode | 字符串 | \$1=, = |
| 活动 | optimizationGoalTypes | 列表 | |
| 活动 | date | 日期 | BETWEEN, =, <, >, <=, >= |
| 活动 | averageCost | 双精度 | |
| 活动 | clicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动 | costMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动 | 展示 | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动 | useAudienceGrouped | 布尔值 | \$1=, = |
| 活动 | activeViewMeasurableCostMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动 | costPerAllConversions | 双精度 | \$1=, =, <, > |
| 活动 | costPerConversion | 双精度 | \$1=, =, <, > |
| 活动 | invalidClicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动 | publisherPurchasedClicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动 | averagePageViews | 双精度 | \$1=, =, <, > |
| 活动 | videoViews | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动 | allConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 活动 | allConversionsValueByConversionDate | 双精度 | \$1=, =, <, > |
| 活动 | conversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 活动 | conversionsValueByConversionDate | 双精度 | \$1=, =, <, > |
| 活动 | valuePerAllConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 活动 | valuePerConversionsByConversionDate | 双精度 | \$1=, =, <, > |
| 活动 | allConversions | 双精度 | \$1=, =, <, > |
| 活动 | absoluteTopImpressionPercentage | 双精度 | \$1=, =, <, > |
| 活动 | searchAbsoluteTopImpressionShare | 双精度 | \$1=, =, <, > |
| 活动 | averageCpc | 双精度 | \$1=, =, <, > |
| 活动 | searchImpressionShare | 双精度 | \$1=, =, <, > |
| 活动 | searchTopImpressionShare | 双精度 | \$1=, =, <, > |
| 活动 | activeViewCtr | 双精度 | \$1=, =, <, > |
| 活动 | ctr | 双精度 | \$1=, =, <, > |
| 活动 | relativeCtr | 双精度 | \$1=, =, <, > |
| 活动 | updateMask | 字符串 | |
| 活动 | 创建 | 结构体 | |
| 活动 | 更新 | 结构体 | |
| 活动预算 | resourceName | 字符串 | \$1=, = |
| 活动预算 | id | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动预算 | 状态 | 字符串 | \$1=, = |
| 活动预算 | deliveryMethod | 字符串 | \$1=, = |
| 活动预算 | 周期 | 字符串 | \$1=, = |
| 活动预算 | type | 字符串 | \$1=, = |
| 活动预算 | 名称 | 字符串 | \$1=, =, LIKE |
| 活动预算 | amountMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动预算 | explicitlyShared | 布尔值 | \$1=, = |
| 活动预算 | referenceCount | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动预算 | hasRecommendedBudget | 布尔值 | \$1=, = |
| 活动预算 | date | 日期 | BETWEEN, =, <, >, <=, >= |
| 活动预算 | costMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动预算 | startDate | 日期 | BETWEEN, =, <, >, <=, >= |
| 活动预算 | endDate | 日期 | BETWEEN, =, <, >, <=, >= |
| 活动预算 | maximizeConversionValueTargetRoas | 双精度 | \$1=, =, <, > |
| 活动预算 | maximizeConversionsTargetCpaMicros | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动预算 | selectiveOptimizationConversionActions | 字符串 | |
| 活动预算 | averageCost | 双精度 | \$1=, =, <, > |
| 活动预算 | costPerAllConversions | 双精度 | \$1=, =, <, > |
| 活动预算 | costPerConversion | 双精度 | \$1=, =, <, > |
| 活动预算 | videoViews | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动预算 | clicks | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动预算 | allConversions | 双精度 | \$1=, =, <, > |
| 活动预算 | valuePerAllConversions | 双精度 | \$1=, =, <, > |
| 活动预算 | averageCpc | 双精度 | \$1=, =, <, > |
| 活动预算 | 展示 | BigInteger | BETWEEN, =, \$1=, <, >, <=, >= |
| 活动预算 | ctr | 双精度 | \$1=, =, <, > |
| 活动预算 | updateMask | 字符串 | |
| 活动预算 | 创建 | 结构体 | |
| 活动预算 | 更新 | 结构体 | |
**对查询进行分区**
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-02-06"`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
基于实体的分区字段支持详细信息如下表中所示。
| 实体名称 | 分区字段 | 数据类型 |
| --- | --- | --- |
| 广告组广告 | date | 日期 |
| 广告组 | date | 日期 |
| 活动 | date | 日期 |
| 活动预算 | date | 日期 |
**示例**
```
googleads_read = glueContext.create_dynamic_frame.from_options(
connection_type="googleads",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "campaign-3467***",
"API_VERSION": "v16",
"PARTITION_FIELD": "date"
"LOWER_BOUND": "2024-01-01"
"UPPER_BOUND": "2024-06-05"
"NUM_PARTITIONS": "10"
}
)
```
# Google Ads 连接选项
以下是 Google Ads 的连接选项：
+ `ENTITY_NAME`（字符串）–（必填）用于读/写。Google Ads 中对象的名称。
+ `API_VERSION`（字符串）–（必填）用于读/写。要使用的 Google Ads Rest API 版本。示例：v16。
+ `DEVELOPER_TOKEN`（字符串）–（必填）用于读/写。对发出 API 请求的开发人员或应用程序进行身份验证时需要用到该项。
+ `MANAGER_ID`（字符串）：用于读取/写入。允许管理多个 Google Ads 账户的唯一标识符。这是授权管理员的客户 ID。如果通过管理员账户访问客户账户，则需要 `MANAGER_ID`。有关更多信息，请参阅 [login-customer-id](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid)。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# 创建 Google Ads 账户
1. 使用您的凭证登录 [Google Ads 开发者账户](https://console.cloud.google.com)，然后前往 \$1MyProject。
![\[屏幕截图显示了登录到 Google Ads 开发者账户的欢迎屏幕。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/google-ads-log-in-developer-account.png)
1. 如果您还没有注册任何应用程序，请选择**新建项目**，然后提供创建 Google 项目所需的信息。
![\[屏幕截图显示了“选择项目”页面。选择右上角的“新建项目”。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/google-ads-new-project.png)
![\[屏幕截图显示了“新建项目”窗口，用于输入项目名称并选择位置。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/google-ads-new-project-name-location.png)
1. 选择**导航**选项卡，然后选择 **API 和设置**，然后选择**创建客户端 Id** 和**客户密钥**，这需要进一步配置才能在 AWS Glue 与 Google Ads 之间建立连接。有关更多信息，请参阅 [API credentials](https://console.cloud.google.com/apis/credentials)。
![\[屏幕截图显示了 API 和服务配置页面。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/google-ads-apis-and-services.png)
1. 选择**创建凭证**，然后选择 **OAuth 客户端 ID**。
![\[屏幕截图显示了 API 和服务配置页面，其中突出显示了“创建凭证”下拉列表和“Oauth 客户端 ID”选项。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/google-ads-create-credentials.png)
1. 对于**应用程序类型**，选择 **Web 应用程序**。
![\[屏幕截图显示了“创建 OAuth 客户端 ID”页面，并且对于“应用程序类型”选择了 “Web 应用程序”。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/google-ads-oauth-client-id-application-type.png)
1. 在**授权重定向 URI** 下，添加 OAuth 重定向 URI，然后选择**创建**。您可以根据需要添加多个重定向 URI。
![\[屏幕截图显示的是“创建 OAuth 客户端 ID”页面和“授权重定向 URI”部分。在此处添加 URI，并根据需要选择“添加 URI”。操作完成后选择“创建”。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/google-ads-oauth-redirect-uris.png)
1. 您的**客户端 Id** 和**客户端密钥**将在创建 AWS Glue 与 Google Ads 之间的连接时生成。
![\[屏幕截图显示的是“创建 OAuth 客户端 ID”页面和“授权重定向 URI”部分。在此处添加 URI，并根据需要选择“添加 URI”。操作完成后选择“创建”。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/google-ads-oauth-client-created.png)
1. 根据应用程序需求添加范围，选择 **OAuth 同意屏幕**并提供所需的信息，然后根据要求添加范围。
![\[屏幕截图显示了“更新选定范围”页面。根据需要选择范围。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/google-ads-selected-scopes.png)
# 限制
以下是 Google Ads 连接器的限制：
+ `MANAGER_ID` 是创建连接时的可选输入。但如果要访问任何特定管理员下的客户，则必须输入 `MANAGER_ID`。下表根据连接中是否包含 `MANAGER_ID` 说明访问限制。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/googleads-connector-limitations.html)
+ 选择管理员账户作为对象时，只会显示 `Account` 为子对象。在 Google Ads 连接器中，将根据各个客户端账户而不是管理员账户来检索活动、广告等实体。
+ 虽然无法检索管理员账户的指标，但可以检索各个客户端账户的指标。
+ 每个账户可以包含最多 10000 个活动，包括处于活动状态和暂停状态的活动。有关更多信息，请参阅[每个账户的活动](https://support.google.com/google-ads/answer/6372658)。
+ 创建报告时，如果您选择要显示某些指标，则不会返回所选指标全部为零的任何行。有关更多信息，请参阅 [Zero Metrics](https://developers.google.com/google-ads/api/docs/reporting/zero-metrics?hl=en#exclude_zero_metrics_by_segmenting)。
+ 如果使用以下字段，则完整映射流程不适用于账户、广告组和广告组广告实体，特别是 conversionAction、conversionActionCategory、conversionActionName。有关更多信息，请参阅 [Segment and Metrics](https://developers.google.com/google-ads/api/docs/reporting/segmentation?hl=en#selectability_between_segments_and_metrics)。
+ 选择 `segments.date` 字段时，必须使用日期范围筛选器。
# 连接到 Google Analytics 4
Google Analytics 4 是一项分析服务，用于跟踪和报告有关访客与应用程序和网站互动的指标。这些指标包括页面查看次数、活跃用户数和事件数等。如果您是 Google Analytics 4 用户，则可将 AWS Glue 连接到自己的 Google Analytics 4 账户。可以将 Google Analytics 4 作为 ETL 作业中的数据来源。通过运行这些作业，可将数据从 Google Analytics 4 传输到 AWS 服务或其他受支持的应用程序。
**Topics**
+ [AWS Glue 对 Google Analytics 4 的支持](googleanalytics-support.md)
+ [包含创建和使用连接的 API 操作的策略](googleanalytics-configuring-iam-permissions.md)
+ [配置 Google Analytics 4](googleanalytics-configuring.md)
+ [配置 Google Analytics 4 连接](googleanalytics-configuring-connections.md)
+ [从 Google Analytics 4 实体读取内容](googleanalytics-reading-from-entities.md)
+ [Google Analytics 4 连接选项](googleanalytics-connection-options.md)
+ [创建 Google Analytics 4 账户](googleanalytics-create-account.md)
+ [创建客户端应用程序和 OAuth 2.0 凭证的步骤](googleanalytics-client-app-oauth-credentials.md)
+ [限制和注意事项](googleanalytics-connector-limitations.md)
# AWS Glue 对 Google Analytics 4 的支持
AWS Glue 对 Google Analytics 4 的支持如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Google Analytics 4 中的数据。
**是否支持作为目标？**
否。
**支持的 Google Analytics 4 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 控制台的用户。
# 配置 Google Analytics 4
您必须满足以下要求，才能使用 AWS Glue 从 Google Analytics 4 传出数据：
## 最低要求
+ 您拥有一个 Google Analytics 账户，以及一个或多个用于收集要传输的数据的数据流。
+ 拥有一个 Google Cloud Platform 账户和 Google Cloud 项目。
+ 在您的 Google Cloud 项目中，您已启用了以下 API：
+ Google Analytics API
+ Google Analytics Admin API
+ Google Analytics Data API
+ 在 Google Cloud 项目中，为外部用户配置了 OAuth 同意屏幕。有关 OAuth 同意屏幕的详细信息，请参阅 Google Cloud Platform Console 帮助中心中的 [Setting up your OAuth consent screen](https://support.google.com/cloud/answer/10311615#)。
+ 在 Google Cloud 项目中，配置了 OAuth 2.0 客户端 ID。有关更多信息，请参阅 [Setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849?hl=en#zippy=)。
如果满足这些要求，就可以将 AWS Glue 连接到 Google Analytics 4 账户。
# 配置 Google Analytics 4 连接
要配置 Google Sheet 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。
1. 对于 AuthorizationCode 授权类型：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在选择**连接类型**时，请选择 Google Analytics 4。
1. 提供想要连接到的 Google Analytics 4 的 `INSTANCE_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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
`AUTHORIZATION_CODE` 授权类型。
此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Google Analytics 4，用户必须登录并向 AWS Glue 授予所请求的权限，以便访问其 Google Analytics 4 实例。
用户仍然可以选择在 Google Analytics 4 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Google Analytics 4，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
有关更多信息，请参阅[使用 OAuth 2.0 访问 Google API](https://developers.google.com/identity/protocols/oauth2)。
# 从 Google Analytics 4 实体读取内容
**先决条件**
+ 您要从中读取内容的 Google Analytics 4 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 实时报告 | 支持 | 是 | 是 | 是 | 否 |
| 核心报告 | 支持 | 是 | 是 | 是 | 是 |
**示例**
```
googleAnalytics4_read = glueContext.create_dynamic_frame.from_options(
connection_type="GoogleAnalytics4",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v1beta"
}
```
**Google Analytics 4 实体和字段详细信息**
| 实体 | 字段 | 数据类型 | 支持的运算符 |
| --- | --- | --- | --- |
| 核心报告 | 动态字段 | | |
| 核心报告 | 维度字段 | 字符串 | LIKE、= |
| 核心报告 | 维度字段 | 日期 | LIKE、= |
| 核心报告 | 指标字段 | 字符串 | >、<、>=、<=、=、BETWEEN |
| 核心报告 | 自定义维度和自定义指标字段 | 字符串 | NA |
| 实时报告 | appVersion | 字符串 | LIKE、= |
| 实时报告 | audienceId | 字符串 | LIKE、= |
| 实时报告 | audienceName | 字符串 | LIKE、= |
| 实时报告 | city | 字符串 | LIKE、= |
| 实时报告 | cityId | 字符串 | LIKE、= |
| 实时报告 | country | 字符串 | LIKE、= |
| 实时报告 | countryId | 字符串 | LIKE、= |
| 实时报告 | deviceCategory | 字符串 | LIKE、= |
| 实时报告 | eventName | 字符串 | LIKE、= |
| 实时报告 | minutesAgo | 字符串 | LIKE、= |
| 实时报告 | platform | 字符串 | LIKE、= |
| 实时报告 | streamId | 字符串 | LIKE、= |
| 实时报告 | streamName | 字符串 | LIKE、= |
| 实时报告 | unifiedScreenName | 字符串 | LIKE、= |
| 实时报告 | activeUsers | 字符串 | >、<、>=、<=、=、BETWEEN |
| 实时报告 | conversions | 字符串 | >、<、>=、<=、=、BETWEEN |
| 实时报告 | eventCount | 字符串 | >、<、>=、<=、=、BETWEEN |
| 实时报告 | screenPageViews | 字符串 | >、<、>=、<=、=、BETWEEN |
**对查询进行分区**
1. **基于筛选条件的分区**：
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-02-06"`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
**示例**
```
googleAnalytics4_read = glueContext.create_dynamic_frame.from_options(
connection_type="GoogleAnalytics4",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v1beta",
"PARTITION_FIELD": "date"
"LOWER_BOUND": "2022-01-01"
"UPPER_BOUND": "2024-01-02"
"NUM_PARTITIONS": "10"
}
```
1. **基于记录的分区**
如果要在 Spark 中利用并发，则可以提供附加 Spark 选项 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `NUM_PARTITIONS`：分区的数量。
**示例**
```
googleAnalytics4_read = glueContext.create_dynamic_frame.from_options(
connection_type="GoogleAnalytics4",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v1beta",
"NUM_PARTITIONS": "10"
}
```
# Google Analytics 4 连接选项
Google Analytics 4 的连接选项如下：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Google Analytics 4 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Google Analytics 4 Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（整数）：用于读取。（可选）
# 创建 Google Analytics 4 账户
按照下述步骤创建一个 Google Analytics 4 账户：[https://support.google.com/analytics/answer/9304153?hl=en](https://support.google.com/analytics/answer/9304153?hl=en)
# 创建客户端应用程序和 OAuth 2.0 凭证的步骤
如需了解更多信息，请参阅 [Google Analytics4 API 文档](https://developers.google.com/analytics/devguides/reporting/data/v1)。
1. 使用您的凭证登录到您的 [Google Analytics 账户](https://analytics.google.com/)，然后创建和设置您的账户。然后导航到**管理员** > **创建账户**。
1. 选择**创建属性**，从而为您创建的账户创建属性。使用所需的详细信息设置属性。提供所有详细信息后，系统将会生成相应的属性 ID。
1. 从下拉列表中选择**数据流** > **添加流** > **Web**，为已创建的属性添加数据流。提供网站详细信息，例如 URL 和其他必填字段。提供所有详细信息后，系统将会生成相应的**流 ID** 和**测量 ID**。
1. 复制测量 ID 并将其添加到您的网站配置中，从而在您的网站上设置 Google Analytics。
1. 导航到**报告**并生成所需的报告，从而从 Google Analytics 创建报告。
1. 导航到 [console.cloud.google.com]( https://console.cloud.google.com) 并搜索 Google Analytics Data API，然后启用该 API，从而授权您的应用程序。
1. 导航至“API 和服务”页面，然后选择**凭据** > **设置 OAuth 2.0 客户端 ID**。
1. 通过添加 AWS Glue 重定向 URL 来提供重定向 URL。
1. 复制客户端 ID 和客户端密钥，这将需要进一步的配置才能创建连接。
# 限制和注意事项
Google Analytics 4 连接器的限制如下：
+ 对于核心报告实体，只允许在请求中发送 9 个维度字段和 10 个指标字段。如果超出允许的字段数，则请求将会失败，并且连接器将发出一条错误消息。
+ 对于实时报告实体，只允许在请求中发送 4 个维度字段。如果超出允许的字段数，则请求将会失败，并且连接器将发出一条错误消息。
+ Google Analytics 4 是一款测试版的免费工具，因此会定期发布有关新功能、实体增强、增加新字段和弃用现有字段的更新。
+ 核心报告字段是动态填充的，因此可能随时会增加、弃用和重命名字段，以及对字段实施新的限制。
+ 默认开始日期为 30 天，结束日期为昨日（当前日期前一日）。如果用户设置了该值或者流程属于增量，则这些日期将在筛选表达式代码中被覆盖。
+ 根据文档的说明，如果请求中未传递限制值，则实时报告实体将返回 1 万条记录，否则无论请求的行数为多少，API 将最多为每个请求返回 25 万行。有关更多信息，请参阅 Google Analytics 文档中的 [Method: properties.runRealtimeReport](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runRealtimeReport)。
+ 实时报告实体不支持基于记录的分区，因为它不支持分页。此外，这种实体不支持基于字段的分区，因为没有任何字段符合定义的标准。
+ 由于可以在请求中传递的字段数存在限制，我们在指定限制范围内设置默认维度和指标字段。如果选择“全选”，则将仅检索这些预先确定字段中的数据。
+ 核心报告
+ 根据 SAAS 规定的限制，最多允许请求 9 个维度和最多 10 个指标，即一条请求最多可以包含 19 个字段（指标\$1维度）。
+ 根据具体实现，如果用户使用 SELECT\$1ALL 或选定的字段数超过 25 个，则系统将在请求中传递默认字段。
+ 以下字段属于核心报告的默认字段：“country”、“city”、“eventName”、“cityId”、“browser”、“date”、“currencyCode”、“deviceCategory”、“transactionId”、“active1DayUsers”、“active28DayUsers”、“active7DayUsers”、“activeUsers”、“averagePurchaseRevenue”、“averageRevenuePerUser”、“averageSessionDuration”、“engagedSessions”、“eventCount”、“engagementRate”。
+ 实时报告
+ 根据 SAAS 规定的限制，最多允许请求 4 个维度。
+ 如果用户使用 SELECT\$1ALL 或选定的字段数超过 15 个，则系统将在请求中传递默认字段。
+ 以下字段属于实时报告的默认字段：“country”、“deviceCategory”、“city”、“cityId”、“activeUsers”、“conversions”、“eventCount”、“screenPageViews”。
+ 在核心报告实体中，如果同时存在基于 date 字段的分区和基于 StartDate 的筛选条件，则在这种情况下，dateRange 值会被 startDate 筛选条件值覆盖。但是，由于分区必须始终优先，因此，如果已经存在基于 date 字段上的分区，则会丢弃 startDate 筛选条件。
+ 由于现在 cohortSpecs 也是核心报告请求正文的一部分，因此我们对当前核心报告实体进行了增强，增加了对 cohortSpec 属性的支持。在 cohortSpecs 请求正文中，几乎所有字段都要求用户输入。为了解决这一问题，我们为这些属性/字段设置了默认值，并提供了让用户在需要时覆盖这些值的功能。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/googleanalytics-connector-limitations.html)
+ 您也可以一次性传递所有这些筛选条件，或与其他筛选条件一起传递。
+ 示例 1 – filterPredicate：startDate between "2023-05-09" and "2023-05-10" AND startOffset=1 AND endOffset=2 AND granularity="WEEKLY"
+ 示例 2 – filterPredicate: city=“xyz” AND startOffset=1 AND endOffset=2 AND granularity="WEEKLY"
+ 在 cohort 请求中：
+ 如果请求中传递的是“cohortNthMonth”，则内部 granularity 值将设置为“MONTHLY”
+ 同样，如果传递的是“cohortNthWeek”，则 granularity 值将设置为“WEEKLY”
+ 对于“cohortNthDay”，granularity 值将设置为“DAILY”。有关更多信息，请参阅：
+ [ https://developers.google.com/analytics/devguides/reporting/data/v1/advanced ](https://developers.google.com/analytics/devguides/reporting/data/v1/advanced)
+ [ https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/CohortSpec ](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/CohortSpec)
+ 为用户提供了覆盖 dateRange 和 granularity 默认值的功能。请参阅上表。
# 连接到 AWS Glue Studio 中的 Google BigQuery
**注意**
在 AWS Glue 4.0 及更高版本中，您可以使用 AWS Glue for Spark 在 Google BigQuery 中读取和写入表。要以编程方式为 Google BigQuery 配置 AWS Glue 作业，请参阅 [BigQuery 连接](aws-glue-programming-etl-connect-bigquery-home.md)。
AWS Glue Studio 提供一个可视化界面，用于连接到 BigQuery、编写数据集成作业并在 AWS Glue Studio 无服务器 Spark 运行时系统上运行这些作业。
在中 AWS Glue Studio 创建与 Google BigQuery 的连接时，系统会创建一个统一连接。有关更多信息，请参阅 [注意事项](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。
现在，通过与 Google BigQuery 的统一连接，无需创建具有特定格式 `{"credentials": "base64 encoded JSON"}` 的凭证的密钥，就可以创建直接包含来自 Google BigQuery 的 JSON 的密钥：`{"type": "service-account", ...}`。
**Topics**
+ [创建 BigQuery 连接](creating-bigquery-connection.md)
+ [创建 BigQuery 源节点](creating-bigquery-source-node.md)
+ [创建 BigQuery 目标节点](creating-bigquery-target-node.md)
+ [高级选项](#creating-bigquery-connection-advanced-options)
# 创建 BigQuery 连接
要从 AWS Glue 中连接到 Google BigQuery，您需要创建 Google Cloud Platform 凭证并将其存储在 AWS Secrets Manager 密钥中，然后将该密钥与 Google BigQuery AWS Glue 连接关联。
**要配置与 BigQuery 的连接：**
1. 在 Google Cloud Platform，创建并识别相关资源：
+ 创建或标识包含您想要连接的 BigQuery 表的 GCP 项目。
+ 启用 BigQuery API。有关更多信息，请参阅[使用 BigQuery 存储读取 API 读取表数据](https://cloud.google.com/bigquery/docs/reference/storage/#enabling_the_api)。
1. 在 Google Cloud Platform 中，创建和导出服务账户凭证：
您可以使用 BigQuery 凭证向导来加快此步骤：[创建凭证](https://console.cloud.google.com/apis/credentials/wizard?api=bigquery.googleapis.com)。
要在 GCP 中创建服务账户，请按照[创建服务账户](https://cloud.google.com/iam/docs/service-accounts-create)中的教程进行操作。
+ 选择**项目**时，请选择包含您的 BigQuery 表的项目。
+ 为您的服务账户选择 GCP IAM 角色时，请添加或创建一个角色，该角色将授予运行 BigQuery 作业的相应权限，以读取、写入或创建 BigQuery 表。
要为您的服务账户创建凭证，请按照[创建服务账户密钥](https://cloud.google.com/iam/docs/keys-create-delete#creating)中的教程进行操作。
+ 在选择密钥类型时，请选择 **JSON**。
现在，您应该已经下载了包含服务账户凭证的 JSON 文件。如下所示：
```
{
"type": "service_account",
"project_id": "*****",
"private_key_id": "*****",
"private_key": "*****",
"client_email": "*****",
"client_id": "*****",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "*****",
"universe_domain": "googleapis.com"
}
```
1. 在 AWS Secrets Manager 中，使用您下载的凭证文件创建密钥。您可以选择“**纯文本**”选项卡并粘贴 JSON 格式的文件内容。要在 Secrets Manager 中创建密钥，请按照 AWS Secrets Manager 文档中[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中的教程进行操作。创建密钥后，保留密钥名称 *secretName*，以供下一步使用。
1. 在 AWS Glue Data Catalog 中，按照 [https://docs.aws.amazon.com/glue/latest/dg/console-connections.html](https://docs.aws.amazon.com/glue/latest/dg/console-connections.html) 中的步骤创建连接。创建连接后，保留连接名称 *connectionName*，以供下一步使用。
+ 在选择**连接类型**时，请选择 Google BigQuery。
+ 选择 **AWS 密钥**时，请提供 *secretName*。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 *secretName* 的权限。
1. 在 AWS Glue 作业配置中，提供 *connectionName* 作为**附加网络连接**。
# 创建 BigQuery 源节点
## 所需的先决条件
+ BigQuery 类型 AWS Glue Data Catalog 连接
+ 您的 Google BigQuery 凭证的 AWS Secrets Manager 密钥，供连接使用。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要读取的表的名称和数据集以及相应的 Google Cloud 项目。
## 添加 BigQuery 数据来源
**要添加**数据来源 – BigQuery** 节点，请执行以下操作：**
1. 为您的 BigQuery 数据来源选择连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 BigQuery 连接**。有关更多信息，请参阅 [Overview of using connectors and connections](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#using-connectors-overview)。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 确定您想要读取的 BigQuery 数据，然后选择 **BigQuery 来源**选项
+ 选择单个表 – 允许您从表中提取所有数据。
+ 输入自定义查询 – 允许您通过提供查询来自定义检索哪些数据。
1. 描述您想要读取的数据
**（必填）**将**父项目**设置为包含您的表的项目，或计费父项目（如果相关）。
如果您选择单个表，则请按以下格式将**表**设置为 Google BigQuery 表的名称：`[dataset].[table]`
如果您选择了查询，则请将其提供给 **Query**。在查询中，引用具有完全限定表名的表，使用的格式为：`[project].[dataset].[tableName]`。
1. 提供 BigQuery 属性
如果选择了单个表，则无需提供其他属性。
如果选择了查询，则必须提供以下**自定义 Google BigQuery 属性**：
+ 将 `viewsEnabled` 设置为 true。
+ 将 `materializationDataset` 设置为数据集。通过 AWS Glue 连接提供的凭证进行身份验证的 GCP 主体必须能够在此数据集中创建表。
# 创建 BigQuery 目标节点
## 所需的先决条件
+ BigQuery 类型 AWS Glue Data Catalog 连接
+ 您的 Google BigQuery 凭证的 AWS Secrets Manager 密钥，供连接使用。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要写入到的表和相应的 Google Cloud 项目的名称和数据集。
## 添加 BigQuery 数据目标
**要添加**数据目标 – BigQuery** 节点，请执行以下操作：**
1. 为您的 BigQuery 数据目标选择连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 BigQuery 连接**。有关更多信息，请参阅 [Overview of using connectors and connections](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#using-connectors-overview)。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 确定您要写入的 BigQuery 表，然后选择**写入方法**。
+ 直接 – 使用 BigQuery 存储写入 API 直接写入 BigQuery。
+ 间接 – 写入 Google Cloud Storage，然后复制到 BigQuery。
如果您想间接写入，请使用**临时 GCS 存储桶**提供目标 GCS 位置。您需要在 AWS Glue 连接中提供其他配置。有关更多信息，请参阅在 [Google BigQuery 中使用间接写入](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-connect-bigquery-home.html#aws-glue-programming-etl-connect-bigquery-indirect-write)。
1. 描述您想要读取的数据
**（必填）**将**父项目**设置为包含您的表的项目，或计费父项目（如果相关）。
如果您选择单个表，则请按以下格式将**表**设置为 Google BigQuery 表的名称：`[dataset].[table]`
## 高级选项
您可以在创建 BigQuery 节点时提供高级选项。这些选项与编程 Spark 脚本的 AWS Glue 时可用的选项相同。
请参阅 AWS Glue 开发者指南中的 [BigQuery 连接选项参考](https://docs.aws.amazon.com//glue/latest/dg/aws-glue-programming-etl-connect-bigquery-home.html)。
# 连接到 Google Search Console
Google Search Console 是一个免费平台，网站所有者可以使用该平台来监控 Google 如何查看他们的网站并优化网站自然呈现情况。这包括查看引用域、移动网站性能、丰富的搜索结果以及流量最高的查询和页面。如果是 Google Search Console 用户，则可将 AWS Glue 连接到 Google Search Console 账户。可以使用 Google Search Console 作为 ETL 作业中的数据来源。通过运行这些作业，可将数据从 Google Search Console 传输到 AWS 服务或其他受支持的应用程序。
**Topics**
+ [AWS Glue 支持 Google Search Console](google-search-console-support.md)
+ [包含创建和使用连接的 API 操作的策略](google-search-console-configuring-iam-permissions.md)
+ [配置 Google Search Console](google-search-console-configuring.md)
+ [配置 Google Search Console 连接](google-search-console-configuring-connections.md)
+ [从 Google Search Console 实体读取内容](google-search-console-reading-from-entities.md)
+ [Google Search Console 连接选项](google-search-console-connection-options.md)
+ [Google Search Console 限制](google-search-console-limitations.md)
# AWS Glue 支持 Google Search Console
AWS Glue 对 Google Search Console 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Google Search Console 中的数据。
**是否支持作为目标？**
否。
**支持的 Google Search Console API 版本**
支持以下 Google Search Console API 版本：
+ v3
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Google Search Console
必须满足以下要求，才能使用 AWS Glue 从 Google Search Console 传输数据：
## 最低要求
以下是最低要求：
+ 拥有一个 Google Search Console 账户。
+ 拥有一个 Google Cloud Platform 账户和 Google Cloud 项目。
+ 在 Google Cloud 项目中，启用了 Google Search Console API。
+ 在 Google Cloud 项目中，为外部用户配置了 OAuth 同意屏幕。有关更多信息，请参阅 Google Cloud Platform Console 帮助中心中的 [Setting up your OAuth consent screen](https://support.google.com/cloud/answer/10311615)。
+ 在 Google Cloud 项目中，配置了 OAuth 2.0 客户端 ID。请参阅 [Setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849)，了解在对账户进行身份验证调用时，AWS Glue 用于安全访问数据的凭证。
如果满足这些要求，就可以将 AWS Glue 连接到 Google Search Console 账户。对于常见连接，无需在 Google Search Console 中执行其他操作。
# 配置 Google Search Console 连接
Google Search Console 支持 OAuth2 的 AUTHORIZATION\$1CODE 授权类型。该授权类型决定了 AWS Glue 如何与 Google Search Console 通信来请求访问数据。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。
+ 用户仍然可以选择在 Google Search Console 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Google Search Console，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 Google Search Console 公共文档，请参阅[使用 OAuth 2.0 访问 Google API](https://developers.google.com/identity/protocols/oauth2)。
要配置 Google Search Console 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的消费者密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在选择**连接类型**时，请选择 Google Search Console。
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` 的权限。
# 从 Google Search Console 实体读取内容
**先决条件**
要从中读取内容的 Google Search Console 对象。您将需要对象名称。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 搜索分析 | 支持 | 是 | 否 | 是 | 否 |
| 站点 | 否 | 否 | 否 | 是 | 否 |
| 站点地图 | 否 | 否 | 否 | 是 | 否 |
**示例：**
```
googleSearchConsole_read = glueContext.create_dynamic_frame.from_options(
connection_type="googlesearchconsole",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v3"
}
```
**Google Search Console 实体和字段详细信息**：
Google Search Console 提供了端点，用于为所支持实体动态获取元数据。因此，可在数据类型级别捕获运算符支持。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/google-search-console-reading-from-entities.html)
**注意**
如需更新后的筛选条件有效值列表，请参阅 [Google Search Console](https://developers.google.com/webmaster-tools/v1/searchanalytics/query) API 文档。
字段 `start_end_date` 是 `start_date` 和 `end_date` 的组合。
## 对查询进行分区
不支持基于筛选条件的分区和基于记录的分区。
# Google Search Console 连接选项
以下是 Google Search Console 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Google Search Console 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Google Search Console Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：“start\$1end\$1date 介于 <当前日期前 30 天> 和 <昨天：即当前日期前 1 天> 之间”。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：“start\$1end\$1date 介于 <当前日期前 30 天> 和 <昨天：即当前日期前 1 天> 之间”用于读取。完整的 Spark SQL 查询。
+ `INSTANCE_URL`（字符串）– 用于读取。有效的 Google Search Console 实例 URL。
# Google Search Console 限制
以下是 Google Search Console 的限制或说明：
+ Google Search Console 对 API 强制执行使用限制。有关更多信息，请参阅[使用限制](https://developers.google.com/webmaster-tools/limits)。
+ 没有为 `Search Analytics` 实体传递任何筛选条件时，API 会将指定默认日期范围内整个网站的所有点击次数、展示次数、CTR 和其他数据汇总起来，显示为单个记录。
+ 要将数据细分为较小的区段，需要在查询中引入维度。维度会告诉 API 细分数据的方式。
+ 例如，若添加 `filterPredicate: dimensions="country"`，则会获得指定时段内网站接收流量的每个国家/地区的一条记录。
+ 传递多个维度的示例：`filterPredicate: dimensions="country" AND dimensions="device" AND dimensions="page"`。在这种情况下，将在响应中获得这三个维度的每个唯一组合的一行数据。
+ 为 `start_end_date` 和 `dataState` 字段设置默认值。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/google-search-console-limitations.html)
# 连接到 Google Sheets
Google Sheets 是一款在线电子表格软件，可让您整理大量数据、创建自定义报告、自动执行计算以及与其他人协作。如果您是 Google Sheets 用户，则可以将 AWS Glue 连接到自己的 Google Sheets 账户。然后，可以将 Google Sheets 作为 ETL 作业中的数据来源。通过运行这些作业，可在 Google Sheets 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 对 Google Sheets 的支持](googlesheets-support.md)
+ [包含创建和使用连接的 API 操作的策略](googlesheets-configuring-iam-permissions.md)
+ [配置 Google Sheets](googlesheets-configuring.md)
+ [配置 Google Sheets 连接](googlesheets-configuring-connections.md)
+ [从 Google Sheets 实体读取内容](googlesheets-reading-from-entities.md)
+ [Google Sheets 连接选项](googlesheets-connection-options.md)
+ [为 Google Sheets 设置授权码 OAuth 流](googlesheets-oauth-authorization.md)
+ [Google Sheets 连接器的限制](googlesheets-connector-limitations.md)
# AWS Glue 对 Google Sheets 的支持
AWS Glue 对 Google Sheets 的支持如下：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业查询 Google Sheets 中的数据。
**是否支持作为目标？**
否。
**支持的 Google Sheets API 版本**
Google Sheets API v4 和 Google Drive API v3
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Google Sheets
您必须满足以下要求，才能使用 AWS Glue 从 Google Sheets 传出数据：
## 最低要求
+ 您拥有一个 Google Sheets 账户，以及电子邮件地址和密码。
+ 您的 Google Sheets 账户已启用 API 访问权限。对 Google Sheets API 的所有使用均无需额外付费。
+ 您的 Google Sheets 账户允许您安装连接的应用程序。如果您无法使用此功能，请联系您的 Google Sheets 管理员。
如果满足这些要求，就可以将 AWS Glue 连接到 Google Sheets 账户。
# 配置 Google Sheets 连接
要配置 Google Sheet 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于 AuthorizationCode 授权类型：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**数据来源**时，请选择 Google Sheets。
1. 提供 Google Sheets 环境。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
**AUTHORIZATION\$1CODE 授权类型**
此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Google Sheets，用户必须登录并向 AWS Glue 授予所请求的权限，以便访问其 Google Sheets 实例。
用户可以选择在 Google Sheets 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Google Sheets，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
有关为授权码 OAuth 流创建关联应用程序的公共 Google Sheets 文档，请参阅[创建访问凭据](https://developers.google.com/workspace/guides/create-credentials)。
# 从 Google Sheets 实体读取内容
**先决条件**
+ 要从中读取内容的 Google 电子表格。需要电子表格的 SpreadSheet ID 和 tabName。
**Google Sheets 实体和字段详细信息：**
| 实体 | 数据类型 | 支持的运算符 |
| --- | --- | --- |
| 电子表格 | 字符串 | N/A（不支持筛选） |
**示例**
```
googleSheets_read = glueContext.create_dynamic_frame.from_options(
connection_type="googlesheets",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "{SpreadSheetID}#{SheetTabName}",
"API_VERSION": "v4"
}
```
**对查询进行分区**
仅对于基于记录的分区，如果想在 Spark 中利用并发性，可以将 `NUM_PARTITIONS` 作为附加 Spark 选项。使用此参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
**使用 `NUM_PARTITIONS` 的示例**
```
googlesheets_read = glueContext.create_dynamic_frame.from_options(
connection_type="googlesheets",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "{SpreadSheetID}#{SheetTabName}",
"API_VERSION": "v4",
"NUM_PARTITIONS": "10"
}
```
# Google Sheets 连接选项
Google Sheets 的连接选项如下：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Google Sheets 中的 `SpreadSheet ID` 和 `sheetTabName`。示例：`{SpreadSheetID}#{SheetTabName}`。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Google Sheets Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# 为 Google Sheets 设置授权码 OAuth 流
**先决条件**
+ 您可以在登录后使用 Google Sheets 应用程序的 Google 账户。在您的 Google 账户中，Google Sheets 已包含要传输的数据。
+ 一个 Google Cloud Platform 账户和 Google Cloud 项目。有关更多详细信息，请参阅 [Create Google Cloud Project](https://developers.google.com/workspace/guides/create-project)。
**要设置 Google 账户并获取 OAuth 2.0 凭证，请按以下步骤操作：**
1. 设置好 Google Cloud 项目后，在该项目中启用 Google Sheets API 和 Google Drive API。有关启用步骤，请参阅 Google Cloud Platform 的 API Console 帮助中的 [Enable and disable APIs](https://support.google.com/googleapi/answer/6158841)。
1. 然后为外部用户配置 OAuth 同意屏幕。有关 OAuth 同意屏幕的更多信息，请参阅 Google Cloud Platform Console 帮助中心中的 [Setting up your OAuth consent screen](https://support.google.com/cloud/answer/10311615#)。
1. 在 OAuth 同意屏幕中，添加以下范围：
+ [Google Sheets API 只读范围](https://www.googleapis.com/auth/spreadsheets.readonly)
+ [Google Drive API 只读范围](ttps://www.googleapis.com/auth/drive.readonly)
有关这些范围的更多信息，请参阅 Google Identity 文档中的 [OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes)。
1. 生成 OAuth 2.0 客户端 ID 和密钥。有关创建此客户端 ID 的步骤，请参阅 Google Cloud Platform Console 帮助中的 [Setting up OAuth 2.0](https://support.google.com/cloud/answer/6158849?hl=en#zippy=)。
OAuth 2.0 客户端 ID 必须有一个或多个经过授权的重定向 URL。
重定向 URL 采用以下格式：
+ https://.console.aws.amazon.com/gluestudio/oauth
1. 记下 OAuth 2.0 客户端 ID 设置中的客户端 ID 和客户端密钥。
# Google Sheets 连接器的限制
以下是 Google Sheets 连接器的限制：
+ Google Sheets 连接器不支持筛选条件。因此，不支持基于筛选条件的分区。
+ 在基于记录的分区中，未要求按 SAAS 返回确切的记录数。因此，在某些情况下，可能会创建记录为空的文件。
+ 由于 Google Sheets 连接器不支持基于筛选条件的分区，`partitionField`、`lowerbound` 和 `upperbound` 不是有效的连接选项。如果提供了这些选项，预计 AWS Glue 作业会失败。
+ 必须将工作表的第一行指定为标题行，以避免出现数据处理问题。
+ 如果未提供，则工作表包含第一行为空的数据时将标题行替换为 `Unnamed:1`、`Unnamed:2`、`Unnamed:3`...。
+ 如果提供了标题行，则空列名将替换为 `Unnamed:`。例如，如果标题行为 `['ColumnName1', 'ColumnName2', '', '', 'ColumnName5', 'ColumnName6']`，它将变为 `['ColumnName1', 'ColumnName2', 'Unnamed:3', 'Unnamed:4', 'ColumnName5', 'ColumnName6'].`
+ Google Sheets 连接器不支持增量传输。
+ Google Sheets 连接器仅支持字符串数据类型。
+ 工作表中的重复标题将使用数字后缀迭代重命名。重命名重复的标题时，用户提供的标题名称将优先。例如，如果标题行是 ["Name", "", "Name", null, "Unnamed:6", ""]，它将更改为：["Name", "Unnamed:2", "Name1", "Unnamed:4", "Unnamed:6", "Unnamed:61"]。
+ Google Sheets 连接器不支持 tabName 中的空格。
+ 文件夹名称不能包含下面的特殊字符：
+ \$1
+ /
# 连接到 HubSpot
HubSpot 的 CRM 平台提供了营销、销售、内容管理和客户服务所需的各种工具和集成。
+ Marketing Hub：一种营销软件，可帮助您增加流量，转化更多访客，并大规模进行全面的集客营销活动。
+ Sales Hub：一种销售 CRM 软件，可帮助您更深入地了解潜在客户，自动完成各种任务，更快地促成更多交易。
+ Service Hub：一种客户服务软件，可帮助您与客户沟通互动，超越客户预期，并将客户变为您业务增长的推动者。
+ Operations Hub：一种运营软件，可同步您的各种应用程序，清理和创建客户数据，自动化执行相关流程，从而让您的各种系统和团队能够更好地协同工作。
**Topics**
+ [AWS Glue 支持 HubSpot](hubspot-support.md)
+ [包含创建和使用连接的 API 操作的策略](hubspot-configuring-iam-permissions.md)
+ [配置 HubSpot](hubspot-configuring.md)
+ [配置 HubSpot 连接](hubspot-configuring-connections.md)
+ [从 HubSpot 实体中读取](hubspot-reading-from-entities.md)
+ [写入 HubSpot 实体](hubspot-writing-to-entities.md)
+ [HubSpot 连接选项](hubspot-connection-options.md)
+ [HubSpot 连接器的限制和说明](hubspot-connector-limitations.md)
# AWS Glue 支持 HubSpot
AWS Glue 对 HubSpot 的支持如下：
**是否支持作为来源？**
是，支持同步和异步。可以使用 AWS Glue ETL 作业查询 HubSpot 中的数据。
**是否支持作为目标？**
是。您可以使用 AWS Glue ETL 作业将数据写入 HubSpot。
**支持的 HubSpot API 版本**
支持以下 HubSpot API 版本：
+ v1
+ v2
+ v3
+ v4
有关每个版本的相应实体支持，请参阅[同步源支持的实体](hubspot-reading-from-entities.md#sync-table)与[异步源支持的实体](hubspot-reading-from-entities.md#async-table)。
# 包含创建和使用连接的 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 控制台的用户。
# 配置 HubSpot
必须满足以下要求，才能使用 AWS Glue 从 HubSpot 传输数据：
## 最低要求
以下是最低要求：
+ 有 HubSpot 账户。有关更多信息，请参阅 [创建 HubSpot 账户](#hubspot-configuring-creating-hubspot-account)。
+ HubSpot 账户已启用 API 访问权限。
+ 在 HubSpot 开发者账户下有应用程序，提供 AWS Glue 在对账户进行经身份验证的调用时用于安全访问数据的客户端凭证。有关更多信息，请参阅 [创建 HubSpot 开发者应用程序](#hubspot-configuring-creating-hubspot-developer-app)。
如果满足这些要求，就可以将 AWS Glue 连接到 HubSpot 账户。对于常见连接，无需在 HubSpot 中执行其他操作。
## 创建 HubSpot 账户
要创建 HubSpot 账户：
1. 前往 [HubSpot CRM 注册网址](https://app.hubspot.com/login)。
1. 输入电子邮件地址，选择**验证电子邮件**（也可以选择使用 Google、Microsoft 或 Apple 账户登录）。
1. 在收件箱中查看来自 HubSpot 的验证码。
1. 输入 6 位数的验证码，点击**下一步**。
1. 输入密码，点击**下一步**。
1. 输入名字和姓氏，点击**下一步**；或者通过**使用 Google 登录**链接登录。
1. 输入行业，点击**下一步**。
1. 输入职位，点击**下一步**。
1. 输入公司名称，点击**下一步**。
1. 选择公司规模（员工人数），点击**下一步**。
1. 进入公司网站，点击**下一步**。
1. 选择数据托管地点（美国或欧洲），点击**创建账户**。
1. 选择创建账户的目的，点击**下一步**。
1. 选择**关联 Google 账户**或选择自行添加联系人，将联系人与 HubSpot 账户关联起来。
1. 如果选择**关联 Google 账户**选项来关联联系人并开始使用 HubSpot 账户，则请登录 Google 账户。
## 创建 HubSpot 开发者应用程序
应用程序开发者账户用于创建和管理应用程序、集成及开发者测试账户。您也可以在其中创建和管理 App Marketplace 上架信息。不过，应用程序开发者账户及其关联的测试账户并未关联到标准的 HubSpot 账户。这些账户无法与另一个 HubSpot 账户同步彼此的数据或资产。要获取客户端 ID 和客户端密钥，必须创建一个开发者账户。
1. 前往 https://developers.hubspot.com/
1. 选择**创建开发者账户**，再向下滚动。
1. 系统会询问是要创建应用程序开发者账户、私人应用程序账户还是 CMS 开发者沙盒账户。选择**创建应用程序开发者账户**。
1. 由于您已经创建了一个 HubSpot 账户，您可以选择**继续使用此用户**。
1. 点击**开始注册**。
1. 输入职位，点击**下一步**。
1. 为开发者账户命名，点击**下一步**，再点击**跳过**。
1. 选择 **Create App (创建应用程序)**。
1. 创建应用程序后，选择**身份验证**。
1. 记下身份验证下的客户端 ID 和 客户端密钥。
1. 添加所在地区特定的**重定向 URL**：https:*//*.console.aws.amazon.com/gluestudio/oauth。例如，如果是 us-east-1 区域，则添加 https://us-east-1.console.aws.amazon.com/gluestudio/oauth。
1. 向下滚动，找到作用域。必须在“CRM”和“标准”标题下选择两种类型的作用域。
1. 添加以下作用域：
```
content
automation
oauth
crm.objects.owners.read
forms
tickets
crm.objects.contacts.write
e-commerce
crm.schemas.custom.read
crm.objects.custom.read
sales-email-read
crm.objects.custom.write
crm.objects.companies.write
crm.lists.write
crm.objects.companies.read
crm.lists.read
crm.objects.deals.read
crm.objects.deals.write
crm.objects.contacts.read
```
1. 点击**保存**，开发者账户现在就可以使用了。
1. 向上滚动，找到**客户端 ID**。
1. 在同一页面上，点击**显示**，获取**客户端密钥**。
## 创建 HubSpot 开发者测试账户
在应用程序开发者账户中，可以创建开发者测试账户来测试应用程序和集成，这不会对任何真实的 HubSpot 数据造成影响。开发者测试账户不能镜像生产账户，但可以使用营销、销售、服务、CMS 和运营中心企业版的 90 天试用版，这样可以测试大多数 HubSpot 工具和 API。
1. 点击**主页**。
1. 点击**创建测试账户**。
1. 点击**创建应用程序测试账户**。
1. 此时会显示一个新窗口。输入应用程序测试账户名称，点击**创建**。
此时，应用程序测试账户就创建好了。
**注意**
开发者账户用于 API 集成等开发活动，应用程序测试账户用于查看开发者账户创建或拉取的数据。
# 配置 HubSpot 连接
HubSpot 支持 OAuth2 的 AUTHORIZATION\$1CODE 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。用户要创建连接，则需为 HubSpot 客户端应用程序提供与 OAuth 相关的信息，例如客户端 ID 和客户端密钥。AWS Glue 控制台会将用户重定向到 HubSpot，用户必须登录并向 AWS Glue 授予所请求的权限，以便访问其 HubSpot 实例。
+ 用户仍然可以选择在 HubSpot 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 HubSpot，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 HubSpot 公共文档，请参阅 [Public apps](https://developers.hubspot.com/docs/api/creating-an-app)。
要配置 HubSpot 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的消费者密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 HubSpot。
1. 提供 HubSpot 环境。
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` 的权限。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 HubSpot 实体中读取
**先决条件**
您要从中读取内容的 HubSpot 对象。您将需要联系人或任务等对象名称。下表显示了同步源支持的实体。
## 同步源支持的实体
| 实体 | API 版本 | 可以筛选 | 支持限制 | 支持排序依据 | 支持选择\$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- | --- |
| 市场活动 | v1 | 否 | 是 | 否 | 是 | 否 |
| 公司 | v3 | 支持 | 是 | 是 | 是 | 是 |
| 联系人 | v3 | 支持 | 是 | 是 | 是 | 是 |
| 联系人列表 | v1 | 否 | 是 | 否 | 是 | 否 |
| 交易 | v3 | 支持 | 是 | 是 | 是 | 是 |
| CRM 管道（交易管道） | v1 | 否 | 否 | 否 | 是 | 否 |
| 电子邮件事件 | v1 | 否 | 是 | 否 | 是 | 否 |
| Calls | v3 | 支持 | 是 | 是 | 是 | 是 |
| 备注 | v3 | 支持 | 是 | 是 | 是 | 是 |
| 电子邮件 | v3 | 支持 | 是 | 是 | 是 | 是 |
| 会议 | v3 | 支持 | 是 | 是 | 是 | 是 |
| 任务 | v3 | 支持 | 是 | 是 | 是 | 是 |
| 邮政邮件 | v3 | 支持 | 是 | 是 | 是 | 是 |
| 自定义对象 | v3 | 支持 | 是 | 是 | 是 | 是 |
| 表单 | v2 | 否 | 否 | 否 | 是 | 否 |
| 所有者 | v3 | 否 | 是 | 否 | 是 | 否 |
| 产品 | v3 | 支持 | 是 | 是 | 是 | 是 |
| 工单 | v3 | 支持 | 是 | 是 | 是 | 是 |
| 工作流 | v3 | 否 | 否 | 否 | 是 | 否 |
| Associations | v4 | 是 | 否 | 否 | 是 | 否 |
| 关联标签 | v4 | 否 | 否 | 否 | 是 | 否 |
**示例：**
```
hubspot_read = glueContext.create_dynamic_frame.from_options(
connection_type="hubspot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "contact",
"API_VERSION": "v3"
}
```
## 异步源支持的实体
| 实体 | API 版本 | 可以筛选 | 支持限制 | 支持排序依据 | 支持选择\$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- | --- |
| 公司 | v3 | 是 | 否 | 是 | 是 | 否 |
| 联系人 | v3 | 是 | 否 | 是 | 是 | 否 |
| 交易 | v3 | 是 | 否 | 是 | 是 | 否 |
| Calls | v3 | 是 | 否 | 是 | 是 | 否 |
| 备注 | v3 | 是 | 否 | 是 | 是 | 否 |
| 电子邮件 | v3 | 是 | 否 | 是 | 是 | 否 |
| 会议 | v3 | 是 | 否 | 是 | 是 | 否 |
| 任务 | v3 | 是 | 否 | 是 | 是 | 否 |
| 邮政邮件 | v3 | 是 | 否 | 是 | 是 | 否 |
| 自定义对象 | v3 | 是 | 否 | 是 | 是 | 否 |
| 产品 | v3 | 是 | 否 | 是 | 是 | 否 |
| 工单 | v3 | 是 | 否 | 是 | 是 | 否 |
**示例：**
```
hubspot_read = glueContext.create_dynamic_frame.from_options(
connection_type="hubspot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "contact",
"API_VERSION": "v3",
"TRANSFER_MODE": "ASYNC"
}
```
**HubSpot 实体和字段详细信息**：
**HubSpot API v4**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/hubspot-reading-from-entities.html)
**注意**
对于 `Associations` 对象，要获取两个对象之间的关联，您需要在创建 AWS Glue 作业时通过强制筛选器提供“from Id”（第一个对象的 ID）。在这种情况下，如果要获取多个 from ID 的关联，则必须在 `where` 子句中提供多个 ID。例如：要获取联系人 ID“1”和“151”的 `Associations`，您需要提供筛选器 `where id=1 AND id=151`。
**HubSpot API v3**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/hubspot-reading-from-entities.html)
对于以下实体，HubSpot 提供用于动态获取元数据的端点，以便在每个实体的数据类型级别捕获运算符支持。
**注意**
`DML_STATUS` 是在运行时添加到每条记录上的虚拟字段，用于在同步模式下确定字段状态（CREATED/UPDATED）。异步模式下不支持 `CONTAINS/LIKE` 运算符。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/hubspot-reading-from-entities.html)
**HubSpot API v2**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/hubspot-reading-from-entities.html)
**HubSpot API v1**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/hubspot-reading-from-entities.html)
## 对查询进行分区
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于日期时间字段，我们接受 ISO 格式的值。
有效值示例：
```
“2024-01-01T10:00:00.115Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
下表描述实体分区字段支持详细信息：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/hubspot-reading-from-entities.html)
示例：
```
hubspot_read = glueContext.create_dynamic_frame.from_options(
connection_type="hubspot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "company",
"API_VERSION": "v3",
"PARTITION_FIELD": "hs_object_id"
"LOWER_BOUND": "50"
"UPPER_BOUND": "16726619290"
"NUM_PARTITIONS": "10"
}
```
# 写入 HubSpot 实体
## 先决条件
+ 您要写入的 HubSpot 对象。您将需要联系人或工单等对象名称。
+ HubSpot 连接器支持以下写入操作：
+ INSERT
+ UPDATE
+ 使用 `UPDATE` 写入操作时，必须提供 `ID_FIELD_NAMES` 选项以指定记录的 ID 字段。
## Sync 目标支持的实体
| 实体 | API 版本 | 是否支持作为目的地连接器 | 是否可以插入 | 是否可以更新 |
| --- | --- | --- | --- | --- |
| 公司 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 联系人 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 交易 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 产品 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| Calls | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 会议 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 备注 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 电子邮件 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 任务 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 邮政邮件 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 自定义对象 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 工单 | v3 | 是 | 是（单条、批量） | 是（单条、批量） |
| 关联 | v4 | 是 | 是（单条、批量） | 否 |
| 关联标签 | v4 | 是 | 是（单条、批量） | 是（单条、批量） |
**示例：**
**INSERT 操作**
```
hubspot_write = glueContext.write_dynamic_frame.from_options(
frame=frameToWrite,
connection_type="hubspot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "contact",
"API_VERSION": "v3",
"WRITE_OPERATION": "INSERT"
}
)
```
**UPDATE 操作**
```
hubspot_write = glueContext.write_dynamic_frame.from_options(
frame=frameToWrite,
connection_type="hubspot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "deal",
"API_VERSION": "v3",
"WRITE_OPERATION": "UPDATE",
"ID_FIELD_NAMES": "hs_object_id"
}
)
```
# HubSpot 连接选项
以下是 HubSpot 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。HubSpot 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 HubSpot Rest API 版本。例如：v1、v2、v3、v4。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `TRANSFER_MODE`（字符串）– 用于指示是否应在异步模式下运行查询。
+ `WRITE_OPERATION`（字符串）– 默认：INSERT。用于写入。值应为 INSERT 或 UPDATE。
+ `ID_FIELD_NAMES`（字符串）– 默认：null。UPDATE 操作所必须。
# HubSpot 连接器的限制和说明
以下是 HubSpot 连接器的限制或说明：
+ 对于任何给定查询，搜索端点的结果总数限制为 1 万条。任何包含超过 1 万条记录的分区都会导致 400 错误。
+ [限制](https://developers.hubspot.com/docs/api/crm/search#limitations)中描述了连接器的其他重要限制。
+ HubSpot 最多接受三个筛选语句。
+ 目前，HubSpot 支持标准 HubSpot 对象（例如联系人、公司、交易或工单）与自定义对象之间的关联。
+ 对于免费账户：在每个对象配对（例如联系人和公司）之间，最多只能创建 10 种关联类型。
+ 对于超级管理员账户：每个对象配对之间最多只能创建 50 种关联类型。
+ 有关更多信息，请参阅 [Associations v4](https://developers.hubspot.com/docs/api/crm/) 和 [Create and use association labels](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels)。
+ “报价”和“通信”对象目前不支持关联，因为连接器中暂不支持这些对象。
+ 对于异步模式，SaaS 仅按升序对值进行排序。
+ 对于 `Ticket` 实体，SaaS 不会在异步模式下返回 `hs_object_id` 字段。
# 连接到 Instagram Ads
Instagram 是一款流行的照片分享应用程序，可让您与品牌、名人、思想领袖、朋友、家人等建立联系。它是一项照片分享和社交网络服务。用户可以拍摄照片或短视频，并与其关注者分享。Instagram 广告是企业可以付费向 Instagram 用户投放的帖子。
**Topics**
+ [AWS Glue 对 Instagram Ads 的支持](instagram-ads-support.md)
+ [包含创建和使用连接的 API 操作的策略](instagram-ads-configuring-iam-permissions.md)
+ [配置 Instagram Ads](instagram-ads-configuring.md)
+ [配置 Instagram Ads 连接](instagram-ads-configuring-connections.md)
+ [从 Instagram Ads 实体中读取](instagram-ads-reading-from-entities.md)
+ [Instagram Ads 连接选项](instagram-ads-connection-options.md)
+ [Instagram Ads 连接器的限制和说明](instagram-ads-connector-limitations.md)
# AWS Glue 对 Instagram Ads 的支持
AWS Glue 对 Instagram Ads 的支持如下：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业查询 Instagram Ads 中的数据。
**是否支持作为目标？**
否。
**支持的 Instagram Ads API 版本**
支持以下 Instagram Ads API 版本：
+ v17.0
+ v18.0
+ v19.0
+ v20.0
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Instagram Ads
您必须满足以下要求，才能使用 AWS Glue 从 Instagram Ads 传输数据：
## 最低要求
以下是最低要求：
+ 可通过 Facebook 间接访问 Instagram 标准账户。
+ 需要进行用户身份验证才能生成访问令牌。
+ Instagram Ads SDK 连接器将实现*用户访问令牌 OAuth* 流程。
+ 我们使用 OAuth2.0 对 Instagram Ads 的 API 请求进行身份验证。这种基于 Web 的身份验证属于多重身份验证（MFA）架构，是 2FA 的超集。
+ 用户需要授予访问端点的权限。为了访问用户的数据，端点授权是通过[权限](https://developers.facebook.com/docs/permissions)和[功能](https://developers.facebook.com/docs/features-reference)来处理的。
## 获取 OAuth 2.0 凭证
要获取 API 凭证以便可对实例进行经过身份验证的调用，请参阅 [Graph API](https://developers.facebook.com/docs/graph-api/)。
# 配置 Instagram Ads 连接
Instagram Ads 支持 OAuth2 的 AUTHIZATION\$1CODE 授权类型。
+ 此授权类型被视为三足型 OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。
+ 用户可以选择在 Instagram Ads 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Instagram Ads，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成访问令牌。即将到期的系统用户令牌自生成或刷新之日起 60 天内有效。为保持连续性，开发者应在 60 天内刷新访问令牌。否则访问令牌将失效，并且需要开发者获取新访问令牌才能重新获得 API 访问权限。请参阅 [Refresh Access Token](https://developers.facebook.com/docs/marketing-api/system-users/install-apps-and-generate-tokens/)。
要配置 Instagram Ads 连接：
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Instagram Ads。
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. 提供用户托管客户端应用程序的客户端 ID。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。所选密钥需要有一个键 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`，其值为关联应用程序的客户端密钥。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Instagram Ads 实体中读取
**先决条件**
您要从中读取内容的 Instagram Ads 对象。您将需要对象名称。下表显示支持的实体。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 活动 | 支持 | 是 | 否 | 是 | 是 |
| 广告集 | 支持 | 是 | 否 | 是 | 是 |
| 广告 | 支持 | 是 | 否 | 是 | 是 |
| 广告创意 | 否 | 是 | 否 | 是 | 否 |
| 洞察 – 账户 | 否 | 是 | 否 | 是 | 否 |
| 广告图片 | 支持 | 是 | 否 | 是 | 否 |
| 洞察 – 广告 | 支持 | 是 | 否 | 是 | 是 |
| 洞察 – 广告组 | 支持 | 是 | 否 | 是 | 是 |
| 洞察 – 活动 | 支持 | 是 | 否 | 是 | 是 |
**示例：**
```
instagramAds_read = glueContext.create_dynamic_frame.from_options(
connection_type="instagramads",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v20.0"
}
```
## Instagram Ads 实体和字段详细信息
有关实体和字段详细信息的更多信息，请参阅：
+ [活动](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group)
+ [广告集](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign)
+ [广告](https://developers.facebook.com/docs/marketing-api/reference/adgroup)
+ [广告创意](https://developers.facebook.com/docs/marketing-api/reference/ad-creative)
+ [广告账户洞察](https://developers.facebook.com/docs/marketing-api/reference/ad-account/insights)
+ [广告图片](https://developers.facebook.com/docs/marketing-api/reference/ad-image)
+ [广告洞察](https://developers.facebook.com/docs/marketing-api/reference/adgroup/insights/)
+ [广告组洞察](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign/insights)
+ [活动洞察](https://developers.facebook.com/docs/marketing-api/reference/ad-campaign-group/insights)
有关更多信息，请参阅 [Marketing API](https://developers.facebook.com/docs/marketing-api/reference/v21.0)。
**注意**
在连接器的响应中，结构和列表数据类型将转换为字符串数据类型。
## 对查询进行分区
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于日期时间字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"2022-01-01T00:00:00.000Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
有效值示例：
```
"2024-01-02T00:00:00.000Z"
```
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
instagramADs_read = glueContext.create_dynamic_frame.from_options(
connection_type="instagramads",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v20.0",
"PARTITION_FIELD": "created_time"
"LOWER_BOUND": "2022-01-01T00:00:00.000Z"
"UPPER_BOUND": "2024-01-02T00:00:00.000Z"
"NUM_PARTITIONS": "10"
}
```
# Instagram Ads 连接选项
以下是 Instagram Ads 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Instagram Ads 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。您想要使用的 Instagram Ads Graph API 版本。例如：v21。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）：用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）：用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）：用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# Instagram Ads 连接器的限制和说明
以下是 Instagram Ads 连接器的限制或说明：
+ 应用程序的调用次数是用户在滚动的一小时窗口内可以调用次数 200 乘以用户数。有关速率限制的详细信息，请参阅 [Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/) 和 [Business Use Case Rate Limits](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#buc-rate-limits)。
# 在 AWS Glue Studio 中连接到 Intercom
Intercom 是一种互动操作系统，它是您的企业与客户之间的开放式渠道，可（在产品中、在当下、按照客户的要求）创建持续的对话，使您能够充分利用客户旅程中的每一次互动。
**Topics**
+ [AWS Glue 对 Intercom 的支持](intercom-support.md)
+ [包含创建和使用连接的 API 操作的策略](intercom-configuring-iam-permissions.md)
+ [配置 Intercom](intercom-configuring.md)
+ [配置 Intercom 连接](intercom-configuring-connections.md)
+ [从 Intercom 实体中读取](intercom-reading-from-entities.md)
+ [Intercom 连接选项](intercom-connection-options.md)
+ [限制](intercom-limitations.md)
+ [创建新的 Intercom 账户并配置客户端应用程序](intercom-new-account-creation.md)
# AWS Glue 对 Intercom 的支持
AWS Glue 对 Intercom 的支持如下：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业查询 Intercom 中的数据。
**是否支持作为目标？**
否。
**支持的 Intercom API 版本**
v2.5。有关每个版本特定的实体支持，请参阅[从 Intercom 实体中读取](intercom-reading-from-entities.md)。
# 包含创建和使用连接的 API 操作的策略
以下示例策略描述了创建和使用连接所需的 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、Amazon 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 控制台的用户。
# 配置 Intercom
您必须满足以下要求，才能使用 AWS Glue 从 Intercom 传输：
## 最低要求
+ 您有一个 Intercom 账户。有关更多信息，请参阅 [创建新的 Intercom 账户并配置客户端应用程序](intercom-new-account-creation.md)。
+ 您的 Intercom 账户已启用 API 访问权限。
+ 您应该在 Intercom 开发者账户下创建一个应用程序，提供 AWS Glue 在对您的账户进行身份验证调用时用于安全访问数据的客户端凭证。有关更多信息，请参阅“Intercom - 新账户和客户端应用程序创建步骤”。
如果您满足这些要求，就可以将 AWS Glue 连接到您的 Intercom 账户。
# 配置 Intercom 连接
Intercom 支持 OAuth 2 的 `AUTHORIZATION_CODE` 授权类型。
此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Google Ads，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Intercom 实例。
用户在通过 AWS Glue 控制台创建连接时，应提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Intercom，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
有关为授权码 OAuth 流程创建关联应用程序的更多信息，请参阅 [Ads API](https://developers.intercom.com/building-apps/docs/setting-up-oauth)。
要配置 Intercom 连接：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。
1. 对于客户托管的关联应用程序：密钥应包含关联应用程序的访问令牌、刷新令牌、client\$1id 和 client\$1secret。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Intercom。
1. 提供 Intercom 环境。
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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Intercom 实体中读取
**先决条件**
+ 您要从中读取内容的 Intercom 对象。请参阅下方支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | API\$1Version | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- | --- |
| Admins | v2.5 | 否 | 否 | 否 | 是 | 否 |
| 公司 | v2.5 | 否 | 是 | 否 | 是 | 否 |
| 对话 | v2.5 | 支持 | 是 | 是 | 是 | 是 |
| 数据属性 | v2.5 | 否 | 否 | 否 | 是 | 否 |
| 联系人 | v2.5 | 支持 | 是 | 是 | 是 | 是 |
| Segments | v2.5 | 否 | 否 | 否 | 是 | 否 |
| 标签 | v2.5 | 否 | 否 | 否 | 是 | 否 |
| 团队 | v2.5 | 否 | 否 | 否 | 是 | 否 |
**示例**
```
Intercom_read = glueContext.create_dynamic_frame.from_options(
connection_type="Intercom",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "company",
"API_VERSION": "V2.5"
}
)
```
**Intercom 实体和字段详细信息**
| 实体 | 字段 | 数据类型 | 支持的运算符 |
| --- | --- | --- | --- |
| Admins | type | 字符串 | NA |
| Admins | id | 字符串 | NA |
| Admins | avatar | 结构体 | NA |
| Admins | 名称 | 字符串 | NA |
| Admins | 电子邮件 | 字符串 | NA |
| Admins | away\$1mode\$1enabled | 布尔值 | NA |
| Admins | away\$1mode\$1reassign | 布尔值 | NA |
| Admins | has\$1inbox\$1seat | 布尔值 | NA |
| Admins | teams\$1ids | 列表 | NA |
| Admins | job\$1title | 字符串 | NA |
| 公司 | type | 字符串 | NA |
| 公司 | id | 字符串 | NA |
| 公司 | app\$1id | 字符串 | NA |
| 公司 | created\$1at | 日期时间 | NA |
| 公司 | remote\$1created\$1at | 日期时间 | NA |
| 公司 | updated\$1at | 日期时间 | NA |
| 公司 | last\$1request\$1at | 日期时间 | NA |
| 公司 | 计划 | 结构体 | NA |
| 公司 | company\$1id | 字符串 | NA |
| 公司 | 名称 | 字符串 | NA |
| 公司 | custom\$1attributes | 结构体 | NA |
| 公司 | session\$1count | 整数 | NA |
| 公司 | monthly\$1spend | 整数 | NA |
| 公司 | user\$1count | 整数 | NA |
| 公司 | industry | 字符串 | NA |
| 公司 | size | 整数 | NA |
| 公司 | 网站 | 字符串 | NA |
| 公司 | tags | 结构体 | NA |
| 公司 | segments | 结构体 | NA |
| 联系人 | id | 字符串 | EQUAL\$1TO.NOT\$1EQUAL\$1TO |
| 联系人 | type | 字符串 | NA |
| 联系人 | workspace\$1id | 字符串 | NA |
| 联系人 | external\$1id | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | 角色 | 字符串 | EQUAL\$1TO.NOT\$1EQUAL\$1TO |
| 联系人 | 电子邮件 | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | phone | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | 名称 | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | avatar | 字符串 | NA |
| 联系人 | owner\$1id | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 联系人 | social\$1profiles | 结构体 | NA |
| 联系人 | has\$1hard\$1bounced | 布尔值 | EQUAL\$1TO |
| 联系人 | marked\$1email\$1as\$1spam | 布尔值 | EQUAL\$1TO |
| 联系人 | unsubscribed\$1from\$1emails | 布尔值 | EQUAL\$1TO |
| 联系人 | created\$1at | 日期时间 | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 联系人 | updated\$1at | 日期时间 | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 联系人 | signed\$1up\$1at | 日期时间 | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 联系人 | last\$1seen\$1at | 日期时间 | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 联系人 | last\$1replied\$1at | 日期时间 | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 联系人 | last\$1contacted\$1at | 日期时间 | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 联系人 | last\$1email\$1opened\$1at | 日期时间 | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 联系人 | last\$1email\$1clicked\$1at | 日期时间 | EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 联系人 | language\$1override | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | 浏览器 | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | browser\$1version | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | browser\$1language | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | os | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | location | 结构体 | NA |
| 联系人 | location\$1country | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | location\$1region | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | location\$1city | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | android\$1app\$1name | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | android\$1app\$1version | 字符串 | NA |
| 联系人 | android\$1device | 字符串 | NA |
| 联系人 | android\$1os\$1version | 字符串 | NA |
| 联系人 | android\$1sdk\$1version | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | android\$1last\$1seen\$1at | 日期 | NA |
| 联系人 | ios\$1app\$1name | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | ios\$1app\$1version | 字符串 | NA |
| 联系人 | ios\$1device | 字符串 | NA |
| 联系人 | ios\$1os\$1version | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | ios\$1sdk\$1version | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 联系人 | ios\$1last\$1seen\$1at | 日期时间 | NA |
| 联系人 | custom\$1attributes | 结构体 | NA |
| 联系人 | tags | 结构体 | NA |
| 联系人 | notes | 结构体 | NA |
| 联系人 | companies | 结构体 | NA |
| 联系人 | unsubscribed\$1from\$1sms | 布尔值 | NA |
| 联系人 | sms\$1consent | 布尔值 | NA |
| 联系人 | opted\$1out\$1subscription\$1types | 结构体 | NA |
| 联系人 | referrer | 字符串 | NA |
| 联系人 | utm\$1campaign | 字符串 | NA |
| 联系人 | utm\$1content | 字符串 | NA |
| 联系人 | utm\$1medium | 字符串 | NA |
| 联系人 | utm\$1source | 字符串 | NA |
| 联系人 | utm\$1term | 字符串 | NA |
| 对话 | type | 字符串 | NA |
| 对话 | id | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | created\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | updated\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | 源 | 结构体 | NA |
| 对话 | source\$1id | 字符串 | EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | source\$1type | 字符串 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, |
| 对话 | source\$1delivered\$1as | 字符串 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, |
| 对话 | source\$1subject | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | source\$1body | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | source\$1author\$1id | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | source\$1author\$1type | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | source\$1author\$1name | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | source\$1author\$1email | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | source\$1url | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | 联系人 | 结构体 | NA |
| 对话 | teammates | 结构体 | NA |
| 对话 | 删除实例快照 | 字符串 | NA |
| 对话 | admin\$1assignee\$1id | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | team\$1assignee\$1id | 整数 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | custom\$1attributes | 结构体 | NA |
| 对话 | 打开 | 布尔值 | EQUAL\$1TO |
| 对话 | 状态 | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | read | 布尔值 | EQUAL\$1TO |
| 对话 | waiting\$1since | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | snoozed\$1until | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | tags | 结构体 | NA |
| 对话 | first\$1contact\$1reply | 结构体 | NA |
| 对话 | priority | 字符串 | EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | topics | 结构体 | NA |
| 对话 | sla\$1applied | 结构体 | NA |
| 对话 | conversation\$1rating | 结构体 | NA |
| 对话 | conversation\$1rating\$1requested\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | conversation\$1rating\$1replied\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | conversation\$1rating\$1score | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | conversation\$1rating\$1remark | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | conversation\$1rating\$1contact\$1id | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | conversation\$1rating\$1admin\$1id | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | statistics | 结构体 | NA |
| 对话 | statistics\$1time\$1to\$1assignment | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1time\$1to\$1admin\$1reply | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1time\$1to\$1first\$1close | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1time\$1to\$1last\$1close | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1median\$1time\$1to\$1reply | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1first\$1contact\$1reply\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1first\$1assignment\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1first\$1admin\$1reply\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1first\$1close\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1last\$1assignment\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1last\$1assignment\$1admin\$1reply\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1last\$1contact\$1reply\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1last\$1admin\$1reply\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1last\$1close\$1at | 日期时间 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1last\$1closed\$1by\$1id | 字符串 | CONTAINS, EQUAL\$1TO, NOT\$1EQUAL\$1TO |
| 对话 | statistics\$1count\$1reopens | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1count\$1assignments | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | statistics\$1count\$1conversation\$1parts | 整数 | EQUAL\$1TO, NOT\$1EQUAL\$1TO, GREATER\$1THAN, LESS\$1THAN |
| 对话 | conversation\$1parts | 列表 | NA |
| 数据属性 | id | 整数 | NA |
| 数据属性 | type | 字符串 | NA |
| 数据属性 | 模型 | 字符串 | NA |
| 数据属性 | 名称 | 字符串 | NA |
| 数据属性 | full\$1name | 字符串 | NA |
| 数据属性 | label | 字符串 | NA |
| 数据属性 | description | 字符串 | NA |
| 数据属性 | data\$1type | 字符串 | NA |
| 数据属性 | options | 列表 | NA |
| 数据属性 | api\$1writable | 布尔值 | NA |
| 数据属性 | ui\$1writable | 布尔值 | NA |
| 数据属性 | 自定义 | 布尔值 | NA |
| 数据属性 | archived | 布尔值 | NA |
| 数据属性 | created\$1at | 布尔值 | NA |
| 数据属性 | updated\$1at | 日期时间 | NA |
| 数据属性 | admin\$1id | 字符串 | NA |
| Segments | type | 字符串 | NA |
| Segments | id | 字符串 | NA |
| Segments | 名称 | 字符串 | NA |
| Segments | created\$1at | 日期时间 | NA |
| Segments | updated\$1at | 日期时间 | NA |
| Segments | person\$1type | 字符串 | NA |
| Segments | count | 整数 | NA |
| 标签 | type | 字符串 | NA |
| 标签 | id | 字符串 | NA |
| 标签 | 名称 | 字符串 | NA |
| 团队 | type | 字符串 | NA |
| 团队 | id | 字符串 | NA |
| 团队 | 名称 | 字符串 | NA |
| 团队 | admin\$1ids | 列表 | NA |
**对查询进行分区**
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-02-06"`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
基于实体的分区字段支持详细信息如下表中所示。
| 实体名称 | 分区字段 | 数据类型 |
| --- | --- | --- |
| 联系人 | created\$1at, updated\$1at,last\$1seen\$1at | 日期时间 |
| 对话 | id | 整数 |
| 对话 | created\$1at, updated\$1at | 日期时间 |
**示例**
```
Intercom_read = glueContext.create_dynamic_frame.from_options(
connection_type="Intercom",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "conversation",
"API_VERSION": "V2.5",
"PARTITION_FIELD": "created_at"
"LOWER_BOUND": "2022-07-13T07:55:27.065Z"
"UPPER_BOUND": "2022-08-12T07:55:27.065Z"
"NUM_PARTITIONS": "2"
}
)
```
# Intercom 连接选项
以下是 Intercom 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Intercom 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。您想要使用的 Intercom Rest API 版本。示例：v2.5。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（字符串）：用户要在其中运行操作的实例的 URL。例如：[https://api.intercom.io](https://api.intercom.io)。
# 限制
以下是 Intercom 连接器的限制：
+ 使用公司实体时，可返回的公司数量上限为 10000 家。如需了解更多信息，请参阅 [List all companies API](https://developers.intercom.com/docs/references/2.5/rest-api/companies/list-companies)。
+ 在应用排序依据时，**联系人**和**对话**实体都必须进行筛选。
+ MCA 由 SaaS 提供商提供支持。但是，根据文档中提到的 API 速率限制，我们不会在 AWS Glue 上托管 MCA，因为其可能会影响其他工作负载，并可能因资源争用而导致性能问题。
# 创建新的 Intercom 账户并配置客户端应用程序
**创建 Intercom 账户**
1. 选择 [Intercom URL](https://app.intercom.com/)，然后选择页面右上角的**开始我的免费试用**。
1. 选择页面右上角的**免费试用按钮**。
1. 选择所需的企业类型。
1. 输入页面上所需的所有信息。
1. 输入所有信息后，选择**注册**。
**创建 Intercom 开发者应用程序**
要获取**客户端 ID** 和**客户端密钥**，您需要创建一个开发者账户。
1. 导航到 [https://app.intercom.com/](https://app.intercom.com/)。
1. 输入电子邮件 ID 和密码/使用 Google 登录，然后登录。
1. 选择左下角的**用户个人资料**，然后选择设置。
1. 选择**应用程序和集成**。
1. 选择**应用程序和集成**下的**开发者中心**选项卡。
1. 选择**新应用程序**，然后在此处创建应用程序。
1. 提供应用程序名称，然后选择**创建**应用程序。
1. 在应用程序中，导航到**身份验证**部分。
1. 选择**编辑**并添加重定向 URI。将您的区域特定重定向 URL 添加为 `https://.console.aws.amazon.com/gluestudio/oauth`。例如，添加 `https://us-east-1.console.aws.amazon.com/gluestudio/oauth for the us-east-1 region`。
1. 在基本信息部分获取生成的**客户端 ID** 和**客户端密钥**。
# 连接到 Jira Cloud
Jira Cloud 是一个由 Atlassian 开发的平台，提供了有助于团队规划和跟踪其敏捷项目的问题追踪产品。作为 Jira Cloud 用户，您的账户包含有关您项目的各种数据，例如问题、工作流和事件等。可以使用 AWS Glue 将 Jira Cloud 数据传输到某些 AWS 服务或其他受支持的应用程序。
**Topics**
+ [AWS Glue 对 Jira Cloud 的支持](jira-cloud-support.md)
+ [包含创建和使用连接的 API 操作的策略](jira-cloud-configuring-iam-permissions.md)
+ [配置 Jira Cloud](jira-cloud-configuring.md)
+ [配置 Jira Cloud 连接](jira-cloud-configuring-connections.md)
+ [从 Jira Cloud 实体中读取](jira-cloud-reading-from-entities.md)
+ [Jira Cloud 连接选项](jira-cloud-connection-options.md)
+ [Jira Cloud 连接器的限制和说明](jira-cloud-connector-limitations.md)
# AWS Glue 对 Jira Cloud 的支持
AWS Glue 对 Jira Cloud 的支持如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Jira Cloud 中的数据。
**是否支持作为目标？**
否。
**支持的 Jira Cloud API 版本**
支持以下 Jira Cloud API 版本：
+ v3
有关每个版本特定的实体支持，请参阅[从 Jira Cloud 实体中读取](jira-cloud-reading-from-entities.md)。
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Jira Cloud
您必须满足以下要求，才能使用 AWS Glue 将数据从 Jira Cloud 传输到支持的目标：
## 最低要求
以下是最低要求：
+ 您拥有一个 Atlassian 账户，以便在 Jira Cloud 中使用 Jira 软件产品。有关更多信息，请参阅 [创建 Jira Cloud 账户](#jira-cloud-configuring-creating-jira-cloud-account)。
+ 必须创建一个拥有 AWS Glue 服务访问权限的 AWS 账户。
+ 此应用程序提供 AWS Glue 在对账户进行身份验证调用时，用于安全访问数据的客户端凭证。有关更多信息，请参阅 Atlassian 开发者文档中的 [Enabling OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#enabling-oauth-2-0--3lo-)。
如果满足这些要求，就可以将 AWS Glue 连接到 Jira Cloud 账户。
## 创建 Jira Cloud 账户
要创建 Jira Cloud 账户，请按以下步骤操作：
1. 导航到 [Atlassian 注册 URL](https://id.atlassian.com/signup)。
1. 输入您的工作电子邮件地址和姓名，然后选择**同意**。您会收到一封验证电子邮件。
1. 验证您的电子邮件地址后，您可以创建密码，然后选择**注册**。
1. 输入您的用户名和密码，然后选择**注册**。
1. 随后您将被重定向到需要输入您的网站信息的页面。输入网站名称，然后选择**同意**。
Atlassian Cloud 网站启动后，您可以根据自己的项目类型偏好回答几个问题来设置 Jira。
登录到现有账户
1. 导航到 [Atlassian 登录 URL](https://id.atlassian.com/login) 并输入凭证。
1. 输入电子邮件地址和密码，然后单击**登录**。这时您将被重定向到 Jira 控制面板。
## 在 Jira Cloud 中创建应用程序
要在 Jira Cloud 中创建应用程序并从托管式客户端应用程序获取客户端 ID 和客户端密钥，请按以下步骤操作：
1. 导航到 [Jira Cloud URL](https://id.atlassian.com/login) 并输入凭证。
1. 选择**创建**并选择 **OAuth 2.0 集成**选项。
1. 输入应用程序名称，勾选 **T&C**，然后选择**创建**。
1. 导航到左侧菜单中的**分发**部分，然后选择**编辑**。
1. 在**编辑分发控制**部分：
1. 对于**分发状态**请选择**共享**。
1. 输入供应商名称。
1. 输入您的**隐私政策** URL。例如，https://docs.aws.amazon.com/glue/latest/dg/security-iam-awsmanpol.html
1. 输入您的**服务条款** URL（可选）。
1. 输入您的**客户支持联系人** URL（可选）。
1. 在**个人数据声明**中选择“是/否”，然后选择**保存更改**。
1. 导航到左侧菜单中相关应用程序的**权限**。
1. 对于 **Jira API**，请选择**添加**。添加后，选择**配置**选项。
1. 在**经典范围** > **Jira 平台 REST API** 部分下，选择**编辑范围**。然后选中所有范围。单击**保存**。
1. 在**粒度范围**下，选择**编辑范围**，然后选择以下范围：
1. 向下滚动，找到作用域。必须在“CRM”和“标准”标题下选择两种类型的作用域。
1. 添加以下作用域：
```
read:application-role:jira
read:audit-log:jira
read:avatar:jira
read:field:jira
read:group:jira
read:instance-configuration:jira
read:issue-details:jira
read:issue-event:jira
read:issue-link-type:jira
read:issue-meta:jira
read:issue-security-level:jira
read:issue-security-scheme:jira
read:issue-type-scheme:jira
read:issue-type-screen-scheme:jira
read:issue-type:jira
read:issue.time-tracking:jira
read:label:jira
read:notification-scheme:jira
read:permission:jira
read:priority:jira
read:project:jira
read:project-category:jira
read:project-role:jira
read:project-type:jira
read:project-version:jira
read:project.component:jir
read:project.property:jira
read:resolution:jira
read:screen:jira
read:status:jira
read:user:jira
read:workflow-scheme:jira
read:workflow:jira
read:field-configuration:jira
read:issue-type-hierarchy:jira
read:webhook:jira
```
1. 导航到左侧菜单中的**身份验证**，然后选择**添加**。
1. 输入**回调 URL**，比如 https://us-east-1.console.aws.amazon.com/gluestudio/oauth
1. 导航到左侧菜单中的**设置**，然后向下滚动查看**身份验证**详细信息。记下客户端 ID 和密钥。
# 配置 Jira Cloud 连接
Jira Cloud 支持 OAuth2 的 AUTHIZATION\$1CODE 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Jira Cloud，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Jira Cloud 实例。
+ 用户仍然可以选择在 Jira Cloud 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Jira Cloud，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 Jira Cloud 公共文档，请参阅 [Enabling OAuth 2.0 (3LO)](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/#enabling-oauth-2-0--3lo-)。
要配置 Jira Cloud 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的消费者密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Jira Cloud。
1. 提供 Jira Cloud 环境。
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` 的权限。
# 从 Jira Cloud 实体中读取
**先决条件**：。
您要从中读取内容的 Jira Cloud 对象。您将需要审计记录或问题等对象名称。下表显示支持的实体。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 审计记录 | 支持 | 是 | 否 | 是 | 是 |
| 问题 | 支持 | 是 | 否 | 是 | 是 |
| 问题字段 | 否 | 否 | 否 | 是 | 否 |
| 问题字段配置 | 支持 | 是 | 否 | 是 | 是 |
| 问题链接类型 | 否 | 否 | 否 | 是 | 否 |
| 问题通知方案 | 支持 | 是 | 否 | 是 | 是 |
| 问题安全方案 | 否 | 否 | 否 | 是 | 否 |
| 问题类型方案 | 支持 | 是 | 是 | 是 | 是 |
| 问题类型屏幕方案 | 支持 | 是 | 是 | 是 | 是 |
| 问题类型 | 否 | 否 | 否 | 是 | 否 |
| Jira 设置 | 是 | 否 | 否 | 是 | 否 |
| Jira 设置高级 | 否 | 否 | 否 | 是 | 否 |
| Jira 设置全局 | 否 | 否 | 否 | 是 | 否 |
| 标签 | 否 | 否 | 否 | 是 | 是 |
| 我自己 | 是 | 否 | 否 | 是 | 否 |
| 权限 | 否 | 否 | 否 | 是 | 否。 |
| 项目 | 支持 | 是 | 是 | 是 | 是 |
| 项目类别 | 否 | 否 | 否 | 是 | 否 |
| 项目类型 | 否 | 否 | 否 | 是 | 否 |
| 服务器信息 | 否 | 否 | 否 | 是 | 否 |
| 用户 | 否 | 否 | 否。 | 是 | 否 |
| 工作流 | 支持 | 是 | 是 | 是 | 是 |
| 工作流方案 | 否 | 是 | 否 | 是 | 是 |
| 工作流方案项目关联 | 是 | 否 | 否 | 是 | 否 |
| 工作流状态 | 否 | 否 | 否 | 是 | 否 |
| 工作流状态类别 | 否 | 否 | 否 | 是 | 否 |
**示例**：
```
jiracloud_read = glueContext.create_dynamic_frame.from_options(
connection_type="JiraCloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "audit-record",
"API_VERSION": "v3"
}
```
**Jira Cloud 实体和字段详细信息**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/jira-cloud-reading-from-entities.html)
## 对查询进行分区
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `NUM_PARTITIONS`。使用此参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
jiraCloud_read = glueContext.create_dynamic_frame.from_options(
connection_type="JiraCloud",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "issue",
"API_VERSION": "v3",
"NUM_PARTITIONS": "10"
}
```
# Jira Cloud 连接选项
Jira Cloud 的连接选项如下：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Jira Cloud 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Jira Cloud Rest API 版本。例如：v3。
+ `DOMAIN_URL`（字符串）：（必需）要使用的 Jira Cloud ID。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# Jira Cloud 连接器的限制和说明
Jira Cloud 连接器的限制或说明如下：
+ `Contains` 运算符不适用于 `resourceName` 字段，后者属于 `String` 数据类型。
+ 默认情况下，如果未应用显式筛选条件，则只会爬取过去 30 天内的问题。用户可以选择通过指定自定义筛选条件来覆盖此默认筛选条件。
# 连接到 Kustomer
Kustomer 是一个强大的客户体验平台，也是一款易于使用的工具，汇集了为客户提供更好服务所需的一切。
**Topics**
+ [AWS Glue 对 Kustomer 的支持](kustomer-support.md)
+ [包含创建和使用连接的 API 操作的策略](kustomer-configuring-iam-permissions.md)
+ [配置 Kustomer](kustomer-configuring.md)
+ [配置 Kustomer 连接](kustomer-configuring-connections.md)
+ [从 Kustomer 实体读取内容](kustomer-reading-from-entities.md)
+ [Kustomer 连接选项](kustomer-connection-options.md)
+ [Kustomer 限制](kustomer-connection-limitations.md)
# AWS Glue 对 Kustomer 的支持
AWS Glue 对 Kustomer 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Kustomer 中的数据。
**是否支持作为目标？**
否。
**支持的 Kustomer API 版本**
支持以下 Kustomer 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 控制台的用户。
# 配置 Kustomer
必须满足以下要求，才能使用 AWS Glue 将数据从 Kustomer 传输到支持的目标：
## 最低要求
以下是最低要求：
+ 拥有 Kustomer 账户，其中包含要传输的数据。
+ 在账户设置中创建了一个 API 密钥。有关更多信息，请参阅 [创建 API 密钥](#kustomer-configuring-creating-an-api-key)。
+ 在创建连接时向 AWS Glue 提供 API 密钥。
如果满足这些要求，就可以将 AWS Glue 连接到 Kustomer 账户。
## 创建 API 密钥
要创建用于在 AWS Glue Studio 中为 Kustomer 连接器创建连接的 API 密钥，请执行以下操作：
1. 使用凭证[登录 Kustomer 控制面板](https://amazon-appflow.kustomerapp.com/login)。
1. 在左侧菜单中选择**设置**图标。
1. 展开**安全**下拉列表并选择 **API 密钥**。
1. 在 API 密钥创建页面中，选择右上角的**添加 API 密钥**。
1. 填写创建 API 密钥所需的必填项。
+ 名称：API 密钥的任何名称。
+ 角色：必须选择“org”，Kustomer API 才能正常运行。
+ 有效期（天）：希望 API 密钥有效的天数。如果该密钥适合用例，可将其设置为**永不过期**。
1. 选择**创建**。
1. 存储 API 密钥（令牌）值以备将来使用，以便在 AWS Glue Studio 中为 Kustomer 连接器创建连接。
# 配置 Kustomer 连接
要配置 Kustomer 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户托管的关联应用程序，密钥应包含关联应用程序的使用者密钥，且以 `apiKey` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在**连接**下，选择**创建连接**。
1. 选择**数据来源**时，请选择 Kustomer。
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` 的权限。
# 从 Kustomer 实体读取内容
**先决条件**
要从中读取内容的 Kustomer 对象。需要 Brands 或 Cards 等对象名称。下表显示支持的实体。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| Brands | 否 | 是 | 否 | 是 | 否 |
| Cards | 否 | 是 | 否 | 是 | 否 |
| Chat Settings | 否 | 否 | 否 | 是 | 否 |
| 公司 | 支持 | 是 | 是 | 是 | 是 |
| 对话 | 支持 | 是 | 是 | 是 | 是 |
| Customers | 支持 | 是 | 是 | 是 | 是 |
| Customer Searches Pinned | 否 | 是 | 否 | 是 | 否 |
| Customer Searches Position | 否 | 否 | 否 | 是 | 否 |
| Email Hooks | 否 | 是 | 否 | 是 | 否 |
| Web Hooks | 否 | 是 | 否 | 是 | 否 |
| KB Articles | 否 | 是 | 否 | 是 | 否 |
| KB Categories | 否 | 是 | 否 | 是 | 否 |
| KB Forms | 否 | 是 | 否 | 是 | 否 |
| KB Routes | 否 | 是 | 否 | 是 | 否 |
| KB Tags | 否 | 是 | 否 | 是 | 否 |
| KB Templates | 否 | 是 | 否 | 是 | 否 |
| KB Themes | 否 | 是 | 否 | 是 | 否 |
| Klasses | 否 | 是 | 否 | 是 | 否 |
| kViews | 否 | 是 | 否 | 是 | 否 |
| 消息 | 支持 | 是 | 是 | 是 | 是 |
| 备注 | 支持 | 是 | 是 | 是 | 是 |
| 通知 | 否 | 是 | 否 | 是 | 否 |
**示例：**
```
Kustomer_read = glueContext.create_dynamic_frame.from_options(
connection_type="kustomer",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "brands",
"API_VERSION": "v1"
}
```
## Kustomer 实体和字段详细信息
有关实体和字段详细信息的更多信息，请参阅：
+ [Brands](https://api.kustomerapp.com/v1/brands)
+ [Cards](https://api.kustomerapp.com/v1/cards)
+ [Chat Settings](https://api.kustomerapp.com/v1/chat/settings)
+ [Companies](https://api.kustomerapp.com/v1/companies)
+ [Conversations](https://api.kustomerapp.com/v1/conversations)
+ [Customers](https://api.kustomerapp.com/v1/customers)
+ [Customers Searches Pinned](https://api.kustomerapp.com/v1/customers/searches/pinned)
+ [Customer Searches Positions](https://api.kustomerapp.com/v1/customers/searches/positions)
+ [Hooks Email](https://api.kustomerapp.com/v1/hooks/email)
+ [Hooks Web](https://api.kustomerapp.com/v1/hooks/web)
+ [KB Articles](https://api.kustomerapp.com/v1/kb/articles)
+ [KB Categories](https://api.kustomerapp.com/v1/kb/categories)
+ [KB Forms]( https://api.kustomerapp.com/v1/kb/forms)
+ [KB Routes](https://api.kustomerapp.com/v1/kb/routes)
+ [KB Tags](https://api.kustomerapp.com/v1/kb/tags)
+ [KB Templates](https://api.kustomerapp.com/v1/kb/templates)
+ [KB Themes](https://api.kustomerapp.com/v1/kb/themes)
+ [Klasses](https://api.kustomerapp.com/v1/klasses)
+ [Kviews](https://api.kustomerapp.com/v1/kviews)
+ [ 消息](https://api.kustomerapp.com/v1/messages)
+ [备注](https://api.kustomerapp.com/v1/notes)
+ [通知](https://api.kustomerapp.com/v1/notifications)
Kustomer API v1
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/kustomer-reading-from-entities.html)
## 对查询进行分区
**基于字段的分区**
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于日期时间字段，我们接受 ISO 格式的值。
有效值示例：
```
"2023-01-15T11:18:39.205Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
基于实体的分区字段支持详细信息如下表中所示：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/kustomer-reading-from-entities.html)
示例：
```
Kustomer_read = glueContext.create_dynamic_frame.from_options(
connection_type="kustomer",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "conversation",
"API_VERSION": "v1",
"PARTITION_FIELD": "createdAt"
"LOWER_BOUND": "2023-01-15T11:18:39.205Z"
"UPPER_BOUND": "2023-02-15T11:18:39.205Z"
"NUM_PARTITIONS": "2"
}
```
# Kustomer 连接选项
以下是 Kustomer 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Kustomer 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Kustomer Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）：用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）：用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）：用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（字符串）：（必填）用于读取。Kustomer 实例 URL。
# Kustomer 限制
以下是 Kustomer 的限制或说明：
+ 由于 Kustomer API 文档尚未为 `Customer Searches` 实体声明任何端点，因此不支持该实体。
+ 不支持对 `Klasses` 实体进行筛选和增量传输。
+ 在单个请求中，支持对多个适用字段应用排序依据。
然而，据观察，对于某些组合，多个字段的排序依据功能在 SaaS 端表现不一致。这是不可预测的，因为可能存在“n”种组合，因而会显示错误的排序结果。例如：
对于 `Customers` 实体，按 `progressiveStatus desc, name asc` 排序无法产生正确的排序结果。只会根据 `progressiveStatus` 依据进行排序。如果出现这种情况，可对单个字段进行排序。
+ 只有 `Conversations` 和 `Messages` 实体支持将字段“id”作为查询参数进行排序。例如：https://api.kustomerapp.com/v1/conversations?sort=desc（将根据“id”对结果降序排序。）
此外，任何其他筛选条件或对任何其他字段的排序都会转换为 POST 请求正文，对应的 API 端点为 POST https://api.kustomerapp.com/v1/customers/search。若要支持在 `Conversations` 和 `Messages` 中按“id”排序，则只能按 id 排序，或者对任何其他适用字段应用任何其他筛选条件和/或排序。
+ 无论请求是经过筛选还是未经过筛选，Kustomer 允许获取最多 1 万条记录。由于此限制，任何持有超过 1 万条记录的实体都会存在数据丢失。您可以采取两种可能的解决方法来部分改善这种情况：
+ 应用筛选条件，获取一组特定的记录。
+ 如果应用筛选条件的记录超过 1 万条，请在后续新请求中继续应用筛选条件值或在筛选条件中指定范围。例如：
第一个请求的 filterExpression：`modifiedAt >= 2022-03-15T05:26:23.000Z and modifiedAt < 2023-03-15T05:26:23.000Z`
假设其已达到 1 万条记录限制。
可用 filterExpression `modifiedAt >= 2023-03-15T05:26:23.000Z` 触发另一个请求
+ 基于 SaaS 行为，Kustomer 中的 `CONTAINS` 运算符仅支持匹配完整的单词，而不支持对单词中的部分内容进行匹配。例如：“body CONTAINS 'test record'”将匹配“body”字段中包含“test”的记录。但是，“body CONTAINS 'test'”不会匹配“body”字段中含有“testAnotherRecord”的记录。
# 连接到 LinkedIn
LinkedIn 是一种付费营销工具，支持通过各种赞助帖子和其他方式访问 LinkedIn 社交网络。LinkedIn 是一款强大的营销工具，可供 B2B 公司吸引潜在客户、进行在线识别、共享内容等。
**Topics**
+ [AWS Glue 支持 LinkedIn](linkedin-support.md)
+ [包含创建和使用连接的 API 操作的策略](linkedin-configuring-iam-permissions.md)
+ [配置 LinkedIn](linkedin-configuring.md)
+ [配置 LinkedIn 连接](linkedin-configuring-connections.md)
+ [从 LinkedIn 实体读取内容](linkedin-reading-from-entities.md)
+ [LinkedIn 连接选项](linkedin-connection-options.md)
+ [创建 LinkedIn 账户](linkedin-create-account.md)
+ [限制](linkedin-connector-limitations.md)
# AWS Glue 支持 LinkedIn
AWS Glue 对 LinkedIn 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 LinkedIn 中的数据。
**是否支持作为目标？**
否。
**支持的 LinkedIn API 版本**
**202406（2024 年 6 月）**
# 包含创建和使用连接的 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 控制台的用户。
# 配置 LinkedIn
必须满足以下要求，才能使用 AWS Glue 从 LinkedIn 传输数据：
## 最低要求
+ 拥有一个 LinkedIn 账户。有关创建账户的更多信息，请参阅[创建 LinkedIn 账户](linkedin-create-account.md)。
+ LinkedIn 账户已启用 API 访问权限。
+ 已在 LinkedIn 账户中创建了 `OAuth2 API` 集成。此集成提供 AWS Glue 在对账户进行身份验证调用时，用于安全访问数据的客户端凭证。有关更多信息，请参阅 [创建 LinkedIn 账户](linkedin-create-account.md)。
如果满足这些要求，就可以将 AWS Glue 连接到 LinkedIn 账户。对于常见连接，无需在 LinkedIn 中执行其他操作。
# 配置 LinkedIn 连接
LinkedIn 支持 OAuth2 的 `AUTHORIZATION_CODE` 授权类型。
此授权类型被视为“三足型”`OAuth`，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。用户可以选择在 LinkedIn 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 LinkedIn，以便登录并授权 AWS Glue 访问其资源。
此授权类型会同时生成刷新令牌和访问令牌。访问令牌在创建 60 天后过期。可以使用刷新令牌获取新的访问令牌。
有关为 `Authorization Code OAuth` 流创建关联应用程序的 LinkedIn 公共文档，请参阅 [Authorization Code Flow (3-legged OAuth)](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?toc=%2Flinkedin%2Fmarketing%2Ftoc.json&bc=%2Flinkedin%2Fbreadcrumb%2Ftoc.json&view=li-lms-2024-07&tabs=HTTPS1)。
**配置 LinkedIn 连接**
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
+ 对于 AWS 托管式关联应用程序：密钥可以为空或具有某个临时值。
**注意**
必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 **LinkedIn**。
1. 提供 LinkedIn 环境。
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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择**网络选项**。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 LinkedIn 实体读取内容
**先决条件**
要从中读取内容的 LinkedIn 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 广告账户 | 支持 | 是 | 是 | 是 | 否 |
| 市场活动 | 支持 | 是 | 是 | 是 | 否 |
| 活动组 | 支持 | 是 | 是 | 是 | 否 |
| 素材 | 支持 | 是 | 是 | 是 | 否 |
| Ad Analytics | 是 | 否 | 否 | 是 | 否 |
| Ad Analytics 所有广告账户 | 是 | 否 | 否 | 是 | 否 |
| Ad Analytics 所有活动 | 是 | 否 | 否 | 是 | 否 |
| Ad Analytics 所有活动组 | 是 | 否 | 否 | 是 | 否 |
| Ad Analytics 所有广告素材 | 是 | 否 | 否 | 是 | 否 |
| 共享统计数据 | 是 | 否 | 否 | 是 | 否 |
| 页面统计数据 | 是 | 否 | 否 | 是 | 否 |
| 粉丝统计数据 | 是 | 否 | 否 | 是 | 否 |
**示例**
```
netsuiteerp_read = glueContext.create_dynamic_frame.from_options(
connection_type="linkedin",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "adaccounts",
"API_VERSION": "202406"
}
)
```
**LinkedIn 实体和字段详细信息**
| **字段数据类型** | **支持的筛选运算符** |
| --- | --- |
| 字符串 | = |
| 日期时间 | BETWEEN、= |
| 数值 | = |
| 布尔值 | = |
# LinkedIn 连接选项
以下是 LinkedIn 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取/写入。LinkedIne 中对象的名称。例如，adAccounts。
+ `API_VERSION`（字符串）：（必填）用于读取/写入。要使用的 LinkedIn Rest API 版本。该值将为 202406，因为 LinkedIn 目前仅支持版本 202406。
+ `SELECTED_FIELDS`（列表<字符串>）– 默认：empty(SELECT \$1)。用于读取。要为所选实体选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# 创建 LinkedIn 账户
**创建 LinkedIn 应用程序和 OAuth 凭证**
1. 导航到 **LinkedIn 开发人员网络**页面，然后使用 LinkedIn 账户凭证登录。
1. 导航到**我的应用程序**页面，然后选择**创建应用程序**，创建新的 LinkedIn 应用程序。
1. 在应用程序注册表中输入以下详细信息：
+ **公司名称**：选择现有公司或创建新公司。
+ **名称**：输入应用程序名称。
+ **描述**：输入应用程序描述。
+ **应用程序徽标**：选择图像文件作为应用程序徽标。
+ **应用程序用途**：选择应用程序的用途。
+ **网站 URL**：输入包含应用程序详细信息的网站 URL。
+ **企业电子邮件**：输入企业电子邮件地址。
+ **企业电话**：输入企业电话号码。
+ **LinkedIn API 使用条款**：阅读并同意。
1. 填写好应用程序注册表后，选择**提交**。
系统会重定向到**身份验证**页面，此页面会显示身份验证密钥（客户端 ID 和客户端密钥）和其他相关详细信息。
1. 如果 Web 应用程序需要从用户的 LinkedIn 账户访问用户的电子邮件地址，请选择 `r_emailaddress` 权限。此外，可以为 LinkedIn 应用程序指定已授权的重定向 URL。
**在 LinkedIn 账户中创建页面**
1. 导航到 [LinkedIn 开发人员产品](https://developer.linkedin.com/)。
1. 在 **LinkedIn 开发人员产品**页面的右上角，选择**我的应用程序**。
1. 在**我的应用程序**页面的右上角，选择**创建应用程序**。
1. 在**创建应用程序**页面上的**应用程序名称**字段中，输入应用程序名称。
1. 在 **LinkedIn 页面**字段中，输入公司页面名称或 URL。
**注意**
如果没有 LinkedIn 页面，可以选择**创建新的 LinkedIn** 来创建一个页面。
1. 在**隐私政策 URL** 字段中，输入隐私政策 URL。
1. 选择**上传徽标**，上传一张用户授权使用应用程序时会显示的图片。
1. 在**法律协议**部分，选择**我已阅读并同意这些条款**。
1. 选择**创建应用程序**。
随即会创建新应用程序并显示在**我的应用程序**选项卡下。
**在 LinkedIn 上发布活动广告**
1. 登录**营销管理工具**。
1. 选择现有**活动组**，或选择**创建**来创建新的活动组。
1. 选择目标。
1. 选择活动组、预算和时间表。
1. 建立目标受众。
1. 选择广告格式。
1. 选择预算和时间表。
1. 设置广告。
1. 审核和启动。
# 限制
对于 Analytics 字段 `ad_analytics_all_adAccounts`、`ad_analytics_all_campaigns`、`ad_analytics_all_campaign_groups` 和 `ad_analytics_all_adCreatives`，必须使用筛选条件才能检索记录。
# 连接到 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`
# 连接到 Microsoft Dynamics 365 CRM
Microsoft Dynamics 365 是一系列企业资源规划和客户关系管理智能业务应用程序产品。
**Topics**
+ [AWS Glue 对 Microsoft Dynamics 365 的支持](microsoft-dynamics-365-support.md)
+ [包含创建和使用连接的 API 操作的策略](microsoft-dynamics-365-configuring-iam-permissions.md)
+ [配置 Microsoft Dynamics 365 CRM](microsoft-dynamics-365-configuring.md)
+ [配置 Microsoft Dynamics 365 CRM 连接](microsoft-dynamics-365-configuring-connections.md)
+ [从 Microsoft Dynamics 365 CRM 实体读取](microsoft-dynamics-365-reading-from-entities.md)
+ [Microsoft Dynamics 365 CRM 连接选项参考](microsoft-dynamics-365-connection-options.md)
+ [限制](microsoft-dynamics-365-connector-limitations.md)
# AWS Glue 对 Microsoft Dynamics 365 的支持
AWS Glue 支持 Microsoft Dynamics 365，如下所示：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Microsoft Dynamics 365 中的数据。
**是否支持作为目标？**
否。
**支持的 Microsoft Dynamics 365 CRM API 版本**
v9.2。
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Microsoft Dynamics 365 CRM
必须满足以下要求，才能使用 AWS Glue 从 Microsoft Dynamics 365 CRM 传输数据：
## 最低要求
+ 您有一个带有 ClientId 和密钥的 Microsoft Dynamics 365 CRM 开发人员账户。
+ 您的 Microsoft Dynamics 365 CRM 账户拥有 API 访问权限及有效的许可证。
如果满足这些要求，就可以将 AWS Glue 连接到 Microsoft Dynamics 365 CRM 账户。对于常见连接，无需在 Microsoft Dynamics 365 CRM 中执行任何其他操作。
# 配置 Microsoft Dynamics 365 CRM 连接
**AUTHORIZATION\$1CODE 授权类型**
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Microsoft Dynamics 365 CRM，用户必须在此登录并向 AWS Glue 授予所请求的权限，以访问其 Microsoft Dynamics 365 CRM 实例。
+ 用户可以选择在 Microsoft Dynamics 365 CRM 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Microsoft Dynamics 365 CRM，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 Microsoft Dynamics 365 CRM 公共文档，请参阅 \$1 Microsoft Learn。[Microsoft 应用程序注册](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/authenticate-oauth#app-registration)。
Microsoft Dynamics 365 CRM 支持 OAuth2.0 身份验证。
配置 Microsoft Dynamics 365 CRM 连接：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。
+ 对于 AuthorizationCode 授权类型：
对于客户托管的关联应用程序：密钥应包含关联应用程序的客户端密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**数据来源**时，请选择 Microsoft Dynamics 365 CRM。
1. 选择想要连接到的 Microsoft Dynamics 365 CRM 实例的 **INSTANCE\$1URL** 。
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. 选择**令牌 URL** 和**授权码 URL** 以访问您的 Microsoft Dynamics 365 CRM 工作区。
1. 提供 Microsoft Dynamics 365 CRM 应用程序的**用户托管客户端应用程序 ClientId**。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。选择**下一步**。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 Microsoft Dynamics 365 CRM 实体读取
**先决条件**
+ 要从中读取内容的 Microsoft Dynamics 365 CRM 对象。您将需要联系人或账户等对象名称。下表显示支持的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 动态实体 | 支持 | 是 | 是 | 是 | 是 |
**示例**
```
dynamics365_read = glueContext.create_dynamic_frame.from_options(
connection_type="microsoftdynamics365crm",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "dynamic_entity",
"API_VERSION": "v9.2",
"INSTANCE_URL": "https://{tenantID}.api.crm.dynamics.com"
}
```
## Microsoft Dynamics 365 CRM 实体和字段详细信息
**具有动态元数据的实体**：
Microsoft Dynamics 365 CRM 提供用于动态获取元数据的端点。因此，对于动态实体，可在数据类型级别捕获运算符支持。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/microsoft-dynamics-365-reading-from-entities.html)
**对查询进行分区**
Microsoft Dynamics 365 CRM 仅支持基于字段的分区。
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期时间，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。有效值示例：`"2024-01-30T06:47:51.000Z"`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
基于实体的分区字段支持详细信息如下表中所示：
| 实体名称 | 分区字段 | DataType |
| --- | --- | --- |
| 动态实体（标准实体） | 可查询的动态日期时间字段 | createdon、modifiedon |
| 动态实体（自定义实体） | createdon、modifiedon | createdon、modifiedon |
**示例**
```
dynamics365_read = glueContext.create_dynamic_frame.from_options(
connection_type="microsoftdynamics365crm",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "dynamic_entity",
"API_VERSION": "v9.2",
"instanceUrl": "https://{tenantID}.api.crm.dynamics.com"
"PARTITION_FIELD": "createdon"
"LOWER_BOUND": "2024-01-30T06:47:51.000Z"
"UPPER_BOUND": "2024-06-30T06:47:51.000Z"
"NUM_PARTITIONS": "10"
}
```
# Microsoft Dynamics 365 CRM 连接选项参考
以下是 Microsoft Dynamics 365 CRM 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Microsoft Dynamics 365 CRM 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Microsoft Dynamics 365 CRM Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `INSTANCE_URL`（字符串）：（必填）有效的 Microsoft Dynamics 365 CRM 实例 URL，格式为：`https://{tenantID}.api.crm.dynamics.com`
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。示例：`2024-01-30T06:47:51.000Z`。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。示例：`2024-06-30T06:47:51.000Z`。
# 限制
以下是 Microsoft Dynamics 365 CRM 连接器的限制：
+ Microsoft Dynamics 365 CRM 中不支持基于记录的分区，因为其不支持偏移参数，因此无法支持基于记录的分区。
+ 分页设置为每页最多 500 条记录，以避免 SaaS 因数据大小和速率限制组合而导致内部服务器异常。
+ [关于分页的 SaaS 文档](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/webapi/query/page-results?view=dataverse-latest)
+ [关于速率限制的 SaaS 文档](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/api-limits?tabs=sdk)
+ Microsoft Dynamics 365 CRM 仅对所有实体的父字段支持 `order by`。子字段不支持 `order by`。
+ ASC 和 DESC 方向排序均支持。
+ 对多个字段支持 `order by`。
+ 对 `aadusers` 标准实体的“createddatetime”字段进行筛选会引发来自 SaaS 的不正确的请求错误，尽管该字段支持筛选。由于元数据的动态性质，尚无特定证据显示任何其他实体存在类似问题，也无法确定根本原因。因此，无法处理该问题。
+ Struct、List 和 Map 等复杂对象类型不支持筛选。
+ 在动态元数据响应中，许多可以从响应中检索的字段都将 `isRetrievable` 标记为 `false`。为避免数据丢失，所有字段的 `isRetrievable` 均设置为 `true`。
+ 如果满足以下标准，则所有实体均支持基于字段的分区：
+ 标准实体中应包含日期时间可查询字段，或者自定义实体中应包含 `createdon` 和 `modifiedon`（系统生成）字段。
+ 任何 SaaS 元数据 API 都没有系统生成字段的专属标识或可为空属性，但通用的做法是：只有默认提供的字段方可筛选且不可为空。因此，上述字段选择标准被视为空值安全，如果其可筛选，则符合分区的条件。
# 连接到 Microsoft Teams
Microsoft Teams 是 Microsoft 365 中的协作工作空间，也是工作场所对话、协作团队合作、视频聊天和文档共享的中枢，旨在通过一套统一的工具来提高员工的工作效率。
**Topics**
+ [AWS Glue 对 Microsoft Teams 的支持](microsoft-teams-support.md)
+ [包含创建和使用连接的 API 操作的策略](microsoft-teams-configuring-iam-permissions.md)
+ [配置 Microsoft Teams](microsoft-teams-configuring.md)
+ [配置 Microsoft Teams 连接](microsoft-teams-configuring-connections.md)
+ [从 Microsoft Teams 实体读取内容](microsoft-teams-reading-from-entities.md)
+ [Microsoft Teams 连接选项参考](microsoft-teams-connection-options.md)
+ [限制](microsoft-teams-connector-limitations.md)
+ [创建新的 Microsoft Teams 账户：](#microsoft-teams-account-creation)
# AWS Glue 对 Microsoft Teams 的支持
AWS Glue 对 Microsoft Teams 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Microsoft Teams 中的数据。
**是否支持作为目标？**
否。
**支持的 Microsoft Teams 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 控制台的用户。
# 配置 Microsoft Teams
必须满足以下要求，才能使用 AWS Glue 从 Microsoft Teams 传输数据：
## 最低要求
+ 拥有 Microsoft Teams 开发人员账户，其中包含电子邮件和密码。有关更多信息，请参阅 [创建新的 Microsoft Teams 账户：](connecting-to-microsoft-teams.md#microsoft-teams-account-creation)。
+ 需要在 Microsoft 账户下创建一个 OAuth2 应用程序，提供 AWS Glue 在对账户进行身份验证调用时用于安全访问数据的客户端 ID 和密钥凭证。有关更多信息，请参阅 [创建新的 Microsoft Teams 账户：](connecting-to-microsoft-teams.md#microsoft-teams-account-creation)。
如果满足这些要求，就可以将 AWS Glue 连接到 Microsoft Teams 账户。对于常见连接，无需在 Microsoft Teams 中执行其他操作。
# 配置 Microsoft Teams 连接
Microsoft Teams 支持以下两种类型的身份验证机制：
1. OAuth 身份验证：Microsoft Teams 支持 OAuth2 的 AUTHORIZATION\$1CODE 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。默认情况下，创建连接的用户可以依赖于 AWS Glue 拥有的关联应用程序；在该应用程序中，除了 Microsoft Teams 实例 URL 之外，用户无需提供任何与 OAuth 相关的信息。AWS Glue 控制台会将用户重定向到 Microsoft Teams，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Microsoft Teams 实例。
+ 用户可以选择在 Microsoft Teams 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Microsoft Teams，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期为一小时，可以通过刷新令牌在不需要用户互动的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 Microsoft Teams 公共文档，请参阅 \$1 Microsoft Learn。[Register an application with the Microsoft identity platform - Microsoft Graph](https://learn.microsoft.com/en-us/graph/auth-register-app-v2)。
要配置 Microsoft Teams 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。
1. OAuth 身份验证：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET 作为键。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在“数据连接”下，选择**创建连接**。
1. 选择**数据来源**时，请选择 Microsoft Teams。
1. 提供 Microsoft Teams **租户 ID**。
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. 提供 Microsoft Teams 应用程序的用户托管客户端应用程序 ClientId
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。选择**下一步**。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 Microsoft Teams 实体读取内容
**先决条件**
+ 要从中读取内容的 Microsoft Teams 对象。需要 team 或 channel-message 等对象名称。下表显示支持的实体。
**源支持的实体**
API 1.0 版本支持所有实体。
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 团队 | 否 | 否 | 否 | 是 | 否 |
| Team Members | 支持 | 是 | 否 | 是 | 是 |
| 组 | 支持 | 是 | 是 | 是 | 是 |
| Group Members | 支持 | 是 | 否 | 是 | 否 |
| 渠道 | 是 | 否 | 否 | 是 | 是 |
| Channel Messages | 否 | 是 | 否 | 是 | 否 |
| Channel Message Replies | 否 | 是 | 否 | 是 | 否 |
| Channel Tabs | 是 | 否 | 否 | 是 | 否 |
| Chats | 支持 | 是 | 是 | 是 | 是 |
| Calendar Events | 支持 | 是 | 是 | 是 | 是 |
**示例**
```
MicrosoftTeams_read = glueContext.create_dynamic_frame.from_options(
connection_type="MicrosoftTeams",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "company",
"API_VERSION": "v1.0"
}
```
## Microsoft Teams 实体和字段详细信息
实体列表：
+ Team：[https://docs.microsoft.com/en-us/graph/api/user-list-joinedteams?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/user-list-joinedteams?view=graph-rest-1.0)
+ Team-Member：[https://docs.microsoft.com/en-us/graph/api/team-list-members?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/team-list-members?view=graph-rest-1.0)
+ Group：[https://docs.microsoft.com/en-us/graph/api/group-list?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/group-list?view=graph-rest-1.0)
+ Group-Member：[https://docs.microsoft.com/en-us/graph/api/group-list-members?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/group-list-members?view=graph-rest-1.0)
+ Channel：[https://docs.microsoft.com/en-us/graph/api/channel-list?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/channel-list?view=graph-rest-1.0)
+ Channel-Message：[https://docs.microsoft.com/en-us/graph/api/channel-list-messages?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/channel-list-messages?view=graph-rest-1.0)
+ Channel-Message-Reply：[https://docs.microsoft.com/en-us/graph/api/chatmessage-list-replies?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/chatmessage-list-replies?view=graph-rest-1.0)
+ Channel-Tab：[https://docs.microsoft.com/en-us/graph/api/channel-list-tabs?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/channel-list-tabs?view=graph-rest-1.0)
+ Chat：[https://docs.microsoft.com/en-us/graph/api/chat-list?view=graph-rest-1.0]( https://docs.microsoft.com/en-us/graph/api/chat-list?view=graph-rest-1.0)
+ Calendar-Event：[https://docs.microsoft.com/en-us/graph/api/group-list-events?view=graph-rest-1.0](https://docs.microsoft.com/en-us/graph/api/group-list-events?view=graph-rest-1.0)
**对查询进行分区**
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-02-06"`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
基于实体的分区字段支持详细信息如下表中所示：
| 实体名称 | 分区字段 | 数据类型 |
| --- | --- | --- |
| Team Members | visibleHistoryStartDateTime | 日期时间 |
| 组 | createdDateTime | 日期时间 |
| 渠道 | createdDateTime | 日期时间 |
| Chats | createdDateTime、lastModifiedDateTime | 日期时间 |
| Calendar Events | createdDateTime、lastModifiedDateTime、originalStart | 日期时间 |
**示例**
```
microsoftteams_read = glueContext.create_dynamic_frame.from_options(
connection_type="MicrosoftTeams",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "group",
"API_VERSION": "v1.0",
"PARTITION_FIELD": "createdDateTime"
"LOWER_BOUND": "2022-07-13T07:55:27.065Z"
"UPPER_BOUND": "2022-08-12T07:55:27.065Z"
"NUM_PARTITIONS": "2"
}
```
# Microsoft Teams 连接选项参考
以下是 Microsoft Teams 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Microsoft Teams 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Microsoft Teams Rest API 版本。示例：v1.0。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# 限制
以下是 Microsoft Teams 连接器的限制：
+ Microsoft Teams API 返回的记录数少于为 Chat 和 Team Member 实体指定的记录数。此问题已报告给 Microsoft Teams Support，目前正在调查中。
## 创建新的 Microsoft Teams 账户：
1. 导航到 Microsoft Teams 主页（[https://account.microsoft.com/account/](https://account.microsoft.com/account/)），然后选择**登录**。
1. 选择**创建账户！**
1. 输入创建账户所需的信息，然后创建新账户。
1. 导航到 Microsoft Teams 网站 [https://www.microsoft.com/en-in/microsoft-teams/log-in](https://www.microsoft.com/en-in/microsoft-teams/log-in)。
1. 使用刚刚创建的 Microsoft 账户进行注册。
1. 成功注册 Teams 后，导航到 [https://account.microsft.com/services](https://account.microsft.com/services)。
1. 选择**试用 Microsoft 365**。
1. 激活以下某一个 Microsoft 365 或 Microsoft Teams 订阅，即可访问 Microsoft Teams 连接器的所有必要功能：
+ Microsoft Teams 基础版
+ Microsoft 365 商业版
+ Microsoft 365 商业基础版
+ Microsoft 365 商业标准版
+ Microsoft 365 商业高级版
**创建托管客户端应用程序：**
1. 要创建托管应用程序，必须在 Microsoft Entra（前身为 Azure Active Directory）上注册新的 OAuth 应用程序：
1. 登录 [Microsoft Entra 管理中心](https://entra.microsoft.com)。
1. 如果有权访问多个租户，则使用顶部菜单中的“设置”图标，从“目录 \$1 订阅”菜单切换到要在其中注册应用程序的租户。
1. 导航到“身份 > 应用程序 > 应用程序注册”，然后选择**新注册**。
1. 输入应用程序的显示名称。
1. 在“支持的账户类型”部分中指定可以使用该应用程序的对象。要将此应用程序设为全局可用，请选择“任何组织目录中的账户”或“任何组织目录中的账户和 Microsoft 个人账户”。
1. 输入重定向 URI `https://{region}.console.aws.amazon.com/appflow/oauth`。例如，对于 `us-west-2 region`，添加 `https://us-west-2.console.aws.amazon.com/appflow/oauth`。可以为要使用的不同区域添加多个 URL。
1. 注册应用程序。
1. 记下客户端 ID，留待将来使用。
1. 在“基本信息”部分中选择**添加证书或密钥**。
1. 选择**新建客户端密钥**。
1. 输入描述和有效时长。
1. 复制并保存客户端密钥，留待将来使用。
1. 在左侧菜单列表中选择 **API 权限**。
1. 选择**添加权限**。
1. 选择“Microsoft Graph”。
1. 选择“委派权限”。
1. 检查以下所有权限：
+ User.Read
+ Offline\$1access
+ User.Read.All
+ User.ReadWrite.All
+ TeamsTab.ReadWriteForTeam
+ TeamsTab.ReadWriteForChat
+ TeamsTab.ReadWrite.All
+ TeamsTab.Read.All
+ TeamSettings.ReadWrite.All
+ TeamSettings.Read.All
+ TeamMember.ReadWrite.All
+ TeamMember.Read.All
+ Team.ReadBasic.All
+ GroupMember.ReadWrite.All
+ GroupMember.Read.All
+ Group.ReadWrite.All
+ Group.Read.All
+ Directory.ReadWrite.All
+ Directory.Read.All
+ Directory.AccessAsUser.All
+ Chat.ReadWrite
+ Chat.ReadBasic
+ Chat.Read
+ ChannelSettings.ReadWrite.All
+ ChannelSettings.Read.All
+ ChannelMessage.read.all
+ Channel.ReadBasic.All
1. 选择**添加权限**。现在，应用程序已成功设置。可以使用客户端 ID 和客户端密钥创建新连接。有关更多信息，请参阅 [https://learn.microsoft.com/en-us/graph/auth-register-app-v2](https://learn.microsoft.com/en-us/graph/auth-register-app-v2)。
# 连接到 Mixpanel
Mixpanel 是一个强大的实时分析平台，可帮助公司衡量和优化用户参与度。Mixpanel 是一款用于跟踪客户行为的应用程序。此应用可跟踪用户如何与产品进行交互，并借助交互式报告分析这些数据，让您只需点击几下即可查询和可视化分析结果。若是 Mixpanel 用户，则可将 AWS Glue 连接到 Mixpanel 账户。然后，可以使用 Mixpanel 作为 ETL 作业中的数据来源。通过运行这些作业，可在 Mixpanel 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 支持 Mixpanel](Mixpanel-support.md)
+ [包含创建和使用连接的 API 操作的策略](mixpanel-configuring-iam-permissions.md)
+ [配置 Mixpanel](mixpanel-configuring.md)
+ [配置 Mixpanel 连接](mixpanel-configuring-connections.md)
+ [从 Mixpanel 实体读取内容](mixpanel-reading-from-entities.md)
+ [Mixpanel 连接选项](mixpanel-connection-options.md)
+ [创建 Mixpanel 账户并配置客户端应用程序](mixpanel-create-account.md)
+ [限制](mixpanel-connector-limitations.md)
# AWS Glue 支持 Mixpanel
AWS Glue 对 Mixpanel 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Mixpanel 中的数据。
**是否支持作为目标？**
否。
**支持的 Mixpanel API 版本**
2.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 控制台的用户。
# 配置 Mixpanel
必须满足以下要求，才能使用 AWS Glue 从 Mixpanel 传输数据：
## 最低要求
+ 拥有一个 Mixpanel 账户。有关创建账户的更多信息，请参阅[创建 Mixpanel 账户](mixpanel-create-account.md)。
+ Mixpanel 账户已启用 API 访问权限。默认情况下，Enterprise、Unlimited、Developer 和 Performance 版已启用 API 访问权限。
如果满足这些要求，就可以将 AWS Glue 连接到 Mixpanel 账户。对于常见连接，无需在 Mixpanel 中执行其他操作。
# 配置 Mixpanel 连接
Mixpanel 支持 `BasicAuth` 的用户名和密码。基本身份验证是一种简单的身份验证方法，客户端直接提供凭证即可访问受保护的资源。AWS Glue 能够使用用户名和密码对 Mixpanel API 进行身份验证。
有关 `BasicAuth` 流的 Mixpanel 公共文档，请参阅 [Mixpanel Service Accounts ](https://developer.mixpanel.com/reference/service-accounts)。
要配置 Mixpanel 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
+ 对于基本身份验证，密钥应包含关联应用程序的消费者密钥，且以 `USERNAME` 和 `PASSWORD` 为键。
**注意**
必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 **Mixpanel**。
1. 提供想要连接到的 Mixpanel 的 `INSTANCE_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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择**网络选项**。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Mixpanel 实体读取内容
**先决条件**
必须拥有一个要从中读取数据的 Mixpanel 对象，例如 `Funnels`、`Retention` 或 `Retention Funnels`。此外，还需要知道对象名称。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 漏斗 | 是 | 否 | 否 | 是 | 否 |
| 保留 | 是 | 否 | 否 | 是 | 否 |
| 客户细分 | 是 | 否 | 否 | 是 | 否 |
| 分段总和 | 是 | 否 | 否 | 是 | 否 |
| 分段平均值 | 是 | 否 | 否 | 是 | 否 |
| 队列 | 是 | 否 | 否 | 是 | 否 |
| 互动 | 否 | 是 | 否 | 是 | 否 |
| Events | 是 | 否 | 否 | 是 | 否 |
| 顶级事件 | 是 | 否 | 否 | 是 | 否 |
| 事件名称 | 是 | 否 | 否 | 是 | 否 |
| 事件属性 | 是 | 否 | 否 | 是 | 否 |
| 顶级事件属性 | 是 | 否 | 否 | 是 | 否 |
| 事件属性值 | 是 | 否 | 否 | 是 | 否 |
| Annotations | 是 | 否 | 否 | 是 | 否 |
| 配置文件事件活动 | 是 | 否 | 否 | 是 | 否 |
**示例**
```
mixpanel_read = glueContext.create_dynamic_frame.from_options(
connection_type="mixpanel",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "/cohorts/list?project_id=2603353",
"API_VERSION": "2.0",
"INSTANCE_URL": "https://www.mixpanel.com/api/app/me"
}
```
**Mixpanel 实体和字段详细信息**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/mixpanel-reading-from-entities.html)
# Mixpanel 连接选项
以下是 Mixpanel 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取/写入。Mixpanel 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取/写入。要使用的 Mixpanel Rest API 版本。例如：V2.0。
+ `SELECTED_FIELDS`（列表<字符串>）– 默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# 创建 Mixpanel 账户并配置客户端应用程序
**创建 MixPanel 账户**
1. 导航到 [Mixpanel 主页/](https://mixpanel.com/)。
1. 在 **Mixpanel** 主页上，选择页面右上角的**注册**。
1. 在**我们开始吧**页面上，完成以下操作：
+ 在指定字段中输入电子邮件地址。
+ 选中所需的复选框来同意条款。
+ 选择**开始使用**来继续操作。
成功完成以上操作后，即会收到一封验证电子邮件。
1. 确认电子邮件收件箱中有验证消息，打开电子邮件，然后按照说明验证电子邮件地址。
1. 在验证页面上，选择**验证电子邮件**来完成电子邮件验证。
1. 在**为组织命名**页面上输入组织名称，然后选择**下一步**。
1. 在**第一个项目**页面上输入项目详细信息，然后选择**创建**。
1. 在下一页上，选择**我们开始吧**来完成账户的创建。
**登录 Mixpanel 账户**
1. 导航到 [Mixpanel 登录页面/](https://mixpanel.com/login/)。
1. 输入电子邮件地址，然后选择**继续**。
1. 确认电子邮件收件箱中有验证消息，打开电子邮件，然后按照说明验证电子邮件地址。
1. 在下一页上，点击**登录**按钮来登录账户。
**购买 Mixpanel 方案**
1. 在 Mixpanel 页面上，选择页面右上角的**设置**图标。
1. 从选项列表中选择**方案详情和账单**。
1. 在**方案详情和账单**页面上，选择**升级或修改**。
1. 在下一页中，选择要购买的方案。
账户创建和方案购买流程到此完成。
**创建用户名和客户端密钥（用于注册应用程序）**
1. 在 Mixpanel 页面上，选择页面右上角的**设置**图标。
1. 从选项列表中选择**项目设置**。
1. 在**项目设置**页面上选择**服务账户**，然后选择**添加服务账户**。
1. 从**服务账户**下拉列表中选择**服务账户或输入要创建的名称**，添加**项目角色**，指定**过期时间**，然后选择**添加**。
**重要**
完成上一步后，下一页会显示服务账户的密钥。务必保存好服务账户的密钥。因为此后无法再次访问此页面。
# 限制
以下是 Mixpanel 连接器的限制：
+ 对于 `Segmentation Numeric` 实体，如果未找到必要筛选条件的数字数据，Mixpanel API 会引发 `400 (Bad Request)` 错误。我们将其视作防止流失败的 `OK` 响应。
+ 出于以下原因，已从支持的实体中删除了可查询字段 `limit`：
+ 由于被解释为 SDK 的限制功能而导致错误
+ 筛选条件没有实际用途
+ 限制功能实现现已涵盖了等效功能
+ 由于 SaaS 平台缺少分区所需的运算符（`>=`、`<=`、`<`、`>`、`between`），因此无法支持基于字段的分区。尽管其支持 `between` 运算符，但支持该运算符的字段是不可检索的。因此，不符合基于字段的分区标准。
+ 由于未要求为支持分页的实体提供“偏移量”值，因此无法支持 Mixpanel 基于记录的分区。
+ `Cohorts` 实体仅支持 `CreatedDate/Time` 字段，没有字段可识别 `UpdatedDate/Time`，因此无法识别结果 `DML_Status`。此外，没有端点可以识别已删除的记录。因此，无法支持 CDC。
+ 要为下面提到的实体运行 AWS Glue 作业，需要使用必要筛选条件。有关实体名称及其所需的筛选条件，请参阅下表。
**实体名称和所需的筛选条件**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/mixpanel-connector-limitations.html)
# 连接到 Monday
Monday.com 是一款多功能工作操作系统，有助于简化项目管理和团队协作。该系统具有可自定义的工作流、可视化控制面板以及自动化工具，能够提高工作效率。用户可以在一个集成平台上跟踪任务、管理资源并开展有效沟通。
**Topics**
+ [AWS Glue 对 Monday 的支持](monday-support.md)
+ [包含创建和使用连接的 API 操作的策略](monday-configuring-iam-permissions.md)
+ [配置 Monday](monday-configuring.md)
+ [配置 Monday 连接](monday-configuring-connections.md)
+ [从 Monday 实体读取内容](monday-reading-from-entities.md)
+ [Monday 连接选项参考](monday-connection-options.md)
+ [限制](monday-connector-limitations.md)
+ [创建新的 Monday 账户：](#monday-account-creation)
# AWS Glue 对 Monday 的支持
AWS Glue 对 Monday 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Monday 中的数据。
**是否支持作为目标？**
否。
**支持的 Monday API 版本**
v2.
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Monday
必须满足以下要求，才能使用 AWS Glue 从 Monday 传输数据：
## 最低要求
+ 拥有 Monday 开发人员账户，其中包含电子邮件和密码。有关更多信息，请参阅 [创建新的 Monday 账户：](connecting-to-monday.md#monday-account-creation)。
+ Monday 开发人员账户已启用 API 访问权限。试用期内，使用任何 Monday API 服务均不会产生额外费用。试用期结束后，需要购买订阅才能创建和访问数据。有关更多信息，请参阅 [Monday 授权页面](https://developer.monday.com/api-reference/reference/about-the-api-reference)了解详细信息。
如果满足这些要求，就可以将 AWS Glue 连接到 Monday 账户。对于常见连接，无需在 Monday 中执行其他操作。
# 配置 Monday 连接
Monday 支持以下两种类型的身份验证机制：
1. OAuth 身份验证：Monday 支持 OAuth2 的 AUTHORIZATION\$1CODE 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。默认情况下，创建连接的用户可以依赖于 AWS Glue 拥有的关联应用程序；在该应用程序中，除了 Monday 实例 URL 之外，用户无需提供任何与 OAuth 相关的信息。AWS Glue 控制台会将用户重定向到 Monday，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Monday 实例。
+ 用户应该选择在 Monday 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Monday，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期为一小时，可以通过刷新令牌在不需要用户互动的情况下自动刷新。
+ 有关更多信息，请参阅[有关为 AUTHORIZATION\$1CODE OAuth 流创建关联应用程序的文档](https://developers.Monday.com/docs/api/v1/Oauth)。
1. 自定义身份验证：
+ 有关生成自定义授权所需 API 密钥的 Monday 公共文档，请参阅 [https://developer.monday.com/api-reference/docs/authentication\$1api-token-permissions](https://developer.monday.com/api-reference/docs/authentication#api-token-permissions)。
要配置 Monday 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。
1. OAuth 身份验证：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET 作为键。
1. 对于自定义身份验证：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将 `personalAccessToken` 作为键。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在“数据连接”下，选择**创建连接**。
1. 选择**数据来源**时，请选择 Monday。
1. 提供 Monday **实例 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. 选择身份验证类型以连接到 Monday
+ OAuth 身份验证：提供要连接的 Monday 的**令牌 URL** 以及**用户托管客户端应用程序 ClientId**。
+ 对于自定义身份验证：选择**自定义**身份验证类型以连接到 Monday。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。选择**下一步**。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 Monday 实体读取内容
**先决条件**
+ 要从中读取内容的 Monday 对象。请参阅下面的支持的实体表，查看可用的实体。
**源支持的实体**
实体列表：
+ Account：[https://developer.monday.com/api-reference/docs/account\$1queries](https://developer.monday.com/api-reference/docs/account#queries)
+ Board：[https://developer.monday.com/api-reference/docs/boards\$1queries](https://developer.monday.com/api-reference/docs/boards#queries)
+ Column：[https://developer.monday.com/api-reference/docs/columns\$1queries](https://developer.monday.com/api-reference/docs/columns#queries)
+ Docs：[https://developer.monday.com/api-reference/docs/docs\$1queries](https://developer.monday.com/api-reference/docs/docs#queries)
+ Document Block：[https://developer.monday.com/api-reference/docs/blocks\$1queries](https://developer.monday.com/api-reference/docs/blocks#queries)
+ Files：[https://developer.monday.com/api-reference/docs/files\$1queries](https://developer.monday.com/api-reference/docs/files#queries)
+ Folders：[https://developer.monday.com/api-reference/docs/folders\$1queries](https://developer.monday.com/api-reference/docs/folders#queries)
+ Groups：[https://developer.monday.com/api-reference/docs/groups\$1queries](https://developer.monday.com/api-reference/docs/groups#queries)
+ Item：[https://developer.monday.com/api-reference/docs/items\$1queries](https://developer.monday.com/api-reference/docs/items#queries)
+ Subitems：[https://developer.monday.com/api-reference/docs/subitems\$1queries](https://developer.monday.com/api-reference/docs/subitems#queries)
+ Tags：[https://developer.monday.com/api-reference/docs/tags-queries\$1queries](https://developer.monday.com/api-reference/docs/tags-queries#queries)
+ Teams：[https://developer.monday.com/api-reference/docs/teams\$1queries](https://developer.monday.com/api-reference/docs/teams#queries)
+ Updates：[https://developer.monday.com/api-reference/docs/updates\$1queries](https://developer.monday.com/api-reference/docs/updates#queries)
+ Users：[https://developer.monday.com/api-reference/docs/users\$1queries](https://developer.monday.com/api-reference/docs/users#queries)
+ Workspaces：[https://developer.monday.com/api-reference/docs/workspaces\$1queries](https://developer.monday.com/api-reference/docs/workspaces#queries)
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| Account | 否 | 否 | 否 | 是 | 否 |
| Boards | 支持 | 是 | 否 | 是 | 否 |
| Columns | 否 | 否 | 否 | 是 | 否 |
| Docs | 支持 | 是 | 否 | 是 | 否 |
| Document Blocks | 否 | 是 | 否 | 是 | 否 |
| 文件 | 是 | 否 | 否 | 是 | 否 |
| 组 | 否 | 否 | 否 | 是 | 否 |
| Item | 支持 | 是 | 否 | 是 | 否 |
| Subitems | 否 | 否 | 否 | 是 | 否 |
| 标签 | 是 | 否 | 否 | 是 | 是 |
| 团队 | 是 | 否 | 否 | 是 | 否 |
| 更新 | 否 | 是 | 否 | 是 | 否 |
| Users | 支持 | 是 | 否 | 是 | 否 |
| Workspaces | 支持 | 是 | 否 | 是 | 否 |
| 文件夹 | 支持 | 是 | 否 | 是 | 否 |
**示例**
```
monday_read = glueContext.create_dynamic_frame.from_options(
connection_type="monday",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "account",
"API_VERSION": "v2"
}
```
# Monday 连接选项参考
以下是 Monday 的连接选项：
+ `ENTITY_NAME`（字符串）–（必填）用于读/写。Monday 中对象的名称。
+ `API_VERSION`（字符串）–（必填）用于读/写。要使用的 Monday Rest API 版本。示例：v2。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# 限制
以下是 Monday 连接器的限制：
+ 动态元数据响应与文档存在某些冲突，如下所述：
+ Group、Column 实体支持筛选操作，但动态元数据端点中不存在该实体，因而其为不可筛选的实体。
+ 动态端点包含 15000 多行响应，并且会在单次响应中返回所有实体的元数据，因此，这些字段平均需要 10 秒才能加载完成，鉴于此，在运行作业时需预留一些额外时间。
+ 有关 Monday 速率限制，请参阅下表。动态实体的响应数据量庞大，会导致明显的延迟，字段平均需要 10 秒才能加载完成。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/monday-connector-limitations.html)
## 创建新的 Monday 账户：
1. 导航到 Monday 主页（[https://monday.com/](https://monday.com/)），然后选择**登录**。
1. 此时会重定向到登录页面。选择页面底部的**注册**。
1. 输入电子邮件地址，然后选择**继续**。也可以使用 Google 账户登录。
1. 输入必要的详细信息，然后选择**继续**。
1. 回答完调查问题，再按照步骤完成账户创建过程。
**注册 OAuth 应用程序：**
1. 登录自己的 monday.com 账户。点击屏幕左下角的头像（图片图标）。
1. 选择**开发者**。
1. 选择**创建应用程序**。
1. 填写必填的名称和描述字段。
1. 导航到右侧的“OAuth”部分，添加范围，然后选择“保存功能”。
1. 导航到范围旁边的“重定向 URL”选项卡，添加重定向 URL，然后选择“保存功能”。
1. 在**重定向 URL** 选项卡下，提供自己的应用程序 URL。此即 https://\$1region-code\$1.console.aws.amazon.com/appflow/oauth。例如，如果正在使用 `us-east-1 `，则可添加 `https://us-east-1.console.aws.amazon.com/appflow/oauth`。
1. 应用程序现已准备就绪，可供立即使用。在“基本信息”部分中找到自己的凭证。记下客户端 ID 和客户端密钥。使用 AppFlow 连接器与该应用程序建立连接时会用到这些字符串。
**生成个人访问令牌：**
目前，monday.com 仅提供我们的 V2 API 令牌，而这些都是个人令牌。可以使用两种方法中的任意一种来访问自己的 API 令牌，具体方法取决于用户级别。管理员用户可以使用这两种方法来获取自己的 API 令牌。成员用户可以从“开发者”选项卡访问自己的 API 令牌。
管理员：如果您是 monday.com 账户的管理员用户，则可以按照以下步骤从“管理员”选项卡访问自己的 API 令牌：
1. 登录自己的 monday.com 账户。点击屏幕左下角的头像（图片图标）。
1. 从出现的菜单中选择“管理”（要求具有管理员权限）。
1. 导航到“API”部分并生成“API V2 令牌”。此时可以复制自己的令牌加以使用。
开发者：如果您是 monday.com 账户的成员用户，则可以按照以下步骤从“开发者”选项卡访问自己的 API 令牌：
1. 登录自己的 monday.com 账户。点击屏幕左下角的头像（图片图标）。
1. 从出现的菜单中选择“开发者”。
1. 在顶部菜单中选择“开发者”下拉菜单。在下拉菜单上选择标题为“我的访问令牌”的第一个选项。
# 在 AWS Glue Studio 中连接到 MongoDB
AWS Glue 提供了对 MongoDB 的内置支持。AWS Glue Studio 提供了直观的界面，以用于连接到 MongoDB、编写数据集成作业以及在 AWS Glue Studio 无服务器 Spark 运行时系统上运行这些作业。
**Topics**
+ [创建 MongoDB 连接](creating-mongodb-connection.md)
+ [创建 MongoDB 源节点](creating-mongodb-source-node.md)
+ [创建 MongoDB 目标节点](creating-mongodb-target-node.md)
+ [高级选项](#creating-mongodb-connection-advanced-options)
# 创建 MongoDB 连接
**先决条件：**
+ 如果您的 MongoDB 实例位于某个 Amazon VPC 中，请确保您的 Amazon VPC 配置允许您的 AWS Glue 作业与 MongoDB 实例进行通信，并且无需通过公共互联网路由流量。
在 Amazon VPC 中，确定或创建 AWS Glue 将在执行作业时使用的 **VPC**、**子网**和**安全组**。此外，您的 Amazon VPC 配置需要允许您的 MongoDB 实例与该位置之间的网络流量。根据您的网络布局，这可能需要更改安全组规则、网络 ACL、NAT 网关和对等连接。
**配置 MongoDB 连接：**
1. 您还可以在 AWS Secrets Manager 中使用您的 MongoDB 凭证创建密钥。要在 Secrets Manager 中创建密钥，请按照 AWS Secrets Manager 文档中[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中的教程进行操作。创建密钥后，保留密钥名称 *secretName*，以供下一步使用。
+ 在选择**键/值对**时，请使用键 `username` 和值 *mongodbUser* 创建一个键值对。
在选择**键/值对**时，请使用键 `password` 和值 *mongodbPass* 创建一个键值对。
1. 在 AWS Glue 控制台中，按照 [添加 AWS Glue 连接](console-connections.md) 中的步骤创建一个连接。创建连接后，保留连接名为 *connectionName*，以供未来在 AWS Glue 中使用。
+ 选择**连接类型**时，请选择 **MongoDB** 或 **MongoDB Atlas**。
+ 选择 **MongoDB URL** 或 **MongoDB Atlas URL** 时，请提供 MongoDB 实例的主机名。
MongoDB URL 的格式为 `mongodb://mongoHost:mongoPort/mongoDBname`。
MongoDB Atlas URL 的格式为 `mongodb+srv://mongoHost/mongoDBname`。
+ 如果您选择创建 Secrets Manager 密钥，请选择 AWS Secrets Manager **凭证类型**。
然后在 **AWS密钥**中提供 *secretName*。
+ *如果您选择提供**用户名和密码**，请提供 *mongodbUser* 和 mongodbPass*。
1. 对于下列情况，您可能需要添加额外的配置：
+
对于通过 Amazon VPC 在 AWS 云端托管的 MongoDB 实例
+ 您需要向 AWS Glue 连接提供用于定义 MongoDB 安全凭证的 Amazon VPC 连接信息。创建或更新连接时，请在**网络选项**中设置 **VPC**、**子网**和**安全组**。
创建 AWS Glue MongoDB 连接后，您需要完成以下操作，然后才能运行 AWS Glue 作业：
+ 在可视化编辑器中处理 AWS Glue 作业时，您必须提供作业的 Amazon VPC 连接信息，才能连接到 MongoDB。确定 Amazon VPC 中的适当位置并将其提供给您的 AWS Glue MongoDB 连接。
+ 如果您选择创建 Secrets Manager 密钥，请向与您的 AWS Glue 作业关联的 IAM 角色授予读取 *secretName* 的权限。
# 创建 MongoDB 源节点
## 所需的先决条件
+ 一个 AWS Glue MongoDB 连接，如上一节“[创建 MongoDB 连接](creating-mongodb-connection.md)”所述。
+ 如果您选择创建 Secrets Manager 密钥，则需要提供对您的作业具有读取连接使用的密钥的相应权限。
+ 您要读取的 MongoDB 集合。您将需要该集合的标识信息。
MongoDB 集合由数据库名 *mongodbName* 和集合名 *mongodbCollection* 来标识。
## 添加 MongoDB 数据来源
**添加**数据来源 - MongoDB** 节点：**
1. 选择 MongoDB DB 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 MongoDB 连接**。有关更多信息，请参阅之前的 [创建 MongoDB 连接](creating-mongodb-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 选择一个**数据库**。输入 *mongodbName*。
1. 选择一个**集合**。进入 *mongodbCollection*。
1. 选择**分区程序**、**分区大小（MB）**和**分区键**。有关分区参数的更多信息，请参阅 ["connectionType": "mongodb" as Source](aws-glue-programming-etl-connect-mongodb-home.md#etl-connect-mongodb-as-source)。
1. 在**自定义 Azure MongoDB 属性**中，根据需要输入相关参数和值。
# 创建 MongoDB 目标节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue MongoDB 连接，如上一节“[创建 MongoDB 连接](creating-mongodb-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要写入的 MongoDB 表 *tableName*。
## 添加 MongoDB 数据目标
**添加**数据目标 - MongoDB** 节点：**
1. 选择 MongoDB DB 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 MongoDB 连接**。有关更多信息，请参阅之前的 [创建 MongoDB 连接](creating-mongodb-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 选择一个**数据库**。输入 *mongodbName*。
1. 选择一个**集合**。进入 *mongodbCollection*。
1. 选择**分区程序**、**分区大小（MB）**和**分区键**。有关分区参数的更多信息，请参阅 ["connectionType": "mongodb" as Source](aws-glue-programming-etl-connect-mongodb-home.md#etl-connect-mongodb-as-source)。
1. 在需要时选择**重试写入**。
1. 在**自定义 Azure MongoDB 属性**中，根据需要输入相关参数和值。
## 高级选项
您可以在创建 MongoDB 节点时提供高级选项。这些选项与编程 Spark 脚本的 AWS Glue 时可用的选项相同。
请参阅[MongoDB 连接选项参考](aws-glue-programming-etl-connect-mongodb-home.md#aws-glue-programming-etl-connect-mongodb)。
# 连接到 Oracle NetSuite
Oracle NetSuite 是一款一站式云业务管理解决方案，通过自动化执行核心流程并实现运营和财务表现的实时可见性，帮助组织提高运营效率。Oracle NetSuite 一站式集成了管理会计、订单处理、库存管理、生产、供应链和仓库操作应用程序套件，使企业能够清晰地了解自己的数据，加强对业务的控制。
**Topics**
+ [AWS Glue 对 Oracle NetSuite 的支持](oracle-netsuite-support.md)
+ [包含创建和使用连接的 API 操作的策略](oracle-netsuite-configuring-iam-permissions.md)
+ [配置 Oracle NetSuite](oracle-netsuite-configuring.md)
+ [配置 Oracle NetSuite 连接](oracle-netsuite-configuring-connections.md)
+ [从 Oracle NetSuite 实体中读取](oracle-netsuite-reading-from-entities.md)
+ [Oracle NetSuite 连接选项](oracle-netsuite-connection-options.md)
+ [Oracle NetSuite 连接器的限制和说明](oracle-netsuite-connector-limitations.md)
# AWS Glue 对 Oracle NetSuite 的支持
AWS Glue 对 Oracle NetSuite 的支持如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Oracle NetSuite 中的数据。
**是否支持作为目标？**
否。
**支持的 Oracle NetSuite API 版本**
支持以下 Oracle NetSuite 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 控制台的用户。
# 配置 Oracle NetSuite
您必须满足以下要求，才能使用 AWS Glue 从 Oracle NetSuite 传出数据：
## 最低要求
以下是最低要求：
+ 您拥有一个 Oracle NetSuite 账户。有关更多信息，请参阅 [创建 Oracle NetSuite 账户](#oracle-netsuite-configuring-creating-oracle-netsuite-account)。
+ 您的 Oracle NetSuite 账户已启用 API 访问权限。
+ 您已在您的 Oracle NetSuite 开发者账户中创建了 OAuth 2.0 API 集成。此集成提供 AWS Glue 在对账户进行身份验证调用时，用于安全访问数据的客户端凭证。有关更多信息，请参阅 [创建 Oracle NetSuite 客户端应用程序和 OAuth 2.0 凭证](#oracle-netsuite-configuring-creating-oracle-netsuite-client-app)。
如果满足这些要求，就可以将 AWS Glue 连接到 Oracle NetSuite 账户。
## 创建 Oracle NetSuite 账户
导航到 [Oracle NetSuite](https://www.netsuite.com/portal/home.shtml)，然后选择**免费产品演示**。填写所需的详细信息以获取免费产品演示，您可以通过这种方式联系供应商。购买账户的过程如下：
+ NetSuite 账户需要通过供应商才能采购，供应商提供的表格/报价必须通过法律审查。
+ 要为 Oracle NetSuite 连接器购买的账户属于**标准云服务账户**。
+ 该账户由供应商创建，并由其提供临时凭证。您将收到一封来自 NetSuite 的欢迎邮件，其中包含用户名等详细信息，以及用于设置密码的链接。
+ 使用**设置密码**链接为供应商提供的用户名设置密码。
## 创建 Oracle NetSuite 客户端应用程序和 OAuth 2.0 凭证
要获取您创建的 Oracle NetSuite 客户端应用程序的客户端 ID 和客户端密钥，请按以下步骤操作：
1. 通过 [NetSuite 客户登录](https://system.netsuite.com/pages/customerlogin.jsp)链接登录到您的 NetSuite 账户。
1. 选择**设置** > **公司** > **启用功能**。
1. 导航到 **SuiteCloud** 部分，然后选中 **SuiteTalk（Web 服务）**下的 **REST WEB 服务**复选框。
1. 选中**管理身份验证**下的 **OAUTH 2.0** 复选框。单击**保存**。
1. 前往**设置** > **集成** > **管理集成**，然后选择**新建**以创建 OAuth2.0 应用程序。
1. 输入您选择的名称，并将**状态**保持为“已启用”。
1. 在**基于令牌的身份验证**下，如果已选中 **TBA: 授权流**和**基于令牌的身份验证**复选框，则将其取消选中。
1. 选中 **OAuth** 2.0 下的**授权码授予**和**公共客户端**复选框。
1. 记下身份验证下的客户端 ID 和 客户端密钥。
1. 输入一个**重定向 URI**。例如，https://us-east-1.console.aws.amazon.com/gluestudio/oauth
1. 选中**范围**下的 **REST WEB 服务**复选框。
1. 选中**用户凭证**下的**用户凭证**复选框。选择**保存**。
1. 记下**客户凭证**下的“使用者密钥/客户端 ID”和“使用者密钥/客户端密钥”。这些值仅会显示一次。
1. 必要时导航至**用户/角色** > **管理角色** > **新建**，创建一个 ADMINISTRATOR 角色。
1. 创建自定义角色时，请在**权限**选项卡下添加以下实体/功能的完全访问权限：
+ “Deposit”、“Items”、“Item Fulfillment”、“Make Journal Entry”、“Purchase Order”、“Subsidiaries”、“Vendors”、“Bills”、“Vendor Return Authorization”、“Track Time”、“Customer Payment”、“Custom Record Entries”、“Custom Record Types”、“REST Web Services”、“OAuth 2.0 Authorized Applications Management”、“Custom Entity Fields”、“Log in using OAuth 2.0 Access Tokens"。
有关更多信息，请参阅 NetSuite Applications Suite 文档中的 [OAuth 2.0](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_157769826287.html)。
# 配置 Oracle NetSuite 连接
Oracle NetSuite 支持 OAuth2 的 AUTHIZATION\$1CODE 授权类型。该授权类型决定了 AWS Glue 如何与 Oracle NetSuite 通信来请求访问数据。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。默认情况下，创建连接的用户可以依赖于 AWS Glue 拥有的关联应用程序（AWS Glue 托管式客户端应用程序）；在该应用程序中，除了 Oracle NetSuite 实例 URL 之外，用户无需提供任何与 OAuth 相关的信息。AWS Glue 控制台会将用户重定向到 Oracle NetSuite，用户必须登录并向 AWS Glue 授予所请求的权限，以便访问其 Oracle NetSuite 实例。
+ 用户仍然可以选择在 Oracle NetSuite 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Oracle NetSuite，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 Oracle NetSuite 公共文档，请参阅 [Public apps](https://developers.oracle-netsuite.com/docs/api/creating-an-app)。
要配置 Oracle NetSuite 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的消费者密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
1. 注意：您必须在 AWS Glue 中为您的连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Oracle NetSuite。
1. 提供 Oracle NetSuite 环境。
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` 的权限。
# 从 Oracle NetSuite 实体中读取
**先决条件**
您要从中读取内容的 Oracle NetSuite 对象。您将需要 `deposit` 或 `timebill` 等对象名称。下表显示支持的实体。
**源支持的实体**：
| 实体 | 可以筛选 | 支持排序依据 | 支持限制 | 支持 SELECT \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 定金 | 是 | 否 | 是 | 是 | 是 |
| 商品描述 | 是 | 否 | 是 | 是 | 是 |
| 库存商品 | 是 | 否 | 是 | 是 | 是 |
| 商品履行 | 是 | 否 | 是 | 是 | 是 |
| 商品组 | 是 | 否 | 是 | 是 | 是 |
| 日记账条目 | 是 | 否 | 是 | 是 | 是 |
| 非库存采购商品 | 是 | 否 | 是 | 是 | 是 |
| 非库存转售商品 | 是 | 否 | 是 | 是 | 是 |
| 非库存销售商品 | 是 | 否 | 是 | 是 | 是 |
| 采购订单 | 是 | 否 | 是 | 是 | 是 |
| 子公司 | 是 | 否 | 是 | 是 | 是 |
| Vendor | 是 | 否 | 是 | 是 | 是 |
| 供应商账单 | 是 | 否 | 是 | 是 | 是 |
| 供应商退货授权 | 是 | 否 | 是 | 是 | 是 |
| 工时账单 | 是 | 否 | 是 | 是 | 是 |
| 客户付款 | 是 | 否 | 是 | 是 | 是 |
| 配送请求 | 是 | 否 | 是 | 是 | 是 |
| Item | 支持 | 是 | 是 | 是 | 是 |
| 交易明细 | 支持 | 是 | 是 | 是 | 是 |
| 交易会计明细 | 支持 | 是 | 是 | 是 | 是 |
| 自定义记录类型（动态） | 支持 | 是 | 是 | 是 | 是 |
**示例：**
```
netsuiteerp_read = glueContext.create_dynamic_frame.from_options(
connection_type="netsuiteerp",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "deposit",
"API_VERSION": "v1"
}
)
```
**Oracle NetSuite 实体和字段详细信息**：
Oracle NetSuite 会动态加载所选实体下的可用字段。根据字段的数据类型，它支持以下筛选运算符。
| 字段数据类型 | 支持的筛选运算符 |
| --- | --- |
| 字符串 | LIKE, =, \$1= |
| 日期 | BETWEEN, =, <, <=, >, >= |
| 日期时间 | BETWEEN, <, <=, >, >= |
| 数值 | =, \$1=, <, <=, >, >= |
| 布尔值 | =, \$1= |
**筛选表达式中布尔值的预期输入格式**：
| 实体 | 布尔值“true”的格式 | 布尔值“false”的格式 | 示例 |
| --- | --- | --- | --- |
| 项目、交易明细、交易会计明细和自定义记录类型实体 | T 或 t | F 或 f | isinactive =“T”或 isinactive =“t” |
| 所有其他实体 | true | false | isinactive = true |
## 对查询进行分区
**基于字段的分区**
Oracle NetSuite 连接器具有动态元数据，因此可以动态选择基于字段的分区所支持的字段。数据类型为整数、大整数、日期或日期时间的字段支持基于字段的分区。
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于时间戳字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"TIMESTAMP \"1707256978123\""
"TIMESTAMP \"1702600882\""
"TIMESTAMP '2024-02-06T22:00:00:00.000Z'"
"TIMESTAMP '2024-02-06T22:00:00:00Z'"
"TIMESTAMP '2024-02-06'"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
netsuiteerp_read = glueContext.create_dynamic_frame.from_options(
connection_type="netsuiteerp",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "deposit",
"API_VERSION": "v1",
"PARTITION_FIELD": "id",
"LOWER_BOUND": "1",
"UPPER_BOUND": "10000",
"NUM_PARTITIONS": "10"
}
```
**基于记录的分区**
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `NUM_PARTITIONS`。使用此参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
在基于记录的分区中，从 Oracle NetSuite API 查询现有的记录总数，将其除以提供的 `NUM_PARTITIONS` 数字，然后由每个子查询同时提取生成的记录数。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
netsuiteerp_read = glueContext.create_dynamic_frame.from_options(
connection_type="netsuiteerp",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "deposit",
"API_VERSION": "v1",
"NUM_PARTITIONS": "3"
}
```
# Oracle NetSuite 连接选项
Oracle NetSuite 的连接选项如下：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Oracle NetSuite 实体的名称。示例：deposit。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Oracle NetSuite Rest API 版本。该值将为 v1，因为 Oracle NetSuite 目前仅支持版本 v1。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您要为所选实体选择的列的逗号分隔列表。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于对查询进行分区的字段（基于字段的分区）。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区依据字段的含本数下限值（用于基于字段的分区）。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区依据字段的不含本数上限值（用于基于字段的分区）。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。用于基于字段和基于记录的分区。
+ `INSTANCEE_URL`（字符串）：有效的 NetSuite 实例 URL，格式为 https://\$1account-id\$1.suitetalk.api.netsuite.com。
# Oracle NetSuite 连接器的限制和说明
以下是 Oracle NetSuite 连接器的限制或说明：
+ access\$1token 和 refresh\$1token 参数的值采用 JSON Web 令牌（JWT）格式。访问令牌的有效期为 60 分钟，而刷新令牌的有效期为 7 天。
+ 在生成客户端 ID 和客户端密钥期间，如果您选择“公共客户端”以及“授权码授予”，则刷新令牌仅在三个小时内有效，并且只能使用一次。
+ 您可以使用该连接器最多获取 100000 条记录。有关更多信息，请参阅 [Executing SuiteQL Queries Through REST Web Services](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157909186990.html)。
+ 创建分区时，每个分区都将以 1000 的倍数获取记录，将获取剩余记录的最后一个分区可能除外。
+ 对于项目、交易明细和交易会计明细对象，由于以下原因，连接器将不支持部分操作符：
+ 将 `EQUAL_TO`、`NOT_EQUAL_TO` 筛选运算符应用于日期类型的字段会得到不可靠的结果。
+ 将 `LESS_THAN_OR_EQUAL_TO` 筛选运算符应用于日期类型的字段会得到不可靠的结果，其行为类似于 `LESS_THAN` 运算符。
+ 将 `GREATER_THAN` 筛选运算符应用于 Date= 类型的字段会得到不可靠的结果，其行为类似于 `GREATER_THAN_OR_EQUAL_TO` 运算符。
+ 对于项目、交易明细、交易会计明细和自定义记录类型对象，布尔值采用 T/F 格式，而不是标准的 true/false。连接器将 t/f 值映射到 true/false，以确保数据的一致性。
# 在 AWS Glue Studio 中连接到 OpenSearch Service
AWS Glue 提供了对 Amazon OpenSearch Service 的内置支持。AWS Glue Studio 提供了直观的界面，以用于连接到 Amazon OpenSearch Service、编写数据集成作业以及在 AWS Glue Studio 无服务器 Spark 运行时系统上运行这些作业。此功能与 OpenSearch Service 无服务器不兼容。
AWS Glue Studio 为 Amazon OpenSearch Service 创建统一连接。有关更多信息，请参阅 [注意事项](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。
**Topics**
+ [创建 OpenSearch Service 连接](creating-opensearch-connection.md)
+ [创建 OpenSearch Service 源节点](creating-opensearch-source-node.md)
+ [创建 OpenSearch Service 目标节点](creating-opensearch-target-node.md)
+ [高级选项](#creating-opensearch-connection-advanced-options)
# 创建 OpenSearch Service 连接
**先决条件**
+ 确定您要从中读取的域端点 *aosEndpoint* 和端口 *aosPort*，或者按照 Amazon OpenSearch Service 文档中的说明创建资源。有关更多信息，请参阅《Amazon OpenSearch Service 开发人员指南》中的 [Creating and managing Amazon OpenSearch Service domains](https://docs.aws.amazon.com//opensearch-service/latest/developerguide/createupdatedomains.html)。
Amazon OpenSearch Service 域端点的默认格式为 https://search-*domainName*-*unstructuredIdContent*.*region*.es.amazonaws.com。有关如何确定域端点的更多信息，请参阅《Amazon OpenSearch Service 开发人员指南》中的 [Creating and managing Amazon OpenSearch Service domains](https://docs.aws.amazon.com//opensearch-service/latest/developerguide/createupdatedomains.html)。
确定或生成域的 HTTP 基本身份验证凭证（*aosUser* 和 *aosPassword*）。
**配置 OpenSearch Service 连接：**
1. 在 AWS Secrets Manager 中，使用您的 OpenSearch Service 凭证创建一个密钥。要在 Secrets Manager 中创建密钥，请按照 AWS Secrets Manager 文档中[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中的教程进行操作。创建密钥后，保留密钥名称 *secretName*，以供下一步使用。
+ 在选择**键/值对**时，请使用键 `USERNAME` 和值 *aosUser* 创建一个键值对。
+ 在选择**键/值对**时，请使用键 `PASSWORD` 和值 *aosPassword* 创建一个键值对。
1. 在 AWS Glue 控制台中，按照 [添加 AWS Glue 连接](console-connections.md) 中的步骤创建一个连接。创建连接后，保留连接名为 *connectionName*，以供未来在 AWS Glue 中使用。
+ 选择**连接类型**时，请选择 OpenSearch Service。
+ 选择域端点时，请提供 *aosEndpoint*。
+ 选择端口时，请提供 *aosPort*。
+ 选择 **AWS 密钥**时，请提供 *secretName*。
# 创建 OpenSearch Service 源节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue OpenSearch Service 连接，如上一节“[创建 OpenSearch Service 连接](creating-opensearch-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要读取的 OpenSearch Service 索引 *aosIndex*。
## 添加 OpenSearch Service 数据来源
**添加**数据来源 – OpenSearch Service** 节点：**
1. 选择 OpenSearch Service 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 OpenSearch Service 连接**。有关更多信息，请参阅之前的 [创建 OpenSearch Service 连接](creating-opensearch-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 提供**索引**，即您要读取的索引。
1. （可选）提供**查询**，即用于提供更多具体结果的 OpenSearch 查询。有关编写 OpenSearch 查询的更多信息，请参阅 [读取 OpenSearch Service 索引](aws-glue-programming-etl-connect-opensearch-home.md#aws-glue-programming-etl-connect-opensearch-read)。
1. 在**自定义 OpenSearch Service 属性**中，根据需要输入相关参数和值。
# 创建 OpenSearch Service 目标节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue OpenSearch Service 连接，如上一节“[创建 OpenSearch Service 连接](creating-opensearch-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要写入的 OpenSearch Service 索引 *aosIndex*。
## 添加 OpenSearch Service 数据目标
**添加**数据目标 – OpenSearch Service** 节点：**
1. 选择 OpenSearch Service 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 OpenSearch Service 连接**。有关更多信息，请参阅之前的 [创建 OpenSearch Service 连接](creating-opensearch-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 提供**索引**，即您要读取的索引。
1. 在**自定义 OpenSearch Service 属性**中，根据需要输入相关参数和值。
## 高级选项
您可以在创建 Amazon OpenSearch Service 节点时提供高级选项。这些选项与编程 Spark 脚本的 AWS Glue 时可用的选项相同。
请参阅[OpenSearch Service 连接](aws-glue-programming-etl-connect-opensearch-home.md)。
# 连接到 Okta
Okta API 是 Okta 的编程接口，用于管理大型或复杂的 Okta 账户和广告活动。如果您是 Okta 用户，则可以将 AWS Glue 连接到自己的 Okta 账户。然后，可以使用 Okta 作为 ETL 作业中的数据来源。通过运行这些作业，可在 Okta 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 对 Okta 的支持](okta-support.md)
+ [包含创建和使用连接的 API 操作的策略](okta-configuring-iam-permissions.md)
+ [配置 Okta](okta-configuring.md)
+ [配置 Okta 连接](okta-configuring-connections.md)
+ [从 Okta 实体读取内容](okta-reading-from-entities.md)
+ [Okta 连接选项参考](okta-connection-options.md)
+ [Okta 新账户和开发人员应用程序创建步骤](okta-create-account.md)
+ [限制](okta-connector-limitations.md)
# AWS Glue 对 Okta 的支持
AWS Glue 对 Okta 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Okta 中的数据。
**是否支持作为目标？**
否。
**支持的 Okta 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 控制台的用户。
# 配置 Okta
必须满足以下要求，才能使用 AWS Glue 与 Okta 进行数据往来传输：
## 最低要求
+ 拥有 Okta 账户。有关创建账户的更多信息，请参阅 [Okta 新账户和开发人员应用程序创建步骤](okta-create-account.md)。
+ Okta 账户已启用 API 访问权限。
+ 已在 Okta 账户中创建 OAuth2 API 集成。此集成提供 AWS Glue 在对账户进行身份验证调用时，用于安全访问数据的客户端凭证。有关更多信息，请参阅客户端应用程序创建步骤以及 OAuth2.0 凭证：Okta 新账户和开发人员应用程序创建步骤
+ 拥有 Okta 账户，其中包含 OktaApiToken。请参阅 [Okta 文档](https://developer.okta.com/docs/guides/create-an-api-token/main/#create-the-token)。
如果满足这些要求，就可以将 AWS Glue 连接到 Okta 账户。对于常见连接，无需在 Okta 中执行其他操作。
# 配置 Okta 连接
Okta 支持两种类型的身份验证机制：
+ OAuth 身份验证：Okta 支持 `AUTHORIZATION_CODE` 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Okta，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Okta 实例。
+ 用户可以选择在 Okta 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Okta，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关更多信息，请参阅[有关为授权码 OAuth 流创建关联应用程序的 Okta 公共文档](https://developers.google.com/workspace/guides/create-credentials)。
+ 自定义身份验证：
+ 有关生成自定义授权所需 API 密钥的 Okta 公共文档，请参阅 [Okta 文档](https://developer.okta.com/docs/guides/create-an-api-token/main/#create-the-token)。
要配置 Okta 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。
1. OAuth 身份验证：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
1. 对于自定义身份验证：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将 `OktaApiToken` 作为键。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在“连接”下，选择**创建连接**。
1. 选择**数据来源**时，请选择 Okta。
1. 提供 Okta 子域。
1. 选择 Okta 账户的 Okta 域 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. 选择身份验证类型以连接到数据来源。
1. 对于 OAuth2 身份验证类型，请提供 Okta 应用程序的**用户托管客户端应用程序 ClientId**。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 Okta 实体读取内容
**先决条件**
+ 要从中读取内容的 Okta 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 应用程序 | 支持 | 是 | 否 | 是 | 否 |
| 设备 | 支持 | 是 | 否 | 是 | 是 |
| 组 | 支持 | 是 | 是 | 是 | 是 |
| Users | 支持 | 是 | 是 | 是 | 是 |
| 用户类型 | 否 | 否 | 否 | 是 | 否 |
**示例**
```
okta_read = glueContext.create_dynamic_frame.from_options(
connection_type="Okta",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "applications",
"API_VERSION": "v1"
}
```
**Okta 实体和字段详细信息**
实体列表：
+ Application：[https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Application/](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Application/)
+ Device：[https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Device/)
+ Group：[https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/Group/)
+ User：[https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/User/)
+ User Type：[https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserType/](https://developer.okta.com/docs/api/openapi/okta-management/management/tag/UserType/)
**对查询进行分区**
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-02-06"`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
**示例**
```
okta_read = glueContext.create_dynamic_frame.from_options(
connection_type="okta",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "lastUpdated",
"API_VERSION": "v1",
"PARTITION_FIELD": "lastMembershipUpdated"
"LOWER_BOUND": "2022-08-10T10:28:46.000Z"
"UPPER_BOUND": "2024-08-10T10:28:46.000Z"
"NUM_PARTITIONS": "10"
}
```
# Okta 连接选项参考
以下是 Okta 的连接选项：
+ `ENTITY_NAME`（字符串）–（必填）用于读/写。Okta 中对象的名称。
+ `API_VERSION`（字符串）–（必填）用于读/写。要使用的 Okta Rest API 版本。示例：v1。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# Okta 新账户和开发人员应用程序创建步骤
在 Okta 上创建开发人员账户，以获取 Okta API 访问权限。免费的 Okta 开发人员账户可访问大部分关键的开发人员功能，以实现 Okt API 访问。
**在 Okta 上创建开发人员账户**
1. 导航到 [https://developer.okta.com/signup/](https://console.cloud.google.com)。
1. 输入账户信息、电子邮件、名字、姓氏和国家/地区。选择**我不是机器人**，然后选择**注册**。
1. 验证电子邮件将发送到注册邮箱 ID。电子邮件包含用于激活 Okta 开发人员账户的链接。选择**激活**。
1. 您将重定向到密码重置页面。输入新密码两次，然后选择**重置密码**。
1. 您将重定向到 Okta 开发人员账户控制面板。
**创建客户端应用程序和 OAuth 2.0 凭证**
1. 在开发人员控制面板中，选择创建应用程序集成。
![\[屏幕截图显示的是“创建 OAuth 客户端 ID”页面和“授权重定向 URI”部分。在此处添加 URI，并根据需要选择“添加 URI”。操作完成后选择“创建”。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/create-client-app-step-1.png)
1. 将显示**新建应用程序集成**窗口，并提供各种登录方法。选择 **OIDC – OpenID Connect**。
1. 向下滚动到“应用程序类型”部分。选择 **Web 应用程序**，然后选择**下一步**。
1. 在“新建 Web 应用程序集成”屏幕上，填写以下信息：
+ 应用程序集成名称：输入应用程序的名称。
+ 授予类型：请从列表中选择**授权码**和**刷新令牌**。
+ 登录重定向 URI：选择**添加 URI** 并添加 `https://{regioncode}.console.aws.amazon.com/appflow/oauth`。例如，如果正在使用 `us-west-2 (Oregon)`，则可添加 `https://us-east-1.console.aws.amazon.com/appflow/oauth`。
+ 受控访问权限：根据需要将应用程序分配给用户组，然后选择**保存**。
1. 客户端 ID 和客户端密钥现已生成。
# 限制
以下是 Okta 连接器的限制：
+ 对于“Applications”实体，只能应用一个筛选条件。如果应用多个筛选条件，则会返回 400 错误请求，并显示错误摘要“搜索条件无效”。
+ 仅搜索查询支持排序依据。例如，` http://dev-15940405.okta.com/api/v1/groups?search=type e.q. "OKTA_GROUP"&sortBy=lastUpdated&sortOrder=asc `
# 连接到 PayPal
PayPal 是一种支付系统，旨在方便各方进行在线转账，例如客户和在线供应商之间的转账。如果是 PayPal 用户，则账户包含有关交易的数据，例如付款人、付款日期和付款状态。可以使用 AWS Glue 将数据从 PayPal 传输到某些 AWS 服务或其他受支持的应用程序。
**Topics**
+ [AWS Glue 支持 PayPal](paypal-support.md)
+ [包含创建和使用连接的 API 操作的策略](paypal-configuring-iam-permissions.md)
+ [配置 PayPal](paypal-configuring.md)
+ [配置 PayPal 连接](paypal-configuring-connections.md)
+ [从 PayPal 实体读取内容](paypal-reading-from-entities.md)
+ [PayPal 连接选项](paypal-connection-options.md)
+ [PayPal 连接器的限制和说明](paypal-connector-limitations.md)
# AWS Glue 支持 PayPal
AWS Glue 对 PayPal 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 PayPal 中的数据。
**是否支持作为目标？**
否。
**支持的 PayPal API 版本**
支持以下 PayPal 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 控制台的用户。
# 配置 PayPal
必须满足以下要求，才能使用 AWS Glue 从 PayPal 传输数据：
## 最低要求
以下是最低要求：
+ 拥有一个包含客户端凭证的 PayPal 账户。
+ PayPal 账户拥有 API 访问权限和有效许可证。
如果满足这些要求，就可以将 AWS Glue 连接到 PayPal 账户。对于常见连接，无需在 PayPal 中执行其他操作。
# 配置 PayPal 连接
PayPal 支持 OAuth2 的客户端凭证授权类型。
+ 此授权类型被视为双足型 OAuth 2.0，因为客户端将其用于在用户环境之外获取访问令牌。AWS Glue 能够使用客户端 ID 和客户端密钥对由您定义的自定义服务提供的 PayPal API 进行身份验证。
+ 每项自定义服务均归仅限 API 的用户所有，该用户拥有一组角色和权限，可授权该服务执行特定操作。访问令牌与单项自定义服务相关联。
+ 这种授权类型会生成一个短期访问令牌，并且可以通过再次调用 `/v2/oauth2/token` 端点来续订。
+ 有关包含客户端凭证的 OAuth 2.0 的 PayPal 公共文档，请参阅 [Authentication](https://developer.paypal.com/api/rest/authentication/)。
要配置 PayPal 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的消费者密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 PayPal。
1. 提供想要连接到的 PayPal 实例的 `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` 的权限。
## 获取 OAuth 2.0 凭证
要调用 Rest API，需要用客户端 ID 和客户端密钥交换访问令牌。有关更多信息，请参阅 [Get started with PayPal REST APIs](https://developer.paypal.com/api/rest/)。
# 从 PayPal 实体读取内容
**先决条件**
要从中读取内容的 PayPal 对象。需要对象名称 `transaction`。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 交易 | 支持 | 是 | 否 | 是 | 是 |
**示例：**
```
paypal_read = glueContext.create_dynamic_frame.from_options(
connection_type="paypal",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "transaction",
"API_VERSION": "v1",
"INSTANCE_URL": "https://api-m.paypal.com"
}
```
**PayPal 实体和字段详细信息**：
具有静态元数据的实体：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/paypal-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`：分区的数量。
以下字段支持基于实体的分区：
| 实体名称 | 分区字段 | 数据类型 |
| --- | --- | --- |
| 交易 | transaction\$1initiation\$1date | 日期时间 |
示例：
```
paypal_read = glueContext.create_dynamic_frame.from_options(
connection_type="paypal",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "transaction",
"API_VERSION": "v1",
"PARTITION_FIELD": "transaction_initiation_date"
"LOWER_BOUND": "2024-07-01T00:00:00.000Z"
"UPPER_BOUND": "2024-07-02T00:00:00.000Z"
"NUM_PARTITIONS": "10"
}
```
# PayPal 连接选项
以下是 PayPal 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。PayPal 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 PayPal Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# PayPal 连接器的限制和说明
以下是 PayPal 连接器的限制或说明：
+ [PayPal 交易文档](https://developer.paypal.com/docs/api/transaction-search/v1/#search_get)中提到，已执行的交易最多需要三个小时才能在列表交易调用中显示。然而，据观察，实际花费的时间比文中提到的时间更长，具体取决于 [https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=last_refreshed_datetime](https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=last_refreshed_datetime)。此处的 `last_refreshed_datetime` 是从 API 获得数据所需的时间。
+ 如果 `last_refreshed_datetime` 小于请求的 `end_date`，`end_date` 就会等于 `last_refreshed_datetime`，因为我们只有到该时间点的数据。
+ `transaction_initiation_date` 字段是必须为 `transaction` 实体提供的筛选条件，该字段[支持的最大](https://developer.paypal.com/docs/transaction-search/#:~:text=The%20maximum%20supported%20date%20range%20is%2031%20days.)日期范围为 31 天。
+ 使用 `transaction_initiation_date` 字段以外的筛选条件（查询参数）调用 `transaction` 实体 API 请求时，预计不会在响应中获取 [https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=If%20you%20specify%20one%20or%20more%20optional%20query%20parameters%2C%20the%20ending_balance%20response%20field%20is%20empty.](https://developer.paypal.com/docs/api/transaction-search/v1/#search_get:~:text=If%20you%20specify%20one%20or%20more%20optional%20query%20parameters%2C%20the%20ending_balance%20response%20field%20is%20empty.) 字段的值。
# 连接到 Pendo
Pendo 为用户交互数据提供了丰富的数据存储功能。客户将用户交互数据传输到 AWS，如此就可以将此类数据与其他产品数据合并，进行额外的分析和控制面板制作，也能根据需要设置提醒。
**Topics**
+ [AWS Glue 对 Pendo 的支持](pendo-support.md)
+ [包含创建和使用连接的 API 操作的策略](pendo-configuring-iam-permissions.md)
+ [配置 Pendo](pendo-configuring.md)
+ [配置 Pendo 连接](pendo-configuring-connections.md)
+ [从 Pendo 实体读取内容](pendo-reading-from-entities.md)
+ [Pendo 连接选项](pendo-connection-options.md)
+ [限制](pendo-connector-limitations.md)
# AWS Glue 对 Pendo 的支持
AWS Glue 对 Pendo 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Pendo 中的数据。
**是否支持作为目标？**
否。
**支持的 Pendo 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 控制台的用户。
# 配置 Pendo
必须满足以下要求，才能使用 AWS Glue 从 Pendo 传输数据：
## 最低要求
+ 拥有 Pendo 账户，并已启用 `apiKey` 和 `write access`。
+ Pendo 账户拥有 API 访问权限和有效许可证。
如果满足这些要求，就可以将 AWS Glue 连接到 Pendo 账户。对于常见连接，无需在 Pendo 中执行其他操作。
# 配置 Pendo 连接
Pendo 支持自定义身份验证。
有关生成自定义身份验证所需 API 密钥的 Pendo 公共文档，请参阅 [Authentication – Pendo REST API Documentation](https://engageapi.pendo.io/?bash#getting-started)
要配置 Pendo 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
+ 对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将 `apiKey` 作为键。
**注意**
必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**数据来源**时，请选择 Pendo。
1. 提供要连接的 Pendo 实例的 `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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为附加网络连接。
# 从 Pendo 实体读取内容
**先决条件**
要从中读取内容的 Pendo 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
+ [功能](https://developers.pendo.io/docs/?bash#feature)
+ [Guide](https://developers.pendo.io/docs/?bash#guide)
+ [页面](https://developers.pendo.io/docs/?bash#page)
+ [报告](https://developers.pendo.io/docs/?bash#report)
+ [Report Data](https://developers.pendo.io/docs/?bash#return-report-contents-as-array-of-json-objects)
+ [Visitor](https://developers.pendo.io/docs/?bash#visitor)
+ [Account](https://developers.pendo.io/docs/?bash#entities)
+ [Event (事件)](https://developers.pendo.io/docs/?bash#events-grouped)
+ [Feature Event](https://developers.pendo.io/docs/?bash#events-grouped)
+ [Guide Event](https://developers.pendo.io/docs/?bash#events-ungrouped)
+ [Page Event](https://developers.pendo.io/docs/?bash#events-grouped)
+ [Poll Event](https://developers.pendo.io/docs/?bash#events-ungrouped)
+ [Track Event](https://developers.pendo.io/docs/?bash#events-grouped)
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 功能 | 否 | 否 | 否 | 是 | 否 |
| Guide | 否 | 否 | 否 | 是 | 否 |
| 页面 | 否 | 否 | 否 | 是 | 否 |
| 报告 | 否 | 否 | 否 | 是 | 否 |
| Report Data | 否 | 否 | 否 | 是 | 否 |
| Visitor（Aggregation API） | 是 | 否 | 是 | 是 | 否 |
| Account（Aggregation API） | 是 | 否 | 是 | 是 | 否 |
| Event（Aggregation API） | 是 | 否 | 是 | 是 | 否 |
| Feature Event（Aggregation API） | 是 | 否 | 是 | 是 | 是 |
| Guide Event（Aggregation API） | 是 | 否 | 是 | 是 | 是 |
| Account（Aggregation API） | 是 | 否 | 是 | 是 | 是 |
| Page Event（Aggregation API） | 是 | 否 | 是 | 是 | 是 |
| Poll Event（Aggregation API） | 是 | 否 | 是 | 是 | 是 |
| Track Event（Aggregation API） | 是 | 否 | 是 | 是 | 是 |
**示例**
```
Pendo_read = glueContext.create_dynamic_frame.from_options(
connection_type="glue.spark.Pendo",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "feature",
"API_VERSION": "v1",
"INSTANCE_URL": "instanceUrl"
}
```
## 对查询进行分区
如果您想在 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`：分区的数量。
下表描述实体分区字段支持详细信息：
| 实体名称 |
| --- |
| 事件 |
| Feature Event |
| Guide Event |
| Page Event |
| Poll Event |
| Track Event |
示例：
```
pendo_read = glueContext.create_dynamic_frame.from_options(
connection_type="glue.spark.pendo",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "event",
"API_VERSION": "v1",
"INSTANCE_URL": "instanceUrl"
"NUM_PARTITIONS": "10",
"PARTITION_FIELD": "appId"
"LOWER_BOUND": "4656"
"UPPER_BOUND": "7788"
}
```
# Pendo 连接选项
以下是 Pendo 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取/写入。Pendo 中对象的名称。
+ `INSTANCE_URL`（字符串）：（必填）有效的 Pendo 实例 URL，其中包含以下允许的值：
+ [默认](https://app.pendo.io/)
+ [欧洲](https://app.eu.pendo.io/)
+ [US1](https://us1.app.pendo.io/)
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Pendo 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。用于读取。要读取的分区数。
# 限制
以下是 Pendo 连接器的限制：
+ Pendo 不支持分页。
+ 仅聚合 API 对象（`Account`、`Event`、`Feature Event`、`Guide Events`、`Page Event`、`Poll Event`、`Track Event` 和 `Visitor`）支持筛选
+ DateTimeRange 是聚合 API 对象（`Event`、`Feature Event`、`Guide Events`、`Page Event`、`Poll Event,`、`Track Event`）的必填筛选条件参数
+ dayRange 时段将向下四舍五入为该时区时段的起始时间。例如，如果提供的筛选条件为 `2023-01-12T07:55:27.065Z`，则该时段将四舍五入至起始时间，也就是 `2023-01-12T00:00:00Z`。
# 连接到 Pipedrive
Pipedrive 是一个销售管线 CRM，旨在帮助小型企业管理潜在客户、跟踪销售活动以及完成更多交易。Pipedrive 让小型企业的销售团队能够：在一个统一的 CRM 销售工具中简化流程并整合销售数据。如果您是 Pipedrive 用户，则可以将 AWS Glue 连接到自己的 Pipedrive 账户。然后，您可以使用 Pipedrive 作为 ETL 作业中的数据来源。通过运行这些作业，可在 Pipedrive 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 对 Pipedrive 的支持](pipedrive-support.md)
+ [包含创建和使用连接的 API 操作的策略](pipedrive-configuring-iam-permissions.md)
+ [配置 Pipedrive](pipedrive-configuring.md)
+ [配置 Pipedrive 连接](pipedrive-configuring-connections.md)
+ [从 Pipedrive 实体读取内容](pipedrive-reading-from-entities.md)
+ [Pipedrive 连接选项参考](pipedrive-connection-options.md)
+ [限制](pipedrive-connector-limitations.md)
# AWS Glue 对 Pipedrive 的支持
AWS Glue 对 Pipedrive 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Pipedrive 中的数据。
**是否支持作为目标？**
否。
**支持的 Pipedrive 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 控制台的用户。
# 配置 Pipedrive
必须满足以下要求，才能使用 AWS Glue 从 Pipedrive 传输数据：
## 最低要求
+ 拥有 Pipedrive 账户。
+ Pipedrive 账户已启用 API 访问权限。
如果满足这些要求，就可以将 AWS Glue 连接到 Pipedrive 账户。对于常见连接，无需在 Pipedrive 中执行其他操作。
# 配置 Pipedrive 连接
Pipedrive 支持 OAuth2 的 AUTHORIZATION\$1CODE 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。默认情况下，创建连接的用户可以依赖于 AWS Glue 拥有的关联应用程序；在该应用程序中，除了 Pipedrive 实例 URL 之外，用户无需提供任何与 OAuth 相关的信息。AWS Glue 控制台会将用户重定向到 Pipedrive，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Pipedrive 实例。
+ 用户可以选择在 Pipedrive 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Pipedrive，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期为一小时，可以通过刷新令牌在不需要用户互动的情况下自动刷新。
+ 有关更多信息，请参阅[有关为 AUTHORIZATION\$1CODE OAuth 流创建关联应用程序的文档](https://developers.pipedrive.com/docs/api/v1/Oauth)。
要配置 Pipedrive 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。
1. 对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET 作为键。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 在“数据连接”下，选择**创建连接**。
1. 选择**数据来源**时，请选择 Pipedrive。
1. 提供 Pipedrive **实例 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. 提供要连接的 Pipedrive 的用户托管客户端应用程序 ClientId。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。选择**下一步**。
1. 提供 **connectionName**，然后选择**下一步**。
1. 在下一页上，选择**创建连接**。系统将要求您登录 Pipedrive。提供用户名和密码，然后选择**登录**。
1. 登录后，选择**继续使用应用程序**。连接现已就绪，随时可用。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 Pipedrive 实体读取内容
**先决条件**
+ 要从中读取内容的 Pipedrive 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 活动 | 支持 | 是 | 否 | 是 | 是 |
| 活动类型 | 否 | 否 | 否 | 是 | 否 |
| Call Logs | 否 | 否 | 否 | 是 | 否 |
| Currencies | 支持 | 是 | 否 | 是 | 否 |
| 交易 | 支持 | 是 | 是 | 是 | 是 |
| 线索 | 支持 | 是 | 是 | 是 | 否 |
| Lead Sources | 否 | 是 | 否 | 是 | 否 |
| Lead Labels | 否 | 否 | 否 | 否 | 否 |
| 备注 | 支持 | 是 | 是 | 是 | 是 |
| 组织 | 支持 | 是 | 否 | 是 | 是 |
| 权限集 | 是 | 否 | 否 | 是 | 否 |
| 人员 | 支持 | 是 | 是 | 是 | 是 |
| Pipelines | 否 | 是 | 否 | 是 | 否 |
| 产品 | 支持 | 是 | 否 | 是 | 是 |
| 角色 | 否 | 是 | 否 | 是 | 否 |
| 阶段 | 支持 | 是 | 否 | 是 | 否 |
| Users | 否 | 否 | 否 | 是 | 否 |
**示例**
```
pipedrive_read= glueContext.create_dynamic_frame.from_options(
connection_type="PIPEDRIVE",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "activites",
"API_VERSION": "v1"
}
```
**Pipedrive 实体和字段详细信息**
实体列表：
+ Activities：[ https://developers.pipedrive.com/docs/api/v1/Activities](https://developers.pipedrive.com/docs/api/v1/Activities)
+ Activity Type：[https://developers.pipedrive.com/docs/api/v1/ActivityTypes](https://developers.pipedrive.com/docs/api/v1/ActivityTypes)
+ Call Logs：[https://developers.pipedrive.com/docs/api/v1/CallLogs](https://developers.pipedrive.com/docs/api/v1/CallLogs)
+ Currencies：[https://developers.pipedrive.com/docs/api/v1/Currencies](https://developers.pipedrive.com/docs/api/v1/Currencies)
+ Deals：[https://developers.pipedrive.com/docs/api/v1/Deals](https://developers.pipedrive.com/docs/api/v1/Deals)
+ Leads：[https://developers.pipedrive.com/docs/api/v1/Leads](https://developers.pipedrive.com/docs/api/v1/Leads)
+ Lead Sources：[https://developers.pipedrive.com/docs/api/v1/LeadSources](https://developers.pipedrive.com/docs/api/v1/LeadSources)
+ Lead Labels：[https://developers.pipedrive.com/docs/api/v1/LeadLabels](https://developers.pipedrive.com/docs/api/v1/LeadLabels)
+ Notes：[https://developers.pipedrive.com/docs/api/v1/Notes](https://developers.pipedrive.com/docs/api/v1/Notes)
+ Organizations：[https://developers.pipedrive.com/docs/api/v1/Organizations](https://developers.pipedrive.com/docs/api/v1/Organizations)
+ Permission Sets：[ https://developers.pipedrive.com/docs/api/v1/PermissionSets](https://developers.pipedrive.com/docs/api/v1/PermissionSets)
+ Persons：[https://developers.pipedrive.com/docs/api/v1/Persons](https://developers.pipedrive.com/docs/api/v1/Persons)
+ Pipelines：[https://developers.pipedrive.com/docs/api/v1/Pipelines](https://developers.pipedrive.com/docs/api/v1/Pipelines)
+ Products：[https://developers.pipedrive.com/docs/api/v1/Products](https://developers.pipedrive.com/docs/api/v1/Products)
+ Roles：[https://developers.pipedrive.com/docs/api/v1/Roles](https://developers.pipedrive.com/docs/api/v1/Roles)
+ Stages：[https://developers.pipedrive.com/docs/api/v1/Stages](https://developers.pipedrive.com/docs/api/v1/Stages)
+ Users：[https://developers.pipedrive.com/docs/api/v1/Users](https://developers.pipedrive.com/docs/api/v1/Users)
| 实体 | 数据类型 | 支持的运算符 |
| --- | --- | --- |
| Activities、Deals、Notes、Organization、Persons 及 Products。 | 日期 | '=' |
| | 整数 | '=' |
| | 字符串 | '=' |
| | 布尔值 | '=' |
## 对查询进行分区
在 Pipedrive 中，“Activities”实体中只有一个字段（due\$1date）支持基于字段的分区。即“Date”字段。
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-02-06"`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
**示例**
```
pipedrive_read = glueContext.create_dynamic_frame.from_options(
connection_type="PIPEDRIVE",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "activites",
"API_VERSION": "v1",
"PARTITION_FIELD": "due_date"
"LOWER_BOUND": "2023-09-07T02:03:00.000Z"
"UPPER_BOUND": "2024-05-07T02:03:00.000Z"
"NUM_PARTITIONS": "10"
}
```
# Pipedrive 连接选项参考
以下是 Pipedrive 的连接选项：
+ `ENTITY_NAME`（字符串）–（必填）用于读/写。Pipedrive 中对象的名称。
+ `API_VERSION`（字符串）–（必填）用于读/写。要使用的 Pipedrive Rest API 版本。示例：v1。
+ `INSTANCE_URL`（字符串）：（必填）用户要在其中执行操作的实例的 URL。示例：v1。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# 限制
以下是 Pipedrive 连接器的限制：
+ Pipedrive 仅支持对一个实体（Activities）基于字段的分区。
+ Pipedrive 支持对 Activities、Deals、Notes、Persons、Organizations 和 Products 实体进行基于记录的分区。
+ 在 Deals 实体中，如果筛选条件值使用了无效值，则状态字段作为筛选条件将返回所有记录。
+ 在 Deals 实体中，不支持对多个字段排序。
+ 要获得性能数据，需要使用本地 AWS 账户。然而，由于存在本地刷新访问令牌限制，处理 1 GB 数据的 AWS Glue 作业执行失败。因此，我们对 179 MB 数据的性能测试进行了优化，上述结果也基于此优化得出。但是我们观察到，随着分区越来越多，相较于单个分区，SaaS 端点所需的处理时间也更多。我们就此咨询了 Pipedrive 支持团队，他们表示，Pipedrive 会无提示地限制请求并延迟响应。因此，运行包含大型数据集的 AWS Glue 作业或多次调用相同 API 端点时，可能会由于 Pipedrive API 的实施而导致超时问题。但是，随着分区数量增加，连接器和 shim 的响应时间会按预期缩短。
# 连接到 Productboard
Productboard 是一种产品管理系统，有助于产品团队更快地将合适的产品推向市场。3000 多家以产品为主导的现代企业（例如 Zendesk、UiPath 和 Microsoft）都使用 Productboard 来了解用户的真正需求，确定待构建内容的优先级，以及让所有人都凝聚在企业的路线图周围。
**Topics**
+ [AWS Glue 对 Productboard 的支持](productboard-support.md)
+ [包含创建和使用连接的 API 操作的策略](productboard-configuring-iam-permissions.md)
+ [配置 Productboard](productboard-configuring.md)
+ [配置 Productboard 连接](productboard-configuring-connections.md)
+ [从 Productboard 实体中读取](productboard-reading-from-entities.md)
+ [Productboard 连接选项](productboard-connection-options.md)
+ [创建 Productboard 账户](productboard-create-account.md)
+ [限制](productboard-connector-limitations.md)
# AWS Glue 对 Productboard 的支持
AWS Glue 对 Productboard 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Productboard 中的数据。
**是否支持作为目标？**
否。
**支持的 Productboard 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 控制台的用户。
# 配置 Productboard
必须满足以下要求，才能使用 AWS Glue 从 Productboard 传输数据：
## 最低要求
+ 拥有一个 Productboard 账户以及相应的电子邮件地址和密码。有关创建账户的更多信息，请参阅 [Creating a Productboard account](productboard-create-account.md)。
+ 必须创建一个可以访问 AWS Glue 服务的 AWS 账户。
+ 拥有 Productboard 账户的身份验证详细信息：如果想使用自定义身份验证，可以使用 JWT 令牌；如果想使用 OAuth2.0，可以使用客户端 ID 和密钥。
+ 如果用户想使用 `OAuth2.0`，请[在 Productboard 上注册应用程序](https://app.productboard.com/oauth2/applications/new)，然后按照 [How to integrate with Productboard via OAuth2 – 开发人员文档](https://developer.productboard.com/docs/how-to-integrate-with-productboard-via-oauth2-developer-documentation)中的说明设置应用程序。
如果满足这些要求，就可以将 AWS Glue 连接到 Productboard 账户。对于常见连接，无需在 Productboard 中执行其他操作。
# 配置 Productboard 连接
Productboard 支持自定义身份验证和 `OAuth2.0`。对于 `OAuth2.0`，Productboard 支持 `AUTHORIZATION_CODE` 授权类型。
+ 此授权类型为“三足型”`OAuth`，因其依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。默认情况下，创建连接的用户可以依赖于 AWS Glue 拥有的关联应用程序，在该应用程序中，除了 Productboard Client ID 和客户端密钥之外，用户无需提供任何与 `OAuth` 相关的信息。AWS Glue 控制台会将用户重定向到 Productboard，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Productboard 实例。
+ 用户仍然可以选择在 Productboard 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Productboard，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为 `AUTHORIZATION_CODE OAuth` 流创建关联应用程序的 Productboard 公共文档，请参阅 [How to integrate with Productboard via OAuth2 - developer documentation](https://developer.productboard.com/docs/how-to-integrate-with-productboard-via-oauth2-developer-documentation)。
要配置 Productboard 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
+ 对于 `OAuth` 身份验证：对于客户托管的关联应用程序：密钥应包含关联应用程序的使用者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
+ 对于 `Custom auth`：对于客户托管的关联应用程序：密钥应包含关联应用程序的 `JWT token`，并将 `access_token` 作为键。
**注意**
必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**数据来源**时，请选择 Productboard。
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. 选择身份验证类型以连接到数据来源：
+ 对于 `OAuth` 身份验证：提供 `Token URL` 和 Productboard 应用程序的 `User Managed Client Application ClientId`。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为附加网络连接。
# 从 Productboard 实体中读取
**先决条件**
要从中读取内容的 Productboard 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
+ [Abuse-reports](https://productboard.com/developer/marketing/api/campaign-abuse/)
+ [自动化](https://productboard.com/developer/marketing/api/automation/list-automations/)
+ [活动](https://productboard.com/developer/marketing/api/campaigns/list-campaigns/)
+ [Click-details](https://productboard.com/developer/marketing/api/link-clickers/)
+ [Lists](https://productboard.com/developer/marketing/api/link-clickers/)
+ [成员](https://productboard.com/developer/marketing/api/list-segment-members/)
+ [Open-details](https://productboard.com/developer/marketing/api/list-members/)
+ [Segments](https://productboard.com/developer/marketing/api/list-segments/)
+ [Stores](https://productboard.com/developer/marketing/api/ecommerce-stores/list-stores/)
+ [Unsubscribed](https://productboard.com/developer/marketing/api/unsub-reports/)
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 功能 | 支持 | 是 | 否 | 是 | 是 |
| 组件 | 否 | 是 | 否 | 是 | 否 |
| 产品 | 否 | 是 | 否 | 是 | 否 |
| Feature Statuses | 否 | 是 | 否 | 是 | 是 |
| Custom Field Definitions | 否 | 是 | 否 | 是 | 否 |
| Custom Field Values | 支持 | 是 | 否 | 是 | 否 |
**示例**
```
Productboard_read = glueContext.create_dynamic_frame.from_options(
connection_type="Productboard",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "feature",
"API_VERSION": "1"
}
```
**Productboard entity and field details**
+ [功能](https://developer.productboard.com/#tag/features)
+ [组件](https://developer.productboard.com/#tag/components)
+ [Feature statuses](https://developer.productboard.com/#tag/statuses)
+ [产品](https://developer.productboard.com/#tag/products)
+ [Custom fields definitions](https://developer.productboard.com/#tag/hierarchyEntitiesCustomFields)
+ [Custom fields values](https://developer.productboard.com/#tag/hierarchyEntitiesCustomFieldsValues)
# Productboard 连接选项
以下是 Productboard 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取/写入。Productboard 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Productboard Engage Rest API 版本。例如：3.0。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# 创建 Productboard 账户
1. 导航到 [Productboard 注册页面](https://app.productboard.com/)，输入电子邮件 ID 和密码，然后选择**登录**。
1. 在**账户名称**字段中，输入 Productboard 账户名称，然后选择**我同意隐私政策**复选框。
1. 在**立即创建工作区**页面上的**工作区 URL** 字段中，输入新工作区的 URL。然后选择**继续**进入下一页并提供其余的详细信息。
这会创建试用账户。可免费试用试用账户 15 天。试用期到期后，可以购买付费套餐。记下电子邮件地址、密码和工作区 URL。之后将需要这些信息来访问账户。
**注册 `OAuth2.0` 应用程序**
1. 导航到 [Productboard 登录页面](https://login.productboard.com/?locale=en)，输入电子邮件 ID 和密码，然后选择**登录**。
1. 选择右上角的**用户**图标，然后从下拉菜单中选择**账户和计费**。
1. 选择**其他**，然后从下拉菜单中选择**已注册的应用程序**。
1. 查找并选择**注册应用程序**。
1. 输入以下详细信息：
+ **应用程序名称**：应用程序的名称。
+ **公司/组织**：您的公司或组织名称。
+ **应用程序网站**：应用程序的网站。
+ **重定向 URI**：重定向 URI 模式是一个 URI 路径（或以逗号分隔的路径列表）；在登录流程完成后，Productboard 可以重定向（如果请求）到此路径。例如，`https://ap-southeast-2\\.console\\.aws\\.amazon\\.com`
1. 选择**创建**。
1. 将会显示**客户端 ID** 和**客户端密钥**。复制并将其保存在安全位置。然后选择**完成**。
**注意**
使用 AppFlow 或 AWS Glue 期间，客户端 ID 和客户端密钥字符串是用于与此连接器建立连接的凭证。
**检索 CustomAuth 凭证**
1. 导航到 [Productboard 登录页面](https://app.productboard.com/)，输入电子邮件 ID 和密码，然后选择**登录**。
您将重定向至主页。
1. 在主页上，导航到**工作区设置** > **集成** > **公有 API** > **访问令牌**。
**注意**
如果**公有 API** 部分不可见，则您的账户可能购买了基础套餐。访问 API 令牌至少需要购买专业版套餐。套餐功能和名称可能会随时更改。有关套餐的更多信息，请参阅 [Productboard 定价](https://www.productboard.com/pricing/)。
1. 选择 **\$1** 生成新令牌，并确保将其安全存储，以备将来参考。
**创建 `OAuth2.0` 凭证**
要使用 Productboard 连接器进行 `OAuth2.0` 身份验证，需要在 Productboard 平台上注册应用程序并生成 `Client ID` 和 `Client Secret`。
1. 导航到 [Productboard 登录页面](https://app.productboard.com/)，输入电子邮件 ID 和密码，然后选择**登录**。
1. 要使用 Productboard 账户注册新的 OAuth2 应用程序，请导航到 [Producboard](to register new OAuth2 application with your Productboard account) 页面。
1. 填写必填字段，并为要访问的每个实体选择必要的范围。
**注意**
您已选择以下四个范围，这四个范围是六个受支持的实体的必要范围。
1. **重定向 URL** 必须采用以下格式：`https://ap-southeast-2\\.console\\.aws\\.amazon\\.com`
**注意**
Appflow 重定向 URL 可能会随时更改。一旦可用，请更新 AWS Glue 平台的重定向 URL。
1. 将会显示**客户端 ID** 和**客户端密钥**。复制并将其保存在安全位置。
1. 可以按照 [How to Integrate with Productboard via OAuth2](https://developer.productboard.com/docs/how-to-integrate-with-productboard-via-oauth2-developer-documentation) 开发人员文档中的步骤设置和验证 `OAuth2`。
# 限制
以下是 Productboard 连接器的限制：
+ Productboard 不支持基于字段的分区或基于记录的分区。
# 连接到 QuickBooks
QuickBooks 是一款面向中小型企业的领先会计应用程序。QuickBooks 会计应用程序的历史可以追溯到 20 世纪 80 年代，是 Intuit 的首批产品之一，最初作为一款桌面软件推出。如今，QuickBooks 提供多种会计和商业财务应用程序，既可作为可安装软件使用，又可作为基于云的 SaaS 软件使用。若是 QuickBooks 用户，则可将 AWS Glue 连接到 QuickBooks 账户。然后，可以使用 QuickBooks 作为 ETL 作业中的数据来源。通过运行这些作业，可在 QuickBooks 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 支持 QuickBooks](quickbooks-support.md)
+ [包含创建和使用连接的 API 操作的策略](quickbooks-configuring-iam-permissions.md)
+ [配置 QuickBooks](quickbooks-configuring.md)
+ [配置 QuickBooks 连接](quickbooks-configuring-connections.md)
+ [从 QuickBooks 实体读取内容](quickbooks-reading-from-entities.md)
+ [QuickBooks 连接选项](quickbooks-connection-options.md)
+ [QuickBooks 连接器的限制和说明](quickbooks-connector-limitations.md)
# AWS Glue 支持 QuickBooks
AWS Glue 对 QuickBooks 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 QuickBooks 中的数据。
**是否支持作为目标？**
否。
**支持的 QuickBooks API 版本**
支持以下 QuickBooks API 版本：
+ v3
# 包含创建和使用连接的 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 控制台的用户。
# 配置 QuickBooks
必须满足以下要求，才能使用 AWS Glue 从 QuickBooks 传输数据：
## 最低要求
以下是最低要求：
+ 拥有一个 QuickBooks 账户。
+ QuickBooks 账户已启用 API 访问权限。
有关更多信息，请参阅 QuickBooks 文档中的以下主题：
+ [Create an Intuit Account](https://quickbooks.intuit.com/learn-support/en-us/help-article/account-management/create-intuit-user-account/L62kSFEOM_US_en_US)
+ [Create and start developing your app](https://developer.intuit.com/app/developer/qbo/docs/get-started/start-developing-your-app)
如果满足这些要求，就可以将 AWS Glue 连接到 QuickBooks 账户。对于常见连接，无需在 QuickBooks 中执行其他操作。
# 配置 QuickBooks 连接
QuickBooks 支持 OAuth2 的 AUTHIZATION\$1CODE 授权类型。该授权类型决定了 AWS Glue 如何与 QuickBooks 通信来请求访问数据。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。
+ 用户仍然可以选择在 QuickBooks 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 QuickBooks，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 QuickBooks 公共文档，请参阅 [Set up OAuth 2.0](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0)。
要配置 QuickBooks 连接，请执行以下操作：
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 QuickBooks。
1. 提供想要连接到的 QuickBooks 实例的实例 URL 和公司 ID。
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` 的权限。
# 从 QuickBooks 实体读取内容
**先决条件**
要从中读取内容的 QuickBooks 对象。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| Account | 支持 | 是 | 是 | 是 | 是 |
| 账单 | 支持 | 是 | 是 | 是 | 是 |
| 公司信息 | 否 | 否 | 否 | 是 | 否 |
| Customer | 支持 | 是 | 是 | 是 | 是 |
| 员工 | 支持 | 是 | 是 | 是 | 是 |
| Estimate | 支持 | 是 | 是 | 是 | 是 |
| 发票 | 支持 | 是 | 是 | 是 | 是 |
| Item | 支持 | 是 | 是 | 是 | 是 |
| Payment | 支持 | 是 | 是 | 是 | 是 |
| Preferences（首选项） | 否 | 否 | 否 | 是 | 否 |
| 盈亏 | 是 | 否 | 否 | 是 | 否 |
| 税务局 | 支持 | 是 | 是 | 是 | 是 |
| 供应商 | 支持 | 是 | 是 | 是 | 是 |
**示例：**
```
QuickBooks_read = glueContext.create_dynamic_frame.from_options(
connection_type="quickbooks",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Account",
"API_VERSION": "v3"
}
```
**QuickBooks 实体和字段详细信息**：
有关实体和字段详细信息的更多信息，请参阅：
+ [Account](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/account)
+ [Bill](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/bill)
+ [CompanyInfo](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/companyinfo)
+ [Customer](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/customer)
+ [Employee](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/employee)
+ [Estimate](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/estimate)
+ [Invoice](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/invoice)
+ [Item](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/item)
+ [Payment](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/payment)
+ [Preferences](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/preferences)
+ [ProfitAndLoss](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/profitandloss)
+ [TaxAgency](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/taxagency)
+ [Vendor](https://developer.intuit.com/app/developer/qbo/docs/api/accounting/most-commonly-used/vendor)
## 对查询进行分区
**基于字段的分区**：
在 QuickBooks 中，“整数”和“日期时间”数据类型字段支持基于字段的分区。
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于“日期时间”字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"2024-05-07T02:03:00.00Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
QuickBooks_read = glueContext.create_dynamic_frame.from_options(
connection_type="quickbooks",
connection_options={
"connectionName": "connectionName",
"REALMID": "12345678690123456789",
"ENTITY_NAME": "Account",
"API_VERSION": "v3",
"PARTITION_FIELD": "MetaData_CreateTime"
"LOWER_BOUND": "2023-09-07T02:03:00.000Z"
"UPPER_BOUND": "2024-05-07T02:03:00.000Z"
"NUM_PARTITIONS": "10"
}
```
**基于记录的分区**：
原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行：
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
QuickBooks_read = glueContext.create_dynamic_frame.from_options(
connection_type="quickbooks",
connection_options={
"connectionName": "connectionName",
"REALMID": "1234567890123456789",
"ENTITY_NAME": "Bill",
"API_VERSION": "v3",
"NUM_PARTITIONS": "10"
}
```
# QuickBooks 连接选项
以下是 QuickBooks 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。QuickBooks 中对象的名称。
+ `INSTANCE_URL`（字符串）：（必填）有效的 QuickBooks 实例 URL。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 QuickBooks Rest API 版本。
+ `REALM_ID`（字符串）：用于识别向其发送请求的单个 QuickBooks Online 公司的 ID。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# QuickBooks 连接器的限制和说明
以下是 QuickBooks 连接器的限制或说明：
+ 在 `taxAgency` API 中，无法按排序依据筛选。
# 连接到 REST API
AWS Glue 允许您配置可用于将 AWS Glue 连接到任何基于 REST API 的数据来源的 AWS Glue ConnectionType。这可以用作 ETL 作业中的数据来源。您可以运行这些作业，在基于 REST API 的数据来源和 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 支持 REST API](rest-api-support.md)
+ [包含用于注册连接类型和创建/使用连接的 API 操作的策略](rest-api-configuring-iam-permissions.md)
+ [配置 REST API ConnectionType](rest-api-configuring.md)
+ [配置 REST API 连接](rest-api-configuring-connections.md)
+ [教程：创建 REST API ConnectionType 和连接](rest-api-example.md)
+ [限制](rest-api-limitations.md)
# AWS Glue 支持 REST API
AWS Glue 支持 REST API，如下所示：
**是否支持作为来源？**
可以。您可以使用 AWS Glue ETL 作业从基于 REST API 的数据来源查询数据。
**是否支持作为目标？**
否。
# 包含用于注册连接类型和创建/使用连接的 API 操作的策略
以下示例 IAM 策略描述了在 AWS Glue ETL 作业中注册、创建、管理和使用 REST API 连接所需的权限。如果您要创建新角色，请创建包含以下内容的策略：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:RegisterConnectionType",
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:CreateConnection",
"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 控制台的用户。
如果在创建 REST API 连接时提供网络选项，则还必须在 IAM 角色中包含下面的操作：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
# 配置 REST API ConnectionType
在使用 AWS Glue 从基于 REST API 的数据来源传输数据之前，您必须满足以下要求：
## 最低要求
以下是最低要求：
+ 您已配置并注册了 AWS Glue REST API 连接类型。请参阅[连接到 REST API](https://docs.aws.amazon.com/glue/latest/dg/rest-api-connections.html)。
+ 如果使用 OAuth2 客户端凭证、授权码或者 JWT，请相应地配置客户端应用程序。
如果满足这些要求，就可以将 AWS Glue 连接到基于 REST API 的数据来源。通常情况下，REST API 端不需要进行其他配置。
# 配置 REST API 连接
要配置 AWS Glue REST API 连接器，您需要配置 AWS Glue 连接类型。此连接类型包含有关 REST 数据来源如何运行和解释身份验证、请求、响应、分页、验证和实体/元数据等属性的详细信息。有关 AWS Glue REST 连接类型所需属性的完整列表，请参阅 [RegisterConnectionType](https://docs.aws.amazon.com/glue/latest/webapi/API_DescribeConnectionType.html) API 和[连接到 REST API](https://docs.aws.amazon.com/glue/latest/dg/rest-api-connections.html) 的步骤。
创建 REST API 连接器时，需要以下策略以允许相关操作：
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:RegisterConnectionType",
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:CreateConnection",
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
# 教程：创建 REST API ConnectionType 和连接
**连接到 Foo REST API**
我们将为 Foo REST API 创建 AWS Glue REST API 连接类型和相应的 AWS Glue 连接。此 API 具有下面的属性（可从 REST API 文档中检索）。
+ **实例 URL**：https://foo.cloud.com/rest/v1。
+ **身份验证类型**：OAuth2（客户端凭证）。
+ **REST 方法**：GET。
+ **分页类型**：在请求的查询参数中放置“limit”和“offset”属性的偏移量。
+ **支持的实体**：
+ **Bar**：相对路径 [/bar.json]。
+ **Baz**：相对路径 [/baz.json]。
获得所有详细信息后，我们就可以开始创建与 Foo REST API 的 AWS Glue 连接了。
**要创建 REST API 连接，请执行下列操作**：
1. 使用 AWS API、CLI 或 SDK 调用 RegisterConnectionType API 来在 AWS Glue 中创建 REST API 连接类型。这将在 AWS Glue 中创建新的 ConnectionType 资源。
```
{
"ConnectionType": "REST-FOO-CONNECTOR",
"IntegrationType": "REST",
"Description": "AWS Glue Connection Type for the FOO REST API",
"ConnectionProperties": {
"Url": {
"Name": "Url",
"Required": true,
"DefaultValue": "https://foo.cloud.com/rest/v1",
"PropertyType": "USER_INPUT"
}
},
"ConnectorAuthenticationConfiguration": {
"AuthenticationTypes": ["OAUTH2"],
"OAuth2Properties": {
"OAuth2GrantType": "CLIENT_CREDENTIALS"
}
},
"RestConfiguration": {
"GlobalSourceConfiguration": {
"RequestMethod": "GET",
"ResponseConfiguration": {
"ResultPath": "$.result",
"ErrorPath": "$.error.message"
},
"PaginationConfiguration": {
"OffsetConfiguration": {
"OffsetParameter": {
"Key": "offset",
"PropertyLocation": "QUERY_PARAM"
},
"LimitParameter": {
"Key": "limit",
"PropertyLocation": "QUERY_PARAM",
"DefaultValue": "50"
}
}
}
},
"ValidationEndpointConfiguration": {
"RequestMethod": "GET",
"RequestPath": "/bar.json?offset=1&limit=10"
},
"EntityConfigurations": {
"bar": {
"SourceConfiguration": {
"RequestMethod": "GET",
"RequestPath": "/bar.json",
"ResponseConfiguration": {
"ResultPath": "$.result",
"ErrorPath": "$.error.message"
}
},
"Schema": {
"name": {
"Name": "name",
"FieldDataType": "STRING"
},
"description": {
"Name": "description",
"FieldDataType": "STRING"
},
"id": {
"Name": "id",
"FieldDataType": "STRING"
},
"status": {
"Name": "status",
"FieldDataType": "STRING"
}
}
}
}
}
}
```
1. 在 AWS Secrets Manager 中，创建密钥。密钥应包含关联应用程序的使用者密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
**注意**
您必须在 AWS Glue 中为每个连接创建密钥
1. 使用 AWS API、CLI 或 SDK 调用 CreateConnection API 来创建 AWS Glue 连接。
1. 将步骤 1 中的 REST 连接类型名称引用为“ConnectionType”。
1. 提供 InstanceUrl 以及在 AWS Glue ConnectionType 注册过程中定义的任何其他 ConnectionProperties。
1. 从配置的身份验证类型中进行选择。REST API Foo 使用授权类型为 ClientCredentials 的 OAuth2。
1. 提供 **SecretArn** 和配置的其他 **AuthenticationProperties**。例如，我们已将 `OAUTH2` 配置为 AuthenticationType，因此我们将在 CreateConnectionInput 中设置“OAuth2Properties”。这将需要“OAuth2GrantType”、“TokenUrl”和“OAuth2ClientApplication”等属性。
1. 发出 CreateConnection 请求，这将创建 AWS Glue 连接。
```
{
"ConnectionInput": {
"Name": "ConnectionFooREST",
"ConnectionType": "REST-FOO-CONNECTOR",
"ConnectionProperties": {},
"ValidateCredentials": true,
"AuthenticationConfiguration": {
"AuthenticationType": "OAUTH2",
"SecretArn": "arn:aws:secretsmanager:::secret:",
"OAuth2Properties": {
"OAuth2GrantType": "CLIENT_CREDENTIALS",
"TokenUrl": "https://foo.cloud.com/oauth/token",
"OAuth2ClientApplication": {
"UserManagedClientApplicationClientId": "your-managed-client-id"
}
}
}
}
}
```
# 限制
下面是 REST API 连接器的限制
+ REST API 连接器只能通过 AWS API、CLI 或者 SDK 使用。不能通过控制台配置 REST 连接器。
+ AWS Glue REST ConnectionType 只能配置为从基于 REST API 的数据来源读取数据。该连接只能用作 AWS Glue ETL 作业中的来源。
+ 不支持筛选和分区。
+ 不支持选择字段。
# 连接到 Salesforce
Salesforce 提供客户关系管理（CRM）软件，可在销售、客户服务、电子商务等方面为您提供帮助。如果您是 Salesforce 用户，可以将 AWS Glue 连接到您的 Salesforce 账户。然后，您可以使用 Salesforce 作为 ETL 作业中的数据来源或目标。通过运行这些作业，可在 Salesforce 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 对 Salesforce 的支持](salesforce-support.md)
+ [包含创建和使用连接的 API 操作的策略](salesforce-configuring-iam-permissions.md)
+ [配置 Salesforce](salesforce-configuring.md)
+ [应用系统管理员配置文件](#salesforce-configuring-apply-system-admin-profile)
+ [配置 Salesforce 连接](salesforce-configuring-connections.md)
+ [从 Salesforce 读取](salesforce-reading-from-entities.md)
+ [写入 Salesforce](salesforce-writing-to.md)
+ [Salesforce 连接选项](salesforce-connection-options.md)
+ [Salesforce 连接器的限制](salesforce-connector-limitations.md)
+ [为 Salesforce 设置授权代码流](salesforce-setup-authorization-code-flow.md)
+ [为 Salesforce 设置 JWT 持有者 OAuth 流程](salesforce-setup-jwt-bearer-oauth.md)
# AWS Glue 对 Salesforce 的支持
AWS Glue 按如下方式支持 Salesforce：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业查询 Salesforce 中的数据。
**是否支持作为目标？**
是。您可以使用 AWS Glue ETL 作业将记录写入 Salesforce。
**支持的 Salesforce API 版本**
支持以下 Salesforce API 版本
+ v58.0
+ v59.0
+ v60.0
# 包含创建和使用连接的 API 操作的策略
以下示例 IAM 策略描述了在 AWS Glue ETL 作业中创建、管理和使用 Salesforce 连接所需的权限。如果您要创建新角色，请创建包含以下内容的策略：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue",
"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 连接时提供网络选项，则还必须在 IAM 角色中包含下面的操作：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
有关零 ETL 的 Salesforce 连接，请参阅[零 ETL 先决条件](https://docs.aws.amazon.com/glue/latest/dg/zero-etl-prerequisites.html)。
有关零 ETL 的 Salesforce 连接，请参阅[零 ETL 先决条件](https://docs.aws.amazon.com/glue/latest/dg/zero-etl-prerequisites.html)。
# 配置 Salesforce
您必须满足以下要求，才能使用 AWS Glue 与 Salesforce 进行数据往来传输：
## 最低要求
以下是最低要求：
+ 您有一个 Salesforce 账户。
+ 您的 Salesforce 账户已启用 API 访问权限。默认情况下，Enterprise、Unlimited、Developer 和 Performance 版已启用 API 访问权限。
如果您满足这些要求，就可以将 AWS Glue 连接到您的 Salesforce 账户。AWS Glue 会使用 AWS 托管式关联应用程序处理其余要求。
## 适用于 Salesforce 的 AWS 托管式关联应用程序
AWS 托管式互联应用程序可帮助您以更少的步骤创建 Salesforce 连接。在 Salesforce 中，互联应用程序是一个框架，它授权外部应用程序（例如 AWS Glue）使用 OAuth 2.0 访问您的 Salesforce 数据。要使用 AWS 托管式互联应用程序，请使用 AWS Glue 控制台创建 Salesforce 连接。配置连接时，请将 **OAuth 授权类型**设置为**授权代码**，并选中**使用 AWS 托管客户端应用程序**复选框。
保存连接时，您将被重定向到 Salesforce 以登录并批准 AWS Glue 访问您的 Salesforce 账户。
## 应用系统管理员配置文件
在 Salesforce 中，按照以下步骤应用系统管理员配置文件：
1. 在 Salesforce 中，导航至**设置 > 连接的应用程序 > 连接的应用程序 OAuth 使用情况**。
1. 在连接的应用程序列表中，找到 AWS Glue 并选择**安装**。如果需要，则请选择**解锁**。
1. 导航至**设置 > 管理连接的应用程序，然后选择 AWS Glue**。在 OAuth 策略下，选择**管理员批准的用户已获得预授权**，然后选择**系统管理员**配置文件。此操作仅允许具有系统管理员配置文件的用户访问 AWS Glue。
## 应用系统管理员配置文件
在 Salesforce 中，按照以下步骤应用系统管理员配置文件：
1. 在 Salesforce 中，导航至**设置 > 连接的应用程序 > 连接的应用程序 OAuth 使用情况**。
1. 在连接的应用程序列表中，找到 AWS Glue 并选择**安装**。如果需要，则请选择**解锁**。
1. 导航至**设置 > 管理连接的应用程序，然后选择 AWS Glue**。在 OAuth 策略下，选择**管理员批准的用户已获得预授权**，然后选择**系统管理员**配置文件。此操作仅允许具有系统管理员配置文件的用户访问 AWS Glue。
# 配置 Salesforce 连接
要配置 Salesforce 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于JWT\$1TOKEN 授权类型，密钥应包含 JWT\$1TOKEN 密钥及其值。
1. 对于 AuthorizationCode 授权类型：
1. 对于 AWS 托管式互联应用程序，必须提供一个空密钥或具有某些临时值的密钥。
1. 对于客户管理的互联应用程序，密钥应包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键的互联应用程序`Consumer Secret`。
1. 注意：您必须在 AWS Glue 中为您的连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择“Salesforce”。
1. 提供您想要连接到的 Salesforce 实例的 INSTANCE\$1URL。
1. 提供 Salesforce 环境。
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. 选择要用于连接的 OAuth2 授权类型。授权类型决定了 AWS Glue 如何与 Salesforce 通信以请求访问您的数据。您选择的授权类型会影响您在创建连接之前必须满足的要求。您可以选择以下任一类型：
+ **JWT\$1BEARER 授权类型**：此授权类型非常适合自动化场景，因为它允许预先创建一个 JSON Web 令牌（JWT），并附带特定用户在 Salesforce 实例中的权限。创建者可以控制 JWT 的有效期。AWS Glue 能够使用 JWT 来获取用于调用 Salesforce API 的访问令牌。
此流程要求用户已在其 Salesforce 实例中创建关联的应用程序，以便为用户发放基于 JWT 的访问令牌。
有关为 JWT 持有者 OAuth 流程创建关联应用程序的信息，请参阅[用于服务器到服务器集成的 OAuth 2.0 JWT 持有者流程](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm)。要使用 Salesforce 关联应用程序设置 JWT 持有者流程，请参阅[为 Salesforce 设置 JWT 持有者 OAuth 流程](salesforce-setup-jwt-bearer-oauth.md)。
+ **AUTHORIZATION\$1CODE 授权类型**：此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。默认情况下，创建连接的用户可以依赖于 AWS Glue 关联应用程序（AWS Glue 托管客户端应用程序），在该应用程序中，除了 Salesforce 实例 URL 之外，用户无需提供任何与 OAuth 相关的信息。AWS Glue 控制台会将用户重定向到 Salesforce，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Salesforce 实例。
用户仍然可以选择在 Salesforce 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Salesforce，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
有关为授权码 OAuth 流程创建互联应用程序的信息，请参阅[为 Salesforce 设置授权代码流](salesforce-setup-authorization-code-flow.md)。
1. 选择您想要在 AWS Glue 中用于此连接的 `secretName`，以存储 OAuth 2.0 令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
1. 如果提供网络选项，则还授予 IAM 角色以下权限：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DescribeNetworkInterfaces",
"ec2:DeleteNetworkInterface"
],
"Resource": "*"
}
]
}
```
------
## 使用 AWS CLI 配置 Salesforce 连接
您可以使用 AWS CLI 创建 Salesforce 连接：
```
aws glue create-connection --connection-input \
"{\"Name\": \"salesforce-conn1\",\"ConnectionType\": \"SALESFORCE\",\"ConnectionProperties\": {\"ROLE_ARN\": \"arn:aws:iam::123456789012:role/glue-role\",\"INSTANCE_URL\": \"https://example.my.salesforce.com\"},\"ValidateCredentials\": true,\"AuthenticationConfiguration\": {\"AuthenticationType\": \"OAUTH2\",\"SecretArn\": \"arn:aws:secretsmanager:us-east-1:123456789012:secret:salesforce-conn1-secret-IAmcdk\",\"OAuth2Properties\": {\"OAuth2GrantType\": \"JWT_BEARER\",\"TokenUrl\": \"https://login.salesforce.com/services/oauth2/token\"}}}" \
--endpoint-url https://glue.us-east-1.amazonaws.com \
--region us-east-1
```
# 从 Salesforce 读取
**先决条件**
您要从中读取内容的 Salesforce sObject。您将需要 `Account`、`Case` 或 `Opportunity` 等对象名称。
**示例：**
```
salesforce_read = glueContext.create_dynamic_frame.from_options(
connection_type="salesforce",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Account",
"API_VERSION": "v60.0"
}
)
```
## 对查询进行分区
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于日期或时间戳字段，连接器接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"TIMESTAMP \"1707256978123\""
"TIMESTAMP '2018-01-01 00:00:00.000 UTC'"
"TIMESTAMP \"2018-01-01 00:00:00 Pacific/Tahiti\""
"TIMESTAMP \"2018-01-01 00:00:00\""
"TIMESTAMP \"-123456789\" Pacific/Tahiti"
"TIMESTAMP \"1702600882\""
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
+ `TRANSFER_MODE`：支持两种模式：`SYNC` 和 `ASYNC`。默认值为 `SYNC`。设置为 `ASYNC` 时，将使用 Bulk API 2.0 Query 进行处理。
示例：
```
salesforce_read = glueContext.create_dynamic_frame.from_options(
connection_type="salesforce",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Account",
"API_VERSION": "v60.0",
"PARTITION_FIELD": "SystemModstamp",
"LOWER_BOUND": "TIMESTAMP '2021-01-01 00:00:00 Pacific/Tahiti'",
"UPPER_BOUND": "TIMESTAMP '2023-01-10 00:00:00 Pacific/Tahiti'",
"NUM_PARTITIONS": "10",
"TRANSFER_MODE": "ASYNC"
}
)
```
## FILTER\$1PREDICATE 选项
**FILTER\$1PREDICATE**：这是一个可选参数。此选项用于查询筛选。
**FILTER\$1PREDICATE** 示例：
```
Case 1: FILTER_PREDICATE with single criterion
Examples:
LastModifiedDate >= TIMESTAMP '2025-04-01 00:00:00 Pacific/Tahiti'
LastModifiedDate <= TIMESTAMP "2025-04-01 00:00:00"
LastModifiedDate >= TIMESTAMP '2018-01-01 00:00:00.000 UTC'
LastModifiedDate <= TIMESTAMP "-123456789 Pacific/Tahiti"
LastModifiedDate <= TIMESTAMP "1702600882"
Case 2: FILTER_PREDICATE with multiple criteria
Examples:
LastModifiedDate >= TIMESTAMP '2025-04-01 00:00:00 Pacific/Tahiti' AND Id = "0012w00001CotGiAAJ"
LastModifiedDate >= TIMESTAMP "1702600882" AND Id = "001gL000002i26MQAQ"
Case 3: FILTER_PREDICATE single criterion with LIMIT
Examples:
LastModifiedDate >= TIMESTAMP "1702600882" LIMIT 2
Case 4: FILTER_PREDICATE with LIMIT
Examples:
LIMIT 2
```
# 写入 Salesforce
**先决条件**
您要向其中写入内容的 Salesforce sObject。您将需要 `Account`、`Case` 或 `Opportunity` 等对象名称。
Salesforce 连接器支持四种写入操作：
+ INSERT
+ UPSERT
+ UPDATE
+ DELETE
使用 `UPSERT` 写入操作时，必须提供 `ID_FIELD_NAMES` 选项以指定记录的外部 ID 字段。
您还能添加连接选项：
+ `TRANSFER_MODE`：支持两种模式：`SYNC` 和 `ASYNC`。默认值为 `SYNC`。设置为 `ASYNC` 时，将使用 Bulk API 2.0 Ingest 进行处理。
+ `FAIL_ON_FIRST_ERROR`：默认值为 `FALSE`，这意味着即使有一些失败的写入记录，AWS Glue 作业仍将继续处理所有数据。设置为 `TRUE` 时，如果有任何失败的写入记录，则 AWS Glue 作业将失败，并且不会继续处理。
**示例**
```
salesforce_write = glueContext.write_dynamic_frame.from_options(
frame=frameToWrite,
connection_type="salesforce",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Account",
"API_VERSION": "v60.0",
"WRITE_OPERATION": "INSERT",
"TRANSFER_MODE": "ASYNC",
"FAIL_ON_FIRST_ERROR": "true"
}
)
```
# Salesforce 连接选项
Salesforce 连接器支持以下连接选项：
+ `ENTITY_NAME`（字符串）–（必填）用于读/写。您在 Salesforce 中的对象的名称。
+ `API_VERSION`（字符串）–（必填）用于读/写。您想要使用的 Salesforce Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
提供筛选器谓词时，仅支持 `AND` 运算符。目前不支持 `OR` 和 `IN` 等其他运算符。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `IMPORT_DELETED_RECORDS`（字符串）– 默认：FALSE。用于读取。在查询时获取删除记录。
+ `WRITE_OPERATION`（字符串）– 默认：INSERT。用于写入。值应为 INSERT、UPDATE、UPSERT、DELETE。
+ `ID_FIELD_NAMES`（字符串）– 默认：null。UPDATE 和 UPSERT 必需。
# Salesforce 连接器的限制
以下是 Salesforce 连接器的限制：
+ 我们只支持 Spark SQL，不支持 Salesforce SOQL。
+ 不支持作业书签。
+ Salesforce 字段名称区分大小写。写入 Salesforce 时，数据必须与 Salesforce 中定义的字段的大小写匹配。
# 为 Salesforce 设置授权代码流
请参阅 Salesforce 公共文档，以了解如何启用 OAuth 2.0 授权代码流。
要配置互联应用程序，请执行以下操作：
1. 激活**启用 OAuth 设置**复选框。
1. 在**回调 URL** 文本字段中，为 AWS Glue 输入一个或多个重定向 URL。
重定向 URL 采用以下格式：
https://*region*.console.aws.amazon.com/gluestudio/oauth
在此 URL 中，*region* 是您使用 AWS Glue 从 Salesforce 传输数据的 AWS 区域的代码。例如，美国东部（弗吉尼亚州北部）区域的代码为 `us-east-1`。对于该区域，URL 如下：
https://us-east-1.console.aws.amazon.com/gluestudio/oauth
有关 AWS Glue 支持的 AWS 区域及其代码，请参阅《*AWS 一般参考*》中的 [AWS Glue endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/glue.html)。
1. 激活 **Web 服务器流需要密钥**复选框。
1. 在**可用的 OAuth 范围**列表中，添加以下范围：
+ 通过 API (api) 管理用户数据
+ 访问自定义权限 (custom\$1permissions)
+ 访问身份 URL 服务（id、profile、email、address、phone）
+ 访问唯一用户标识符 (openid)
+ 随时执行请求（refresh\$1token、offline\$1access）
1. 将互联应用程序的刷新令牌策略设置为**刷新令牌在撤销之前一直有效**。否则，当您的刷新令牌过期时，您的作业将会失败。有关如何检查和编辑刷新令牌策略的更多信息，请参阅 Salesforce 文档中的[管理连接的应用程序的 OAuth 访问策略](https://help.salesforce.com/articleView?id=connected_app_manage_oauth.htm)。
# 为 Salesforce 设置 JWT 持有者 OAuth 流程
要了解如何启用与 [OAuth 2.0 JSON 网络令牌](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm)的服务器到服务器集成，请参阅 Salesforce 公开文档。
在 Salesforce 中创建 JWT 并适当配置互联应用程序后，您可以使用在 Secrets Manager 密钥中设置的 `JWT_TOKEN` 键创建新的 Salesforce 连接。创建连接时，请将 OAuth 授予类型设置为 **JWT 持有者令牌**。
# 连接到 Salesforce Marketing Cloud
Salesforce Marketing Cloud 是一家营销自动化和分析软件供应商，其软件产品用于进行电子邮件、移动、社交及在线营销。该供应商还提供咨询和实施服务。Salesforce Marketing Cloud 用户可以将 AWS Glue 连接到 Salesforce Marketing Cloud 账户。然后可以使用 Salesforce Marketing Cloud 作为 ETL 作业中的数据来源或目的地。通过运行这些作业，可在 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
您必须满足以下要求，才能使用 AWS Glue 从 Salesforce Marketing Cloud 传输数据：
## 最低要求
以下是最低要求：
+ 您有一个 Salesforce Marketing Cloud 账户。有关更多信息，请参阅 [创建 Salesforce Marketing Cloud 账户](#salesforce-marketing-cloud-configuring-creating-salesforce-marketing-cloud-account)。
+ 您的 Salesforce Marketing Cloud 账户已启用 API 访问权限。默认情况下，Enterprise、Unlimited、Developer 和 Performance 版已启用 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_cn/glue/latest/dg/images/sfmc-platform-tools.png)
1. 在**已安装的软件包**页面上，单击右上角的**新建**。提供该软件包的名称和描述。
保存该软件包。保存该软件包后，您可以查看软件包详细信息。
1. 在软件包**详细信息**页面的**组件**部分下，选择**添加组件**。
![\[\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/sfmc-add-component.png)
1. 选择**组件类型**为“API 集成”，然后单击**下一步**。
1. 选择**集成类型**为“服务器到服务器”（具有客户端凭证 OAuth 授权类型），然后单击**下一步**。
1. 根据您的要求添加范围，然后单击**保存**。
# 配置 Salesforce Marketing Cloud 连接
Salesforce Marketing Cloud 支持 OAuth2 的客户端凭证授权类型。
+ 此授权类型被视为双足型 OAuth 2.0，因为客户端将其用于在用户环境之外获取访问令牌。AWS Glue 能够使用客户端 ID 和客户端密钥对由您定义的自定义服务提供的 Salesforce Marketing Cloud API 进行身份验证。
+ 每项自定义服务均归仅限 API 的用户所有，该用户拥有一组角色和权限，可授权该服务执行特定操作。访问令牌与单项自定义服务相关联。
+ 这种授权类型会生成一个短期有效的访问令牌，并且可以通过调用身份端点来续订。
+ 有关包含客户端凭证的 OAuth 2.0 的 Salesforce Marketing Cloud 公共文档，请参阅 [Set Up Your Development Environment for Enhanced Packages](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 中，按照以下步骤在**数据连接**下创建连接：
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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Salesforce Marketing Cloud 实体中读取
**先决条件**
您要从中读取内容的 Salesforce Marketing Cloud 对象。您将需要 `Activity` 或 `Campaigns` 等对象名称。下表显示支持的实体。
**源支持的实体**：
| 实体 | 接口 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 SELECT \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- | --- |
| 事件通知回调 | REST | 否 | 否 | 否 | 是 | 否 |
| 种子列表 | REST | 否 | 是 | 否 | 是 | 否 |
| 设置 | REST | 支持 | 是 | 否 | 是 | 否 |
| 域验证 | REST | 支持 | 是 | 是 | 是 | 否 |
| 对象嵌套标签 | REST | 是 | 否 | 否 | 是 | 否 |
| 联系人 | REST | 否 | 是 | 否 | 是 | 否 |
| 事件通知订阅 | REST | 否 | 否 | 否 | 是 | 否 |
| 消息收发 | REST | 否 | 是 | 否 | 是 | 否 |
| 活动 | SOAP | 否 | 否 | 否 | 是 | 是 |
| 退回事件 | SOAP | 否 | 否 | 否 | 是 | 是 |
| 单击事件 | SOAP | 否 | 否 | 否 | 是 | 是 |
| 内容区域 | SOAP | 否 | 否 | 否 | 是 | 是 |
| 数据扩展 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 电子邮件 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 转发的电子邮件事件 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 转发电子邮件选择加入事件 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 链接 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 链接发送 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 列表 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 列出订阅用户 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 未发送的事件 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 公开事件 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 发送 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 已发送事件 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 订阅者 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 调查事件 | SOAP | 否 | 是 | 否 | 是 | 是 |
| 取消订阅事件 | 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_cn/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_cn/glue/latest/dg/salesforce-marketing-cloud-reading-from-entities.html)
## 对查询进行分区
在 Salesforce Marketing Cloud 中，整数和日期时间数据类型字段支持基于字段的分区。
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `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 字段。
**目的地支持的实体**：
| 实体 | 优先级 | 接口（REST、SOAP 等） | 是否可以插入 | 是否可以更新 | 是否可以更新插入 |
| --- | --- | --- | --- | --- | --- |
| 市场活动 | P0 | REST | 是，单条 | 是，单条 | N |
| 内容素材 | P0 | REST | 是，单条、批量 | 是，单条 | N |
| 联系人 | P1 | REST | 是，单条 | 是，单条 | N |
| 域验证 | P1 | REST | 是，单条 | 是，单条、批量 | N |
| 事件通知回调 | P1 | REST | 是，单条 | 是，单条 | N |
| 事件通知订阅 | P1 | REST | 是，单条 | 是，单条 | N |
| 消息收发 | P1 | REST | 是，单条 | N | N |
| 对象嵌套标签 | P2 | REST | 是，单条 | 是，单条 | N |
| 种子列表 | P1 | REST | 是，单条 | 是，单条 | N |
| 设置 | P1 | REST | 是，单条 | 是，单条 | N |
| 数据扩展 | P0 | SOAP | 是，单条 | 是，单条 | 是，单条 |
| 电子邮件 | P0 | SOAP | 是，单条 | 是，单条 | N |
| 列表 | P0 | SOAP | 是，单条 | 是，单条 | N |
| 发送 | P0 | SOAP | 是，单条 | N | N |
| 订阅者 | P0 | SOAP | 是，单条 | 是，单条 | 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`（字符串）：（必填）用于读取。Salesforce Marketing Cloud 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Salesforce Marketing Cloud Rest 和 SOAP API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `WRITE_OPERATION`（字符串）– 默认：INSERT。用于写入。值应为 INSERT、UPDATE、UPSERT。
+ `ID_FIELD_NAMES`（字符串）– 默认：null。执行 UPDATE/UPSERT 操作需要。
# Salesforce Marketing Cloud 连接器的限制和说明
以下是 Salesforce Marketing Cloud 连接器的限制：
+ 在日期时间数据类型字段上使用筛选条件时，需要以“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 响应中。这样的延迟也会影响数据检索和计划运行。
+ 在 AWS Glue 中执行写入操作时，支持两种不同的日期时间格式：**2025-03-11T04:46:00**（不带毫秒）和 **2025-03-11T04:46:00.000Z**（带毫秒）。
+ 对于事件通知订阅实体，只能为经过验证的回调 URL 创建订阅，且每个回调最多可以有 200 个订阅。
+ 对于事件通知回调实体，每个账户最多可以创建 50 条记录。
# 连接到 Salesforce Commerce Cloud
B2C Commerce API 是一系列 RESTful API，用于与 B2C Commerce 实例进行交互。该类 API 还有几个别的名字：Salesforce Commerce API、SCAPI（首字母缩写词）或者 Commerce API。
该类 API 让开发者能够构建各种各样的应用程序：从完整的店面到自定义商家工具，再到增强业务管理器。所有 B2C Commerce 客户均可免费使用该类 API。
该类 API 分为两大类 API：Shopper API 和 Admin API。在每个组中，该类 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
您必须满足以下要求，才能使用 AWS Glue 从 Salesforce Commerce Cloud 传输数据：
## 最低要求
+ 拥有带 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 中，按照以下步骤在**数据连接**下创建连接：
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. 提供 OAuth 范围（可选），以及要连接的 Salesforce Commerce Cloud 的用户托管客户端应用程序 ClientId。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 Salesforce Commerce Cloud 实体中读取
**先决条件**
+ 要从中读取内容的 Salesforce Commerce Cloud 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 分配 | 支持 | 是 | 是 | 是 | 是 |
| 市场活动 | 支持 | 是 | 是 | 是 | 是 |
| 目录 | 支持 | 是 | 是 | 是 | 是 |
| 类别 | 支持 | 是 | 是 | 是 | 是 |
| 优惠券 | 支持 | 是 | 是 | 是 | 是 |
| Gift Certificates | 支持 | 是 | 是 | 是 | 是 |
| 产品 | 支持 | 是 | 是 | 是 | 是 |
| Promotions | 支持 | 是 | 是 | 是 | 是 |
| Source Code Groups | 支持 | 是 | 是 | 是 | 是 |
**示例**
```
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 实体和字段详细信息**
实体列表：
+ Assignments：[https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments]( https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments)
+ Campaigns：[https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns)
+ Catalogs：[https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs)
+ Categories：[https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories](https://developer.salesforce.com/docs/commerce/commerce-api/references/catalogs?meta=searchCategories)
+ Gift Certificates：[https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates)
+ Products：[https://developer.salesforce.com/docs/commerce/commerce-api/references/products](https://developer.salesforce.com/docs/commerce/commerce-api/references/products)
+ Promotions：[https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions)
+ Source Code Groups：[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`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-02-06"`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
基于实体的分区字段支持详细信息如下表中所示：
| 实体 | 分区字段 | DataType |
| --- | --- | --- |
| 市场活动 | lastModified | 日期时间 |
| 市场活动 | startDate | 日期时间 |
| 市场活动 | endDate | 日期时间 |
| 目录 | creationDate | 日期时间 |
| 类别 | creatiionDate | 日期时间 |
| Gift Certificates | merchantId | 字符串 |
| Gift Certificates | creatiionDate | 日期时间 |
| 产品 | creatiionDate | 日期时间 |
| 产品 | lastModified | 日期时间 |
| Source Code Groups | creationDate | 日期时间 |
| Source Code Groups | startTime | 日期时间 |
| Source Code Groups | endTime | 日期时间 |
**示例**
```
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`（字符串）：（必填）用于读取。Salesforce Commerce Cloud 中对象的名称。
+ `API_VERSION`（字符串）–（必填）用于读/写。要使用的 Salesforce Commerce Cloud Rest API 版本。示例：v1。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# 限制
以下是 Salesforce Commerce Cloud 连接器的限制：
+ 分区时，“包含”筛选条件未按预期工作。
+ 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”值。有关更多信息，请参阅 [Base URL and Request Formation](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_cn/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html)
+ 在某些实体中，检索时的字段数据类型与用作可搜索字段时的数据类型不同。因此，没有为这些字段提供筛选功能。下表提供了有关此类字段的详细信息。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/salesforce-commerce-cloud-connector-limitations.html)
# 连接到 Salesforce Marketing Cloud Account Engagement
Salesforce Marketing Cloud Account Engagement 是一种营销自动化解决方案，可帮助公司建立有意义的联系，生成更多渠道，帮助销售人员达成更多交易。如果您是 Salesforce Marketing Cloud Account Engagement 用户，则可以将 AWS Glue 连接到您的 Salesforce Marketing Cloud Account Engagement 账户。您可以使用 Salesforce Marketing Cloud Account Engagement 作为 ETL 作业中的数据来源。通过运行这些作业，可将数据从 Salesforce Marketing Cloud Account Engagement 传输到 AWS 服务或其他受支持的应用程序。
**Topics**
+ [AWS Glue 对 Salesforce Marketing Cloud Account Engagement 的支持](salesforce-marketing-cloud-account-engagement-support.md)
+ [包含创建和使用连接的 API 操作的策略](salesforce-marketing-cloud-account-engagement-configuring-iam-permissions.md)
+ [配置 Salesforce Marketing Cloud Account Engagement](salesforce-marketing-cloud-account-engagement-configuring.md)
+ [配置 Salesforce Marketing Cloud Account Engagement 连接](salesforce-marketing-cloud-account-engagement-configuring-connections.md)
+ [从 Salesforce Marketing Cloud Account Engagement 实体中读取](salesforce-marketing-cloud-account-engagement-reading-from-entities.md)
+ [Salesforce Marketing Cloud Account Engagement 连接选项](salesforce-marketing-cloud-account-engagement-connection-options.md)
+ [Salesforce Marketing Cloud Account Engagement 连接器的限制和说明](salesforce-marketing-cloud-account-engagement-connector-limitations.md)
# AWS Glue 对 Salesforce Marketing Cloud Account Engagement 的支持
AWS Glue 对 Salesforce Marketing Cloud Account Engagement 的支持如下：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业以异步或同步模式查询 Salesforce Marketing Cloud Account Engagement 中的数据。
**是否支持作为目标？**
否。
**支持的 Salesforce Marketing Cloud Account Engagement API 版本**
支持以下 Salesforce Marketing Cloud Account Engagement API 版本：
+ v5
# 包含创建和使用连接的 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 Account Engagement
您必须满足以下要求，才能使用 AWS Glue 从 Salesforce Marketing Cloud Account Engagement 传输数据：
## 最低要求
以下是最低要求：
+ 您有一个 Salesforce Marketing 账户。
+ 您已有针对 Salesforce 账户的授权 Account Engagement 计划。
+ 您已将 Salesforce 用户与 Account Engagement 用户同步。
+ 您已在应用程序管理器下创建新的关联应用程序用于获取 OAuth 凭证。
如果您满足这些要求，就可以将 AWS Glue 连接到您的 Salesforce Marketing Cloud Account Engagement 账户。
# 配置 Salesforce Marketing Cloud Account Engagement 连接
授权类型决定了 AWS Glue 如何与 Salesforce Marketing Cloud Account Engagement 通信以请求访问您的数据。您选择的授权类型会影响您在创建连接之前必须满足的要求。Salesforce Marketing Cloud Account Engagement 仅支持 OAuth 2.0 的 AUTHORIZATION\$1CODE 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。
+ 用户仍然可以选择在 Salesforce Marketing Cloud Account Engagement 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Salesforce Marketing Cloud Account Engagement，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权代码 OAuth 流创建关联应用程序的公开 Salesforce Marketing Cloud Account Engagement 文档，请参阅 [Authentication](https://developer.salesforce.com/docs/marketing/pardot/guide/version5overview.html#authentication)。
要配置 Salesforce Marketing Cloud Account Engagement 连接：
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Salesforce Marketing Cloud Account Engagement。
1. 提供您想要连接到的 Salesforce Marketing Cloud Account Engagement 实例的 `INSTANCE_URL`。
1. 提供您想要连接到的 Salesforce Marketing Cloud Account Engagement 实例的 `PARDOT_BUSINESS_UNIT_ID`。
1. 从下拉列表中选择相应的**授权码 URL**。
1. 从下拉列表中选择相应的**令牌 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. 提供用户托管客户端应用程序的客户端 ID（已关联应用程序的客户端 ID）。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。所选密钥需要有一个键 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`，其值为关联应用程序的客户端密钥。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 Salesforce Marketing Cloud Account Engagement 实体中读取
**先决条件**
您要从中读取内容的 Salesforce Marketing Cloud Account Engagement 对象。您将需要对象名称。
**同步源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 活动 | 支持 | 是 | 是 | 是 | 是 |
| 动态内容 | 支持 | 是 | 是 | 是 | 是 |
| 电子邮件 | 支持 | 是 | 是 | 是 | 是 |
| 电子邮件模板 | 支持 | 是 | 是 | 是 | 是 |
| Engagement Studio 程序 | 支持 | 是 | 是 | 是 | 是 |
| 文件夹内容 | 支持 | 是 | 是 | 是 | 是 |
| 登录页面 | 支持 | 是 | 是 | 是 | 是 |
| 生命周期历史记录 | 支持 | 是 | 是 | 是 | 是 |
| 生命周期阶段 | 支持 | 是 | 是 | 是 | 是 |
| 列表 | 支持 | 是 | 是 | 是 | 是 |
| 电子邮件列表 | 支持 | 是 | 是 | 是 | 是 |
| 成员资格列表 | 支持 | 是 | 是 | 是 | 是 |
| Opportunity | 支持 | 是 | 是 | 是 | 是 |
| 潜在客户 | 支持 | 是 | 是 | 是 | 是 |
| 潜在客户账户 | 支持 | 是 | 是 | 是 | 是 |
| 用户 | 是 | 是 | 是 | 是 | 是 |
**示例：**
```
salesforcepardot_read = glueContext.create_dynamic_frame.from_options(
connection_type="SalesforcePardot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v5"
}
)
```
**异步源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 活动 | 是 | 否 | 否 | 是 | 否 |
| 动态内容 | 是 | 否 | 否 | 是 | 否 |
| 电子邮件模板 | 是 | 否 | 否 | 是 | 否 |
| 登录页面 | 是 | 否 | 否 | 是 | 否 |
| 生命周期历史记录 | 是 | 否 | 否 | 是 | 否 |
| 生命周期阶段 | 是 | 否 | 否 | 是 | 否 |
| 列表 | 是 | 否 | 否 | 是 | 否 |
| 电子邮件列表 | 是 | 否 | 否 | 是 | 否 |
| 成员资格列表 | 是 | 否 | 否 | 是 | 否 |
| Opportunity | 是 | 否 | 否 | 是 | 否 |
| 潜在客户 | 是 | 否 | 否 | 是 | 否 |
| 潜在客户账户 | 是 | 否 | 否 | 是 | 否 |
| 用户 | 是 | 否 | 否 | 是 | 否 |
**示例：**
```
salesforcepardot_read = glueContext.create_dynamic_frame.from_options(
connection_type="SalesforcePardot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v5",
"TRANSFER_MODE": "ASYNC"
}
)
```
**Salesforce Marketing Cloud Account Engagement 实体和字段详细信息**：
要查看以下实体的字段详细信息，请导航到 [Salesforce Marketing Cloud Account Engagement API](https://developer.salesforce.com/docs/marketing/pardot)，选择**指南**，向下滚动到**开源 API 包装器**，从菜单中展开**版本 5 文档**，然后选择一个实体。
实体列表：
+ 活动
+ 动态内容
+ 电子邮件
+ 电子邮件模板
+ Engagement Studio 程序
+ 文件夹内容
+ 登录页面
+ 生命周期历史记录
+ 生命周期阶段
+ 列表
+ 电子邮件列表
+ 成员资格列表
+ Opportunity
+ 潜在客户
+ 潜在客户账户
+ 用户
除上述字段外，异步模式还支持每个实体的特定可筛选字段，如下表所示。
| 实体 | 异步模式支持的其他可筛选字段 |
| --- | --- |
| 活动 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
| 动态内容 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
| 电子邮件模板 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
| Engagement Studio 程序 | - |
| 登录页面 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
| 生命周期历史记录 | createdAfter, createdBefore |
| 生命周期阶段 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
| 列表 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
| 电子邮件列表 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
| 成员资格列表 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
| Opportunity | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
| 潜在客户 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
| 潜在客户账户 | createdAfter, createdBefore, deleted |
| 用户 | createdAfter, createdBefore, deleted, updatedAfter, updatedBefore |
有关其他字段的更多信息，请参阅 [Salesforce Export API](https://developer.salesforce.com/docs/marketing/pardot/guide/export-v5.html#procedures)
请注意连接器的以下注意事项：
+ 实体中 `delete` 字段的值可以是 `false`（默认）、`true` 或 `all`。
## 对查询进行分区
**基于筛选器的分区**：
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于日期时间字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"2022-01-01T01:01:01.000Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
+ `PARTITION_BY`：要执行的分区类型。如果是基于字段的分区，则需要传递“FIELD”。
示例：
```
salesforcepardot_read = glueContext.create_dynamic_frame.from_options(
connection_type="salesforcepardot",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v5",
"PARTITION_FIELD": "createdAt"
"LOWER_BOUND": "2022-01-01T01:01:01.000Z"
"UPPER_BOUND": "2024-01-01T01:01:01.000Z"
"NUM_PARTITIONS": "10",
"PARTITION_BY": "FIELD"
}
)
```
# Salesforce Marketing Cloud Account Engagement 连接选项
以下是 Salesforce Marketing Cloud Account Engagement 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Salesforce Marketing Cloud Account Engagement 中对象的名称。
+ `PARDOT_BUSINESS_UNIT_ID`：（必填）用于创建连接。您想要连接到的 Salesforce Marketing Cloud Account Engagement 实例的业务部门 ID。
+ `API_VERSION`（字符串）：（必填）用于读取。您想要使用的 Salesforce Marketing Cloud Account Engagement Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）–
+ 在同步模式下 – 默认：空。用于读取。应采用 Spark SQL 格式。
+ 在异步模式下 – 默认：当前 `DateTime` 值（根据用户时区）– 1 年。用于读取。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（字符串）：（必填）用于读取。有效的 Salesforce Marketing Cloud Account Engagement 实例 URL。
+ `PARTITION_BY`（字符串）：（必填）用于读取。要执行的分区类型。如果是基于字段的分区，则需要传递“FIELD”。
+ `TRANSFER_MODE`（字符串）–（可选），用于在异步模式下运行作业的值，若未提供此选项，作业会在同步模式下运行。
# Salesforce Marketing Cloud Account Engagement 连接器的限制和说明
以下说明和限制适用：
+ 当同时应用限制和分区时，限制优先于分区。
+ 根据 API 文档，`SalesforceMarketingCloudEngagement` 对每日请求数和并发请求数强制实施 RateLimit。有关更多信息，请参阅 [Rate Limits](https://developer.salesforce.com/docs/marketing/pardot/guide/overview.html?q=limitation#rate-limits)。
+ 导出 API 受账户每日 Account Engagement API调用限制和并发 Account Engagement API 调用限制的约束。
+ 与队列类似，导出/异步 API 调用针对每个账户按顺序执行。先处理较旧的导出，然后再处理较新的导出。
+ 异步模式下不支持分区。
+ 导出/异步 API 调用中指定的选定字段数不得超过 150 个。
+ **潜在客户**实体支持 150 多个字段，但一次只能选择 150 个字段。如果选中 `Select All`，部分字段会被排除在外。要检索这些排除字段的数据，必须将这些字段包含在 `Selected Fields` 选项中。
以下是 `SELECT_ALL` 中排除字段的列表 – `updatedBy.firstName`、`updatedBy.lastName`、`updatedBy.jobTitle`、`updatedBy.roleName`、`updatedBy.salesforceId`、`updatedBy.createdAt`、`updatedBy.updatedAt`、`updatedBy.isDeleted`、`updatedBy.createdById`、`updatedBy.updatedById`、`updatedBy.tagReplacementLanguage`
+ 无法在异步模式下导出集合字段。例如，“列出电子邮件”不支持 `senderOptions` 和 `replyToOptions` 字段。
+ 所有实体都必须要有筛选条件。如果未提供筛选条件，则默认筛选谓词将设置为 `Created After` 字段，其值为当前日期时间（根据您的时区进行调整）减去一年。
+ 根据 Salesforce Marketing Cloud Account Engagement 限制，在异步模式下，获取数据的最大时间范围为 1 年。如果查询的时间范围超过 1 年，作业会抛出错误。
+ 目前，Salesforce Pardot 中存在一个错误。作业仅包含一个没有任何数据的字段时，字段值不会返回正确的结果，而是会多次返回字段名称。Salesforce Pardot 团队已知晓这个问题，正在积极研究解决方案。
# 在 AWS Glue Studio 中连接到 SAP HANA
AWS Glue 提供了对 SAP HANA 的内置支持。AWS Glue Studio 提供了直观的界面，以用于连接到 SAP HANA、编写数据集成作业以及在 AWS Glue Studio 无服务器 Spark 运行时系统上运行这些作业。
AWS Glue Studio 为 SAP HANA 创建统一连接。有关更多信息，请参阅 [注意事项](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。
**Topics**
+ [创建 SAP HANA 连接](creating-saphana-connection.md)
+ [创建 SAP HANA 源节点](creating-saphana-source-node.md)
+ [创建 SAP HANA 目标节点](creating-saphana-target-node.md)
+ [高级选项](#creating-saphana-connection-advanced-options)
# 创建 SAP HANA 连接
要从 AWS Glue 连接到 SAP HANA，您需要创建 SAP HANA 凭证并将其存储在某个 AWS Secrets Manager 密钥中，然后将该密钥关联到某个 SAP HANA AWS Glue 连接。您需要配置 SAP HANA 服务与 AWS Glue 之间的网络连接。
**先决条件**
+ 如果您的 SAP HANA 服务位于某个 Amazon VPC 中，请确保您的 Amazon VPC 配置允许您的 AWS Glue 作业与 SAP HANA 服务进行通信，并且无需通过公共互联网路由流量。
在 Amazon VPC 中，确定或创建 AWS Glue 将在执行作业时使用的 **VPC**、**子网**和**安全组**。此外，您的 Amazon VPC 配置需要允许您的 SAP HANA 端点与该位置之间的网络流量。您的作业需要与您的 SAP HANA JDBC 端口建立 TCP 连接。有关 SAP HANA 端口的更多信息，请参阅 [SAP HANA 文档](https://help.sap.com/docs/HANA_SMART_DATA_INTEGRATION/7952ef28a6914997abc01745fef1b607/88e2e8bded9e4041ad3ad87dc46c7b55.html?locale=en-US)。根据您的网络布局，这可能需要更改安全组规则、网络 ACL、NAT 网关和对等连接。
**配置 SAP HANA 连接：**
1. 在 AWS Secrets Manager 中，使用您的 SAP HANA 凭证创建一个密钥。要在 Secrets Manager 中创建密钥，请按照 AWS Secrets Manager 文档中[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中的教程进行操作。创建密钥后，保留密钥名称 *secretName*，以供下一步使用。
+ 在选择**键/值对**时，请使用键 `username/USERNAME` 和值 *saphanaUsername* 创建一个键值对。
+ 在选择**键/值对**时，请使用键 `password/PASSWORD` 和值 *saphanaPassword* 创建一个键值对。
1. 在 AWS Glue 控制台中，按照 [添加 AWS Glue 连接](console-connections.md) 中的步骤创建一个连接。创建连接后，保留连接名为 *connectionName*，以供未来在 AWS Glue 中使用。
+ 选择**连接类型**时，请选择 SAP HANA。
+ 在提供 **SAP HANA URL** 时，请提供您的实例的 URL。
SAP HANA JDBC URL 的格式为 `jdbc:sap://saphanaHostname:saphanaPort/?databaseName=saphanaDBname,ParameterName=ParameterValue`
AWS Glue 需要以下 JDBC URL 参数：
+ `databaseName` – SAP HANA 中要连接的默认数据库。
+ 选择 **AWS 密钥**时，请提供 *secretName*。
创建 AWS Glue SAP HANA 连接后，您需要完成以下操作，然后才能运行 AWS Glue 作业：
+ 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 *secretName* 的权限。
# 创建 SAP HANA 源节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue SAP HANA 连接，如上一节“[创建 SAP HANA 连接](creating-saphana-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要读取的 SAP HANA 表 *tableName* 或查询 *targetQuery*。
可以使用 SAP HANA 表名和 Schema 名（格式为 `schemaName.tableName`）来指定表。如果表的 Schema 为默认的“public”，则不需要指定 Schema 名和“.”分隔符。调用此 *tableIdentifier* 操作。请注意，数据库在 `connectionName` 中是以 JDBC URL 参数的形式提供的。
## 添加 SAP HANA 数据来源
**添加**数据来源 - SAP HANA** 节点：**
1. 选择 SAP HANA 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 SAP HANA 连接**。有关更多信息，请参阅之前的 [创建 SAP HANA 连接](creating-saphana-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 选择 **SAP HANA 源**选项：
+ **选择单个表** – 访问单个表中的所有数据。
+ **输入自定义查询** - 允许您根据自定义查询访问多个表中的数据集。
1. 如果您选择单个表，请输入 *tableName*。
如果选择**输入自定义查询**，请输入一个 SQL SELECT 查询。
1. 在**自定义 SAP HANA 属性**中，根据需要输入相关参数和值。
# 创建 SAP HANA 目标节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue SAP HANA 连接，如上一节“[创建 SAP HANA 连接](creating-saphana-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要写入的 SAP HANA 表 *tableName*。
可以使用 SAP HANA 表名和 Schema 名（格式为 `schemaName.tableName`）来指定表。如果表的 Schema 为默认的“public”，则不需要指定 Schema 名和“.”分隔符。调用此 *tableIdentifier* 操作。请注意，数据库在 `connectionName` 中是以 JDBC URL 参数的形式提供的。
## 添加 SAP HANA 数据目标
**添加**数据目标 - SAP HANA** 节点：**
1. 选择 SAP HANA 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 SAP HANA 连接**。有关更多信息，请参阅之前的 [创建 SAP HANA 连接](creating-saphana-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 要配置**表名**，请提供 *tableName*。
1. 在**自定义 Teradata 属性**中，根据需要输入相关参数和值。
## 高级选项
您可以在创建 SAP HANA 节点时提供高级选项。这些选项与编程 Spark 脚本的 AWS Glue 时可用的选项相同。
请参阅[SAP HANA 连接](aws-glue-programming-etl-connect-saphana-home.md)。
# 连接到 SAP OData
SAP OData 是一种标准 Web 协议，用于使用 ABAP（高级业务应用程序编程）查询和更新 SAP 中存在的数据，应用和构建 HTTP 等 Web 技术，以提供对来自各种外部应用程序、平台和设备的信息的访问权限。通过该产品，您可以访问所需的一切，以帮助您与 SAP 系统、应用程序或数据无缝集成。
**Topics**
+ [AWS Glue 对 SAP OData 的支持](sap-odata-support.md)
+ [创建 连接](sap-odata-creating-connections.md)
+ [创建 SAP OData 作业](sap-odata-creating-job.md)
+ [写入 SAP OData](sap-odata-writing.md)
+ [使用 SAP OData 状态管理脚本](sap-odata-state-management-script.md)
+ [非 ODP 实体的分区](sap-odata-non-odp-entities-partitioning.md)
+ [SAP OData 连接选项](sap-odata-connection-options.md)
+ [SAP OData 实体和字段详细信息](sap-odata-entity-field-details.md)
# AWS Glue 对 SAP OData 的支持
AWS Glue 对 SAP OData 的支持如下：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业查询 SAP OData 中的数据。
**是否支持作为目标？**
是。您可以使用 AWS Glue ETL 作业将记录写入 SAP OData。
**支持的 SAP OData API 版本**
支持以下 SAP OData API 版本：
+ 2.0
**支持的来源**
支持以下来源：
+ ODP（操作数据供应）来源：
+ BW 提取器（数据源）
+ CDS 视图
+ SLT
+ 非 ODP 来源，例如：
+ CDS 视图服务
+ 基于 RFC 的服务
+ 自定义 ABAP 服务
**支持的 SAP 组件**
以下是最低要求：
+ 您必须启用目录服务才能进行服务发现。
+ 在 SAP 系统的 SAP 网关中配置要提取的操作数据供应（ODP）数据来源。
+ **OData V2.0**：可以通过事务 `/IWFND/MAINT_SERVICE` 在 SAP 网关中启用 OData V2.0 目录服务。
+ 通过事务 `/IWFND/MAINT_SERVICE` 在 SAP 网关中启用 OData V2.0 服务。
+ 您的 SAP OData 服务必须支持客户端分页/查询选项，例如 `$top` 和 `$skip`。该服务还必须支持系统查询选项 `$count`。
+ 您必须为 SAP 中的用户提供所需的授权，才能使用 SAP OData 服务发现这些服务并提取数据。请参阅 SAP 提供的安全文档。
+ 如果要使用 OAuth 2.0 作为授权机制，则必须为 OData 服务启用 OAuth 2.0，并按照 SAP 文档注册 OAuth 客户端。
+ 要基于 ODP 数据来源生成 OData 服务，必须将 SAP Gateway Foundation 安装在本地的 ERP/BW 堆栈中或中心配置中。
+ 对于您的 ERP/BW 应用程序，SAP NetWeaver AS ABAP 堆栈必须为 7.50 SP02 或更高版本。
+ 对于中心系统（SAP 网关），中心系统的 SAP NetWeaver AS ABAP 必须为 7.50 SP01 或更高版本才能进行远程中心设置。
+ 对于非 ODP 来源，您的 SAP NetWeaver 堆栈版本必须为 7.40 SP02 或更高版本。
**支持的身份验证方法**
支持以下身份验证方法：
+ 基本身份验证
+ OAuth 2.0
# 先决条件
在使用 SAP OData 连接启动 AWS Glue 作业从 SAP OData 提取数据之前，请完成以下先决条件：
+ 必须在 SAP 系统中激活相关的 SAP OData 服务，确保数据来源可供使用。如果未激活 OData 服务，则将无法访问 Glue 作业或从 SAP 提取数据。
+ 必须在 SAP 中配置适当的身份验证机制，例如基本（自定义）身份验证或 OAuth 2.0，以确保 AWS Glue 作业能够成功与 SAP OData 服务建立连接。
+ 配置 IAM 策略以授予 AWS Glue 作业相应的权限，使其能够访问 SAP、Secrets Manager 以及流程中涉及的其他 AWS 资源。
+ 如果 SAP 系统托管在私有网络中，则必须配置 VPC 连接，以确保 AWS Glue 作业可以安全地与 SAP 通信，而不会通过公共互联网暴露敏感数据。
AWS Secrets Manager 可用于安全存储 SAP 凭证等敏感信息，AWS Glue 作业可以在运行时动态检索这些信息。通过这种方法，无需对凭证进行硬编码，从而增强了安全性和灵活性。
以下先决条件提供了有关如何设置每个组件以实现 AWS Glue 与 SAP OData 之间顺利集成的分步指导。
**Topics**
+ [SAP OData 激活](sap-odata-activation.md)
+ [IAM 策略](sap-odata-configuring-iam-permissions.md)
+ [连接/VPC 连接](sap-odata-connectivity-vpc-connection.md)
+ [SAP 身份验证](sap-odata-authentication.md)
+ [用于存储身份验证密钥的 AWS Secrets Manager](sap-odata-aws-secret-manager-auth-secret.md)
# SAP OData 激活
完成 SAP OData 连接的以下步骤：
## ODP 源
必须满足以下要求，然后才能从 ODP 提供程序传输数据：
+ 您有一个 SAP NetWeaver AS ABAP 实例。
+ 您的 SAP NetWeaver 实例包含一个要从其传输数据的 ODP 提供程序。ODP 提供程序包括：
+ SAP 数据源（事务代码 RSO2）
+ SAP 核心数据服务 ABAP CDS 视图
+ SAP BW 或 SAP BW/4HANA 系统（InfoObject、DataStore 对象）
+ 通过 SAP Landscape Replication Server（SAP SLT）从 SAP 源系统实时复制表和数据库视图
+ 基于 SAP ABAP 的来源中的 SAP HANA 信息视图
+ 您的 SAP NetWeaver 实例有 SAP Gateway Foundation 组件。
+ 您已创建从 ODP 提供程序提取数据的 OData 服务。要创建 OData 服务，请使用 SAP Gateway Service Builder。要访问您的 ODP 数据，Amazon AppFlow 将使用 OData API 调用此服务。有关更多信息，请参阅 SAP BW/4HANA 文档中的 [Generating a Service for Extracting ODP Data via OData](https://help.sap.com/docs/SAP_BPC_VERSION_BW4HANA/dd104a87ab9249968e6279e61378ff66/69b481859ef34bab9cc7d449e6fff7b6.html?version=11.0)。
+ 要基于 ODP 数据来源生成 OData 服务，必须将 SAP Gateway Foundation 安装在本地的 ERP/BW 堆栈中或中心配置中。
+ 对于您的 ERP/BW 应用程序，SAP NetWeaver AS ABAP 堆栈必须为 7.50 SP02 或更高版本。
+ 对于中心系统（SAP 网关），中心系统的 SAP NetWeaver AS ABAP 必须为 7.50 SP01 或更高版本才能进行远程中心设置。
## 非 ODP 源
+ 您的 SAP NetWeaver 堆栈版本必须为 7.40 SP02 或更高版本。
+ 您必须启用目录服务才能进行服务发现。
+ **OData V2.0**：可以通过事务 `/IWFND/MAINT_SERVICE` 在 SAP 网关中启用 OData V2.0 目录服务
+ 您的 SAP OData 服务必须支持客户端分页/查询选项，例如 `$top` 和 `$skip`。该服务还必须支持系统查询选项 `$count`。
+ 对于 OAuth 2.0，您必须为 OData 服务启用 OAuth 2.0 并根据 SAP 文档注册 OAuth 客户端，并设置授权重定向 URL，如下所示：
+ `https://.console.aws.amazon.com/gluestudio/oauth`，`` 替换为 AWS Glue 正在运行的区域，例如：us-east-1。
+ 必须启用安全设置才能通过 HTTPS 进行连接。
+ 您必须为 SAP 中的用户提供所需的授权，才能使用 SAP OData 服务发现这些服务并提取数据。请参阅 SAP 提供的安全文档。
# IAM 策略
## 包含创建和使用连接的 API 操作的策略
以下示例策略描述了创建和使用连接所需的 AWS IAM 权限。如果您要创建新角色，请创建包含以下内容的策略：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"glue:ListConnectionTypes",
"glue:DescribeConnectionType",
"glue:RefreshOAuth2Tokens",
"glue:ListEntities",
"glue:DescribeEntity"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:PutSecretValue"
],
"Resource": "*"
}
]
}
```
------
该角色必须授予作业所用所有资源的访问权限，例如 Amazon S3。如果您不想使用上述方法，也可以使用以下托管 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 控制台的用户。
+ [SecretsManagerReadWrite](https://console.aws.amazon.com/iam/home#policies/arn:aws:iam::aws:policy/SecretsManagerReadWrite)：提供通过 AWS 管理控制台访问 AWS Secrets Manager 的读/写访问权限。注意：此项不包括 IAM 操作，因此如果需要轮换配置，请与 `IAMFullAccess` 结合使用。
**配置 VPC 所需的 IAM 策略/权限**
使用 VPC 连接创建 AWS Glue 连接时需要以下 IAM 权限。有关更多详细信息，请参阅[为 AWS Glue 创建 IAM 策略](https://docs.aws.amazon.com/glue/latest/dg/create-service-policy.html)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ec2:CreateNetworkInterface",
"ec2:DeleteNetworkInterface",
"ec2:DescribeNetworkInterfaces"
],
"Resource": [
"*"
]
}
]
}
```
------
# 连接/VPC 连接
VPC 连接的步骤：
1. 使用现有 VPC 连接或按照 [Amazon VPC 文档](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html)创建新连接。
1. 确保您拥有将流量路由到互联网的 NAT 网关。
1. 选择 VPC 端点作为 Amazon S3 网关以创建连接。
1. 启用 DNS 解析和 DNS 主机名以使用 AWS 提供的 DNS 服务。
1. 前往已创建的 VPC，为 STS、AWS Glue、Secret Manager 等不同的服务添加必要的端点。
1. 选择 Create Endpoint（创建端点）。
1. 对于“服务类别”，选择 AWS 服务。
1. 对于“服务名称”，选择要连接到的服务。
1. 选择 VPC 并启用 DNS 名称。
1. VPC 连接所需的 VCP 端点：
1. [STS](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sts_vpc_endpoint_create.html)
1. [AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/vpc-interface-endpoints.html)
1. [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)
## 安全组配置
安全组必须允许来自 AWS Glue VPC 的流量进入其侦听端口，以使 AWS Glue 能与其连接。最好尽可能限制源 IP 地址的范围。
AWS Glue 需要特殊的安全组以允许来自自身的所有入站流量。您可以创建自引用规则，允许来自安全组的所有流量。您可以修改现有安全组并将该安全组指定为源。
开放来自 URL 端点（NLB 或 SAP 实例）HTTPS 端口的通信。
## 连接选项
+ 与内部和外部 NLB 的 HTTPS 连接，来自证书颁发机构（CA）的 SSL 证书，非自签名 SSL 证书
+ 与 SAP 实例的 HTTPS 连接，来自证书颁发机构（CA）的 SSL 证书，非自签名 SSL 证书
# SAP 身份验证
SAP 连接器支持自定义（这是 SAP 基本身份验证）和 OAUTH 身份验证方法。
## 自定义身份验证
AWS Glue 支持自定义（基本身份验证）作为与 SAP 系统建立连接的方法，允许使用用户名和密码进行安全访问。此身份验证类型非常适合自动化场景，因为它允许预先使用用户名和密码以及 SAP OData 实例中特定用户的权限。AWS Glue 能够使用用户名和密码对 SAP OData API 进行身份验证。在 AWS Glue 中，基本授权是作为自定义授权实现的。
有关基本身份验证流程的 SAP OData 公开文档，请参阅 [HTTP Basic Authentication](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b/5c8bca0af1654b05a83193b2922dcee2.html)。
## OAuth 2.0 身份验证
AWS Glue 还支持 OAuth 2.0 作为与 SAP 系统建立连接的安全身份验证机制。这可以实现无缝集成，同时确保符合现代身份验证标准并提高数据访问的安全性。
## AUTHORIZATION\$1CODE 授权类型
授权类型决定了 AWS Glue 如何与 SAP OData 通信以请求访问您的数据。SAP OData 仅支持 `AUTHORIZATION_CODE` 授权类型。此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。
用户仍然可以选择在 SAP OData 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 SAP OData，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
有关为授权码 OAuth 流创建关联应用程序的公共 SAP OData 文档，请参阅 [Authentication Using OAuth 2.0](https://help.sap.com/docs/ABAP_PLATFORM_NEW/e815bb97839a4d83be6c4fca48ee5777/2e5104fd87ff452b9acb247bd02b9f9e.html)。
# 用于存储身份验证密钥的 AWS Secrets Manager
您需要将 SAP OData 连接密钥存储在 AWS Secrets Manager 中，按照 [IAM 策略](sap-odata-configuring-iam-permissions.md)一节中的规定配置必要的检索权限，并在创建连接时使用该权限。
使用 AWS Secrets Manager 的 AWS 管理控制台为您的 SAP 源创建密钥。有关更多信息，请参阅 [Create an AWS Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。AWS Secrets Manager 中的详细信息应包含以下代码中的元素。
## 自定义身份验证密钥
您需要输入您的 SAP 系统用户名来代替 **，输入其密码来代替 **，以及输入 True 或 False。在这种情况下，将 `basicAuthDisableSSO` 设置为 `true` 会禁用基本身份验证请求的单点登录（SSO），要求每个请求都提供显式用户凭证。相反，将其设置为 `false` 将允许使用现有的 SSO 会话（如果有）。
```
{
"basicAuthUsername": "",
"basicAuthPassword": "",
"basicAuthDisableSSO": "",
"customAuthenticationType": "CustomBasicAuth"
}
```
## OAuth 2.0 密钥
如果使用 OAuth 2.0 作为身份验证机制，则 AWS Secrets Manager 中的密钥应具有以下格式的**用户托管客户端应用程序 ClientId**。您需要输入 SAP 客户端密钥来代替 。
```
{"USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET": ""
}
```
# 创建 连接
配置 SAP OData 连接：
1. 登录 AWS 管理控制台，打开 [AWS Glue 控制台](https://console.aws.amazon.com/glue)。在 AWS Glue Studio 中，按照以下步骤创建连接：
1. 在左侧面板上单击“数据连接”。
1. 单击“创建连接”。
1. 在**选择数据来源**中选择 **SAP OData**
1. 提供您要连接的 SAP OData 实例的**应用程序主机 URL**。对于非 VPC 连接，必须能够通过公共互联网访问此应用程序主机 url。
1. 提供您要连接的 SAP OData 实例的**应用程序服务路径**。这与目录服务路径相同。例如：`/sap/opu/odata/iwfnd/catalogservice;v=2`。AWS Glue 不接受特定的对象路径。
1. 提供您要连接的 SAP OData 实例的**客户端编号**。可接受的值为 [001-999]。示例：010
1. 提供您要连接的 SAP OData 实例的**端口号**。示例：443
1. 提供您要连接的 SAP OData 实例的**登录语言**。示例：EN
1. 选择 AWS Glue 可以代入并拥有如 [IAM 策略](sap-odata-configuring-iam-permissions.md)一节所述权限的 AWS IAM 角色。
1. 从下拉列表中选择想要在 AWS Glue 中用于此连接的**身份验证类型**：OAUTH2 或自定义
1. 自定义：选择您按照[用于存储身份验证密钥的 AWS Secrets Manager](sap-odata-aws-secret-manager-auth-secret.md) 一节中指定的方式创建的密钥。
1. OAuth 2.0：仅在 OAuth 2.0 中输入以下内容：
1. 在**用户托管客户端应用程序 ClientId** 下，输入您的客户端 ID。
1. 您在[用于存储身份验证密钥的 AWS Secrets Manager](sap-odata-aws-secret-manager-auth-secret.md) 一节中创建的 AWS Secrets Manager 中的 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`（您的客户端密钥）。
1. 在**授权码 URL** 下，输入您的授权码 URL。
1. 在**授权令牌 URL** 下，输入您的授权令牌 URL。
1. 在 **OAuth 范围**下，输入用空格分隔的 OAuth 范围。示例：`/IWFND/SG_MED_CATALOG_0002 ZAPI_SALES_ORDER_SRV_0001`
1. 如果要使用网络，请选择网络选项。有关更多详细信息，请参阅 [连接/VPC 连接](sap-odata-connectivity-vpc-connection.md)。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。有关详细信息，请参阅[IAM 策略](sap-odata-configuring-iam-permissions.md)。
1. 选择**测试连接**并测试您的连接。如果连接测试通过，则请单击“下一步”，输入您的连接名称并保存连接。如果您选择了网络选项（VPC），则测试连接功能不可用。
# 创建 SAP OData 作业
请参阅[使用 AWS Glue Studio 构建可视化 ETL 作业](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html)
# 操作数据供应（ODP）来源
操作数据供应（ODP）提供了一个技术基础架构，可用于支持各种目标应用程序的数据提取和复制，并支持这些场景中的增量机制。对于增量过程，来自源（ODP 提供程序）的数据使用更新过程自动写入到增量队列（操作增量队列 – ODQ），或者使用提取器接口传递到增量队列。ODP 提供程序可以是数据源（提取器）、ABAP 核心数据服务视图（ABAP CDS 视图）、SAP BW 或 SAP BW/4HANA、SAP Landscape Transformation Replication Server（SLT）和 SAP HANA 信息视图（计算视图）。目标应用程序（称为 ODQ“订阅用户”或更普遍的“ODP 使用者”）从增量队列中检索数据并继续处理数据。
## 完全加载
在 SAP OData 和 ODP 实体环境中，**完全加载**是指通过一次操作从 ODP 实体提取所有可用数据的过程。此操作从源系统检索完整的数据集，确保目标系统拥有实体数据全面且最新的副本。完全加载通常用于不支持增量加载的源或需要刷新目标系统的情况。
**示例**
在创建 DynamicFrame 时，您可以将 `ENABLE_CDC` 标志显式设置为 false。注意：默认情况下 `ENABLE_CDC` 为 false；如果您不想初始化增量队列，则无需发送此标志或将其设置为 true。不将此标志设置为 true 将导致完全加载提取。
```
sapodata_df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "false"
}, transformation_ctx=key)
```
## 增量加载
ODP（操作数据供应）实体环境中的**增量加载**涉及仅提取源系统中自上次数据提取以来新的或更改的数据（增量），从而避免对已经处理的记录进行预处理。这种方法显著提高了效率，减少了数据传输量，增强了性能，确保了系统之间的有效同步，并最大限度地缩短了处理时间，对于经常变化的大型数据集尤其如此。
# 基于增量令牌的增量传输
要使用更改数据捕获（CDC）为支持 ODP 的实体启用增量传输，请执行以下步骤：
1. 在脚本模式下创建增量传输作业。
1. 创建 DataFrame 或 Glue DynamicFrame 时，您需要传递选项 `"ENABLE_CDC": "True"`。此选项可确保您将收到来自 SAP 的增量令牌，该令牌可用于随后检索更改的数据。
增量令牌将在数据帧最后一行的 DELTA\$1TOKEN 列中显示。此令牌可用作后续调用中的连接器选项来逐步检索下一组数据。
**示例**
+ 创建 DynamicFrame 时，我们将 `ENABLE_CDC` 标志设置为 `true`。注意：默认情况下 `ENABLE_CDC` 为 `false`；如果您不想初始化增量队列，则无需发送此标志或将其设置为 true。不将此标志设置为 true 将导致完全加载提取。
```
sapodata_df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "true"
}, transformation_ctx=key)
# Extract the delta token from the last row of the DELTA_TOKEN column
delta_token_1 = your_logic_to_extract_delta_token(sapodata_df) # e.g., D20241029164449_000370000
```
+ 提取的增量令牌可作为检索新事件的选项传递。
```
sapodata_df_2 = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
// passing the delta token retrieved in the last run
"DELTA_TOKEN": delta_token_1
} , transformation_ctx=key)
# Extract the new delta token for the next run
delta_token_2 = your_logic_to_extract_delta_token(sapodata_df_2)
```
请注意，存在 `DELTA_TOKEN` 的最后一条记录不是来自源的事务记录，而仅用于传递增量令牌值。
除 `DELTA_TOKEN` 外，数据帧的每一行都会返回以下字段。
+ **GLUE\$1FETCH\$1SQ**：此项是一个序列字段，根据记录接收顺序从 EPOC 时间戳生成，并且每个记录都是唯一的。如果您需要了解或确定源系统中的更改顺序，则可以使用此项。此字段仅对启用 ODP 的实体显示。
+ **DML\$1STATUS**：对于从源新插入和更新的所有记录，此项将显示 `UPDATED`；对于从源删除的记录，此项将显示 `DELETED`。
有关如何通过示例管理状态和重用增量令牌来检索已更改记录的更多详细信息，请参阅[使用 SAP OData 状态管理脚本](sap-odata-state-management-script.md)一节。
## 增量令牌失效
增量令牌与服务集合和用户相关联。如果为同一个服务集合和用户启动新的初始拉取且 `“ENABLE_CDC” : “true”`，则 SAP OData 服务将使因之前初始化发出的所有之前的增量令牌失效。使用过期的增量令牌调用连接器将导致异常：
`Could not open data access via extraction API RODPS_REPL_ODP_OPEN`
# OData 服务（非 ODP 来源）
## 完全加载
对于非 ODP（操作数据供应）系统，**完全加载**包括从源系统提取整个数据集并将其加载到目标系统中。由于非 ODP 系统本质上不支持增量等高级数据提取机制，因此该过程很简单，但可能会占用大量资源，具体取决于数据的大小。
## 增量加载
对于不支持 **ODP（操作数据供应）**的系统或实体，可以通过实施基于时间戳的机制来跟踪和提取更改，从而手动管理增量数据传输。
**基于时间戳的增量传输**
对于未启用 ODP 的实体（或启用 ODP 但未使用 ENABLE\$1CDC 标志的实体），我们可以在连接器中使用 `filteringExpression` 选项来指示我们要检索数据的 `datetime` 间隔。此方法依赖于数据中的时间戳字段，该字段表示每条记录的上次创建/修改时间。
**示例**
检索 2024-01-01T00:00:00.000 之后更改的记录
```
sapodata_df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"filteringExpression": "LastChangeDateTime >= 2024-01-01T00:00:00.000"
}, transformation_ctx=key)
```
注意：在此示例中，`LastChangeDateTime` 是表示每条记录上次修改时间的字段。实际字段名称可能会因具体的 SAP OData 实体而有所不同。
要在后续运行中获得新的数据子集，您需要使用新时间戳更新 `filteringExpression`。通常，此项将是先前检索到的数据的最大时间戳值。
**示例**
```
max_timestamp = get_max_timestamp(sapodata_df) # Function to get the max timestamp from the previous run
next_filtering_expression = f"LastChangeDateTime > {max_timestamp}"
# Use this next_filtering_expression in your next run
```
在下一节中，我们将提供一种自动化的方法来管理这些基于时间戳的增量传输，从而无需在两次运行之间手动更新筛选表达式。
# 写入 SAP OData
本节说明如何使用 SAP OData 的 AWS Glue 连接器将数据写入您的 SAP OData 服务。
**先决条件**
+ 访问 SAP OData 服务
+ 您要写入的 SAP OData 实体集对象。您将需要对象名称。
+ 有效的 SAP OData 凭证和有效的连接
+ [IAM 策略](https://docs.aws.amazon.com/glue/latest/dg/sap-odata-configuring-iam-permissions.html)中描述的适当权限
SAP OData 连接器支持两种写入操作：
+ INSERT
+ UPDATE
在使用 UPDATE 写入操作时，必须提供 ID\$1FIELD\$1NAMES 参数以指定记录的外部 ID 字段。
**示例：**
```
sapodata_write = glueContext.write_dynamic_frame.from_options(
frame=frameToWrite,
connection_type="sapodata",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"WRITE_OPERATION": "INSERT"
}
```
# 使用 SAP OData 状态管理脚本
要在 AWS Glue 作业中使用 SAP OData 状态管理脚本，请执行以下步骤：
+ 从公共 Amazon S3 存储桶下载状态管理脚本：`s3://aws-blogs-artifacts-public/artifacts/BDB-4789/sap_odata_state_management.zip `。
+ 将脚本上传到您的 AWS Glue 作业有权访问的 Amazon S3 存储桶。
+ 在 AWS Glue 作业中引用脚本：创建或更新 AWS Glue 作业时，传递引用 Amazon S3 存储桶中脚本路径的 `'--extra-py-files'` 选项。例如：`--extra-py-files s3://your-bucket/path/to/sap_odata_state_management.py`
+ 在 AWS Glue 作业脚本中导入和使用状态管理库。
## 基于增量令牌的增量传输示例
以下是有关如何使用状态管理脚本进行基于增量令牌的增量传输的示例：
```
from sap_odata_state_management import StateManagerFactory, StateManagerType, StateType
# Initialize the state manager
state_manager = StateManagerFactory.create_manager(
manager_type=StateManagerType.JOB_TAG,
state_type=StateType.DELTA_TOKEN,
options={
"job_name": args['JOB_NAME'],
"logger": logger
}
)
# Get connector options (including delta token if available)
key = "SAPODataNode"
connector_options = state_manager.get_connector_options(key)
# Use the connector options in your Glue job
df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "true",
**connector_options
}
)
# Process your data here...
# Update the state after processing
state_manager.update_state(key, sapodata_df.toDF())
```
## 基于时间戳的增量传输示例
以下是有关如何使用状态管理脚本进行基于增量令牌的增量传输的示例：
```
from sap_odata_state_management import StateManagerFactory, StateManagerType, StateType
# Initialize the state manager
state_manager = StateManagerFactory.create_manager(
manager_type=StateManagerType.JOB_TAG,
state_type=StateType.DELTA_TOKEN,
options={
"job_name": args['JOB_NAME'],
"logger": logger
}
)
# Get connector options (including delta token if available)
key = "SAPODataNode"
connector_options = state_manager.get_connector_options(key)
# Use the connector options in your Glue job
df = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"ENABLE_CDC": "true",
**connector_options
}
)
# Process your data here...
# Update the state after processing
state_manager.update_state(key, sapodata_df.toDF())
```
在这两个示例中，状态管理脚本处理在两次作业运行之间存储状态（增量令牌或时间戳）的复杂性。它会在获取连接器选项时自动检索上次已知状态，并在处理后更新状态，从而确保每次运行的作业仅处理新的或更改的数据。
# 非 ODP 实体的分区
在 Apache Spark 中，分区是指在集群中的 Worker 节点之间划分和分配数据以实现并行处理的方式。每个分区都是一个逻辑数据块，可以通过任务独立处理。分区是 Spark 中的一个基本概念，它直接影响性能、可扩展性和资源利用率。AWS Glue 作业使用 Spark 的分区机制将数据集划分为较小的块（分区），从而可以在集群的 Worker 节点上并行处理。请注意，分区不适用于 ODP 实体。
有关更多详细信息，请参阅 [AWS Glue Spark 和 PySpark 作业](https://docs.aws.amazon.com/glue/latest/dg/spark_and_pyspark.html)。
**先决条件**
您要从中读取内容的 SAP OData 对象。您将需要对象/实体集名称。例如：` /sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder `。
**示例**
```
sapodata_read = glueContext.create_dynamic_frame.from_options(
connection_type="SAPOData",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "/sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder"
}, transformation_ctx=key)
```
## 对查询进行分区
### 基于字段的分区
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。整数、日期和日期时间字段支持 SAP OData 连接器中基于字段的分区。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于任何数据类型为 DateTime 的字段，接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：`"2000-01-01T00:00:00.000Z"`
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
+ `PARTITION_BY`：要执行的类型分区；如果是基于字段的分区，则传递 `FIELD`。
**示例**
```
sapodata= glueContext.create_dynamic_frame.from_options(
connection_type="sapodata",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "/sap/opu/odata/sap/SEPM_HCM_SCENARIO_SRV/EmployeeSet",
"PARTITION_FIELD": "validStartDate"
"LOWER_BOUND": "2000-01-01T00:00:00.000Z"
"UPPER_BOUND": "2020-01-01T00:00:00.000Z"
"NUM_PARTITIONS": "10",
"PARTITION_BY": "FIELD"
}, transformation_ctx=key)
```
### 基于记录的分区
原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
只有非 ODP 实体支持基于记录的分区，因为 ODP 实体中的分页通过下一个令牌/跳过令牌支持。
+ `PARTITION_BY`：要执行的类型分区。如果是基于记录的分区，则传递 `COUNT`。
**示例**
```
sapodata= glueContext.create_dynamic_frame.from_options(
connection_type="sapodata",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "/sap/opu/odata/sap/SEPM_HCM_SCENARIO_SRV/EmployeeSet",
"NUM_PARTITIONS": "10",
"PARTITION_BY": "COUNT"
}, transformation_ctx=key)
```
# 限制/标注
+ 由于分页使用跳过令牌/增量令牌处理，ODP 实体与基于记录的分区不兼容。因此，对于基于记录的分区，无论用户输入什么，maxConcurrency 的默认值都设置为“null”。
+ 当同时应用限制和分区时，限制优先于分区。
# SAP OData 连接选项
以下是 SAP OData 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。SAP OData 中对象的名称。
例如：/sap/opu/odata/sap/API\$1SALES\$1ORDER\$1SRV/A\$1SalesOrder
+ `API_VERSION`（字符串）：（可选）用于读取。您想要使用的 SAP OData Rest API 版本。示例：2.0。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
例如：SalesOrder
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
例如：`SalesOrder = "10"`
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
例如：`SELECT * FROM /sap/opu/odata/sap/API_SALES_ORDER_SRV/A_SalesOrder`
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
例如：`ValidStartDate`
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
例如：`"2000-01-01T00:00:00.000Z"`
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
例如：`"2024-01-01T00:00:00.000Z"`
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（字符串）：SAP 实例应用程序主机 URL。
例如：`https://example-externaldata.sierra.aws.dev`
+ `SERVICE_PATH`（字符串）：SAP 实例应用程序服务路径。
例如：`/sap/opu/odata/iwfnd/catalogservice;v=2`
+ `CLIENT_NUMBER`（字符串）：SAP 实例应用程序客户端编号。
例如：100
+ `PORT_NUMBER`（字符串）：默认值：SAP 实例应用程序端口号。
例如：443
+ `LOGON_LANGUAGE`（字符串）：SAP 实例应用程序登录语言。
例如：`EN`
+ `ENABLE_CDC`（字符串）：定义是否在启用 CDC（即跟踪更改）的情况下运行作业。
例如：`True/False`
+ `DELTA_TOKEN`（字符串）：根据提供的有效增量令牌运行增量数据拉取。
例如：`D20241107043437_000463000`
+ `PAGE_SIZE`（整数）：定义查询记录的页面大小。默认页面大小为 50000。指定页面大小后，SAP 在每次 API 调用时仅返回定义的记录数，而不是整个数据集。连接器仍将提供记录总数，并使用您指定的页面大小处理分页。如果您需要更大的页面大小，则可以选择不超过 500000（即允许的最大值）的任何值。任何超过 500000 的指定页面大小都将忽略。而系统将使用允许的最大页面大小。您可以通过添加带有所需值的连接选项 `PAGE_SIZE` 在 AWS Glue Studio UI 中指定页面大小。
例如：`20000`
# SAP OData 实体和字段详细信息
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/sap-odata-entity-field-details.html)
# 连接到 SendGrid
SendGrid 是一个用于收发交易和营销电子邮件的客户沟通平台。
+ SendGrid 连接器可帮助创建和管理联系人列表，以及创建电子邮件营销活动。
+ SendGrid 让在线企业、非营利组织和其他在线实体能够创建和发送营销电子邮件给大量受众，同时监控受众与这些电子邮件的互动情况。
**Topics**
+ [AWS Glue 支持 SendGrid](sendgrid-support.md)
+ [包含创建和使用连接的 API 操作的策略](sendgrid-configuring-iam-permissions.md)
+ [配置 SendGrid](sendgrid-configuring.md)
+ [配置 SendGrid 连接](sendgrid-configuring-connections.md)
+ [从 SendGrid 实体读取内容](sendgrid-reading-from-entities.md)
+ [SendGrid 连接选项](sendgrid-connection-options.md)
+ [SendGrid 限制](sendgrid-limitations.md)
# AWS Glue 支持 SendGrid
AWS Glue 对 SendGrid 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 SendGrid 中的数据。
**是否支持作为目标？**
否。
**支持的 SendGrid API 版本**
支持以下 SendGrid API 版本：
+ v3
# 包含创建和使用连接的 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 控制台的用户。
# 配置 SendGrid
必须满足以下要求，才能使用 AWS Glue 从 SendGrid 传输数据：
## 最低要求
以下是最低要求：
+ 拥有一个包含 API 密钥的 SendGrid 账户。
+ SendGrid 账户拥有有效许可证的 API 访问权限。
如果满足这些要求，就可以将 AWS Glue 连接到 SendGrid 账户。对于常见连接，无需在 SendGrid 中执行其他操作。
# 配置 SendGrid 连接
SendGrid 支持自定义身份验证。
有关生成自定义身份验证所需 API 密钥的 SendGrid 公共文档，请参阅 [Authentication](https://www.twilio.com/docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/authentication)。
要配置 SendGrid 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的消费者密钥，且以 `api_key` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 SendGrid。
1. 提供想要连接到的 SendGrid 实例的 `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` 的权限。
# 从 SendGrid 实体读取内容
**先决条件**
要从中读取内容的 SendGrid 对象。需要 `lists`、`singlesends` 或 `segments` 等对象名称。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| Lists | 否 | 是 | 否 | 是 | 否 |
| 单次发送 | 支持 | 是 | 否 | 是 | 否 |
| 营销活动统计数据-自动化 | 支持 | 是 | 否 | 是 | 否 |
| 营销活动统计数据-单次发送 | 支持 | 是 | 否 | 是 | 否 |
| Segments | 是 | 否 | 否 | 是 | 否 |
| 联系人 | 是 | 否 | 否 | 是 | 否 |
| 类别 | 否 | 否 | 否 | 是 | 否 |
| 统计信息 | 是 | 否 | 否 | 是 | 否 |
| 取消订阅组 | 是 | 否 | 否 | 是 | 否 |
**示例：**
```
sendgrid_read = glueContext.create_dynamic_frame.from_options(
connection_type="sendgrid",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "lists",
"API_VERSION": "v3",
"INSTANCE_URL": "instanceUrl"
}
```
**SendGrid 实体和字段详细信息**：
具有静态元数据的实体：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/sendgrid-reading-from-entities.html)
**注意**
在连接器的响应中，“结构体”和“列表”数据类型将转换为“字符串”数据类型，“日期时间”数据类型将转换为“时间戳”数据类型。
## 对查询进行分区
SendGrid 不支持基于筛选条件的分区或基于记录的分区。
# SendGrid 连接选项
以下是 SendGrid 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。SendGrid 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 SendGrid Rest API 版本。
+ `INSTANCE_URL`（字符串）：（必填）用于读取。有效的 SendGrid 实例 URL。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# SendGrid 限制
以下是 SendGrid 的限制或说明：
+ 仅 `start_date` 字段上的“统计数据”实体和 `event_timestamp` 字段上的“联系人”实体支持增量拉取。
+ 只有“营销活动统计数据（自动化）”、“营销活动统计数据（单次发送）”、“单次发送”和“列表”实体支持分页。
+ 对于“统计数据”实体，`start_date` 是必要的筛选条件参数。
+ 具有受限访问权限的 API 密钥不支持电子邮件 API 和“统计数据”实体的读取权限。使用具有完全访问权限的 API 密钥。有关更多信息，请参阅 [API Overview](https://www.twilio.com/docs/sendgrid/api-reference/api-keys/create-api-keys#api-overview)。
# 连接到 ServiceNow
ServiceNow 是一个基于云的 SaaS 平台，用于实现 IT 管理工作流的自动化。ServiceNow 平台可轻松与其他工具集成，从而让用户能够使用各种应用程序和插件来管理项目、团队以及客户互动。作为 ServiceNow 用户，您可以将 AWS Glue 连接到您的 ServiceNow 账户。然后就可以将 ServiceNow 作为 ETL 作业中的数据来源。通过运行这些作业，可在 ServiceNow 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 对 ServiceNow 的支持](servicenow-support.md)
+ [包含创建和使用连接的 API 操作的策略](servicenow-configuring-iam-permissions.md)
+ [配置 ServiceNow](servicenow-configuring.md)
+ [配置 ServiceNow 连接](servicenow-configuring-connections.md)
+ [从 ServiceNow 实体中读取](servicenow-reading-from-entities.md)
+ [ServiceNow 连接选项](servicenow-connection-options.md)
+ [ServiceNow 连接器的限制和说明](servicenow-connector-limitations.md)
# AWS Glue 对 ServiceNow 的支持
AWS Glue 对 ServiceNow 的支持如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 ServiceNow 中的数据。
**是否支持作为目标？**
否。
**支持的 ServicNow API 版本**
支持以下 ServiceNow API 版本：
+ v2
有关每个版本的相应实体支持，请参阅“源支持的实体”。
# 包含创建和使用连接的 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 控制台的用户。
# 配置 ServiceNow
必须满足以下要求，才能使用 AWS Glue 从 ServiceNow 传出数据：
## 最低要求
以下是最低要求：
+ 您拥有一个 ServiceNow 账户，以及电子邮件地址和密码。有关更多信息，请参阅 [创建 ServiceNow 账户](#servicenow-configuring-creating-servicenow-account)。
+ 您的 ServiceNow 账户已启用 API 访问权限。对 ServiceNow API 的所有使用均无需额外付费。
如果满足这些要求，就可以将 AWS Glue 连接到 ServiceNow 账户。
## 创建 ServiceNow 账户
要创建 ServiceNow 账户，请按以下步骤操作：
1. 导航到 servicenow.com 上的注册页面，输入您的详细信息，然后单击**继续**。
1. 当您通过注册邮件收到验证码后，请输入该验证码，然后选择**验证**。
1. 设置多重验证或跳过多重验证。
这时您的账户将创建完毕，并且 ServiceNow 会显示您的个人资料。
## 创建 ServiceNow 开发者实例
登录 ServiceNow 后请求开发者实例。
1. 在 [ServiceNow 登录页面](https://signon.service-now.com/x_snc_sso_auth.do?pageId=username)上，输入您的账户凭证。
1. 选择 **ServiceNow 开发者计划**。
![\[\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/servicenow-dev-program.png)
1. 选择右上角的**请求实例**。
1. 输入您的工作职责。确认您同意使用条款，然后选择**完成设置**。
1. 创建实例后，请记下实例 URL 和您的凭证。
## 检索 BasicAuth 凭证
要检索免费账户的 Basic Auth 凭证，请执行以下操作：
1. 在 [ServiceNow 登录页面](https://signon.service-now.com/x_snc_sso_auth.do?pageId=username)上，输入您的账户凭证。
1. 在主页上，选择编辑配置文件部分（右上角），然后选择**管理实例密码**。
1. 检索登录凭证，例如用户名、密码和实例 URL 等。
**注意**
如果账户启用了 MFA，请将 MFA 令牌附加到 Basic Auth 中的用户密码末尾：:
有关更多信息，请参阅 ServiceNow 文档中的 [Building applications](https://docs.servicenow.com/bundle/xanadu-application-development/page/build/custom-application/concept/build-applications.html)。
## 创建 OAuth 2.0 凭证
要在 ServiceNow 连接器中使用 OAuth2.0，您需要创建一个入站客户端来生成客户端 ID 和客户端密钥：
1. 在 [ServiceNow 登录页面](https://signon.service-now.com/x_snc_sso_auth.do?pageId=username)上，输入您的账户凭证。
1. 在首页中，选择**开始生成**。
1. 在 App Engine Studio 页面上，搜索**应用程序注册表**。
1. 选择右上角的**新建**。
1. 选择**为外部客户端创建 OAuth API 端点**选项。
1. 对 OAuth 配置进行任何必要的更改，然后选择**更新**。
重定向 URL 示例：https://us-east-1.console.aws.amazon.com/gluestudio/oauth
1. 选择新创建的 OAuth 客户端应用程序，检索客户端 ID 和客户端密钥。
1. 存储客户端 ID 和客户端密钥，以便用于后续处理。
要在非生产开发者账户中配置 OAuth，请按以下步骤操作：
1. 按照 ServiceNow 文档中[创建身份验证配置文件](https://docs.servicenow.com/bundle/washingtondc-platform-security/page/integrate/authentication/task/create-an-authentication-profile.html)主题的说明操作，创建一个身份验证配置文件。
1. 在 OAuth 的身份验证配置文件中，将**类型**选择为 OAuth，然后选择上面创建的入站客户端来设置 **OAuth 实体**。
1. 如果有多个客户端，则需要创建多个身份验证配置文件，以在身份验证配置文件中设置所需的 OAuth 实体。
1. 如果尚未配置 REST API 访问策略，则请创建一个，以便授予对 TABLE API 的访问权限。请参阅 [Create REST API access policy](https://docs.servicenow.com/bundle/washingtondc-platform-security/page/integrate/authentication/task/create-api-access-policy.html)。
# 配置 ServiceNow 连接
该授权类型决定了 AWS Glue 如何与 ServiceNow 通信来请求访问数据。您选择的授权类型会影响您在创建连接之前必须满足的要求。ServiceNow 仅支持 OAuth 2.0 的 AUTHORIZATION\$1CODE 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 ServiceNow，用户必须登录并向 AWS Glue 授予所请求的权限，以便访问其 ServiceNow 实例。
+ 用户仍然可以选择在 ServiceNow 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 ServiceNow，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 ServiceNow 公共文档，请参阅 [Set up OAuth](https://docs.servicenow.com/bundle/vancouver-platform-security/page/administer/security/task/t_SettingUpOAuth.html)。
要配置 ServiceNow 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于基本身份验证，密钥应包含关联应用程序的消费者密钥，且以 `USERNAME` 和 `PASSWORD` 为键。
1. 对于授权码授权类型，密钥应包含关联应用程序的消费者密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
1. 注意：您必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 ServiceNow。
1. 提供想要连接到的 ServiceNow 实例的 INSTANCE\$1URL。
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 中此连接的**授权类型**。
1. 基本身份验证：此身份验证类型非常适合自动化场景，因为它允许预先使用用户名和密码以及 ServiceNow 实例中特定用户的权限。AWS Glue 能够使用用户名和密码对 ServiceNow API 进行身份验证。仅在使用基本身份验证的情况下输入以下输入以下内容：`Username` 和 `Password`。
1. OAuth2：仅在使用 OAuth 2 的情况下输入以下内容：`ClientId`、`ClientSecret`、`Authorization URL`、`Authorization Token URL`。
1. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 ServiceNow 实体中读取
**先决条件**
您要从中读取内容的 ServiceNow 表对象。您将需要 pa\$1bucket 或 incident 等对象名称。
**示例：**
```
servicenow_read = glueContext.create_dynamic_frame.from_options(
connection_type="servicenow",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "pa_buckets",
"API_VERSION": "v2"
"instanceUrl": "https://.service-now.com"
}
)
```
**ServiceNow 实体和字段详细信息**：
对于以下实体，ServiceNow 提供用于动态获取元数据的端点，以便在每个实体的数据类型级别捕获运算符支持。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/servicenow-reading-from-entities.html)
**注意**
在连接器的响应中，结构数据类型将转换为字符串数据类型。
**注意**
`DML_STATUS` 是用于跟踪 CREATED/UPDATED 记录的附加用户定义属性。
## 对查询进行分区
**基于字段的分区**：
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/servicenow-reading-from-entities.html)
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于日期时间字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"2024-01-30T06:47:51.000Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
下表描述实体分区字段支持详细信息：
示例：
```
servicenow_read = glueContext.create_dynamic_frame.from_options(
connection_type="servicenow",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "pa_buckets",
"API_VERSION": "v2",
"instanceUrl": "https://.service-now.com"
"PARTITION_FIELD": "sys_created_on"
"LOWER_BOUND": "2024-01-30T06:47:51.000Z"
"UPPER_BOUND": "2024-06-30T06:47:51.000Z"
"NUM_PARTITIONS": "10"
}
```
**基于记录的分区**：
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `NUM_PARTITIONS`。使用此参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
在基于记录的分区中，从 ServiceNow API 查询存在的记录总数，然后将其除以提供的 `NUM_PARTITIONS` 数字。然后，每个子查询会同时获取生成的记录数。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
servicenow_read = glueContext.create_dynamic_frame.from_options(
connection_type="servicenow",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "pa_buckets",
"API_VERSION": "v2",
"instanceUrl": "https://.service-now.com"
"NUM_PARTITIONS": "2"
}
```
# ServiceNow 连接选项
以下是 ServiceNow 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。ServiceNow 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 ServiceNow Rest API 版本。例如：v1、v2、v3、v4。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。例如：2024-01-30T06:47:51.000Z。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。例如：2024-06-30T06:47:51.000Z。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。例如：10。
+ `INSTANCE_URL`（字符串）：（必填）有效的 ServiceNow 实例 URL，格式为 https://.service-now.com。
+ `PAGE_SIZE`（整数）：定义查询记录的页面大小。默认页面大小为 1000。指定页面大小后，ServiceNow 在每次 API 调用时仅返回定义的记录数，而不是整个数据集。连接器仍将提供记录总数，并使用您指定的页面大小处理分页。如果您需要更大的页面大小，则可以选择不超过 10000（即允许的最大值）的任何值。任何超过 10000 的指定页面大小都将忽略。而系统将使用允许的最大页面大小。您可以通过添加带有所需值的连接选项 `PAGE_SIZE` 在 AWS Glue UI 中指定页面大小。例如：5000。
# ServiceNow 连接器的限制和说明
以下是 ServiceNow 连接器的限制或说明：
+ 根据 [SaaS文档](https://www.servicenow.com/docs/bundle/washingtondc-application-development/page/build/applications/reference/r_GlobalDefaultFields.html)，`sys_created_on`、`sys_updated_on` 和 `sys_mod_count` 是系统生成的字段。连接器依赖 SaaS API 来在响应正文中提供这些字段。
+ 如果 SaaS 没有为任何实体生成这些字段，则不支持基于筛选条件的分区。
+ 如果 SaaS API 在响应中未返回 `sys_created_on` 和 `sys_updated_on` 字段，则无法计算 `DML_STATUS`。
+ 提高读取性能和效率
+ 当用户未指定 ORDER BY 子句时，ServiceNow 连接器现会自动按 `sys_id` 字段（该字段必须存在于元数据中）对记录进行升序排序。在此情况下，记录将根据新的基于键集优化的分页机制进行分页。
+ 如果指定了 ORDER BY 子句，则不会使用新的优化方案，而是采用现有方法（基于用户定义的 Order By 和 Offset-Limit 的分页机制）来获取记录。
# 在 AWS Glue Studio 中连接到 Slack
Slack 是一款企业通信应用程序，允许用户通过各种公共和私人频道发送消息和附件。如果您是 Slack 用户，则可以将 AWS Glue 连接到您的 Slack 账户。然后，您可以使用 Slack 作为 ETL 作业中的数据来源。通过运行这些作业，可在 Slack 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 对 Slack 的支持](slack-support.md)
+ [包含创建和使用连接的 API 操作的策略](slack-configuring-iam-permissions.md)
+ [配置 Slack](slack-configuring.md)
+ [配置 Slack 连接](slack-configuring-connections.md)
+ [从 Slack 实体中读取](slack-reading-from-entities.md)
+ [Slack 连接选项](slack-connection-options.md)
+ [限制](slack-limitations.md)
+ [创建新的 Slack 账户并配置客户端应用程序](slack-new-account-creation.md)
# AWS Glue 对 Slack 的支持
AWS Glue 对 Slack 的支持如下：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业查询 Slack 中的数据。
**是否支持作为目标？**
否。
**支持的 Slack API 版本**
Slack API v2。
# 包含创建和使用连接的 API 操作的策略
以下示例策略描述了创建和使用连接所需的 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、Amazon 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 控制台的用户。
# 配置 Slack
您必须满足以下要求，才能使用 AWS Glue 与 Slack 进行数据往来传输：
## 最低要求
+ 您必须具有 Slack 账户。有关更多信息，请参阅 [创建新的 Slack 账户并配置客户端应用程序](slack-new-account-creation.md)。
如果您满足这些要求，就可以将 AWS Glue 连接到您的 Slack 账户。
# 配置 Slack 连接
Slack 支持 OAuth 2 的 `AUTHORIZATION_CODE` 授权类型。
此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Slack，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Slack 实例。
用户仍然可以选择在 Slack 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Slack，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌在创建 1 小时后过期。可以使用刷新令牌获取新的访问令牌。
有关为授权码 OAuth 流程创建关联应用程序的更多信息，请参阅 [Slack API](https://api.slack.com/quickstart)。
要配置 Slack 连接：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。必须在 AWS Glue 中为连接创建一个密钥。
1. 对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Slack。
1. 提供 Slack 环境。
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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Slack 实体中读取
**先决条件**
+ 您要从中读取内容的 Slack 对象。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 对话 | 支持 | 是 | 否 | 是 | 是 |
**示例**
```
slack_read = glueContext.create_dynamic_frame.from_options(
connection_type="slack",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "conversations/C058W38R5J8"
}
)
```
**Slack 实体和字段详细信息**
| 实体 | 字段 | 数据类型 | 支持的运算符 |
| --- | --- | --- | --- |
| 对话 | attachments | 列表 | NA |
| 对话 | bot\$1id | 字符串 | NA |
| 对话 | blocks | 列表 | NA |
| 对话 | client\$1msg\$1id | 字符串 | NA |
| 对话 | is\$1starred | 布尔值 | NA |
| 对话 | last read | 字符串 | NA |
| 对话 | latest\$1reply | 字符串 | NA |
| 对话 | reactions | 列表 | NA |
| 对话 | replies | 列表 | NA |
| 对话 | reply\$1count | 整数 | NA |
| 对话 | reply\$1users | 列表 | NA |
| 对话 | reply\$1users\$1count | 整数 | NA |
| 对话 | subscribed | 布尔值 | NA |
| 对话 | subtype | 字符串 | NA |
| 对话 | 文本 | 字符串 | NA |
| 对话 | team | 字符串 | NA |
| 对话 | thread\$1ts | 字符串 | NA |
| 对话 | ts | 字符串 | EQUAL\$1TO, BETWEEN, LESS\$1THAN, LESS\$1THAN\$1OR\$1EQUAL\$1TO, GREATER\$1THAN, GREATER\$1THAN\$1OR\$1EQUAL\$1TO |
| 对话 | type | 字符串 | NA |
| 对话 | 用户 | 字符串 | NA |
| 对话 | inviter | 字符串 | NA |
| 对话 | root | 结构体 | NA |
| 对话 | is\$1locked | 布尔值 | NA |
| 对话 | 文件 | 列表 | NA |
| 对话 | 房间 | 结构体 | NA |
| 对话 | 上传 | 布尔值 | NA |
| 对话 | display\$1as\$1bot | 布尔值 | NA |
| 对话 | 渠道 | 字符串 | NA |
| 对话 | no\$1notifications | 布尔值 | NA |
| 对话 | permalink | 字符串 | NA |
| 对话 | pinned\$1to | 列表 | NA |
| 对话 | pinned\$1info | 结构体 | NA |
| 对话 | edited | 结构体 | NA |
| 对话 | app\$1id | 字符串 | NA |
| 对话 | bot\$1profile | 结构体 | NA |
| 对话 | metadata | 结构体 | NA |
**对查询进行分区**
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-07-01T00:00:00.000Z"`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
基于实体的分区字段支持详细信息如下表中所示。
| 实体名称 | 分区字段 | 数据类型 |
| --- | --- | --- |
| 对话 | ts | 字符串 |
**示例**
```
slack_read = glueContext.create_dynamic_frame.from_options(
connection_type="slack",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "conversations/C058W38R5J8",
"PARTITION_FIELD": "ts"
"LOWER_BOUND": "2022-12-01T00:00:00.000Z"
"UPPER_BOUND": "2024-09-23T15:00:00.000Z"
"NUM_PARTITIONS": "2"
}
)
```
# Slack 连接选项
以下是 Slack 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。支持的实体名称。示例：`conversations/C058W38R5J8`。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的字段。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# 限制
以下是 Slack 连接器的限制：
+ 不支持基于记录的分区，因为连接器不提供任何方法来获取给定对话中可用的记录（消息）总数。
# 创建新的 Slack 账户并配置客户端应用程序
**创建 Slack 账户**
1. 打开 [Slack 主页](https://slack.com/intl/en-in/)注册账户。
1. 选择**使用电子邮件地址注册**。输入您的电子邮件 ID，然后选择**继续**。
1. 输入发送到您电子邮件地址的 6 个字符的代码，其将引导您创建工作区或加入现有工作区。
1. 选择**创建工作区**以创建新工作区。作为设置过程的一部分，其将引导您回答几个问题。
+ 公司的名称
+ 您的姓名
+ 要通过电子邮件添加同事
+ 您的团队在做什么？ （此项将为频道名称）
1. 填写这些问题的输入字段并继续。您的账户现已准备好可供使用。
**创建 Slack 开发者应用程序**
1. 登录您的 Slack 账户并登录 Slack 工作区。
1. 在工作区菜单中，选择**工具和设置**，然后选择**管理应用程序**。
1. 从 Slack 应用程序目录菜单中，选择**构建**。
1. 在**您的应用程序**页面上，选择**创建应用程序**。
1. 在**创建应用程序**页面上，选择**从头开始**。
1. 在打开的**命名应用程序并选择工作区**对话框中，添加应用程序名称并**选择要在其中部署应用程序的工作区**。然后选择**创建应用程序**。
1. 记下应用程序凭证中显示的客户端 ID 和密钥
1. 在 OAuth 和权限侧栏上，转到“范围”并选择**添加 OAuth 范围**。您可以将重定向 URL 添加到您的应用程序以进行配置，从而自动生成“添加到 Slack”按钮或分发您的应用程序。向上滚动到“重定向 URL”部分，选择**添加新的重定向 URL** 并保存。
1. 然后，滚动到“您的工作区的 OAuth 令牌”部分并选择**安装到工作区**。
1. 打开的对话框中说明，您创建的应用程序正在请求对所要连接的 Slack 工作区的访问权限，选择**允许**。
1. 成功完成后，控制台将显示“您的工作区的 OAuth 令牌”屏幕。
1. 从“您的工作区的 OAuth 令牌”屏幕，复制并保存您将用于连接到 AWS Glue 的 OAuth 令牌
1. 接下来，您检索 Slack 团队 ID。在 Slack 工作区菜单中，选择**工具和设置**，然后选择**管理应用程序**。您可以在打开的页面的 URL 中找到您的团队 ID。
1. 要公开分发应用程序，您可以前往侧栏上的**管理分发**按钮进行激活。向下滚动到“与其他工作区共享您的应用程序”部分，然后选择**删除硬编码信息**。同意后选择**主动公开分发**。
1. 您的应用程序现已公开分发。要访问实体 API，需要将应用程序添加到用户想要访问的每个工作区频道。
1. 登录您的 Slack 账户，打开需要访问其频道的工作区。
1. 在工作区中，打开应用程序要访问的频道，然后选择频道标题。从弹出窗口中选择**集成**选项卡并添加该应用程序。通过这种方式，应用程序可以与频道集成以访问其 API。
OAuth 2.0 客户端 ID 必须有一个或多个经过授权的重定向 URL。重定向 URL 采用以下格式：
**注意**
Appflow 重定向 URL 可能会发生变化，AWS Glue 平台的重定向 URL 可用。客户端 ID 和客户端密钥来自 OAuth 2.0 客户端 ID 的设置。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/slack-new-account-creation.html)
# 连接到 Smartsheet
Smartsheet 是一款旨在协助工作管理和协作的 SaaS 产品。从根本上讲，Smartsheet 允许用户使用类似电子表格的对象来创建、存储和利用业务数据。
**Topics**
+ [AWS Glue 支持 SmartSheet](smartsheet-support.md)
+ [包含创建和使用连接的 API 操作的策略](smartsheet-configuring-iam-permissions.md)
+ [配置 Smartsheet](smartsheet-configuring.md)
+ [配置 Smartsheet 连接](smartsheet-configuring-connections.md)
+ [从 Smartsheet 实体读取内容](smartsheet-reading-from-entities.md)
+ [Smartsheet 连接选项](smartsheet-connection-options.md)
+ [创建 Smartsheet 账户](smartsheet-create-account.md)
+ [限制](smartsheet-connector-limitations.md)
# AWS Glue 支持 SmartSheet
AWS Glue 对 Smartsheet 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Smartsheet 的数据。
**是否支持作为目标？**
否。
**支持的 Smartsheet API 版本**
v2.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 控制台的用户。
# 配置 Smartsheet
必须满足以下要求，才能使用 AWS Glue 从 Smartsheet 传输数据：
## 最低要求
+ 拥有一个 Smartsheet 账户以及相应的电子邮件地址和密码。有关创建账户的更多信息，请参阅[创建 Smartsheet 账户](smartsheet-create-account.md)。
+ Smartsheet 账户拥有 API 访问权限和有效许可证。
+ Smartsheet 账户有针对 `Sheets` 实体的**专业版定价**方案，以及针对 `Events` 实体的带事件报告附加组件的企业版定价方案。
如果满足这些要求，就可以将 AWS Glue 连接到 Smartsheet 账户。对于常见连接，无需在 Smartsheet 中执行其他操作。
# 配置 Smartsheet 连接
Smartsheet 支持 OAuth2 的 `AUTHORIZATION_CODE` 授权类型。
此授权类型被视为“三足型”`OAuth`，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。用户可以选择在 Smartsheet 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Smartsheet，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
有关为 AUTHORIZATION\$1CODE OAuth 流创建关联应用程序的 Smartsheet 公共文档，请参阅 [Smartsheet API](https://smartsheet.redoc.ly/#section/OAuth-Walkthrough)。
要配置 Smartsheret 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
**注意**
必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Smartsheet。
1. 提供想要连接到的 Smartsheert 的 `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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Smartsheet 实体读取内容
**先决条件**
要从中读取内容的 `Smartsheet` 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 列表工作表 | 支持 | 是 | 否 | 是 | 否 |
| 行元数据 | 支持 | 是 | 否 | 是 | 否 |
| 工作表元数据 | 否 | 否 | 否 | 是 | 否 |
| 工作表数据 | 支持 | 是 | 是 | 是 | 否 |
| 事件 | 支持 | 是 | 否 | 是 | 否 |
**示例**
```
Smartsheet_read = glueContext.create_dynamic_frame.from_options(
connection_type="smartsheet",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "list-sheets",
"API_VERSION": "2.0",
"INSTANCE_URL": "https://api.smartsheet.com"
})
```
**Smartsheet 实体和字段详细信息**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/smartsheet-reading-from-entities.html)
**具有动态元数据的实体**：
对于以下实体，Smartsheet 提供用于动态获取元数据的端点，以便在数据类型级别捕获运算符支持。
| 实体 | 数据类型 | 支持的运算符 |
| --- | --- | --- |
| 工作表数据 | 字符串 | NA |
| 工作表数据 | 长整型 | "=" |
| 工作表数据 | 整数 | NA |
| 工作表数据 | 日期时间 | > |
**示例**
```
Smartsheet_read = glueContext.create_dynamic_frame.from_options(
connection_type="smartsheet",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "list-sheets",
"API_VERSION": "2.0",
"INSTANCE_URL": "https://api.smartsheet.com"
}
```
# Smartsheet 连接选项
以下是 Smartsheet 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取/写入。Smartsheet 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取/写入。要使用的 Smartsheet Rest API 版本。例如：V2.0。
+ `INSTANCE_URL`（字符串）：（必填）用于读取。Smartsheet 实例 URL。
+ `SELECTED_FIELDS`（列表<字符串>）– 默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# 创建 Smartsheet 账户
1. 访问 [Smartsheet 注册页面](https://app.smartsheet.com/home)即可注册 Smartsheet 账户。
1. 选择**创建一个账户**来创建新账户，也可以使用已注册的 Google、Microsoft 或 Apple 账户登录。
1. 在出现提示时输入工作电子邮件地址。
1. 选择**继续**，再按需验证身份。
1. 打开来自 Smartsheet 的确认电子邮件，然后点击确认链接来验证账户。
此时默认订阅试用版方案。
1. 在左下角选择**账户**图标，然后选择**添加许可证/升级**来升级定价方案。
**注意**
必须执行此操作才能访问**事件报告**，因为事件报告是**企业版**方案中的附加组件。
1. 在**企业版**方案下选择**联系我们**，向支持团队请求账户升级。
1. 在支持请求表中，提供升级方案所需的详细信息以及相应的需求。
**企业版**方案升级到此完成。
**创建 `OAuth2.0` 凭证**
1. 升级账户的定价方案来访问**开发人员工具**后，请访问 [Smartsheet developers](https://developers.smartsheet.com/)。
此时会收到一封激活电子邮件。
1. 打开来自 Smartsheet 的激活电子邮件，点击激活链接，在账户中激活开发人员工具。
开发人员工具允许创建应用程序。
1. 打开 Smartsheet 账户的主页，然后选择**账户**来查看访问权限。
1. 从服务列表中选择**开发人员工具**，然后输入**开发人员资料**详细信息。
1. 选择**创建新的应用程序**。
1. 在应用程序注册表中输入以下详细信息：
+ **名称**：应用程序的名称。
+ **描述**：应用程序的描述。
+ **URL**：允许启动应用程序的 URL 或登录页面的 URL。
+ **联系人/支持人员**：支持团队的联系人信息。
+ **重定向 URL**：应用程序中接收 [OAuth 2.0](https://.console.aws.amazon.com/appflow/oauth) 凭证的 URL（也称为回传 URL）。
1. 选择**保存**。
Smartsheet 为应用程序分配客户端 ID 和客户端密钥。记录这些值，以便后续步骤使用。也可以稍后在**开发人员工具**部分再次查找这些值。
# 限制
Smartsheet 不支持基于字段的分区或基于记录的分区。
# 在 AWS Glue Studio 中连接到 Snapchat Ads
Snapchat 是由 Snap Inc.（原 Snapchat Inc.）开发的一款多媒体即时通讯应用程序和服务。Snapchat 的主要特点之一是，图片和消息通常仅在短时间内对接收者可见，然后便无法再访问。Snapchat Marketing 是企业可以付费向 Snapchat 用户展示的帖子。
**Topics**
+ [AWS Glue 对 Snapchat Ads 的支持](snapchat-ads-support.md)
+ [包含创建和使用连接的 API 操作的策略](snapchat-ads-configuring-iam-permissions.md)
+ [配置 Snapchat Ads](snapchat-ads-configuring.md)
+ [配置 Snapchat Ads 连接](snapchat-ads-configuring-connections.md)
+ [从 Snapchat Ads 实体中读取](snapchat-ads-reading-from-entities.md)
+ [Snapchat Ads 连接选项](snapchat-ads-connection-options.md)
+ [创建 Snapchat Ads 账户并配置客户端应用程序](connecting-to-data-snapchat-ads-new-account.md)
+ [在 Snapchat Ads 账户中创建应用程序](connecting-to-data-snapchat-ads-managed-client-application.md)
# AWS Glue 对 Snapchat Ads 的支持
AWS Glue 对 Snapchat Ads 的支持如下：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业查询 Snapchat Ads 中的数据。
**是否支持作为目标？**
否。
**支持的 Snapchat Ads 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、Amazon 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 控制台的用户。
# 配置 Snapchat Ads
您必须满足以下要求，才能使用 AWS Glue 从 Snapchat Ads 传输：
## 最低要求
+ 您有一个 Snapchat Ads 账户。有关创建账户的更多信息，请参阅 [创建 Snapchat Ads 账户并配置客户端应用程序](connecting-to-data-snapchat-ads-new-account.md)。
+ 您已在 Snapchat Ads 账户中创建了 OAuth2 应用程序。此集成提供 AWS Glue 在对您的账户进行身份验证调用时用于安全访问数据的凭证。有关更多信息，请参阅 [在 Snapchat Ads 账户中创建应用程序](connecting-to-data-snapchat-ads-managed-client-application.md)。
如果您满足这些要求，就可以将 AWS Glue 连接到您的 Snapchat Ads 账户。在 Snapchat Ads 中，关联应用程序是一个框架，用于授权外部应用程序（例如 AWS Glue）访问您的 Snapchat Ads 数据。
# 配置 Snapchat Ads 连接
Snapchat Ads 仅支持 `AUTHORIZATION_CODE` 授权类型。
此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。默认情况下，创建连接的用户可以依赖于 AWS Glue 拥有的关联应用程序（AWS Glue 托管客户端应用程序），在该应用程序中，除了 Snapchat Ads 实例 URL 之外，用户无需提供任何与 OAuth 相关的信息。AWS Glue 控制台会将用户重定向到 Snapchat Ads，用户必须登录并向 AWS Glue 授予所请求的权限，以访问其 Snapchat Ads 实例。
用户仍然可以选择在 Snapchat Ads 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Snapchat Ads，以便登录并授权 AWS Glue 访问其资源。
此授权类型会生成刷新令牌和访问令牌。访问令牌在创建 1 小时后过期。可以使用刷新令牌获取新的访问令牌。
有关为授权码 OAuth 流程创建关联应用程序的更多信息，请参阅 [Ads API](https://marketingapi.snapchat.com/docs/#authentication)。
要配置 Snapchat Ads 连接：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。
1. 对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Snapchat Ads。
1. 提供 Snapchat Ads 环境。
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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Snapchat Ads 实体中读取
**先决条件**
+ 您要从中读取内容的 Snapchat Ads 对象。请参阅下面的支持的实体表，查看可用的实体。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 组织 | 否 | 否 | 否 | 是 | 否 |
| 广告账户 | 否 | 否 | 否 | 是 | 否 |
| 创意 | 否 | 否 | 否 | 是 | 否 |
| 媒体 | 否 | 否 | 否 | 是 | 否 |
| 活动 | 是 | 否 | 否 | 是 | 否 |
| 广告账户下的广告 | 是 | 否 | 否 | 是 | 否 |
| 活动下的广告 | 否 | 否 | 否 | 是 | 否 |
| 广告小组 | 是 | 否 | 否 | 是 | 否 |
| 客户细分 | 否 | 否 | 否 | 是 | 否 |
**示例**
```
snapchatads_read = glueContext.create_dynamic_frame.from_options(
connection_type="snapchatAds",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "organization",
"API_VERSION": "v1"
}
)
```
**Snapchat Ads 实体和字段详细信息**
Snapchat Ads 会动态加载所选实体下的可用字段。根据字段的数据类型，它支持以下筛选运算符。
| 字段数据类型 | 支持的筛选运算符 |
| --- | --- |
| 布尔值 | = |
**对查询进行分区**
+ 基于字段的分区：不支持。
+ 基于记录的分区：不支持。
# Snapchat Ads 连接选项
以下是 Snapchat Ads 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Snapchat Ads 实体的名称。示例：` campaign `。
+ `API_VERSION`（字符串）：（必填）用于读取。您想要使用的 Snapchat Ads Rest API 版本。该值将为 v1，因为 Snapchat Ads 目前仅支持版本 v1。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为所选实体选择的列的逗号分隔列表。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# 创建 Snapchat Ads 账户并配置客户端应用程序
**Topics**
+ [注册 Snapchat Ads](#snapchat-ads-sign-up)
+ [创建 Snapchat Ads 账户的步骤](#snapchat-ads-create-ad-account)
## 注册 Snapchat Ads
**要注册 Snapchat Ads：**
1. 导航到 [Snapchat Ads Manager](https://ads.snapchat.com/)。选择 **Snapchat 新手？**旁边的**注册**。
1. 在**创建账户**屏幕上，按照提示输入您的公司名称、电子邮件、密码等。选择**下一步**。
1. 在**创建您的个人资料**屏幕上，输入用户名、网站（可选）的值，然后选择**创建账户**。这将使您可以选择在**编辑您的个人资料**屏幕上添加个人资料照片和简介。选择**确认**。
1. 在**企业信息**屏幕上，填写国家/地区、货币、电话号码、GSTIN 等必填字段，然后选择**下一步**完成账户创建过程。
## 创建 Snapchat Ads 账户的步骤
**要创建 Snapchat Ad 账户：**
1. 登录**广告管理器**。然后，单击顶部角落的导航栏并选择**广告账户**。
1. 选择 **\$1 新广告账户**。输入您的广告商详细信息：
+ 选择您是否是代表广告商购买广告的代理机构。如果您选择“是”，则您的广告使用的定位参数可能包括年龄、性别或邮政编码级别定位时，该广告可能会被拒绝。最低年龄定位可适用于 21 岁以下的受众。
+ 选择您的广告账户是否投放住房、信贷或招聘广告。如果您选择“是”，则您的广告使用的定位参数可能包括年龄、性别或邮政编码级别定位时，该广告可能会被拒绝。最低年龄定位可适用于 21 岁以下的受众。
+ 选择是否将使用该广告账户投放政治广告。如果您要投放政治广告，则请输入为该广告付费的赞助政治组织或倡导团体。如果没有准确输入政治组织，则您的广告可能会被拒绝。在提交广告之前，您还需要填写必填链接“政治广告审查表”。
1. 选择**账户详细信息**并填写您的广告账户信息：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/connecting-to-data-snapchat-ads-new-account.html)
1. 选择**创建账户**。将创建您的广告账户，您可以在广告管理器的“广告账户”部分中找到该账户。要开始投放广告，您需要输入付款方式。您还可以向广告账户添加成员。
1. 选择是使用现有付款方式还是创建新付款方式。然后，选择**保存付款方式**。
1. 选择[您邀请加入企业的所有成员](https://businesshelp.snapchat.com/s/article/manage-members?language=en_US)，将其添加到广告账户。有关可以分配的角色和权限的更多信息，请参阅 [Roles and Permissions Overview](https://businesshelp.snapchat.com/s/article/roles-permissions?language=en_US)。添加的成员随后将能够登录广告管理器并访问此广告账户。完成后，请保存您的成员。
有关广告账户的更多信息，请参阅 [https://businesshelp.snapchat.com/s/article/roles-permissions?language=en_US](https://businesshelp.snapchat.com/s/article/roles-permissions?language=en_US)https://businesshelp.snapchat.com/s/article/roles-permissions?language=en\$1US
# 在 Snapchat Ads 账户中创建应用程序
要激活对 Snapchat Marketing API 的访问权限，请确保您已设置企业账户。然后按以下步骤操作。
1. 登录广告管理器。然后选择左上角的菜单并选择**企业控制面板**，再选择**企业详细信息**。
1. 选择 **\$1OAuth 应用程序**。
1. 输入应用程序名称并添加以下 URL 作为 Snap 重定向 URI `https://.console.aws.amazon.com/gluestudio/oauth`。例如，如果使用 us-west-1 区域，则该 URL 将为 `https://us-west-1.console.aws.amazon.com/gluestudio/oauth) and choose Create OAuth App`。选择**创建 OAuth 应用程序**。
1. 将显示应用程序凭证（客户端 ID 和客户端密钥）。保存创建连接所需的这些凭证。
# 在 AWS Glue Studio 连接到 Snowflake
**注意**
在 AWS Glue 4.0 及更高版本中，您可以使用 AWS Glue for Spark 在 Snowflake 中读取和写入表。要以编程方式为 Snowflake 连接配置 AWS Glue 作业，请参阅 [Redshift 连接](aws-glue-programming-etl-connect-redshift-home.md)。
AWS Glue 提供对 Snowflake 的内置支持。AWS Glue Studio 提供一个可视化界面，用于连接到 Snowflake、创作数据集成作业并在 AWS Glue Studio 无服务器 Spark 运行时上运行这些作业。
AWS Glue Studio 为 Snowflake 创建统一连接。有关更多信息，请参阅 [注意事项](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。
**Topics**
+ [创建 Snowflake 连接](creating-snowflake-connection.md)
+ [创建 Snowflake 源节点](creating-snowflake-source-node.md)
+ [创建 Snowflake 目标节点](creating-snowflake-target-node.md)
+ [高级选项](#creating-snowflake-connection-advanced-options)
# 创建 Snowflake 连接
**注意**
统一连接（连接 v2）将所有连接标准化，以便使用 `USERNAME`、`PASSWORD` 密钥作为基本身份验证凭证。仍可通过包含 `sfUser`、`sfPassword` 密钥的 API 创建 v1 连接。
在 AWS Glue Studio 中添加**数据来源 - Snowflak** 节点时，您可以选择现有的 AWS Glue Snowflake 连接或创建新连接。必须选择 `SNOWFLAKE` 类型连接，而不是配置为连接到 Snowflake 的 `JDBC` 类型连接。请按照以下过程创建 AWS Glue Snowflake 连接：
**创建 Snowflake 连接**
1. 在 Snowflake 中，生成一个用户 *snowflakeUser* 和密码 *snowflakePassword*。
1. 确定 Snowflake 仓库，该用户将与哪个 *snowflakeWarehouse* 互动。要么将其设置为 *snowflakeUser* 的 `DEFAULT_WAREHOUSE`，要么在下一步中记住它。
1. 在 AWS Secrets Manager 中，使用您的 Snowflake 凭证创建密钥。要在 Secrets Manager 中创建密钥，请按照 AWS Secrets Manager 文档中[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html#create_secret_cli)中的教程进行操作。创建密钥后，保留密钥名称 *secretName*，以供下一步使用。
+ 选择**键/值对**时，请使用键 `sfUser` 为 *snowflakeUser* 创建一对。
+ 选择**键/值对**时，请使用键 `sfPassword` 为 *snowflakePassword* 创建一对。
+ 选择**键/值对**时，请使用键 `sfWarehouse` 为 *snowflakeWarehouse* 创建一对。如果在 Snowflake 中设置了默认值，则不需要这样做。
1. 在 AWS Glue Data Catalog 中，按照[添加 AWS Glue 连接](https://docs.aws.amazon.com//glue/latest/dg/console-connections.html)中的步骤创建连接。创建连接后，保留连接名称 *connectionName*，以供下一步使用。
+ 选择**连接类型**时，请选择 Snowflake。
+ 选择 **Snowflake URL** 时，请提供您的 Snowflake 实例的主机名。URL 将使用表单 `account_identifier.snowflakecomputing.com` 中的主机名。
+ 选择 **AWS 密钥**时，请提供 *secretName*。
# 创建 Snowflake 源节点
## 所需权限
使用 Snowflake 数据来源的 AWS Glue Studio 作业需要额外的权限。有关如何为 ETL 作业添加权限的更多信息，请参阅 [Review IAM permissions needed for ETL jobs](https://docs.aws.amazon.com/glue/latest/ug/setting-up.html#getting-started-min-privs-job)。
`SNOWFLAKE` AWS Glue 连接使用 AWS Secrets Manager 密钥来提供凭证信息。您在 AWS Glue Studio 中的作业和数据预览角色必须具有读取此密钥的权限。
## 添加 Snowflake 数据来源
**先决条件：**
+ 您的 Snowflake 凭证的 AWS Secrets Manager 密钥
+ Snowflake 类型 AWS Glue Data Catalog 连接
**要添加**数据来源 — Snowflake** 节点，请执行以下操作：**
1. 为您的 Snowflake 数据来源选择连接。这假设该连接已经存在，并且您可以从现有连接中进行选择。如果需要创建连接，请选择**创建 Snowflake 连接**。有关更多信息，请参阅 [Overview of using connectors and connections](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#using-connectors-overview)。
选择连接后，您可以通过单击**查看属性**来查看连接属性。可以看到有关连接的信息，包括 URL、安全组、子网、可用区、描述以及创建时间（UTC）和上次更新时间（UTC）时间戳。
1. 选择 Snowflake 源选项：
+ **选择单个表** - 该表包含您要从单个 Snowflake 表中访问的数据。
+ **输入自定义查询** - 允许您根据自定义查询访问多个 Snowflake 表中的数据集。
1. 如果您选择单个表，请输入 Snowflake 架构的名称。
或者，选择**输入自定义查询**。选择此选项可访问多个 Snowflake 表中的自定义数据集。选择此选项后，输入 Snowflake 查询。
1. 在**性能和安全**选项（可选）中，
+ **启用查询下推** — 选择是否要将工作卸载到 Snowflake 实例。
1. 在**自定义 Snowflake 属性**（可选）中，根据需要输入参数和值。
# 创建 Snowflake 目标节点
## 所需权限
使用 Snowflake 数据来源的 AWS Glue Studio 作业需要额外的权限。有关如何为 ETL 作业添加权限的更多信息，请参阅 [Review IAM permissions needed for ETL jobs](https://docs.aws.amazon.com/glue/latest/ug/setting-up.html#getting-started-min-privs-job)。
`SNOWFLAKE` AWS Glue 连接使用 AWS Secrets Manager 密钥来提供凭证信息。您在 AWS Glue Studio 中的作业和数据预览角色必须具有读取此密钥的权限。
## 添加 Snowflake 数据目标
**要创建 Snowflake 目标节点，请执行以下操作：**
1. 选择现有 Snowflake 表作为目标，或输入新的表名。
1. 使用**数据目标 - Snowflake** 目标节点时，可以从以下选项中进行选择：
+ **附加** - 如果表已经存在，则将所有新数据作为插入内容转储到表中。如果表不存在，请创建表并插入所有新数据。
+ **合并** - AWS Glue 将根据您指定的条件更新数据或将数据附加到目标表。
选择选项：
+ **选择键和简单操作** - 选择要用作源数据和目标数据集之间匹配键的列。
匹配时指定以下选项：
+ 使用源数据更新目标数据集中的记录。
+ 删除目标数据集中的记录。
如果不匹配，请指定以下选项：
+ 将源数据作为新行插入目标数据集。
+ 不执行任何操作。
+ **输入自定义 MERGE 语句** - 然后，您可以选择**验证合并语句**来验证该语句是有效还是无效。
+ **截断** - 如果表已经存在，请先清除目标表的内容，从而截断表数据。如果截断成功，则插入所有数据。如果表不存在，请创建表并插入所有数据。如果截断不成功，操作将失败。
+ **丢弃** - 如果表已存在，则删除表的元数据和数据。如果删除成功，则插入所有数据。如果表不存在，请创建表并插入所有数据。如果丢失不成功，操作将失败。
## 高级选项
请参阅《AWS Glue 开发人员者指南》中的 [Snowflake connections](https://docs.aws.amazon.com//glue/latest/dg/aws-glue-programming-etl-connect-snowflake-home.html)。
# 在 AWS Glue Studio 中连接到 Stripe
Stripe 是一个面向企业的在线支付处理和信用卡处理平台。通过 Stripe 平台，企业可以接受在线支付，为其电子商务创建订阅（定期计费），并设置收款账户以接收付款。Stripe 还支持多方支付，允许企业设置自己的市场和收取款项，然后通过“已关联”账户向卖家或服务提供商付款。
**Topics**
+ [AWS Glue 对 Stripe 的支持](stripe-support.md)
+ [包含创建和使用连接的 API 操作的策略](stripe-configuring-iam-permissions.md)
+ [配置 Stripe](stripe-configuring.md)
+ [配置 Stripe 连接](stripe-configuring-connections.md)
+ [从 Stripe 实体中读取](stripe-reading-from-entities.md)
+ [Stripe 连接选项](stripe-connection-options.md)
+ [限制](stripe-limitations.md)
+ [创建新的 Stripe 账户并配置客户端应用程序](stripe-new-account-creation.md)
# AWS Glue 对 Stripe 的支持
AWS Glue 对 Stripe 的支持如下：
**是否支持作为来源？**
是。您可以使用 AWS Glue ETL 作业查询 Stripe 中的数据。
**是否支持作为目标？**
否。
**支持的 Slack API 版本**
v1。
# 包含创建和使用连接的 API 操作的策略
以下示例策略描述了创建和使用连接所需的 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、Amazon 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 控制台的用户。
# 配置 Stripe
您必须满足以下要求，才能使用 AWS Glue 从 Stripe 传输数据：
## 最低要求
+ 您必须拥有一个包含电子邮件和密码的 Stripe 账户。有关更多信息，请参阅 [创建新的 Stripe 账户并配置客户端应用程序](stripe-new-account-creation.md)。
+ 您的 Stripe 账户已启用 API 访问权限。Stripe API 的所有使用均无需额外付费。
如果您满足这些要求，就可以将 AWS Glue 连接到您的 Stripe 账户。
# 配置 Stripe 连接
Stripe 支持自定义身份验证。有关生成自定义授权所需 API 密钥的更多信息，请参阅 [STRIPE REST API 文档](https://docs.stripe.com/api/authentication)。
要配置 Stripe 连接：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥。需要为 AWS Glue 中的每个连接创建一个密钥。
1. 对于客户托管的关联应用程序：密钥应包含关联应用程序的消费者密钥，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Stripe。
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. 在 AWS Glue 中选择您要用于此连接的 `secretName`，然后放置令牌。
1. 如果要使用网络，请选择网络选项。
1. 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 `secretName` 的权限。
# 从 Stripe 实体中读取
**先决条件**
+ 您要从中读取内容的 Stripe 对象。
**支持的实体**
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 余额 | 否 | 否 | 否 | 是 | 否 |
| 余额交易 | 支持 | 是 | 否 | 是 | 是 |
| 收费 | 支持 | 是 | 否 | 是 | 是 |
| 争议 | 支持 | 是 | 否 | 是 | 是 |
| 文件链接 | 支持 | 是 | 否 | 是 | 是 |
| 付款意图 | 支持 | 是 | 否 | 是 | 是 |
| 设置意图 | 支持 | 是 | 否 | 是 | 是 |
| 支出 | 支持 | 是 | 否 | 是 | 是 |
| 退款 | 支持 | 是 | 否 | 是 | 是 |
| 产品 | 支持 | 是 | 否 | 是 | 是 |
| 价格 | 支持 | 是 | 否 | 是 | 是 |
| 优惠券 | 支持 | 是 | 否 | 是 | 是 |
| 促销代码 | 支持 | 是 | 否 | 是 | 是 |
| 税码 | 否 | 是 | 否 | 是 | 否 |
| 税率 | 支持 | 是 | 否 | 是 | 是 |
| 运费 | 支持 | 是 | 否 | 是 | 是 |
| 会话 | 支持 | 是 | 否 | 是 | 是 |
| 信用票据 | 支持 | 是 | 否 | 是 | 是 |
| Customer | 支持 | 是 | 否 | 是 | 是 |
| 账单 | 支持 | 是 | 否 | 是 | 是 |
| 发票项目 | 支持 | 是 | 否 | 是 | 否 |
| 计划 | 支持 | 是 | 否 | 是 | 是 |
| 报价 | 支持 | 是 | 否 | 是 | 否 |
| 订阅 | 支持 | 是 | 否 | 是 | |
| 订阅项目 | 否 | 是 | 否 | 是 | 否 |
| 订阅计划 | 支持 | 是 | 否 | 是 | 是 |
| 账户 | 否 | 是 | 否 | 是 | 是 |
| 申请费 | 支持 | 是 | 否 | 是 | 是 |
| 国家/地区具体要求 | 否 | 是 | 否 | 是 | 否 |
| 转接 | 支持 | 是 | 否 | 是 | 是 |
| 欺诈预警 | 支持 | 是 | 否 | 是 | 是 |
| 报告类型 | 否 | 否 | 否 | 是 | 否 |
**示例**
```
stripe_read = glueContext.create_dynamic_frame.from_options(
connection_type="stripe",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "coupons",
"API_VERSION": "v1"
}
)
```
**Stripe 实体和字段详细信息**
| 实体 | 字段 | 数据类型 | 支持的运算符 |
| --- | --- | --- | --- |
| 余额 | | | |
| | available | 列表 | |
| | connect\$1reserved | 列表 | |
| | 待处理 | 列表 | |
| | livemode | 布尔值 | |
| | object | 字符串 | |
| | instant\$1available | 列表 | |
| | issuing | 结构体 | |
| 余额交易 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 量 | 整数 | |
| | available\$1on | 日期时间 | =, >=, <=,<,> |
| | created | 日期时间 | =, >=, <=,<,> |
| | currency | 字符串 | |
| | description | 字符串 | |
| | exchange\$1rate | BigDecimal | |
| | fee | 整数 | |
| | fee\$1details | 列表 | |
| | net | 整数 | |
| | reporting\$1category | 字符串 | |
| | 源 | 字符串 | = |
| | 状态 | 字符串 | |
| | type | 字符串 | = |
| | cross\$1border\$1classification | 字符串 | |
| 收费 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 量 | 整数 | =, <, > |
| | amount\$1captured | 整数 | |
| | amount\$1refunded | 整数 | |
| | 应用程序 | 字符串 | |
| | application\$1fee | 字符串 | |
| | application\$1fee\$1amount | 整数 | |
| | balance\$1transaction | 字符串 | |
| | billing\$1details | 结构体 | |
| | calculated\$1statement\$1descriptor | 字符串 | |
| | captured | 布尔值 | |
| | created | 日期时间 | =, >=, <=,<,> |
| | currency | 字符串 | |
| | customer | 字符串 | = |
| | description | 字符串 | |
| | destination | 字符串 | |
| | dispute | 字符串 | |
| | disputed | 布尔值 | = |
| | failure\$1balance\$1transaction | 字符串 | |
| | failure\$1code | 字符串 | |
| | failure\$1message | 字符串 | |
| | fraud\$1details | 结构体 | |
| | 发票 | 字符串 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | on\$1behalf\$1of | 字符串 | |
| | 顺序 | 字符串 | |
| | outcome | 结构体 | |
| | paid | 布尔值 | |
| | payment\$1intent | 字符串 | = |
| | payment\$1method | 字符串 | |
| | payment\$1method\$1details | 结构体 | |
| | receipt\$1email | 字符串 | |
| | receipt\$1number | 字符串 | |
| | receipt\$1url | 字符串 | |
| | refunded | 布尔值 | = |
| | 退款 | 结构体 | |
| | 审核 | 字符串 | |
| | shipping | 结构体 | |
| | 源 | 结构体 | |
| | source\$1transfer | 字符串 | |
| | statement\$1descriptor | 字符串 | |
| | statement\$1descriptor\$1suffix | 字符串 | |
| | 状态 | 字符串 | |
| | 转移 | 字符串 | |
| | transfer\$1data | 结构体 | |
| | transfer\$1group | 字符串 | = |
| 争议 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 量 | 整数 | =, <, > |
| | balance\$1transaction | 字符串 | |
| | balance\$1transactions | 列表 | |
| | 费用 | 字符串 | = |
| | created | 日期时间 | =, >=, <=,<,> |
| | currency | 字符串 | |
| | evidence | 结构体 | |
| | evidence\$1details | 结构体 | |
| | is\$1charge\$1refundable | 布尔值 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | payment\$1intent | 字符串 | = |
| | reason | 字符串 | = |
| | 状态 | 字符串 | |
| | payment\$1method\$1details | 结构体 | |
| 文件链接 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | created | 日期时间 | =, >=, <=,<,> |
| | expired | 布尔值 | = |
| | expires\$1at | 日期时间 | |
| | 文件 | 字符串 | = |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | url | 字符串 | |
| 付款意图 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 量 | 整数 | |
| | amount\$1capturable | 整数 | |
| | amount\$1details | 结构体 | |
| | amount\$1received | 整数 | |
| | 应用程序 | 字符串 | |
| | application\$1fee\$1amount | 整数 | |
| | automatic\$1payment\$1methods | 结构体 | |
| | canceled\$1at | 日期时间 | |
| | cancellation\$1reason | 字符串 | |
| | capture\$1method | 字符串 | |
| | client\$1secret | 字符串 | |
| | confirmation\$1method | 字符串 | |
| | created | 日期时间 | =, >=, <=,<,> |
| | currency | 字符串 | |
| | customer | 字符串 | = |
| | description | 字符串 | |
| | 发票 | 字符串 | |
| | last\$1payment\$1error | 结构体 | |
| | latest\$1charge | 字符串 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | next\$1action | 结构体 | |
| | on\$1behalf\$1of | 字符串 | |
| | payment\$1method | 字符串 | |
| | payment\$1method\$1options | 结构体 | |
| | payment\$1method\$1types | 列表 | |
| | payment\$1method\$1configuration\$1details | 结构体 | |
| | 处理 | 结构体 | |
| | receipt\$1email | 字符串 | |
| | 审核 | 字符串 | |
| | setup\$1future\$1usage | 字符串 | |
| | shipping | 结构体 | |
| | 源 | 字符串 | |
| | statement\$1descriptor | 字符串 | |
| | statement\$1descriptor\$1suffix | 字符串 | |
| | 状态 | 字符串 | |
| | transfer\$1data | 结构体 | |
| | transfer\$1group | 字符串 | |
| 设置意图 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 应用程序 | 字符串 | |
| | cancellation\$1reason | 字符串 | |
| | client\$1secret | 字符串 | |
| | created | 日期时间 | =, >=, <=,<,> |
| | customer | 字符串 | = |
| | description | 字符串 | |
| | flow\$1directions | 列表 | |
| | last\$1setup\$1error | 结构体 | |
| | latest\$1attempt | 字符串 | |
| | livemode | 布尔值 | |
| | mandate | 字符串 | |
| | metadata | 结构体 | |
| | next\$1action | 结构体 | |
| | on\$1behalf\$1of | 字符串 | |
| | payment\$1method | 字符串 | |
| | payment\$1method\$1options | 结构体 | |
| | payment\$1method\$1types | 列表 | |
| | single\$1use\$1mandate | 字符串 | |
| | 状态 | 字符串 | |
| | 使用情况 | 字符串 | |
| | automatic\$1payment\$1methods | 结构体 | |
| 支出 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 量 | 整数 | =, <, > |
| | arrival\$1date | 日期时间 | =, >=, <=,<,> |
| | automatic | 布尔值 | |
| | balance\$1transaction | 字符串 | |
| | created | 日期时间 | =, >=, <=,<,> |
| | currency | 字符串 | |
| | description | 字符串 | = |
| | destination | 字符串 | |
| | failure\$1balance\$1transaction | 字符串 | |
| | failure\$1code | 字符串 | |
| | failure\$1message | 字符串 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | method | 字符串 | |
| | original\$1payout | 字符串 | |
| | reversed\$1by | 字符串 | |
| | reconciliation\$1status | 字符串 | |
| | source\$1type | 字符串 | |
| | statement\$1descriptor | 字符串 | |
| | 状态 | 字符串 | |
| | type | 字符串 | |
| | application\$1fee | 字符串 | |
| | application\$1fee\$1amount | 整数 | |
| 退款 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 量 | 整数 | |
| | balance\$1transaction | 字符串 | |
| | 费用 | 字符串 | = |
| | created | 日期时间 | =, >=, <=,<,> |
| | currency | 字符串 | |
| | metadata | 结构体 | |
| | destination\$1details | 结构体 | |
| | payment\$1intent | 字符串 | = |
| | reason | 字符串 | |
| | receipt\$1number | 字符串 | |
| | source\$1transfer\$1reversal | 字符串 | |
| | 状态 | 字符串 | |
| | transfer\$1reversal | 字符串 | |
| 产品 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | active | 布尔值 | = |
| | 属性 | 列表 | |
| | created | 日期时间 | =, >=, <=,<,> |
| | default\$1price | 字符串 | |
| | description | 字符串 | |
| | 映像 | 列表 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | 名称 | 字符串 | |
| | package\$1dimensions | 结构体 | |
| | shippable | 布尔值 | |
| | statement\$1descriptor | 字符串 | |
| | tax\$1code | 字符串 | |
| | type | 字符串 | = |
| | unit\$1label | 字符串 | |
| | 已更新 | 日期时间 | |
| | url | 字符串 | |
| | 功能 | 列表 | |
| 价格 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | active | 布尔值 | = |
| | billing\$1scheme | 字符串 | |
| | created | 日期时间 | =, >=, <=,<,> |
| | currency | 字符串 | = |
| | custom\$1unit\$1amount | 结构体 | |
| | livemode | 布尔值 | |
| | lookup\$1key | 字符串 | |
| | metadata | 结构体 | |
| | nickname | 字符串 | |
| | 产品 | 字符串 | = |
| | recurring | 结构体 | |
| | tax\$1behavior | 字符串 | |
| | tiers\$1mode | 字符串 | |
| | transform\$1quantity | 结构体 | |
| | type | 字符串 | = |
| | unit\$1amount | 整数 | |
| | unit\$1amount\$1decimal | 字符串 | |
| 优惠券 | | | |
| | Id | 字符串 | |
| | object | 字符串 | |
| | amount\$1off | 整数 | |
| | created | 日期时间 | =, >=, <=,<,> |
| | currency | 字符串 | = |
| | duration | 字符串 | = |
| | duration\$1in\$1months | 整数 | =,<,> |
| | livemode | 布尔值 | |
| | max\$1redemptions | 整数 | =, <, > |
| | metadata | 结构体 | |
| | 名称 | 字符串 | |
| | percent\$1off | 双精度 | = |
| | redeem\$1by | 日期时间 | =, >=, <=, <, > |
| | times\$1redeemed | 整数 | |
| | valid | 布尔值 | |
| 促销代码 | | | |
| | Id | 字符串 | |
| | object | 字符串 | |
| | active | 布尔值 | = |
| | code | 字符串 | = |
| | coupon | 结构体 | |
| | created | 日期时间 | =,>=,<=,<,> |
| | customer | 字符串 | |
| | expires\$1at | 日期时间 | |
| | livemode | 布尔值 | |
| | max\$1redemptions | 整数 | |
| | metadata | 结构体 | |
| | 限额 | 结构体 | |
| | times\$1redeemed | 整数 | |
| 税码 | | | |
| | Id | 字符串 | |
| | object | 字符串 | |
| | description | 字符串 | |
| | 名称 | 字符串 | |
| 税率 | | | |
| | Id | 字符串 | |
| | object | 字符串 | |
| | active | 布尔值 | = |
| | country | 字符串 | |
| | created | 日期时间 | =, >=, <=, <, > |
| | description | 字符串 | |
| | display\$1name | 字符串 | |
| | inclusive | 布尔值 | = |
| | jurisdiction | 字符串 | |
| | jurisdiction\$1level | 字符串 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | percentage | 双精度 | |
| | effective\$1percentage | 双精度 | |
| | 状态 | 字符串 | |
| | tax\$1type | 字符串 | |
| 运费 | | | |
| | Id | 字符串 | |
| | object | 字符串 | |
| | active | 布尔值 | = |
| | created | 日期时间 | =, >=, <=, <, > |
| | delivery\$1estimate | 结构体 | |
| | display\$1name | 字符串 | |
| | fixed\$1amount | 结构体 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | tax\$1behavior | 字符串 | |
| | tax\$1code | 字符串 | |
| | type | 字符串 | |
| 会话 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | after\$1expiration | 结构体 | |
| | allow\$1promotion\$1codes | 布尔值 | |
| | amount\$1subtotal | 整数 | |
| | amount\$1total | 整数 | |
| | automatic\$1tax | 结构体 | |
| | billing\$1address\$1collection | 字符串 | |
| | cancel\$1url | 字符串 | |
| | client\$1reference\$1id | 字符串 | |
| | consent | 结构体 | |
| | consent\$1collection | 结构体 | |
| | created | 日期时间 | =, >=, <=, <, > |
| | currency | 字符串 | |
| | custom\$1text | 结构体 | |
| | customer | 字符串 | |
| | customer\$1creation | 字符串 | |
| | customer\$1details | 结构体 | |
| | customer\$1email | 字符串 | |
| | expires\$1at | 日期时间 | |
| | 发票 | 字符串 | |
| | invoice\$1creation | 结构体 | |
| | livemode | 布尔值 | |
| | locale | 字符串 | |
| | metadata | 结构体 | |
| | mode | 字符串 | |
| | payment\$1intent | 字符串 | = |
| | payment\$1link | 字符串 | |
| | payment\$1method\$1collection | 字符串 | |
| | payment\$1method\$1options | 结构体 | |
| | payment\$1method\$1types | 列表 | |
| | payment\$1status | 字符串 | |
| | phone\$1number\$1collection | 结构体 | |
| | recovered\$1from | 字符串 | |
| | setup\$1intent | 字符串 | |
| | shipping\$1address\$1collection | 结构体 | |
| | shipping\$1cost | 结构体 | |
| | shipping\$1details | 结构体 | |
| | shipping\$1options | 列表 | |
| | 状态 | 字符串 | |
| | submit\$1type | 字符串 | |
| | 订阅 | 字符串 | |
| | success\$1url | 字符串 | |
| | tax\$1id\$1collection | 结构体 | |
| | total\$1details | 结构体 | |
| | url | 字符串 | |
| | ui\$1mode | 字符串 | |
| 信用票据 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 量 | 整数 | |
| | created | 日期时间 | =, >=, <=, <, > |
| | currency | 字符串 | |
| | customer | 字符串 | = |
| | customer\$1balance\$1transaction | 字符串 | |
| | discount\$1amount | 整数 | |
| | discount\$1amounts | 列表 | |
| | 发票 | 字符串 | = |
| | lines | 结构体 | |
| | livemode | 布尔值 | |
| | memo | 字符串 | |
| | metadata | 结构体 | |
| | 数字 | 字符串 | |
| | out\$1of\$1band\$1amount | 整数 | |
| | pdf | 字符串 | |
| | reason | 字符串 | |
| | refund | 字符串 | |
| | 状态 | 字符串 | |
| | subtotal | 整数 | |
| | subtotal\$1excluding\$1tax | 整数 | |
| | tax\$1amounts | 列表 | |
| | total | 整数 | |
| | total\$1excluding\$1tax | 整数 | |
| | type | 字符串 | |
| | voided\$1at | 日期时间 | |
| | amount\$1shipping | 整数 | |
| | effective\$1at | 日期时间 | |
| | shipping\$1cost | 结构体 | |
| Customer | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 地址 | 结构体 | |
| | balance | 整数 | |
| | created | 日期时间 | |
| | currency | 字符串 | =, >=, <=, <, > |
| | default\$1source | 字符串 | |
| | delinquent | 布尔值 | = |
| | description | 字符串 | |
| | discount | 结构体 | |
| | 电子邮件 | 字符串 | = |
| | invoice\$1prefix | 字符串 | |
| | invoice\$1settings | 结构体 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | 名称 | 字符串 | |
| | next\$1invoice\$1sequence | 整数 | |
| | phone | 字符串 | |
| | preferred\$1locales | 列表 | |
| | shipping | 结构体 | |
| | tax\$1exempt | 字符串 | |
| | test\$1clock | 字符串 | |
| 账单 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | account\$1country | 字符串 | |
| | account\$1name | 字符串 | |
| | account\$1tax\$1ids | 列表 | |
| | amount\$1due | 整数 | |
| | amount\$1paid | 整数 | |
| | amount\$1remaining | 整数 | |
| | 应用程序 | 字符串 | |
| | application\$1fee\$1amount | 整数 | |
| | attempt\$1count | 整数 | |
| | attempted | 布尔值 | = |
| | auto\$1advance | 布尔值 | = |
| | automatic\$1tax | 结构体 | |
| | billing\$1reason | 字符串 | |
| | 费用 | 字符串 | |
| | collection\$1method | 字符串 | = |
| | created | 日期时间 | =, >=, <=, <, > |
| | currency | 字符串 | |
| | custom\$1fields | 列表 | |
| | customer | 字符串 | = |
| | customer\$1address | 结构体 | |
| | customer\$1email | 字符串 | |
| | customer\$1name | 字符串 | |
| | customer\$1phone | 字符串 | |
| | customer\$1shipping | 结构体 | |
| | customer\$1tax\$1exempt | 字符串 | |
| | customer\$1tax\$1ids | 列表 | |
| | default\$1payment\$1method | 字符串 | |
| | default\$1source | 字符串 | |
| | default\$1tax\$1rates | 列表 | |
| | description | 字符串 | |
| | discount | 结构体 | |
| | discounts | 列表 | |
| | due\$1date | 日期时间 | =, >=, <=, <, > |
| | ending\$1balance | 整数 | |
| | footer | 字符串 | |
| | from\$1invoice | 结构体 | |
| | hosted\$1invoice\$1url | 字符串 | |
| | invoice\$1pdf | 字符串 | |
| | last\$1finalization\$1error | 结构体 | |
| | latest\$1revision | 字符串 | |
| | lines | 结构体 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | next\$1payment\$1attempt | 日期时间 | |
| | 数字 | 字符串 | |
| | on\$1behalf\$1of | 字符串 | |
| | paid | 布尔值 | = |
| | paid\$1out\$1of\$1band | 布尔值 | |
| | payment\$1intent | 字符串 | |
| | payment\$1settings | 结构体 | |
| | period\$1end | 日期时间 | =, >=, <=, <, > |
| | period\$1start | 日期时间 | =, >=, <=, <, > |
| | post\$1payment\$1credit\$1notes\$1amount | 整数 | |
| | pre\$1payment\$1credit\$1notes\$1amount | 整数 | |
| | quote | 字符串 | |
| | receipt\$1number | 字符串 | |
| | rendering | 结构体 | |
| | rendering\$1options | 结构体 | |
| | starting\$1balance | 整数 | |
| | statement\$1descriptor | 字符串 | |
| | 状态 | 字符串 | = |
| | status\$1transitions | 结构体 | |
| | 订阅 | 字符串 | |
| | subscription\$1details | 结构体 | |
| | subtotal | 整数 | =, <, > |
| | subtotal\$1excluding\$1tax | 整数 | |
| | tax | 整数 | |
| | test\$1clock | 字符串 | |
| | total | 整数 | =, <, > |
| | total\$1discount\$1amounts | 列表 | |
| | total\$1excluding\$1tax | 整数 | |
| | total\$1tax\$1amounts | 列表 | |
| | transfer\$1data | 结构体 | |
| | webhooks\$1delivered\$1at | 日期时间 | |
| | automatically\$1finalizes\$1at | 日期时间 | |
| | effective\$1at | 日期时间 | |
| | 发布者 | 结构体 | |
| 发票项目 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 量 | 整数 | =, <, > |
| | currency | 字符串 | |
| | customer | 字符串 | = |
| | date | 日期时间 | |
| | description | 字符串 | |
| | discountable | 布尔值 | |
| | discounts | 列表 | |
| | 发票 | 字符串 | = |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | 周期 | 结构体 | |
| | 计划 | 结构体 | |
| | 价格 | 结构体 | |
| | proration | 布尔值 | = |
| | quantity | 整数 | |
| | 订阅 | 字符串 | |
| | subscription\$1item | 字符串 | |
| | tax\$1rates | 列表 | |
| | test\$1clock | 字符串 | |
| | unit\$1amount | 整数 | |
| | unit\$1amount\$1decimal | 字符串 | |
| 计划 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | active | 布尔值 | = |
| | aggregate\$1usage | 字符串 | |
| | 量 | 整数 | |
| | amount\$1decimal | 字符串 | |
| | billing\$1scheme | 字符串 | |
| | created | 日期时间 | =, >=, <=, <, > |
| | currency | 字符串 | = |
| | interval | 字符串 | = |
| | interval\$1count | 整数 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | nickname | 字符串 | |
| | 产品 | 字符串 | = |
| | tiers\$1mode | 字符串 | |
| | transform\$1usage | 结构体 | |
| | trial\$1period\$1days | 整数 | =, <, > |
| | usage\$1type | 字符串 | |
| | 计量器 | 字符串 | |
| 报价 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | amount\$1subtotal | 整数 | |
| | amount\$1total | 整数 | |
| | 应用程序 | 字符串 | |
| | application\$1fee\$1amount | 整数 | |
| | application\$1fee\$1percent | 双精度 | |
| | automatic\$1tax | 结构体 | |
| | collection\$1method | 字符串 | |
| | computed | 结构体 | |
| | created | 日期时间 | |
| | currency | 字符串 | |
| | customer | 字符串 | = |
| | default\$1tax\$1rates | 列表 | |
| | description | 字符串 | |
| | discounts | 列表 | |
| | expires\$1at | 日期时间 | |
| | footer | 字符串 | |
| | from\$1quote | 结构体 | |
| | header | 字符串 | |
| | 发票 | 字符串 | |
| | invoice\$1settings | 结构体 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | 数字 | 字符串 | |
| | on\$1behalf\$1of | 字符串 | |
| | 状态 | 字符串 | = |
| | status\$1transitions | 结构体 | |
| | 订阅 | 字符串 | |
| | subscription\$1data | 结构体 | |
| | subscription\$1schedule | 字符串 | |
| | test\$1clock | 字符串 | |
| | total\$1details | 结构体 | |
| | transfer\$1data | 结构体 | |
| 订阅 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 应用程序 | 字符串 | |
| | application\$1fee\$1percent | 双精度 | |
| | automatic\$1tax | 结构体 | |
| | billing\$1cycle\$1anchor | 日期时间 | |
| | billing\$1thresholds | 结构体 | |
| | cancel\$1at | 日期时间 | |
| | cancel\$1at\$1period\$1end | 布尔值 | |
| | canceled\$1at | 日期时间 | |
| | collection\$1method | 字符串 | = |
| | created | 日期时间 | =, >=, <=,<,> |
| | currency | 字符串 | |
| | current\$1period\$1end | 日期时间 | =, >=, <= |
| | current\$1period\$1start | 日期时间 | =, >=, <= |
| | customer | 字符串 | = |
| | days\$1until\$1due | 整数 | |
| | default\$1payment\$1method | 字符串 | |
| | default\$1source | 字符串 | |
| | default\$1tax\$1rates | 列表 | |
| | description | 字符串 | |
| | discount | 结构体 | |
| | ended\$1at | 日期时间 | |
| | 物品 | 结构体 | |
| | latest\$1invoice | 字符串 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | next\$1pending\$1invoice\$1item\$1invoice | 日期时间 | |
| | pause\$1collection | 结构体 | |
| | payment\$1settings | 结构体 | |
| | pending\$1invoice\$1item\$1interval | 结构体 | |
| | pending\$1setup\$1intent | 字符串 | |
| | pending\$1update | 结构体 | |
| | 计划 | 结构体 | |
| | quantity | 整数 | |
| | schedule | 字符串 | |
| | start\$1date | 日期时间 | |
| | 状态 | 字符串 | = |
| | test\$1clock | 字符串 | |
| | transfer\$1data | 结构体 | |
| | trial\$1end | 日期时间 | |
| | trial\$1start | 日期时间 | |
| 订阅项目 | | | |
| | Id | 字符串 | |
| | object | 字符串 | |
| | billing\$1thresholds | 结构体 | |
| | created | 日期时间 | =, >=, <=, <, > |
| | metadata | 结构体 | |
| | 计划 | 结构体 | |
| | 价格 | 结构体 | |
| | 订阅 | 字符串 | |
| | tax\$1rates | 列表 | |
| | discounts | 列表 | |
| 订阅计划 | | | |
| | object | 字符串 | |
| | 应用程序 | 字符串 | |
| | canceled\$1at | 日期时间 | |
| | completed\$1at | 日期时间 | |
| | created | 日期时间 | |
| | current\$1phase | 结构体 | |
| | customer | 字符串 | = |
| | default\$1settings | 结构体 | |
| | end\$1behavior | 字符串 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | phases | 列表 | |
| | released\$1at | 日期时间 | |
| | released\$1subscription | 字符串 | |
| | renewal\$1interval | 字符串 | |
| | 状态 | 字符串 | |
| | 订阅 | 字符串 | |
| | test\$1clock | 字符串 | |
| 账户 | | | |
| | details\$1submitted | 布尔值 | |
| | tos\$1acceptance | 结构体 | |
| | type | 字符串 | |
| | metadata | 结构体 | |
| | id | 字符串 | |
| | object | 字符串 | |
| | default\$1currency | 字符串 | |
| | 能力 | 结构体 | |
| | charges\$1enabled | 布尔值 | |
| | 设置 | 结构体 | |
| | 要求 | 结构体 | |
| | payouts\$1enabled | 布尔值 | |
| | future\$1requirements | 结构体 | |
| | external\$1accounts | 结构体 | |
| | 控制器 | 结构体 | |
| | country | 字符串 | |
| | 电子邮件 | 字符串 | |
| | created | 日期时间 | =, >=, <=, <, > |
| | business\$1profile | 结构体 | |
| | business\$1type | 字符串 | |
| | company | 结构体 | |
| 申请费 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 账户 | 字符串 | |
| | 量 | 整数 | =, <, > |
| | amount\$1refunded | 整数 | =, <, > |
| | 应用程序 | 字符串 | |
| | balance\$1transaction | 字符串 | |
| | 费用 | 字符串 | = |
| | created | 日期时间 | |
| | currency | 字符串 | |
| | livemode | 布尔值 | |
| | originating\$1transaction | 字符串 | |
| | refunded | 布尔值 | = |
| | 退款 | 结构体 | |
| | fee\$1source | 结构体 | |
| 国家/地区具体要求 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | default\$1currency | 字符串 | |
| | supported\$1bank\$1account\$1currencies | 结构体 | |
| | supported\$1payment\$1currencies | 列表 | |
| | supported\$1payment\$1methods | 列表 | |
| | supported\$1transfer\$1countries | 列表 | |
| | verification\$1fields | 结构体 | |
| 转接 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | 量 | 整数 | =, <, > |
| | amount\$1reversed | 整数 | |
| | balance\$1transaction | 字符串 | |
| | created | 日期时间 | =, >=, <=, <, > |
| | currency | 字符串 | = |
| | description | 字符串 | |
| | destination | 字符串 | = |
| | destination\$1payment | 字符串 | |
| | livemode | 布尔值 | |
| | metadata | 结构体 | |
| | reversals | 结构体 | |
| | reversed | 布尔值 | |
| | source\$1transaction | 字符串 | |
| | source\$1type | 字符串 | |
| | transfer\$1group | 字符串 | = |
| 欺诈预警 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | actionable | 布尔值 | |
| | 费用 | 字符串 | = |
| | created | 日期时间 | =, >=, <=, <, > |
| | fraud\$1type | 字符串 | |
| | livemode | 布尔值 | |
| | payment\$1intent | 字符串 | = |
| 报告类型 | | | |
| | id | 字符串 | |
| | object | 字符串 | |
| | data\$1available\$1end | 日期时间 | |
| | data\$1available\$1start | 日期时间 | |
| | default\$1columns | 列表 | |
| | livemode | 布尔值 | |
| | 名称 | 字符串 | |
| | 已更新 | 日期时间 | |
| | version | 整数 | |
**对查询进行分区**
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的包含下限值。
对于日期，我们接受 Spark SQL 查询中使用的 Spark 日期格式。有效值示例：`"2024-07-01T00:00:00.000Z"`。
+ `UPPER_BOUND`：所选分区字段的排除上限值。
+ `NUM_PARTITIONS`：分区的数量。
基于实体的分区字段支持详细信息如下表中所示。
| 实体名称 | 分区字段 | 数据类型 |
| --- | --- | --- |
| 余额交易 | created | 日期时间 |
| 收费 | created | 日期时间 |
| 争议 | created | 日期时间 |
| 文件链接 | created | 日期时间 |
| 付款意图 | created | 日期时间 |
| 设置意图 | created | 日期时间 |
| 支出 | created | 日期时间 |
| 退款 | created | 日期时间 |
| 产品 | created | 日期时间 |
| 价格 | created | 日期时间 |
| 优惠券 | created | 日期时间 |
| 促销代码 | created | 日期时间 |
| 税率 | created | 日期时间 |
| 运费 | created | 日期时间 |
| 会话 | created | 日期时间 |
| 信用票据 | created | 日期时间 |
| Customer | created | 日期时间 |
| 账单 | created | 日期时间 |
| 计划 | created | 日期时间 |
| 订阅 | created | 日期时间 |
| 订阅计划 | created | 日期时间 |
| 账户 | created | 日期时间 |
| 申请费 | created | 日期时间 |
| 转接 | created | 日期时间 |
| 欺诈预警 | created | 日期时间 |
**示例**
```
stripe_read = glueContext.create_dynamic_frame.from_options(
connection_type="stripe",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "coupons",
"API_VERSION": "v1",
"PARTITION_FIELD": "created"
"LOWER_BOUND": "2024-05-01T20:55:02.000Z"
"UPPER_BOUND": "2024-07-11T20:55:02.000Z"
"NUM_PARTITIONS": "10"
}
)
```
# Stripe 连接选项
以下是 Stripe 的连接选项：
+ `ENTITY_NAME`（字符串）–（必填）用于读/写。Stripe 中对象的名称。
+ `API_VERSION`（字符串）–（必填）用于读/写。您想要使用的 Stripe Rest API 版本。示例：v1。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# 限制
以下是 Stripe 连接器的限制：
+ 连接器仅支持基于字段的分区。
+ 连接器不支持基于记录的分区，也没有用于检索记录总数的预置。
+ 主键数据类型为字符串，因此连接器不支持基于 ID 的分区。
# 创建新的 Stripe 账户并配置客户端应用程序
**创建 Stripe 账户**
1. 选择链接 **https://dashboard.stripe.com/register**。
1. 输入您的电子邮件、全名、密码，然后选择**创建账户**。
1. 使用账户登录后，选择**打开 Gmail** 以验证该账户。
1. 单击电子邮件中收到的验证链接验证该账户。
1. 单击验证电子邮件地址后，将重定向到另一个页面
1. 单击**激活付款**激活该账户后，将重定向到激活付款（**https://dashboard.stripe.com/welcome**）页面，确保填写所有有效的详细信息，然后选择**继续**按钮。
**创建 Slack 开发者应用程序**
1. 登录 [Stripe](https://dashboard.stripe.com/login)。
1. 选择**开发者**，如下图最上方所示。
1. 在开发者下选择 **API 密钥**。
1. 选择**显示测试密钥**以获取 API 密钥。
# 在 AWS Glue Studio 中连接到 Teradata Vantage
AWS Glue 提供对 Teradata Vantage 的内置支持。AWS Glue Studio 提供一个可视化界面，用于连接到 Teradata、编写数据集成作业并在 AWS Glue Studio 无服务器 Spark 运行时系统上运行这些作业。
AWS Glue Studio 为 Teradata Vantage 创建统一连接。有关更多信息，请参阅 [注意事项](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。
**Topics**
+ [创建 Teradata Vantage 连接](creating-teradata-connection.md)
+ [创建 Teradata 源节点](creating-teradata-source-node.md)
+ [创建 Teradata 目标节点](creating-teradata-target-node.md)
+ [高级选项](#creating-teradata-connection-advanced-options)
# 创建 Teradata Vantage 连接
要从 AWS Glue 连接到 Teradata Vantage，您需要创建 Teradata 凭证并将其存储在某个 AWS Secrets Manager 密钥中，然后将该密钥关联到某个 AWS Glue Teradata 连接。
**先决条件**
+ 如果您通过 Amazon VPC 访问您的 Teradata 环境，您的 Amazon VPC 配置应允许您的 AWS Glue 作业与 Teradata 环境进行通信。我们不建议通过公共互联网访问 Teradata 环境。
在 Amazon VPC 中，确定或创建 AWS Glue 将在执行作业时使用的 **VPC**、**子网**和**安全组**。此外，您的 Amazon VPC 配置需要允许您的 Teradata 实例与该位置之间的网络流量。您的作业需要与您的 Teradata 客户端端口建立 TCP 连接。有关 Teradata 端口的更多信息，请参阅 [Teradata 文档](https://docs.teradata.com/r/Teradata-VantageTM-on-AWS-DIY-Installation-and-Administration-Guide/April-2020/Before-Deploying-Vantage-on-AWS-DIY/Security-Groups-and-Ports)。
根据您的网络布局，可能需要更改 Amazon VPC 和其他联网服务以建立安全的 VPC 连接。有关 AWS 连接的更多信息，请参阅 Teradata 文档中的 [AWS Connectivity Options](https://docs.teradata.com/r/Teradata-VantageCloud-Enterprise/Get-Started/Connecting-Your-Environment/AWS-Connectivity-Options)。
**配置 AWS Glue Teradata 连接：**
1. 在您的 Teradata 配置中，确定或创建 AWS Glue 将用于连接的用户 *teradataUser* 和密码 *teradataPassword*。有关更多信息，请参阅 Teradata 文档中的 [Vantage Security Overview](https://docs.teradata.com/r/Configuring-Teradata-VantageTM-After-Installation/January-2021/Security-Overview/Vantage-Security-Overview)。
1. 在 AWS Secrets Manager 中，使用您的 Teradata 凭证创建一个密钥。要在 Secrets Manager 中创建密钥，请按照 AWS Secrets Manager 文档中[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中的教程进行操作。创建密钥后，保留密钥名称 *secretName*，以供下一步使用。
+ 在选择**键/值对**时，请使用键 `user` 和值 *teradataUsername* 创建一个键值对。
+ 在选择**键/值对**时，请使用键 `password` 和值 *teradataPassword* 创建一个键值对。
1. 在 AWS Glue 控制台中，按照 [添加 AWS Glue 连接](console-connections.md) 中的步骤创建一个连接。创建连接后，保留连接名称 *connectionName*，以供下一步使用。
+ 选择**连接类型**时，请选择 Teradata。
+ 在提供 **JDBC URL** 时，请提供您的实例的 URL。您还可以在 JDBC URL 中将某些连接参数进行硬编码，并以逗号分隔。该 URL 必须符合以下格式：`jdbc:teradata://teradataHostname/ParameterName=ParameterValue,ParameterName=ParameterValue`
支持的 URL 参数包括：
+ `DATABASE` – 主机上默认要访问的数据库的名称。
+ `DBS_PORT` – 在非标准端口上运行时要使用的数据库端口。
+ 选择**凭证类型**时，请选择 **AWS Secrets Manager**，然后将 **AWS 密钥**设置为 *secretName*。
1. 对于下列情况，您可能需要添加额外的配置：
+
对于通过 Amazon VPC 在 AWS 云端托管的 Teradata 实例
+ 您需要向 AWS Glue 连接提供用于定义 Teradata 安全凭证的 Amazon VPC 连接信息。创建或更新连接时，请在**网络选项**中设置 **VPC**、**子网**和**安全组**。
# 创建 Teradata 源节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue Teradata Vantage 连接，如上一节“[创建 Teradata Vantage 连接](creating-teradata-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要读取的 Teradata 表 *tableName* 或查询 *targetQuery*。
## 添加 Teradata 数据来源
**添加**数据来源 - Teradata** 节点：**
1. 选择 Teradata 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建新连接**。有关更多信息，请参阅之前的 [创建 Teradata Vantage 连接](creating-teradata-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 选择一个 **Teradata 源**选项：
+ **选择单个表** – 访问单个表中的所有数据。
+ **输入自定义查询** - 允许您根据自定义查询访问多个表中的数据集。
1. 如果您选择单个表，请输入 *tableName*。
如果选择**输入自定义查询**，请输入一个 SQL SELECT 查询。
1. 在**自定义 Teradata 属性**中，根据需要输入相关参数和值。
# 创建 Teradata 目标节点
## 所需的先决条件
+ 使用 AWS Secrets Manager 密钥配置的 AWS Glue Teradata Vantage 连接，如上一节“[创建 Teradata Vantage 连接](creating-teradata-connection.md)”中所述。
+ 对您的作业具有读取连接使用的密钥的相应权限。
+ 您要写入的 Teradata 表 *tableName*。
## 添加 Teradata 数据目标
**添加**数据目标 - Teradata** 节点：**
1. 选择 Teradata 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 Teradata 连接**。有关更多信息，请参阅 [Overview of using connectors and connections](https://docs.aws.amazon.com/glue/latest/ug/connectors-chapter.html#using-connectors-overview)。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 要配置**表名**，请提供 *tableName*。
1. 在**自定义 Teradata 属性**中，根据需要输入相关参数和值。
## 高级选项
您可以在创建 Teradata 节点时提供高级选项。这些选项与编程 Spark 脚本的 AWS Glue 时可用的选项相同。
请参阅[Teradata Vantage 连接](aws-glue-programming-etl-connect-teradata-home.md)。
# 连接到 Twilio
Twilio 提供可编程通信工具，用于接打电话、收发短信，以及使用其 Web 服务 API 执行其他通信功能。Twilio 的 API 为其通信平台提供支持。这些 API 背后是一个连接和优化全球通信网络的软件层，让用户能给全球范围内的任何人打电话和发送消息。若是 Twilio 用户，则可将 AWS Glue 连接到 Twilio 账户。然后，可以使用 Twilio 作为 ETL 作业中的数据来源。通过运行这些作业，可在 Twilio 与 AWS 服务或其他受支持的应用程序之间传输数据。
**Topics**
+ [AWS Glue 支持 Twilio](twilio-support.md)
+ [包含创建和使用连接的 API 操作的策略](twilio-configuring-iam-permissions.md)
+ [配置 Twilio](twilio-configuring.md)
+ [配置 Twilio 连接](twilio-configuring-connections.md)
+ [从 Twilio 实体读取内容](twilio-reading-from-entities.md)
+ [Twilio 连接选项](twilio-connection-options.md)
+ [Twilio 连接器的限制和说明](twilio-connector-limitations.md)
# AWS Glue 支持 Twilio
AWS Glue 对 Twilio 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Twilio 中的数据。
**是否支持作为目标？**
否。
**支持的 Twilio API 版本**
支持以下 Twilio API 版本：
+ v1
+ 2010-04-01
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Twilio
必须满足以下要求，才能使用 AWS Glue 从 Twilio 传输数据：
## 最低要求
以下是最低要求：
+ 拥有一个 Twilio 账户以及相应的用户名和密码。
+ Twilio 账户已启用 API 访问权限。
如果满足这些要求，就可以将 AWS Glue 连接到 Twilio 账户。对于常见连接，无需在 Twilio 中执行其他操作。
# 配置 Twilio 连接
Twilio 支持使用用户名和密码进行基本身份验证。基本身份验证是一种简单的身份验证方法，客户端直接提供凭证即可访问受保护的资源。AWS Glue 能够使用用户名（账户 SID）和密码（Auth 令牌）对 Twilio API 进行身份验证。
有关基本身份验证流的 Twilio 公共文档，请参阅 [Basic Authentication \$1 Twilio](https://www.twilio.com/docs/glossary/what-is-basic-authentication)。
要配置 Twilio 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
+ 对于基本身份验证：密钥应包含关联应用程序的消费者密钥以及**账户 SID**（用户名）和 **Auth 令牌**（密码）。
**注意**
必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Twilio。
1. 提供想要连接到的 Twilio 实例的 `[Edge\$1Location](https://www.twilio.com/docs/global-infrastructure/edge-locations)`。
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` 的权限。
# 从 Twilio 实体读取内容
**先决条件**
要从中读取内容的 Twilio 对象。您将需要 `SMS-Message` 或 `SMS-CountryPricing` 等对象名称。
**源支持的实体**：
| 实体 | 接口 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- | --- |
| SMS-消息 | REST | 支持 | 是 | 否 | 是 | 是 |
| SMS-国家定价 | REST | 否 | 否 | 否 | 是 | 否 |
| 语音-呼叫 | REST | 支持 | 是 | 否 | 是 | 否 |
| 语音-应用程序 | REST | 支持 | 是 | 否 | 是 | 否 |
| 语音-主叫方 ID | REST | 支持 | 是 | 否 | 是 | 否 |
| 语音-队列 | REST | 支持 | 是 | 否 | 是 | 否 |
| 对话-对话 | REST | 支持 | 是 | 否 | 是 | 否 |
| 对话-用户 | REST | 否 | 是 | 否 | 是 | 否 |
| 对话-角色 | REST | 否 | 是 | 否 | 是 | 否 |
| 对话-配置 | REST | 否 | 否 | 否 | 是 | 否 |
| 对话-地址配置 | REST | 支持 | 是 | 否 | 是 | 否 |
| 对话-Webhook 配置 | REST | 否 | 否 | 否 | 是 | 否 |
| 对话-参与者对话 | REST | 否 | 否 | 否 | 是 | 否 |
| 对话-凭证 | REST | 否 | 是 | 否 | 是 | 否 |
| 对话-对话服务 | REST | 否 | 是 | 否 | 是 | 否 |
**示例：**
```
twilio_read = glueContext.create_dynamic_frame.from_options(
connection_type="twilio",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "sms-message",
"API_VERSION": "2010-04-01",
"Edge_Location": "sydney.us1"
}
```
**Twilio 实体和字段详细信息**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/twilio-reading-from-entities.html)
## 对查询进行分区
**支持分区的字段**：
在 Twilio 中，“日期时间”数据类型字段支持基于字段的分区。
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于“日期时间”字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"2024-05-01T20:55:02.000Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
twilio_read = glueContext.create_dynamic_frame.from_options(
connection_type="twilio",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "sms-message",
"API_VERSION": "2010-04-01",
"PARTITION_FIELD": "date_sent"
"LOWER_BOUND": "2024-05-01T20:55:02.000Z"
"UPPER_BOUND": "2024-06-01T20:55:02.000Z"
"NUM_PARTITIONS": "10"
}
```
# Twilio 连接选项
以下是 Twilio 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Twilio 中对象的名称。
+ `EDGE_LOCATION`（字符串）：（必填）有效的 Twilio 边缘站点。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Twilio Rest API 版本。Twilio 支持两个 API 版本：v1 和 2010-04-01。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（字符串）：（必填）用于读取。有效的 Twilio 实例 URL。
# Twilio 连接器的限制和说明
以下是 Twilio 连接器的限制或说明：
+ 由于未要求从 Twilio 检索记录总数，因此不支持基于记录的分区。
+ 字段 `date_sent`、`start_time` 和 `end_time` 属于“日期时间”数据类型，但在进行筛选时，这些字段仅支持日期值（不考虑时间分量）。
+ 仅当值不包含任何前缀（例如协议或标签）时，筛选“起”或“止”字段才有效。如果存在前缀，则无法筛选相应字段。例如，若将“止”：“whatsapp:\$114xxxxxxxxxx”作为筛选条件传递，Twilio 不会返回响应。需要将“止”：“\$114xxxxxxxx”作为筛选条件传递，才会返回记录（如果存在）。
+ 查询 `conversation-participant-conversation` 实体时，必须使用“身份”字段筛选条件。
# 在 AWS Glue Studio 中连接到 Vertica
AWS Glue 提供对 Vertica 的内置支持。AWS Glue Studio 提供一个可视化界面，用于连接到 Vertica、编写数据集成作业并在 AWS Glue Studio 无服务器 Spark 运行时系统上运行这些作业。
AWS Glue Studio 为 Vertica 创建统一连接。有关更多信息，请参阅 [注意事项](using-connectors-unified-connections.md#using-connectors-unified-connections-considerations)。
**Topics**
+ [创建 Vertica 连接](creating-vertica-connection.md)
+ [创建 Vertica 源节点](creating-vertica-source-node.md)
+ [创建 Vertica 目标节点](creating-vertica-target-node.md)
+ [高级选项](#creating-vertica-connection-advanced-options)
# 创建 Vertica 连接
**先决条件**
+ 读取和写入数据库时用于临时存储的 Amazon S3 存储桶或文件夹，也称为 *tempS3Path*。
**注意**
在 AWS Glue 任务数据预览中使用 Vertica 时，临时文件可能不会自动从 *tempS3Path* 中删除。为确保删除临时文件，请在**数据预览**窗格中选择**结束会话**，以直接结束数据预览会话。
如果无法保证数据预览会话直接结束，请考虑将 Amazon S3 生命周期配置设置为删除旧数据。我们建议根据最大作业运行时间加一定的裕度移除已存在超过 49 小时的数据。有关配置 Amazon S3 生命周期的更多信息，请参阅 Amazon S3 文档中的 [管理存储生命周期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)。
+ 对您的 Amazon S3 路径具有适当权限，并且您可以将其关联到您的 AWS Glue 作业角色的 IAM policy。
+ 如果您的 Vertica 实例位于某个 Amazon VPC 中，请确保您的 Amazon VPC 配置允许您的 AWS Glue 作业与 Vertica 实例进行通信，并且无需通过公共互联网路由流量。
在 Amazon VPC 中，确定或创建 AWS Glue 将在执行作业时使用的 **VPC**、**子网**和**安全组**。此外，您的 Amazon VPC 配置需要允许您的 Vertica 实例与该位置之间的网络流量。您的作业需要与您的 Vertica 客户端端口（默认为 5433）建立 TCP 连接。根据您的网络布局，这可能需要更改安全组规则、网络 ACL、NAT 网关和对等连接。
**配置 Vertica 连接：**
1. 在 AWS Secrets Manager 中，使用您的 Vertica 凭证 *verticaUsername* 和 *verticaPassword* 创建一个密钥。要在 Secrets Manager 中创建密钥，请按照 AWS Secrets Manager 文档中[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com//secretsmanager/latest/userguide/create_secret.html)中的教程进行操作。创建密钥后，保留密钥名称 *secretName*，以供下一步使用。
+ 在选择**键/值对**时，请使用键 `user` 和值 *verticaUsername* 创建一个键值对。
+ 在选择**键/值对**时，请使用键 `password` 和值 *verticaPassword* 创建一个键值对。
1. 在 AWS Glue 控制台中，按照 [添加 AWS Glue 连接](console-connections.md) 中的步骤创建一个连接。创建连接后，保留连接名称 *connectionName*，以供下一步使用。
+ 选择**连接类型**时，请选择 Vertica。
+ 选择 **Vertica 主机**时，请提供您安装了 Vertica 的主机名。
+ 选择 **Vertica 端口**时，请提供可用于访问 Vertica 安装的端口。
+ 选择 **AWS 密钥**时，请提供 *secretName*。
1. 对于下列情况，您可能需要添加额外的配置：
+
对于通过 Amazon VPC 在 AWS 云端托管的 Vertica 实例
+ 向 AWS Glue 连接提供用于定义 Vertica 安全凭证的 Amazon VPC 连接信息。创建或更新连接时，请在**网络选项**中设置 **VPC**、**子网**和**安全组**。
您需要首先完成以下步骤，然后才能运行 AWS Glue 作业：
+ 向与您的 AWS Glue 作业关联的 IAM 角色授予对 *tempS3Path* 的权限。
+ 向与您的 AWS Glue 作业关联的 IAM 角色授予读取 *secretName* 的权限。
# 创建 Vertica 源节点
## 所需的先决条件
+ 一个 Vertica 类型的 AWS Glue Data Catalog 连接 *connectionName* 和一个临时 Amazon S3 位置 *tempS3Path*，如上一节“[创建 Vertica 连接](creating-vertica-connection.md)”所述。
+ 您要读取的 Vertica 表 *tableName* 或查询 *targetQuery*。
## 添加 Vertica 数据来源
**添加**数据来源 - Vertica** 节点：**
1. 选择 Vertica 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 Vertica 连接**。有关更多信息，请参阅之前的 [创建 Vertica 连接](creating-vertica-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 选择包含您的表的**数据库**。
1. 选择 **Amazon S3 中的暂存区域**，然后在 *tempS3Path* 中输入一个 S3A URI。
1. 选择 **Vertica 源**。
+ **选择单个表** – 访问单个表中的所有数据。
+ **输入自定义查询** - 允许您根据自定义查询访问多个表中的数据集。
1. 如果您选择单个表，请输入 *tableName*，此外还可以选择一个 **Schema**。
如果选择**输入自定义查询**，请输入一个 SQL SELECT 查询，此外还可以选择一个 **Schema**。
1. 在**自定义 Vertica 属性**中，根据需要输入相关参数和值。
# 创建 Vertica 目标节点
## 所需的先决条件
+ 一个 Vertica 类型的 AWS Glue Data Catalog 连接 *connectionName* 和一个临时 Amazon S3 位置 *tempS3Path*，如上一节“[创建 Vertica 连接](creating-vertica-connection.md)”所述。
## 添加 Vertica 数据目标
**添加**数据目标 - Vertica** 节点：**
1. 选择 Vertica 数据来源的连接。由于您已经创建了它，它应该提供在下拉列表中。如果需要创建连接，请选择**创建 Vertica 连接**。有关更多信息，请参阅之前的 [创建 Vertica 连接](creating-vertica-connection.md) 部分。
选择连接后，您可以通过单击**查看属性**来查看连接属性。
1. 选择包含您的表的**数据库**。
1. 选择 **Amazon S3 中的暂存区域**，然后在 *tempS3Path* 中输入一个 S3A URI。
1. 输入 *tableName*，此外还可以选择一个 **Schema**。
1. 在**自定义 Vertica 属性**中，根据需要输入相关参数和值。
## 高级选项
您可以在创建 Vertica 节点时提供高级选项。这些选项与编程 Spark 脚本的 AWS Glue 时可用的选项相同。
请参阅[Vertica 连接](aws-glue-programming-etl-connect-vertica-home.md)。
# 连接到 WooCommerce
WooCommerce 是一款灵活的开源软件解决方案，专为基于 WordPress 的网站打造。其通常用于创建在线电子商务商店。借助此软件解决方案，任何人都可以将他们的常规网站变成一个功能齐全的在线商店。
**Topics**
+ [AWS Glue 支持 WooCommerce](woocommerce-support.md)
+ [包含创建和使用连接的 API 操作的策略](woocommerce-configuring-iam-permissions.md)
+ [配置 WooCommerce](woocommerce-configuring.md)
+ [配置 WooCommerce 连接](woocommerce-configuring-connections.md)
+ [从 WooCommerce 实体读取内容](woocommerce-reading-from-entities.md)
+ [WooCommerce 连接选项](woocommerce-connection-options.md)
# AWS Glue 支持 WooCommerce
AWS Glue 对 WooCommerce 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 WooCommerce 中的数据。
**是否支持作为目标？**
否。
**支持的 WooCommerce AP 版本**
支持以下 WooCommerce API 版本：
+ v3
# 包含创建和使用连接的 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 控制台的用户。
# 配置 WooCommerce
必须满足以下要求，才能使用 AWS Glue 从 WooCommerce 传输数据：
## 最低要求
以下是最低要求：
+ 拥有一个 WooCommerce 账户以及相应的 `consumerKey` 和 `consumerSecret`。
+ WooCommerce 账户拥有 API 访问权限和有效许可证。
如果满足这些要求，就可以将 AWS Glue 连接到 WooCommerce 账户。对于常见连接，无需在 WooCommerce 中执行其他操作。
# 配置 WooCommerce 连接
WooCommerce 支持自定义身份验证。有关生成自定义身份验证所需 API 密钥的 WooCommerce 公共文档，请参阅 [Authentication – WooCommerce REST API Documentation](https://woocommerce.github.io/woocommerce-rest-api-docs/#authentication)。
要配置 WooCommerce 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
+ 对于客户管理型关联应用程序，密钥应包含关联应用程序的消费者密钥，且以 `consumerKey` 和 `consumerSecret` 为键。注意：必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 WooCommerce。
1. 提供想要连接到的 WooCommerce 实例的 `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` 的权限。
# 从 WooCommerce 实体读取内容
**先决条件**
要从中读取内容的 WooCommerce 对象。需要优惠券、订单、产品等对象名称。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 优惠券 | 支持 | 是 | 是 | 是 | 是 |
| 优惠券总计 | 否 | 否 | 否 | 是 | 否 |
| 客户总计 | 否 | 否 | 否 | 是 | 否 |
| 订单 | 支持 | 是 | 是 | 是 | 是 |
| 订单总计 | 否 | 否 | 否 | 是 | 否 |
| 付款网关 | 否 | 否 | 否 | 是 | 否 |
| 产品 | 支持 | 是 | 是 | 是 | 是 |
| 产品属性 | 支持 | 是 | 是 | 是 | 是 |
| 产品类别 | 支持 | 是 | 是 | 是 | 是 |
| 产品评论 | 支持 | 是 | 是 | 是 | 是 |
| 产品配送等级 | 支持 | 是 | 是 | 是 | 是 |
| 产品标签 | 支持 | 是 | 是 | 是 | 是 |
| 产品型号 | 支持 | 是 | 是 | 是 | 是 |
| 产品总计 | 否 | 否 | 否 | 是 | 否 |
| 报告（清单） | 否 | 否 | 否 | 是 | 否 |
| 评论总数 | 否 | 否 | 否 | 是 | 否 |
| 销售报告 | 是 | 否 | 否 | 是 | 否 |
| 配送方式 | 否 | 否 | 否 | 是 | 否 |
| 配送区域 | 否 | 否 | 否 | 是 | 否 |
| 配送区域位置 | 否 | 否 | 否 | 是 | 否 |
| 配送区域方法 | 否 | 否 | 否 | 是 | 否 |
| 税率 | 支持 | 是 | 是 | 是 | 是 |
| 税务等级 | 否 | 否 | 否 | 是 | 否 |
| 畅销产品报告 | 是 | 否 | 否 | 是 | 否 |
**示例：**
```
woocommerce_read = glueContext.create_dynamic_frame.from_options(
connection_type="glue.spark.woocommerce",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "coupon",
"API_VERSION": "v3",
"INSTANCE_URL": "instanceUrl"
}
```
**WooCommerce 实体和字段详细信息**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/woocommerce-reading-from-entities.html)
**注意**
在连接器的响应中，“结构体”和“列表”数据类型将转换为“字符串”数据类型，“日期时间”数据类型将转换为“时间戳”数据类型。
## 对查询进行分区
**基于记录的分区**：
如果您想在 Spark 中利用并发，可以提供附加 Spark 选项 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
在基于记录的分区中，从 WooCommerce API 查询存在的记录总数，然后将其除以提供的 `NUM_PARTITIONS` 数字。然后，每个子查询会同时获取生成的记录数。
+ `NUM_PARTITIONS`：分区的数量。
以下实体支持基于记录的分区：
+ coupon
+ 顺序
+ 产品
+ 产品属性
+ 产品属性术语
+ 产品类别
+ 产品评论
+ 产品配送等级
+ 产品标记
+ 产品型号
+ 税率
示例：
```
woocommerce_read = glueContext.create_dynamic_frame.from_options(
connection_type="glue.spark.woocommerce",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "coupon",
"API_VERSION": "v3",
"INSTANCE_URL": "instanceUrl"
"NUM_PARTITIONS": "10"
}
```
**基于记录的分区**：
原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行：
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
WooCommerce_read = glueContext.create_dynamic_frame.from_options(
connection_type="WooCommerce",
connection_options={
"connectionName": "connectionName",
"REALMID": "1234567890123456789",
"ENTITY_NAME": "Bill",
"API_VERSION": "v3",
"NUM_PARTITIONS": "10"
}
```
# WooCommerce 连接选项
以下是 WooCommerce 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。WooCommerce 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 WooCommerce Rest API 版本。
+ `REALM_ID`（字符串）：用于识别向其发送请求的单个 WooCommerce Online 公司的 ID。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `INSTANCE_URL`（字符串）：（必填）有效的 WooCommerce 实例 URL，格式为：https://.wpcomstaging.com
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
# 连接到 Zendesk
Zendesk 是一款基于云的帮助台管理解决方案，提供各种可用来构建客户服务门户、知识库和在线社区的可自定义工具。
**Topics**
+ [AWS Glue 对 Zendesk 的支持](zendesk-support.md)
+ [包含创建和使用连接的 API 操作的策略](zendesk-configuring-iam-permissions.md)
+ [配置 Zendesk](zendesk-configuring.md)
+ [配置 Zendesk 连接](zendesk-configuring-connections.md)
+ [从 Zendesk 实体中读取](zendesk-reading-from-entities.md)
+ [Zendesk 连接选项](zendesk-connection-options.md)
+ [限制](zendesk-limitations.md)
# AWS Glue 对 Zendesk 的支持
AWS Glue 对 Zendesk 的支持如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Zendesk 中的数据。
**是否支持作为目标？**
否。
**支持的 Zendesk API 版本**
支持以下 Zendesk API 版本
+ v2
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Zendesk
您必须满足以下要求，才能使用 AWS Glue 从 Zendesk 传出数据：
## 最低要求
以下是最低要求：
+ 拥有一个 Zendesk 账户。有关更多信息，请参阅 [创建 Zendesk 账户](#zendesk-configuring-creating-account)。
+ 您的 Zendesk 账户已启用 API 访问权限。
+ 您的 Zendesk 账户允许您安装连接的应用程序。
如果满足这些要求，就可以将 AWS Glue 连接到 Zendesk 账户。
## 创建 Zendesk 账户
要创建 Zendesk 账户，请按以下步骤操作：
1. 前往 https://www.zendesk.com/in/register/
1. 输入详细信息，例如您的工作电子邮件、名字、姓氏、电话号码、职务、公司名称、公司员工人数、密码和首选语言。然后选择**完成试用注册**。
1. 创建账户后，请完成收到的验证链接，验证您的电子邮件地址。
1. 工作电子邮件地址通过验证后，您将被重定向到您的 Zendesk 账户。为您期望的计划选择**购买 Zendesk 选项**。注意：对于 Zendesk 连接器，建议购买 Suite Enterprise 计划。
## 创建客户端应用程序和 OAuth 2.0 凭证
要创建客户端应用程序和 OAuth 2.0 凭证，请按以下步骤操作：
1. 登录要在其中创建 OAuth 2.0 应用程序的 Zendesk 账户：https://www.zendesk.com/in/login/
1. 单击齿轮图标。选择**前往管理中心**链接以打开管理中心页面。
1. 在左侧边栏中选择**应用程序和集成**，然后选择 **API** > **Zendesk API**。
1. 在 Zendesk API 页面上，选择 **OAuth 客户端**选项卡。
1. 选择右侧的**添加 Oauth 客户端**。
1. 请填写以下字段，从而创建客户端：
1. 客户端名称：输入应用程序的名称。这是当用户被要求向您的应用程序授予访问权限时，以及查看有权访问其 Zendesk 的第三方应用程序列表时，将会看到的名称。
1. 描述：可选。应用程序的简短描述，这是当用户被要求授予访问权限时将看到的描述。
1. 公司：可选。当用户被要求向您的应用程序授予访问权限时将看到的公司名称。这些信息有助于他们了解向谁授予了访问权限。
1. 徽标：可选。这是当用户被要求向您的应用程序授予访问权限时将看到的徽标。图片可以是 JPG、GIF 或 PNG 格式。为确保最佳效果，请上传正方形图片。系统将调整其大小以满足授权页面的要求。
1. 唯一标识符：系统将根据您为应用程序输入的名称，使用重新格式化后的版本自动填充该字段。如果需要，您可以更改名称。
1. 重定向 URL：输入一个或多个 URL，以便 Zendesk 用于发送用户是否同意向您的应用程序授予访问权限的决定。
例如：https://us-east-1.console.aws.amazon.com/gluestudio/oauth
1. 单击**保存**。
1. 该页面刷新后，下半部会出现一个新的预填充**密钥**字段。这是 OAuth2 规范中指定的“client\$1secret”值。将密钥的值复制到剪贴板并将妥善保管。注意：字符可能会超出文本框的宽度，因此在复制之前请务必选择所有内容。
1. 单击**保存**。
# 配置 Zendesk 连接
Zendesk 连接器支持授权码授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。默认情况下，创建连接的用户可以依赖于 AWS Glue 拥有的关联应用程序（AWS Glue 托管式客户端应用程序）；在该应用程序中，除了 Zendesk 实例 URL 之外，用户无需提供任何与 OAuth 相关的信息。AWS Glue 控制台会将用户重定向到 Zendesk，用户必须登录并向 AWS Glue 授予所请求的权限，以便访问其 Zendesk 实例。
+ 用户仍然可以选择在 Zendesk 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，您仍会重定向到 Zendesk，以便登录并授权 AWS Glue 访问您的资源。
+ 此授权类型会生成访问令牌。访问令牌永不过期。
有关为授权码 OAuth 流创建关联应用程序的 Zendesk 公共文档，请参阅 [OAuth Tokens for Grant Types](https://developer.zendesk.com/api-reference/ticketing/oauth/grant_type_tokens/)。
要配置 Zendesk 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于 AuthorizationCode 授权类型：如果是客户托管的关联应用程序，密钥应包含关联应用程序的 Consumer Secret，并将 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作为键名。
1. 注意：您必须在 AWS Glue 中为每个连接创建密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Zendesk。
1. 提供想要连接到的 Zendesk 的 INSTANCE\$1URL。
1. 提供 Zendesk 环境。
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` 的权限。
# 从 Zendesk 实体中读取
**先决条件**
您要从中读取内容的 Zendesk 对象。您将需要工单、用户或文章等对象名称，如下表中所述。
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 工单 | Y | Y | Y | Y | N |
| 用户 | Y | Y | Y | Y | N |
| 组织 | Y | Y | Y | Y | N |
| 文章 | Y | Y | N | Y | N |
| 工单事件 | Y | Y | N | Y | N |
| 工单指标事件 | Y | Y | N | Y | N |
| 工单备注 | Y | Y | Y | Y | N |
| 工单字段 | Y | Y | N | Y | N |
| 工单指标 | Y | Y | N | Y | N |
| 工单活动 | Y | Y | N | Y | N |
| 工单跳过 | N | Y | N | Y | N |
| 组 | Y | Y | Y | Y | N |
| 组成员资格 | N | Y | Y | Y | N |
| 满意度评分 | Y | Y | N | Y | N |
| 视图 | Y | Y | Y | Y | N |
| 触发器 | Y | Y | Y | Y | N |
| 触发器类别 | N | Y | Y | Y | N |
| 宏 | Y | Y | Y | Y | N |
| 自动化 | N | Y | Y | Y | N |
**示例：**
```
Zendesk_read = glueContext.create_dynamic_frame.from_options(
connection_type="Zendesk",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "Account",
"API_VERSION": "v2"
}
```
**Zendesk 实体和字段详细信息**：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/zendesk-reading-from-entities.html)
**注意**
在连接器的响应中，结构和列表数据类型将转换为字符串数据类型。
## 对查询进行分区
Zendesk 中不支持分区。
# Zendesk 连接选项
Zendesk 的连接选项如下：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Zendesk 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Zendesk Rest API 版本。示例：v2。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。示例：id、name、url、created\$1at
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。例如：group\$1id = 100
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。示例："SELECT id,url FROM users WHERE role=\$1"end-user\$1""
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。支持增量导出 API 的实体，默认字段为 `update_at`（`ticket-events` 的 `created_at`，以及 `ticket-metric-events` 的 `time`）。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。可选；如果作业选项中未提供，则连接器将处理此选项。默认值：“2024-05-01T20:55:02.000Z
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。可选；如果作业选项中未提供，则连接器将处理此选项。默认值：1。
+ `IMPORT_DELETED_RECORDS`（字符串）– 默认：FALSE。用于读取。在查询时获取删除记录。
+ `ACCESS_TOKEN`：要在请求中使用的访问令牌。
+ `INSTANCE_URL`：用户要在其中运行操作的实例的 URL。例如：https://\$1subdomain\$1/.zendesk.com
# 限制
以下是 Zendesk 连接器的限制：
+ 对于基于偏移量的分页，可提取的页数上限为 100，但不建议这样做，因为可以提取的记录总数为 10,000。但是，为 Zendesk 连接器实现的基于游标的分页克服了这一限制。仅支持通过 Zendesk API 使用 EQUAL\$1TO 筛选条件运算符。
由于这一限制，Zendesk 连接器不支持分区。
+ 对于“Ticket Event”实体，速率限制为每分钟 10 个请求。运行 AWS Glue ETL 作业时，您可能会收到 429 错误（请求过多）。
# 连接到 Zoho CRM
Zoho CRM 作为单一存储库，将销售、营销和客户支持活动整合在一起，并在一个平台上简化流程、策略和人员。Zoho CRM 可以轻松定制，以满足任何企业类型和规模的特定需求。
Zoho CRM 的开发者平台为企业提供低代码和专业代码工具的适当组合，使工作自动化，跨企业堆栈整合数据，并创建 Web 版和移动版自定义解决方案。
**Topics**
+ [AWS Glue 对 Zoho CRM 的支持](zoho-crm-support.md)
+ [包含创建和使用连接的 API 操作的策略](zoho-crm-configuring-iam-permissions.md)
+ [配置 Zoho CRM](zoho-crm-configuring.md)
+ [配置 Zoho CRM 连接](zoho-crm-configuring-connections.md)
+ [从 Zoho CRM 实体中读取](zoho-crm-reading-from-entities.md)
+ [Zoho CRM 连接选项](zoho-crm-connection-options.md)
+ [Zoho CRM 连接器的限制和说明](zoho-crm-connector-limitations.md)
# AWS Glue 对 Zoho CRM 的支持
AWS Glue 对 Zoho CRM 的支持如下：
**是否支持作为来源？**
是，支持同步和异步。您可以使用 AWS Glue ETL 作业查询 Zoho CRM 中的数据。
**是否支持作为目标？**
不支持。
**支持的 Zoho CRM API 版本**
支持以下 Zoho CRM API 版本：
+ v7
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Zoho CRM
您必须满足以下要求，才能使用 AWS Glue 从 Zoho CRM 传输数据：
## 最低要求
以下是最低要求：
+ 您有一个 Zoho CRM 账户。
+ 您的 Zoho CRM 账户已启用 API 访问权限。
+ 您在 API 控制台下有一个注册的 API 客户端用于获取 OAuth 凭证。
# 配置 Zoho CRM 连接
授权类型决定了 AWS Glue 如何与 Zoho CRM 通信以请求访问您的数据。您选择的授权类型会影响您在创建连接之前必须满足的要求。Zoho CRM 仅支持 OAuth 2.0 的 AUTHORIZATION\$1CODE 授权类型。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。AWS Glue 控制台会将用户重定向到 Zoho CRM，用户必须登录并向 Glue 授予所请求的权限，以访问其 Zoho CRM 实例。
+ 用户仍然可以选择在 Zoho CRM 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时提供自己的客户端 ID、身份验证 URL、令牌 URL 和实例 URL。在这种情况下，他们仍会重定向到 Zoho CRM，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期为一小时，可以通过刷新令牌在不需要用户互动的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的公共 Zoho CRM 文档，请参阅 [Authentication](https://www.zoho.com/crm/developer/docs/api/v7/oauth-overview.html)。
要配置 Zoho CRM 连接：
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Zoho CRM。
1. 提供您想要连接到的 Zoho CRM 实例的 `INSTANCE_URL`。
1. 提供用户客户端应用程序的客户端 ID。
1. 从下拉列表中选择相应的**身份验证 URL**。
1. 从下拉列表中选择相应的**令牌 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` 的权限。
1. 在 AWS Glue 作业配置中，提供 `connectionName` 作为**附加网络连接**。
# 从 Zoho CRM 实体中读取
**先决条件**
您要从中读取内容的 Zoho CRM 对象。您将需要对象名称。
**同步源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 产品 | 支持 | 是 | 是 | 是 | 是 |
| 报价 | 支持 | 是 | 是 | 是 | 是 |
| 采购订单 | 支持 | 是 | 是 | 是 | 是 |
| 解决方案 | 支持 | 是 | 是 | 是 | 是 |
| Call | 支持 | 是 | 是 | 是 | 是 |
| 任务 | 支持 | 是 | 是 | 是 | 是 |
| 事件 | 支持 | 是 | 是 | 是 | 是 |
| 发票 | 支持 | 是 | 是 | 是 | 是 |
| Account | 支持 | 是 | 是 | 是 | 是 |
| 联系人 | 支持 | 是 | 是 | 是 | 是 |
| Vendor | 支持 | 是 | 是 | 是 | 是 |
| 活动 | 支持 | 是 | 是 | 是 | 是 |
| 交易 | 支持 | 是 | 是 | 是 | 是 |
| 线索 | 支持 | 是 | 是 | 是 | 是 |
| 自定义模块 | 支持 | 是 | 是 | 是 | 是 |
| 销售订单 | 支持 | 是 | 是 | 是 | 是 |
| 价目表 | 支持 | 是 | 是 | 是 | 是 |
| 案例 | 支持 | 是 | 是 | 是 | 是 |
**示例：**
```
zoho_read = glueContext.create_dynamic_frame.from_options(
connection_type="ZOHO",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v7",
"INSTANCE_URL": "https://www.zohoapis.in/"
}
```
**异步源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| 产品 | 是 | 否 | 否 | 是 | 否 |
| 报价 | 是 | 否 | 否 | 是 | 否 |
| 采购订单 | 是 | 否 | 否 | 是 | 否 |
| 解决方案 | 是 | 否 | 否 | 是 | 否 |
| Call | 是 | 否 | 否 | 是 | 否 |
| 任务 | 是 | 否 | 否 | 是 | 否 |
| 事件 | 是 | 否 | 否 | 是 | 否 |
| 发票 | 是 | 否 | 否 | 是 | 否 |
| Account | 是 | 否 | 否 | 是 | 否 |
| 联系人 | 是 | 否 | 否 | 是 | 否 |
| Vendor | 是 | 否 | 否 | 是 | 否 |
| 活动 | 是 | 否 | 否 | 是 | 否 |
| 交易 | 是 | 否 | 否 | 是 | 否 |
| 线索 | 是 | 否 | 否 | 是 | 否 |
| 自定义模块 | 是 | 否 | 否 | 是 | 否 |
| 销售订单 | 是 | 否 | 否 | 是 | 否 |
| 价目表 | 是 | 否 | 否 | 是 | 否 |
| 案例 | 是 | 否 | 否 | 是 | 否 |
**示例：**
```
zoho_read = glueContext.create_dynamic_frame.from_options(
connection_type="ZOHO",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v7",
"INSTANCE_URL": "https://www.zohoapis.in/",
"TRANSFER_MODE": "ASYNC"
}
```
**Zoho CRM 字段详细信息**：
Zoho CRM 提供用于动态获取所支持实体元数据的端点。因此，可在数据类型级别捕获运算符支持。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/zoho-crm-reading-from-entities.html)
## 对查询进行分区
异步模式下不支持分区。
**基于筛选条件的分区（同步模式）**：
如果您想在 Spark 中利用并发，可以提供其他 Spark 选项：`PARTITION_FIELD`、`LOWER_BOUND`、`UPPER_BOUND` 和 `NUM_PARTITIONS`。使用这些参数，原始查询将被拆分为 `NUM_PARTITIONS` 个子查询，这些子查询可以由 Spark 任务同时执行。
+ `PARTITION_FIELD`：用于对查询进行分区的字段的名称。
+ `LOWER_BOUND`：所选分区字段的**包含**下限值。
对于“日期时间”字段，我们接受 Spark SQL 查询中使用的 Spark 时间戳格式。
有效值示例：
```
"2024-09-30T01:01:01.000Z"
```
+ `UPPER_BOUND`：所选分区字段的**排除**上限值。
+ `NUM_PARTITIONS`：分区的数量。
示例：
```
zoho_read = glueContext.create_dynamic_frame.from_options(
connection_type="zohocrm",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "entityName",
"API_VERSION": "v7",
"PARTITION_FIELD": "Created_Time"
"LOWER_BOUND": "2022-01-01T01:01:01.000Z"
"UPPER_BOUND": "2024-01-01T01:01:01.000Z"
"NUM_PARTITIONS": "10"
}
```
# Zoho CRM 连接选项
以下是 Zoho CRM 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Zoho CRM 中对象的名称。
+ `API_VERSION`（字符串）：（必填）用于读取。您想要使用的 Zoho CRM Rest API 版本。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。您想要为对象选择的列。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
+ `PARTITION_FIELD`（字符串）– 用于读取。用于分区查询的字段。
+ `LOWER_BOUND`（字符串）– 用于读取。所选分区字段的包含下限值。
+ `UPPER_BOUND`（字符串）– 用于读取。所选分区字段的排除上限值。
+ `NUM_PARTITIONS`（整数）– 默认：1。用于读取。要读取的分区数。
+ `INSTANCE_URL`（字符串）：（必填）用于读取。有效的 Zoho CRM 实例 URL。
+ `TRANSFER_MODE`（字符串）– 用于指示是否应在异步模式下运行查询。
# Zoho CRM 连接器的限制和说明
以下是 Zoho CRM 连接器的限制或说明：
+ 使用 API 版本 v7，您最多可以获取 100000 条记录。请参阅 [Zoho 文档](https://www.zoho.com/crm/developer/docs/api/v7/get-records.html)。
+ 对于事件实体，将显示“会议”标签，如 [Zoho 文档](https://www.zoho.com/crm/developer/docs/api/v7/modules-api.html)中所述。
+ 对于“全选”功能：
+ 您可以从 SaaS 中通过 GET 和 POST 调用来获取最多 50 个字段。
+ 如果您想要获取不属于前 50 个字段的某些特定字段的数据，则需要手动提供所选字段的列表。
+ 如果选择的字段超过 50 个，则超过 50 个字段的任何字段都将被修剪，并将在 Amazon S3 中包含空数据。
+ 使用筛选表达式时，如果用户提供的 50 个字段列表中不包括“id”和“Created\$1Time”，则会引发自定义异常，提示用户包含这些字段。
+ 尽管数据类型相同，但筛选运算符可能因字段而有所不同。因此，您必须为 SaaS 平台中触发错误的任何字段手动指定不同的运算符。
+ 对于“排序依据”功能：
+ 如果没有筛选表达式，则数据只能按单个字段进行排序；而应用筛选表达式后，数据可以按多个字段进行排序。
+ 如果没有为所选字段指定排序顺序，则默认情况下将按升序检索数据。
+ Zoho CRM 连接器的支持区域包括美国、欧洲、印度、澳大利亚和日本。
+ 异步读取功能[限制](https://www.zoho.com/crm/developer/docs/api/v7/bulk-read/limitations.html)：
+ 异步模式下不支持限制排序和分区。
+ 在异步模式下，我们可以传输多达 500 页的数据，每页 20 万条记录。
+ 在一分钟的间隔内，只允许 10 个下载请求。如果超过下载限制，系统会返回 HTTP 429 错误，并暂停所有下载请求一分钟，之后才能恢复处理。
+ 完成批量作业后，只能在一天内访问可下载的文件。之后则无法通过端点访问该文件。
+ 通过一个端点最多可以指定 200 个选择字段。如果在端点中指定超过 200 个选择字段，系统会自动导出该模块的所有可用字段。
+ 批量读取 API 不支持在任何模块中创建的外部字段。
+ 此 API 端点不支持排序和 `Group_by` 子句。
+ 仅当合规性设置中的**限制通过 API 访问数据**选项为**禁用**时，才会检索包含敏感运行状况数据的字段的值。如果启用该选项，则结果中的值将为**空**。
+ 过滤/条件限制
+ 查询中最多可以使用 25 个条件。
+ 不支持多行文本字段的筛选/条件。
# 连接到 Zoom Meeting
Zoom Meetings 是一个基于云的视频会议平台，可用于开展视频会议、音频会议、网络研讨会、会议录制和实时聊天。
**Topics**
+ [AWS Glue 支持 Zoom Meetings](zoom-meetings-support.md)
+ [包含创建和使用连接的 API 操作的策略](zoom-meetings-configuring-iam-permissions.md)
+ [配置 Zoom Meetings](zoom-meetings-configuring.md)
+ [配置 Zoom Meetings 客户端应用程序](zoom-meetings-configuring-client-app.md)
+ [配置 Zoom Meetings 连接](zoom-meetings-configuring-connections.md)
+ [从 Zoom Meetings 实体读取内容](zoom-meetings-reading-from-entities.md)
+ [Zoom Meetings 连接选项](zoom-meetings-connection-options.md)
+ [Zoom Meetings 限制](zoom-meetings-limitations.md)
# AWS Glue 支持 Zoom Meetings
AWS Glue 对 Zoom Meetings 的支持情况如下：
**是否支持作为来源？**
是。可以使用 AWS Glue ETL 作业查询 Zoom Meetings 中的数据。
**是否支持作为目标？**
否。
**支持的 Zoom Meetings API 版本**
支持以下 Zoom Meetings API 版本：
+ v2
# 包含创建和使用连接的 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 控制台的用户。
# 配置 Zoom Meetings
必须满足以下要求，才能使用 AWS Glue 从 Zoom Meetings 传输数据：
## 最低要求
以下是最低要求：
+ 拥有一个 Zoom Meetings 账户。
+ Zoom Meetings 账户已启用 API 访问权限。
+ 已在 Zoom Meetings 账户中创建了 OAuth2 应用程序。此集成提供 AWS Glue 在对您的账户进行身份验证调用时用于安全访问数据的凭证。有关更多信息，请参阅 [配置 Zoom Meetings 客户端应用程序](zoom-meetings-configuring-client-app.md)。
如果满足这些要求，就可以将 AWS Glue 连接到 Zoom Meetings 账户。对于常见连接，无需在 Zoom Meetings 中执行其他操作。
# 配置 Zoom Meetings 客户端应用程序
1. 登录 Zoom App Marketplace。
1. 选择**开发** > **构建应用程序**。
1. 为基于 OAuth 2.0 的应用程序选择**通用应用程序**。
1. 在**基本信息**页面上添加或更新有关应用程序的信息，例如应用程序的名称、应用程序的管理方式、应用程序凭证和 OAuth 信息。
1. 在**选择应用程序的管理方式**部分，确认要如何管理应用程序：
1. **管理员管理**：账户管理员添加并管理应用程序
1. **用户管理**：个人用户添加并管理应用程序。应用程序只能访问用户授权的数据。
1. **应用程序凭证**：构建流会自动为应用程序生成应用程序凭证（客户端 ID 和客户端密钥）。
1. 在“OAuth 信息”部分，为应用程序设置 OAuth。
1. **OAuth 重定向 URL**（必填）：输入重定向 URL 或端点，以便在应用程序和 Zoom 之间设置 OAuth。
1. **使用严格模式 URL**（可选）
1. **子域检查**（可选）
1. **OAuth 允许列表**（必填）：添加 Zoom 允许的任何唯一 URL 作为 OAuth 流的有效重定向网址。
1. 在**范围**页面上，选择允许应用调用的 Zoom API 方法。此范围定义了用户可以使用的信息和功能。选择以下精细范围：
+ user:read:list\$1users:admin
+ zoom\$1rooms:read:list\$1rooms:admin
+ group:read:list\$1members:admin
+ group:read:administrator:admin
+ group:read:list\$1groups:admin
+ report:read:admin
+ role:read:list\$1roles、role:read:list\$1roles:admin
添加范围后选择**继续**，即可使用应用程序。
有关 OAuth 2.0 设置的更多信息，请参阅 [Integrations (OAuth apps)](https://developers.zoom.us/docs/integrations/)。
# 配置 Zoom Meetings 连接
Zoom Meetings 支持 OAuth2 的 AUTHIZATION\$1CODE 授权类型。该授权类型决定了 AWS Glue 如何与 Zoom Meetings 通信来请求访问数据。
+ 此授权类型被视为“三足型”OAuth，因为它依赖于将用户重定向到第三方授权服务器来对用户进行身份验证。它用于通过 AWS Glue 控制台创建连接。用户要创建连接，则需为 Zoom Meetings 客户端应用程序提供与 OAuth 相关的信息，例如客户端 ID 和客户端密钥。AWS Glue 控制台会将用户重定向到 Zoom Meetings，用户必须登录并向 AWS Glue 授予所请求的权限，以便访问其 Zoom Meetings 实例。
+ 用户仍然可以选择在 Zoom Meetings 中创建自己的关联应用程序，并在通过 AWS Glue 控制台创建连接时，提供自己的客户端 ID 和客户端密钥。在这种情况下，他们仍会重定向到 Zoom Meetings，以便登录并授权 AWS Glue 访问其资源。
+ 此授权类型会生成刷新令牌和访问令牌。访问令牌的有效期很短，可以通过刷新令牌在不需要用户干预的情况下自动刷新。
+ 有关为授权码 OAuth 流创建关联应用程序的 Zoom Meetings 公共文档，请参阅 [Using OAuth 2.0](https://developers.zoom.us/docs/api/using-zoom-apis/#using-oauth-20)。
要配置 Zoom Meetings 连接，请执行以下操作：
1. 在 AWS Secrets Manager 中，创建一个包含以下详细信息的密钥：
1. 对于客户管理型关联应用程序，密钥应包含关联应用程序的消费者密钥，且以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 为键。
1. 注意：必须在 AWS Glue 中为连接创建一个密钥。
1. 在 AWS Glue Glue Studio 中，按照以下步骤在**数据连接**下创建连接：
1. 选择**连接类型**时，请选择 Zoom Meetings。
1. 提供想要连接到的 Zoom Meetings 环境。
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` 的权限。
# 从 Zoom Meetings 实体读取内容
**先决条件**
要从中读取内容的 Zoom Meetings 对象。需要 `Group` 或 `Zoom Rooms` 等对象名称。
**源支持的实体**：
| 实体 | 可以筛选 | 支持限制 | 支持排序依据 | 支持 Select \$1 | 支持分区 |
| --- | --- | --- | --- | --- | --- |
| Zoom Rooms | 否 | 是 | 否 | 是 | 否 |
| 组 | 否 | 否 | 否 | 是 | 否 |
| 群成员 | 支持 | 是 | 否 | 是 | 否 |
| 群管理员 | 否 | 是 | 否 | 是 | 否 |
| 报告（每日） | 是 | 否 | 否 | 是 | 否 |
| 角色 | 否 | 否 | 否 | 是 | 否 |
| Users | 支持 | 是 | 否 | 是 | 否 |
**示例：**
```
zoom_read = glueContext.create_dynamic_frame.from_options(
connection_type="zoom",
connection_options={
"connectionName": "connectionName",
"ENTITY_NAME": "organization",
"API_VERSION": "v2"
}
)
```
**Zoom Meetings 实体和字段详细信息**：
Zoom Meetings 会动态加载所选实体下的可用字段。根据字段的数据类型，它支持以下筛选运算符。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/zoom-meetings-reading-from-entities.html)
## 对查询进行分区
Zoom Meetings 不支持基于筛选条件的分区或基于记录的分区。
# Zoom Meetings 连接选项
以下是 Zoom Meetings 的连接选项：
+ `ENTITY_NAME`（字符串）：（必填）用于读取。Zoom Meetings 实体的名称。例如 `group`。
+ `API_VERSION`（字符串）：（必填）用于读取。要使用的 Zoom Meetings Rest API。该值将为 `v2`，因为 Zoom Meetings 目前仅支持版本 v2。
+ `SELECTED_FIELDS`（列表<字符串>）–默认：empty(SELECT \$1)。用于读取。想要为所选实体选择的列的逗号分隔列表。
+ `FILTER_PREDICATE`（字符串）– 默认：空。用于读取。应采用 Spark SQL 格式。
+ `QUERY`（字符串）– 默认：空。用于读取。完整的 Spark SQL 查询。
# Zoom Meetings 限制
以下是 Zoom Meetings 的限制或说明：
+ Zoom Meetings 不支持排序依据。
+ 由于没有满足所需条件的字段，Zoom Meetings 不支持基于筛选条件的分区。
+ 由于不支持分页限制和基于偏移量的分页，Zoom Meetings 不支持基于记录的分区。
# 使用您自己的 JDBC 驱动程序添加 JDBC 连接
使用 JDBC 连接时，您可以使用自己的 JDBC 驱动程序。当 AWS Glue 爬网程序使用的默认驱动程序无法连接到数据库时，您可以使用自己的 JDBC 驱动程序。例如，如果您想在 Postgres 数据库中使用 SHA-256，而较早的 Postgres 驱动程序不支持此功能，则可以使用自己的 JDBC 驱动程序。
## 支持的数据来源
| 支持的数据来源 | 不支持的数据来源 |
| --- | --- |
| MySQL | Snowflake |
| Postgres | |
| Oracle | |
| Redshift | |
| SQL Server | |
| Aurora\$1 | |
\$1 如果使用原生 JDBC 驱动程序，则支持。并非所有驱动程序功能都可以利用。
## 向 JDBC 连接中添加 JDBC 驱动程序
**注意**
如果您选择引入自己的 JDBC 驱动程序版本，则 AWS Glue 爬网程序将消耗 AWS Glue 作业 和 Amazon S3 存储桶中的资源，以确保您提供的驱动程序在您的环境中运行。额外的资源使用量将反映在您的账户中。AWS Glue 爬网程序和作业的成本属于计费 AWS Glue 类别。此外，提供自己的 JDBC 驱动程序并不意味着爬网程序能够利用该驱动程序的所有功能。
**将您自己的 JDBC 驱动程序添加到 JDBC 连接：**
1. 将 JDBC 驱动程序文件添加到 Amazon S3 位置。您可以创建存储桶和/或文件夹，或使用现有存储桶和/或文件夹。
1. 在 AWS Glue 控制台中，选择 **Data Catalog** 下方左侧菜单中的**连接**，然后创建新连接。
1. 填写**连接属性**字段，然后为**连接类型**选择 JDBC。
1. 在**连接访问**中，输入 **JDBC URL** 和 **JDBC 驱动程序类名** - *（可选）*。驱动程序类名必须是 AWS Glue 爬网程序支持的数据来源的名称。
![\[屏幕截图在“添加数据来源”窗口中显示了一个选中 JDBC 的数据来源和一个连接。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/add-connection-connection-access.png)
1. 在 **JDBC 驱动程序 Amazon S3 路径** - *可选*字段中选择 JDBC 驱动程序所在的 Amazon S3 路径。
1. 如果输入用户名和密码或密钥，请填写“凭证类型”字段。完成后，选择**创建连接**。
**注意**
目前不支持测试连接。使用您提供的 JDBC 驱动程序对数据来源进行爬取时，爬网程序会跳过此步骤。
1. 将新创建的连接添加到爬网程序。在 AWS Glue 控制台中，选择 **Data Catalog** 下方左侧菜单中的**爬网程序**，然后创建新爬网程序。
1. 在**添加爬网程序**向导中，在步骤 2 中选择**添加数据来源**。
![\[屏幕截图在“添加数据来源”窗口中显示了一个选中 JDBC 的数据来源和一个连接。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/add-crawler-add-data-source.png)
1. 选择 **JDBC** 作为数据来源，然后选择在前面的步骤中创建的连接。完成
1. 要将自己的 JDBC 驱动程序与 AWS Glue 爬网程序一起使用，请向该爬网程序使用的角色添加以下权限：
+ 授予以下作业操作的权限：`CreateJob`、`DeleteJob`、`GetJob`、`GetJobRun`、`StartJobRun`。
+ 授予 IAM 操作的权限：`iam:PassRole`
+ 授予 Amazon S3 操作的权限：`s3:DeleteObjects`、`s3:GetObject`、`s3:ListBucket`、`s3:PutObject`。
+ 在 IAM policy 中授予服务主体访问存储桶/文件夹的权限。
示例 IAM policy：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListBucket",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/driver-parent-folder/driver.jar",
"arn:aws:s3:::amzn-s3-demo-bucket"
]
}
]
}
```
------
AWS Glue 爬网程序会创建两个文件夹：\$1glue\$1job\$1crawler 和 \$1crawler。
如果驱动程序 jar 位于 `s3://amzn-s3-demo-bucket/driver.jar"` 文件夹中，则请添加以下资源：
```
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/_glue_job_crawler/*",
"arn:aws:s3:::amzn-s3-demo-bucket/_crawler/*"
]
```
如果驱动程序 jar 位于 `s3://amzn-s3-demo-bucket/tmp/driver/subfolder/driver.jar"` 文件夹中，则请添加以下资源：
```
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/tmp/_glue_job_crawler/*",
"arn:aws:s3:::amzn-s3-demo-bucket/tmp/_crawler/*"
]
```
1. 如果您使用的是 VPC，则必须通过创建接口端点并将其添加到您的路由表中来允许访问 AWS Glue 端点。有关更多信息，请参阅 [Creating an interface VPC endpoint for AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/vpc-interface-endpoints.html#vpc-endpoint-create)
1. 在 Data Catalog 中使用加密时，请创建 AWS KMS 接口端点并将其添加到您的路由表中。有关更多信息，请参阅[为 AWS KMS 创建 VPC 端点](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html#vpce-create-endpoint)。
# 在 AWS Glue Studio 中使用自定义连接器和连接
AWS Glue 使用 JDBC 连接为常用数据存储（例如 Amazon Redshift、Amazon Aurora、Microsoft SQL Server、MySQL、MongoDB 和 PostgreSQL）提供内置支持。AWS Glue 还允许您在数据提取、转换和加载（ETL）任务中使用自定义 JDBC 驱动程序。对于本地不支持的数据存储（如 SaaS 应用程序），您可以使用连接器。
*连接器*是一个可选代码包，可帮助访问 AWS Glue Studio 中的数据存储。您可以订阅 AWS Marketplace 中提供的几个连接器。
创建 ETL 任务时，您可以使用本地支持的数据存储、AWS Marketplace 中的连接器或您自己的自定义连接器。如果您使用连接器，您必须首先为连接器创建连接。*连接*包含连接到特定数据存储所需的属性。您将使用与 ETL 任务中的数据源和数据目标的连接。连接器和连接协同工作，方便访问数据存储。
在创建连接器连接时，可以使用以下连接：
+ **Amazon Aurora** – 一种具有内置安全性、备份还原以及内存加速功能的可扩展、高性能关系数据库引擎。
+ **Amazon DocumentDB** – 一种可扩展、高度可用且完全托管式的文档数据库服务，支持 MongoDB 和 SQL API。
+ **Amazon Redshift** – 一种可扩展、高度可用且完全托管式的文档数据库服务，支持 MongoDB 和 SQL API。
+ **Azure SQL** – 一种由 Microsoft Azure 提供的基于云的关系数据库服务，具有可扩展、可靠和安全的数据存储和管理功能。
+ **Cosmos DB** – 一种由 Microsoft Azure 提供的全球分布式云数据库服务，具有可扩展、高性能的数据存储和查询功能。
+ **Google BigQuery** – 一种无服务器云数据仓库，用于对大型数据集快速运行 SQL 查询。
+ **JDBC** – 一种关系数据库管理系统（RDBMS），使用 Java API 来连接到数据连接并与之交互。
+ **Kafka** – 一种用于实时数据流式传输和消息收发的开源流式处理平台。
+ **MariaDB** – 一种由社区开发的 MySQL 分支，提供增强的性能、可扩展性和功能。
+ **MongoDB** – 一种面向文档的跨平台数据库，具有高可扩展性、高灵活性、高性能等特点。
+ **MongoDB Atlas** – 一种由 MongoDB 提供的基于云的数据库即服务（DBaaS）产品，可简化 MongoDB 部署的管理和扩展。
+ **Microsoft SQL Server** – 一种由微软公司推出的关系数据库管理系统（RDBMS），具有强大的数据存储、分析和报告功能。
+ **Mixpanel**：一种分析平台，可帮助企业分析用户如何与其网站、移动应用程序和其他数字产品进行交互。
+ **MySQL** – 一种广泛用于 Web 应用程序的开源关系数据库管理系统（RDBMS），并以可靠性和可扩展性闻名。
+ **网络** – 网络数据来源是指数据集成平台可以访问并且可通过网络访问的资源或服务。
+ **OpenSearch** – OpenSearch 数据来源是指 OpenSearch 可以连接到并从中提取数据的应用程序。
+ **Oracle** – 一种由甲骨文公司推出的关系数据库管理系统（RDBMS），具有强大的数据存储、分析和报告功能。
+ **PostgreSQL** – 一种开源关系数据库管理系统（RDBMS），具有强大的数据存储、分析和报告功能。
+ **Salesforce** – Salesforce 提供客户关系管理（CRM）软件，可在销售、客户服务、电子商务等方面为您提供帮助。如果您是 Salesforce 用户，可以将 AWS Glue 连接到您的 Salesforce 账户。然后，您可以使用 Salesforce 作为 ETL 作业中的数据来源或目标。通过运行这些作业，可在 Salesforce 与 AWS 服务或其他受支持的应用程序之间传输数据。
+ **SAP HANA** – 一种内存数据库和分析平台，提供快速数据处理、高级分析和实时数据集成等功能。
+ **Snowflake** – 基于云的数据仓库，提供可扩展、高性能的数据存储和分析服务。
+ **Teradata** – 一种开源关系数据库管理系统（RDBMS），提供高性能的数据存储、分析和报告功能。
+ **Vertica** – 一种专门面向大数据分析的列式分析数据仓库，提供快速查询、高级分析和可扩展性等功能。
# 创建自定义连接器
您还可以构建自己的连接器，然后将连接器代码上载到 AWS Glue Studio。
自定义连接器通过 AWS Glue Spark 运行时 API 集成到 AWS Glue Studio。AWS Glue Spark 运行时允许您插入兼容 Spark、Athena 或 JDBC 接口的连接器。它允许您传递自定义连接器可用的连接选项。
您可以使用 [AWS Glue 连接](https://docs.aws.amazon.com/glue/latest/dg/glue-connections.html)封装所有连接属性并为 ETL 任务提供连接名称。与数据目录连接集成，您可以在单个 Spark 应用程序中或跨不同应用程序的多个调用使用相同的连接属性。
您可以指定连接的其他选项。AWS Glue Studio 生成的任务脚本包含 `Datasource` 条目，该条目使用连接通过指定的连接选项插入连接器。例如：
```
Datasource = glueContext.create_dynamic_frame.from_options(connection_type =
"custom.jdbc", connection_options = {"dbTable":"Account","connectionName":"my-custom-jdbc-
connection"}, transformation_ctx = "DataSource0")
```
**将自定义连接器添加到 AWS Glue Studio**
1. 为自定义连接器创建代码。有关更多信息，请参阅 [开发自定义连接器](developing-custom-connectors.md)。
1. 连接器增加了对 AWS Glue 功能的支持。下面举例说明了这些功能，以及如何在 AWS Glue Studio 生成的任务脚本内使用这些功能。
+ **数据类型映射** – 连接器可以在从基础数据存储中读取列的同时对列进行类型化。例如，解析记录并构造 `DynamicFrame` 时，`dataTypeMapping` 的 `{"INTEGER":"STRING"}` 会将所有类型为 `Integer` 的列转换为类型为 `String` 的列。这有助于用户将列转换为他们选择的类型。
```
DataSource0 = glueContext.create_dynamic_frame.from_options(connection_type
= "custom.jdbc", connection_options = {"dataTypeMapping":{"INTEGER":"STRING"}",
connectionName":"test-connection-jdbc"}, transformation_ctx = "DataSource0")
```
+ **分区以进行并行读取** – AWS Glue 允许对列上的数据进行分区，以便从数据存储中读取并行数据。您必须指定分区列、下分区界限、上分区界限和分区数。此功能使您能够利用数据并行性以及为 Spark 应用程序分配的多个 Spark 执行程序。
```
DataSource0 = glueContext.create_dynamic_frame.from_options(connection_type
= "custom.jdbc", connection_options = {"upperBound":"200","numPartitions":"4",
"partitionColumn":"id","lowerBound":"0","connectionName":"test-connection-jdbc"},
transformation_ctx = "DataSource0")
```
+ **使用 AWS Secrets Manager 存储凭证** – 数据目录连接还可以包含 AWS Secrets Manager 中所存储密钥的 `secretId`。AWS 密钥可以安全地存储身份验证和凭证信息，并在运行时将其提供给 AWS Glue。或者，您还可以在 Spark 脚本中指定 `secretId`，如下所示：
```
DataSource = glueContext.create_dynamic_frame.from_options(connection_type
= "custom.jdbc", connection_options = {"connectionName":"test-connection-jdbc",
"secretId"-> "my-secret-id"}, transformation_ctx = "DataSource0")
```
+ **使用行谓词和列投影筛选源数据** – AWS Glue Spark 运行时还允许用户向下推送 SQL 查询，以使用行谓词和列投影在源处筛选数据。这样一来，ETL 任务能够更快地从支持推送的数据存储加载筛选的数据。向下推送到 JDBC 数据源的 SQL 查询示例如下：`SELECT id, name, department FROM department WHERE id < 200.`
```
DataSource = glueContext.create_dynamic_frame.from_options(connection_type =
"custom.jdbc", connection_options = {"query":"SELECT id, name, department FROM department
WHERE id < 200","connectionName":"test-connection-jdbc"}, transformation_ctx =
"DataSource0")
```
+ **任务书签** – AWS Glue 支持从 JDBC 源增量加载数据。AWS Glue 从数据存储中跟踪上次处理的记录，并在后续 ETL 任务运行中处理新的数据记录。任务书签使用主键作为书签键的默认列，前提是此列按顺序增加或减少。有关任务书签的更多信息，请参阅《AWS Glue 开发人员指南》**中的[任务书签](https://docs.aws.amazon.com/glue/latest/dg/monitor-continuations.html)。
```
DataSource0 = glueContext.create_dynamic_frame.from_options(connection_type =
"custom.jdbc", connection_options = {"jobBookmarkKeys":["empno"], "jobBookmarkKeysSortOrder"
:"asc", "connectionName":"test-connection-jdbc"}, transformation_ctx = "DataSource0")
```
1. 将自定义连接器打包为 JAR 文件，然后将文件上载到 Amazon S3。
1. 测试您的自定义连接器。有关更多信息，请参阅 [Glue 自定义连接器：本地验证测试指南](https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/localValidation/README.md)处 GitHub 上的说明。
1. 在 AWS Glue Studio 控制台中，在导航窗格中选择 **Connectors (连接器)**。
1. 在 **Connectors (连接器)** 页面上，选择 **Create custom connector (创建自定义连接器)**。
1. 在 **Create custom connector (创建自定义连接器)** 页面上，输入以下信息：
+ 指向 Amazon S3 中自定义代码 JAR 文件位置的路径。
+ AWS Glue Studio 将使用的连接器的名称。
+ 您的连接器类型，可以是 **JDBC**、**Spark** 或者 **Athena**。
+ 自定义代码中入口点的名称，AWS Glue Studio 将调用以使用连接器。
+ 对于 JDBC 连接器，此字段应该是 JDBC 驱动程序的类名称。
+ 对于 Spark 连接器，此字段应该是完全限定的数据源类名称或其别名，您可以使用 `format` 运算符。
+ （仅限 JDBC）JDBC 连接用于数据存储的基本 URL。
+ （可选）自定义连接器的描述。
1. 选择 **Create connector (创建连接器)**。
1. 在 **Connectors (连接器)** 页面中，创建使用此连接器的连接，如[为连接器创建连接](creating-connections.md)中所示。
## 将连接器添加到 AWS Glue Studio
连接器是一段代码，便于您在数据存储和 AWS Glue 之间通信。您可以订阅 AWS Marketplace 中提供的连接器，或者您还可以创建自己的自定义连接器。
### 订阅 AWS Marketplace 连接器
AWS Glue Studio 助力轻松地从 AWS Marketplace 添加连接器。
**将连接器从 AWS Marketplace 添加到 AWS Glue Studio**
1. 在 AWS Glue Studio 控制台中，在导航窗格中选择 **Connectors (连接器)**。
1. 在 **Connectors (连接器)** 页面上，选择 **Go to AWS Marketplace (转到 Amazon Web Services Marketplace)**。
1. 在 AWS Marketplace 中的 **Featured products (特色产品)** 中，选择要使用的连接器。您可以选择其中一个特色连接器，也可以进行搜索。您可以搜索连接器的名称或类型，也可以使用选项来优化搜索结果。
如果您要使用其中一个特色连接器，请选择 **View product (查看产品)**。如果通过搜索来查找连接器，请选择连接器的名称。
1. 在连接器的产品页面上，使用选项卡查看有关连接器的信息。如果您决定购买此连接器，请选择 **Continue to Subscribe (继续订阅)**。
1. 提供付款信息，然后选择 **Continue to Configure (继续配置)**。
1. 在 **Configure this software (配置此软件)** 页面上，选择部署方法和要使用的连接器版本。然后选择 **Continue to Launch (继续启动)** 以继续。
1. 在 **Launch this software (启动此软件)** 页面上，您可以查看连接器提供程序提供的 **Usage Instructions (使用说明)**。准备就绪后，选择**激活 AWS Glue Studio 中的连接**。
一小段时间后，控制台将显示 AWS Glue Studio 中的 **Create marketplace connection (创建 Marketplace 连接)** 页面。
1. 创建使用此连接器的连接，如[为连接器创建连接](creating-connections.md)中所述。
或者，您可以选择 **Activate connector only (仅激活连接器)** 以跳过此时创建连接。您稍后必须创建连接才能使用该连接器。
# 为连接器创建连接
AWS Glue 连接是存储特定数据存储的连接信息的数据目录对象。这些连接存储登录凭证、URI 字符串、Virtual Private Cloud (VPC) 等信息。在数据目录中创建连接，就可以不必在每次创建任务时都指定所有连接详细信息。
**为连接器创建连接**
1. 在 AWS Glue Studio 控制台中，在导航窗格中选择 **Connectors (连接器)**。在**连接**部分中，选择**创建连接**。
1. 在**创建数据连接**向导的第 1 步中，选择要为其创建连接的数据来源。可通过多种方式查看可用的数据来源，包括：
+ 通过选择选项卡筛选可用的数据来源。默认情况下，**全部连接器**处于选中状态。
+ 切换到**列表**可以列表形式查看数据来源，也可以切换回**网格**以在网格布局查看可用连接器。
+ 使用搜索栏缩小数据来源列表的范围。在键入过程中，系统将显示搜索匹配项，不匹配的来源将从视图中移除。
选好数据来源后，选择**下一步**。
1. 在向导的第 2 步中配置连接。
输入连接详细信息。根据所选连接器的类型，系统会提示您输入附加信息：
![\[屏幕截图显示了“连接器”页面和“连接”部分。创建连接按钮已用红色方框包围起来。选择创建连接以启动连接向导。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/connections-create-connection.png)
1. 在**创建数据连接**向导的第 1 步中，选择要为其创建连接的数据来源。可通过多种方式查看可用的数据来源。默认情况下，您将在网格布局中看到所有可用的数据来源。您也可以：
+ 切换到**列表**可以列表形式查看数据来源，也可以切换回**网格**以在网格布局查看可用连接器。
+ 使用搜索栏缩小数据来源列表的范围。在键入过程中，系统将显示搜索匹配项，不匹配的来源将从视图中移除。
![\[屏幕截图显示了搜索栏和网格-列表切换开关。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/connections-create-step-1-view.png)
选好数据来源后，选择**下一步**。
1. 在向导的第 2 步中配置连接。
输入连接详细信息。根据所选连接器的类型，您可能会需要输入额外的连接信息。这可能包括：
+ **连接详细信息** – 这些字段将根据您要连接的数据来源而变化。例如，假设您要连接到 Amazon DocumentDB 数据库，则需要输入 Amazon DocumentDB URL。如果要连接到 Amazon Aurora，则需要选择数据库实例并输入数据库名称。以下是对于 Amazon Aurora 而言需要的连接详细信息：
![\[屏幕截图显示了将 Amazon Aurora 配置为数据来源时需要的连接详细信息。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/connections-create-step-2-configure.png)
+ 凭证类型 – 可选择**用户名和密码**或者 **AWS Secrets Manager**。输入请求的身份验证信息。
+ 对于使用 JDBC 的连接器，请输入为数据存储创建 JDBC URL 所需的信息。
+ 如果您使用 Virtual Private Cloud（VPC），请为 VPC 输入网络信息。
1. 在向导的第 3 步中设置连接属性。在这一步中，您可以选择添加描述和标签。名称为必填项，且已预先填充默认值。选择**下一步**。
1. 查看连接源、详细信息和属性。如果要进行任何更改，请在向导的这一步选择**编辑**。准备就绪后，选择**创建连接**。
选择**创建连接**。
您将返回到 **Connectors (连接器)** 页面，信息性广告条会指示已创建的连接。您现在可以在您的 AWS Glue Studio 作业中使用连接。
# 创建 Kafka 连接
创建 Kafka 连接时，从下拉菜单中选择 **Kafka** 将显示要配置的其他设置：
+ Kafka 集群详细信息
+ 身份验证
+ 加密
+ 网络操作
**配置 Kafka 集群详细信息**
1. 选择集群位置。可以从 **Amazon Managed for Apache Kafka (MSK)** 集群或 **Customer managed Apache Kafka**（客户管理的 Apache Kafka）集群中选择。有关 Amazon Managed Streaming for Apache Kafka 的更多信息，请参阅 [Amazon Managed Streaming for Apache Kafka (MSK)](https://docs.aws.amazon.com/msk/latest/developerguide/what-is-msk.html)。
**注意**
Amazon Managed Streaming for Apache Kafka 仅支持 TLS 和 SASL/SCRAM-SHA-512 身份验证方法。
![\[屏幕截图显示了 Kafka 集群的详细信息部分，其中包含选择群集位置和输入 Kafka 引导服务器 URL 的选项。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/kafka-cluster-details.png)
1. 输入 Kafka 引导服务器的 URL。通过用逗号分隔每台服务器，可以输入多个服务器。通过在 URL 末尾附加 `:`，包含端口号。
例如：`b-1.vpc-test-2.034a88o.kafka-us-east-1.amazonaws.com:9094`
**选择身份验证方法**
![\[屏幕截图显示了选择 Kafka 身份验证方法的下拉菜单。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/kafka-connection-authentication.png)
AWS Glue 支持用于身份验证的简单身份验证和安全层 (SASL) 框架。SASL 框架支持各种身份验证机制，且 AWS Glue 提供 SCRAM（用户名和密码）、GSSAPI（Kerberos 协议）和 PLAIN （用户名和密码）协议。
从下拉菜单中选择身份验证方法时，可以选择以下客户端身份验证方法：
+ 无 – 不进行身份验证。如果是为进行测试而创建连接，这非常有用。
+ SASL/SCRAM-SHA-512 - 选择此身份验证方法以指定身份验证凭证。有两个可用的选项：
+ 使用 AWS Secrets Manager（推荐）- 如果选择此选项，则可以将凭证存储在 AWS Secrets Manager 中，然后让 AWS Glue 在需要时访问该信息。指定存储 SSL 或 SASL 身份验证凭证的密钥。
![\[如果身份验证方法是 SASL/SCRAM-SHA-512，则屏幕截图显示了身份验证凭证选项。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/kafka-connection-authentication-sha-512.png)
+ 直接提供用户名和密码。
+ SASL/GSSAPI (Kerberos) – 如果选择此选项，则可以选择 keytab 文件、krb5.conf 文件的位置，然后输入 Kerberos 主体名称和 Kerberos 服务名称。keytab 文件和 krb5.conf 文件的位置必须位于 Amazon S3 位置。由于 MSK 尚不支持 SASL/GSSAPI，所以此选项仅适用于客户管理的 Apache Kafka 集群。有关更多信息，请参阅 [MIT Kerberos 文档：keytab](https://web.mit.edu/kerberos/krb5-latest/doc/basic/keytab_def.html)。
+ SASL/PLAIN - 选择此身份验证方法以指定身份验证凭证。有两个可用的选项：
+ 使用 AWS Secrets Manager（推荐）- 如果选择此选项，则可以将凭证存储在 AWS Secrets Manager 中，然后让 AWS Glue 在需要时访问该信息。指定存储 SSL 或 SASL 身份验证凭证的密钥。
+ 直接提供用户名和密码。
+ SSL 客户端身份验证 – 如果选择此选项，则可以通过浏览 Amazon S3 来选择 Kafka 客户端密钥库的位置。或者，您可以输入 Kafka 客户端密钥库密码和 Kafka 客户端密钥密码。
![\[如果 SSL 是身份验证方法，屏幕截图显示了加密选项。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/kafka-connection-authentication-ssl.png)
**配置加密设置**
1. 如果 Kafka 连接需要 SSL 连接，请选中 **Require SSL connection**（需要 SSL 连接）复选框。请注意，如果无法通过 SSL 连接，则连接将失败。用于加密的 SSL 可以与任何身份验证方法（SASL/SCRAM-SHA-512、SASL/GSSAPI、SASL/PLAIN、SSL 客户端身份验证）一起使用，并且是可选的。
如果身份验证方法设置为 **SSL client authentication**（SSL 客户端身份验证），则系统将自动选择并禁用此选项，以防止出现任何更改。
1. （可选）。选择来自证书颁发机构 (CA) 的私有证书的位置。请注意，证书的位置必须在 S3 位置。选择 **Browse**（浏览），从连接的 S3 存储桶中选择文件。路径必须采用 `s3://bucket/prefix/filename.pem` 格式。它必须以文件名和 .pem 扩展名结尾。
1. 可以选择跳过验证证书颁发机构 (CA) 的证书。选择复选框 **Skip validation of certificate from certificate authority (CA)** [跳过验证证书颁发机构（CA）的证书]。如果未选中此框，则 AWS Glue 会验证三种算法的证书：
+ SHA256withRSA
+ SHA384withRSA
+ SHA512withRSA
![\[屏幕截图显示了配置加密的选项，包括是否需要 SSL 连接、从证书颁发机构 (CA) 处选择私有证书位置的选项，以及跳过证书颁发机构 (CA) 颁发的证书验证选项。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/kafka-connection-encryption.png)
**（可选）网络选项**
下面是配置 VPC、子网和安全组的可选步骤。如果您的 AWS Glue 任务需要在 virtual private cloud (VPC) 子网中的 Amazon EC2 实例上运行，必须提供其他特定于 VPC 的配置信息。
1. 选择包含您的数据源的 virtual private cloud (VPC)。
1. 选择您的 VPC 所在的子网。
1. 选择允许访问 VPC 子网中数据存储的一个或多个安全组。安全组与附加到子网的 ENI 相关联。必须为所有 TCP 端口选择至少一个具有自引用入站规则的安全组。
![\[屏幕截图显示了 VPC、子网和安全组的可选网络选项。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/kafka-connection-network-options.png)
# 使用自定义连接器编写任务
您可以在 AWS Glue Studio 中为数据源节点和数据目标节点使用连接器和连接。
**Topics**
+ [创建任务，为数据源使用连接器](#create-job-connectors)
+ [为使用连接器的节点配置源属性](#edit-connector-source)
+ [为使用连接器的节点配置目标属性](#edit-connector-target)
## 创建任务，为数据源使用连接器
创建新任务时，可以为数据源和数据目标选择连接器。
**创建任务，为数据源或数据目标使用连接器**
1. 登录 AWS 管理控制台，然后通过以下网址打开 AWS Glue Studio 控制台：[https://console.aws.amazon.com/gluestudio/](https://console.aws.amazon.com/gluestudio/)。
1. 在 **Connectors (连接器)** 页面的 **Your connections (您的连接)** 资源列表中，选择要在任务中使用的连接，然后选择 **Create job (创建任务)**。
或者，在 AWS Glue Studio **Jobs (任务)** 页面的 **Create job (创建任务)** 下面，选择 **Source and target added to the graph (已添加到图形中的源和目标)**。在 **Source (源)** 下拉列表中，选择要在任务中使用的自定义连接器。还可以为 **Target (目标)** 选择连接器。
![\[\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/create-job-data-sources-screenshot.png)
1. 选择 **Create (创建)** 以打开可视化任务编辑器。
1. 配置数据源节点，如[为使用连接器的节点配置源属性](#edit-connector-source)中所示。
1. 添加转换、其他数据存储和数据目标以继续创建 ETL 任务，如[在 AWS Glue Studio 中启动视觉 ETL 作业](edit-nodes-chapter.md)中所示。
1. 配置任务属性以自定义任务运行环境，如[修改任务属性](managing-jobs-chapter.md#edit-jobs-properties)中所示。
1. 保存并运行任务。
## 为使用连接器的节点配置源属性
创建为数据源使用连接器的任务后，可视任务编辑器将显示任务图，其中包含为连接器配置的数据源节点。您必须为该节点配置数据源属性。
**为使用连接器的数据源节点配置属性**
1. 选择任务图中的连接器数据源节点，或者添加新节点，然后为 **Node type (节点类型)** 选择连接器。然后，在右侧的节点详细信息面板中，选择 **Data source properties (数据源属性)** 选项卡（如果尚未选择）。
![\[\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/data-source-properties-connector-screenshot2.png)
1. 在 **Data source properties (数据源属性)** 选项卡上，选择要用于此任务的连接。
输入每种连接类型所需的附加信息：
------
#### [ JDBC ]
+ **Data source input type (数据源输入类型)**：选择以提供表名称或 SQL 查询作为数据源。根据您的选择，您需要提供以下附加信息：
+ **Table name (表名称)**：数据源中表的名称。如果数据源未使用术语*表*，则提供适当数据结构的名称，如自定义连接器使用信息所示（AWS Marketplace 中提供)。
+ **Filter predicate (筛选条件谓词)**：读取数据源时使用的条件子句，类似于 `WHERE` 子句，用于检索数据的子集。
+ **Query code (查询代码)**：输入用于从数据源检索特定数据集的 SQL 查询。基本 SQL 查询示例：
```
SELECT column_list FROM
table_name WHERE where_clause
```
+ **Schema (架构)**：因为 AWS Glue Studio 使用存储在连接中的信息来访问数据源，而不是从数据目录表中检索元数据信息，所以您必须为数据源提供架构元数据。选择 **Add schema (添加架构)**，打开架构编辑器。
有关如何使用架构编辑器的说明，请参阅[编辑自定义转换节点的架构](transforms-custom.md#transforms-custom-editschema)。
+ **Partition column (分区列)**：（可选）您可以为 **Partition Column (分区列)**、**Lower bound (下限)**、**Upper bound (上限)** 和 **Number of partitions (分区数)** 提供值，对数据读取进行分区。
`lowerBound` 和 `upperBound` 值用于确定分区步长，而不是用于筛选表中的行。对表中的所有行进行分区并返回。
**注意**
列分区为用于读取数据的查询添加额外的分区条件。使用查询（而不是表名称）时，您应验证查询是否适用于指定的分区条件。例如：
如果您的查询格式为 `"SELECT col1 FROM table1"`，则在使用分区列的查询结尾附加 `WHERE` 子句，以测试查询。
如果您的查询格式为 `"SELECT col1 FROM table1 WHERE col2=val"`，则通过 `AND` 和使用分区列的表达式扩展 `WHERE` 子句，以测试查询。
+ **Data type casting (数据类型转换)**：如果数据源使用 JDBC 中不可用的数据类型，请使用此部分指定如何将数据源中的数据类型转换为 JDBC 数据类型。您最多可指定 50 个不同的数据类型转换。数据源中使用相同数据类型的所有列都将以相同的方式进行转换。
例如，如果数据源中有三列使用 `Float` 数据类型，并且您指示 `Float` 数据类型应转换为 JDBC `String` 数据类型，则使用 `Float` 数据类型的所有三列将转换为 `String` 数据类型。
+ **Job bookmark keys (任务书签键)**：任务书签可帮助 AWS Glue 维护状态信息，并防止重新处理旧数据。指定一个或多个列为书签键。AWS Glue Studio 使用书签键跟踪上次运行 ETL 任务期间已处理的数据。用于自定义书签键的列都必须严格单调递增或递减，但是允许有间隙。
如果您输入多个书签键，它们将合并成一个复合键。复合任务书签键不应包含重复的列。如果不指定书签键，则预设情况下，AWS Glue Studio 将使用主键作为书签键，前提是主键按顺序递增或递减（没有间隙）。如果表没有主键，但任务书签属性已启用，则必须提供自定义任务书签键。否则，无法搜索用作默认值的主键，任务运行将失败。
+ **Job bookmark keys sorting order (任务书签键排序)**：选择键值是按顺序递增还是递减。
------
#### [ Spark ]
+ **Schema (架构)**：因为 AWS Glue Studio 使用存储在连接中的信息来访问数据源，而不是从数据目录表中检索元数据信息，所以您必须为数据源提供架构元数据。选择 **Add schema (添加架构)**，打开架构编辑器。
有关如何使用架构编辑器的说明，请参阅[编辑自定义转换节点的架构](transforms-custom.md#transforms-custom-editschema)。
+ **Connection options (连接选项)**：根据需要输入其他键值对，提供其他连接信息或选项。例如，您可以输入数据库名称、表名、用户名和密码。
例如，对于 OpenSearch，您可以输入以下键值对，如[教程：使用 AWS Glue Connector for Elasticsearch](tutorial-elastisearch-connector.md)中所述：
+ `es.net.http.auth.user` : `username`
+ `es.net.http.auth.pass` : `password`
+ `es.nodes` : `https://`
+ `es.port` : `443`
+ `path`: ``
+ `es.nodes.wan.only` : `true`
有关要使用的最小连接选项的示例，请参阅 GitHub 上的测试脚本示例 [MinimalSparkConnectorTest.scala](https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/development/Spark/MinimalSparkConnectorTest.scala)，显示了您通常在连接中提供的连接选项。
------
#### [ Athena ]
+ **Table name (表名称)**：数据源中表的名称。如果您使用从 Athena-CloudWatch logs 读取数据的连接器，则需要输入表名 `all_log_streams`。
+ **Athena schema name (Athena 架构名称)**：在 Athena 数据源中选择与包含该表的数据库相对应的架构。如果您使用从 Athena-CloudWatch logs 读取数据的连接器，则需要输入类似于 `/aws/glue/name` 的表名。
+ **Schema (架构)**：因为 AWS Glue Studio 使用存储在连接中的信息来访问数据源，而不是从数据目录表中检索元数据信息，所以您必须为数据源提供架构元数据。选择 **Add schema (添加架构)**，打开架构编辑器。
有关如何使用架构编辑器的说明，请参阅[编辑自定义转换节点的架构](transforms-custom.md#transforms-custom-editschema)。
+ **Additional connection options (其他连接选项)**：根据需要输入其他键值对，提供其他连接信息或选项。
有关示例，请参阅 `README.md` 文件，网址为 [https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/development/Athena](https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/development/Athena)。在本文档中的步骤中，示例代码显示了所需的最小连接选项，即 `tableName`、`schemaName` 和 `className`。代码示例将这些选项指定为 `optionsMap` 变量，但您可以为连接指定它们，然后使用连接。
------
1. （可选）提供所需信息后，您可以选择节点详细信息面板中的 **Output schema (输出架构)** 选项卡，查看生成的数据架构。此选项卡上显示的架构将由您添加到任务图的子节点使用。
1. （可选）配置节点属性和数据源属性后，您可以选择节点详细信息窗格中的 Data preview (数据预览) 选项卡来预览数据源的数据集。当您首次为任务中的任何节点选择此选项卡时，系统会提示您提供 IAM 角色以访问数据。使用此功能会产生相关费用，并且一旦您提供 IAM 角色，则会立即开始计费。
## 为使用连接器的节点配置目标属性
如果将连接器用于数据目标类型，则必须配置数据目标节点的属性。
**为使用连接器的数据目标节点配置属性**
1. 在任务图中选择连接器数据目标节点。然后，在右侧的节点详细信息面板中，选择 **Data target properties (数据目标属性)** 选项卡（如果尚未选择）。
1. 在 **Data target properties (数据目标属性)** 选项卡上，选择用于写入目标的连接。
输入每种连接类型所需的附加信息：
------
#### [ JDBC ]
+ **Connection (连接)**：选择要与连接器一起使用的连接。有关如何创建连接的信息，请参阅[为连接器创建连接](creating-connections.md)。
+ **Table name (表名称)**：数据目标中表的名称。如果数据目标未使用术语*表*，则提供适当数据结构的名称，如自定义连接器使用信息所示（AWS Marketplace 中提供)。
+ **Batch size (批处理大小)**（可选）：在单个操作中输入要在目标表中插入的行数或记录数。默认值是 1000 行。
------
#### [ Spark ]
+ **Connection (连接)**：选择要与连接器一起使用的连接。如果以前未创建连接，请选择 **Create connection (创建连接)** 创建一个。有关如何创建连接的信息，请参阅[为连接器创建连接](creating-connections.md)。
+ **Connection options (连接选项)**：根据需要输入其他键值对，提供其他连接信息或选项。您可以输入数据库名称、表名、用户名和密码。
例如，对于 OpenSearch，您可以输入以下键值对，如[教程：使用 AWS Glue Connector for Elasticsearch](tutorial-elastisearch-connector.md)中所述：
+ `es.net.http.auth.user` : `username`
+ `es.net.http.auth.pass` : `password`
+ `es.nodes` : `https://`
+ `es.port` : `443`
+ `path`: ``
+ `es.nodes.wan.only` : `true`
有关要使用的最小连接选项的示例，请参阅 GitHub 上的测试脚本示例 [MinimalSparkConnectorTest.scala](https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/development/Spark/MinimalSparkConnectorTest.scala)，显示了您通常在连接中提供的连接选项。
------
1. 提供所需信息后，您可以选择节点详细信息面板中的 **Output schema (输出架构)** 选项卡，查看生成的数据架构。
# 管理连接器和连接
您可以在 AWS Glue 中使用**连接器**页面管理您的连接器和连接。
**Topics**
+ [查看连接器和连接详细信息](#connector-details)
+ [编辑连接器和连接](#editing-connectors)
+ [删除连接器和连接](#deleting-connectors)
+ [取消连接器的订阅](#cancel-subscription)
## 查看连接器和连接详细信息
您可以在 **Connectors (连接)** 页面上的 **Your connectors (您的连接器)** 和 **Your connections (您的连接)** 资源表中，查看关于您的连接器和连接的摘要信息。要查看详细信息，请执行以下步骤。
**查看连接器或连接详细信息**
1. 在 AWS Glue Studio 控制台中，在导航窗格中选择 **Connectors (连接器)**。
1. 选择要查看其详细信息的连接器或连接。
1. 选择 **Actions (操作)**，然后选择 **View details (查看详细信息)**，打开相应连接器或连接的详细信息页面。
1. 在详细信息页面上，您可以选择 **Edit**（编辑）或 **Delete**（删除）连接器或连接。
+ 对于连接器，可以选择 **Create connection (创建连接)**，创建使用连接器的新连接。
+ 对于连接，您可以选择 **Create job (创建任务)**，创建使用连接的任务。
## 编辑连接器和连接
您可以使用 **Connectors (连接器)** 页面更改您的连接器和连接中存储的信息。
**修改连接器或连接**
1. 在 AWS Glue Studio 控制台中，在导航窗格中选择 **Connectors (连接器)**。
1. 选择要更改的连接器或连接。
1. 选择**操作**，然后选择**编辑**。
您还可以选择 **View details (查看详细信息)**，然后在连接器或连接详细信息页面上，选择 **Edit (编辑)**。
1. 在 **Edit connector (编辑连接器)** 或者 **Edit connection (编辑连接)** 页面上，更新信息，然后选择 **Save (保存)**。
## 删除连接器和连接
您可以使用 **connector (连接器)** 页面删除连接器和连接。如果删除某个连接器，还应删除为该连接器创建的所有连接。
**要从 AWS Glue Studio 中删除连接器，请执行以下操作**
1. 在 AWS Glue Studio 控制台中，在导航窗格中选择 **Connectors (连接器)**。
1. 选择要删除的连接器或连接。
1. 选择**操作**，然后选择**删除**。
您还可以选择 **View details (查看详细信息)**，然后在连接器或连接详细信息页面上，选择 **Delete (删除)**。
1. 确认您要删除连接器或连接，方法是输入 **Delete**，然后选择 **Delete (删除)**。
删除某个连接器时，还应删除为该连接器创建的所有连接。
使用已删除连接的任务将不再运行。您可以编辑任务以使用其他数据存储，也可以删除任务。有关如何删除任务的信息，请参阅[删除任务](managing-jobs-chapter.md#delete-jobs)。
如果您删除连接器，此操作不会取消 AWS Marketplace 中该连接器的订阅。要删除已删除连接器的订阅，请按[取消连接器的订阅](#cancel-subscription)中的说明操作。
## 取消连接器的订阅
从 AWS Glue Studio 中删除连接和连接器后，如果您不再需要该连接器，您可以在 AWS Marketplace 中取消订阅。
**注意**
如果您取消对连接器的订阅，则不会从您的账户中删除连接器或连接。使用该连接器和相关连接的任务将无法再使用该连接器，并且会失效。
在您从 AWS Marketplace 中取消订阅或重新订阅之前，您应先删除与该 AWS Marketplace 产品关联的现有连接和连接器。
**取消 AWS Marketplace 中连接器的订阅**
1. 登录 AWS Marketplace，然后通过以下网址打开 控制台：[https://console.aws.amazon.com/marketplace](https://console.aws.amazon.com/marketplace)。
1. 选择 **Manage subscriptions (选择订阅)**。
1. 在 **Manage subscriptions (管理订阅)** 页面上，选择要取消的连接器订阅旁边的 **Manage (管理)**。
1. 依次选择 **Actions (操作)** 和 **Delete Subscriptions (删除订阅)**。
1. 选中此复选框，确认正在运行的实例会向您的账户收取费用，然后选择 **Yes, cancel subscription (是，取消订阅)**。
# 开发自定义连接器
您可以编写从数据存储中读取数据或向数据存储写入数据的代码，并将数据格式化以用于 AWS Glue Studio 任务。您可以为 Spark、Athena 和 JDBC 数据存储创建连接器。GitHub 上发布的示例代码概述了您需要实现的基本接口。
您需要用于创建连接器代码的本地开发环境。您可以使用任意 IDE，甚至只使用命令行编辑器来编写连接器。开发环境示例包括：
+ 具有本地 AWS Glue ETL Maven 库的本地 Scala 环境，正如《AWS Glue 开发人员指南》**中的[使用 Scala 本地开发](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-libraries.html#develop-local-scala)所述。
+ IntelliJ IDE，可从 [https://www.jetbrains.com/idea/](https://www.jetbrains.com/idea/) 下载 IDE。
**Topics**
+ [开发 Spark 连接器](#code-spark-connector)
+ [开发 Athena 连接器](#code-athena-connector)
+ [开发 JDBC 连接器](#code-jdbc-connector)
+ [将自定义连接器与 AWS Glue Studio 结合使用的示例](#custom-connector-examples)
+ [为 AWS Marketplace 开发 AWS Glue 连接器](#code-marketplace-connector)
## 开发 Spark 连接器
您可以使用 Spark DataSource API V2（Spark 2.4）创建 Spark 连接器来读取数据。
**若要创建自定义 Spark 连接器**
按照 AWS Glue GitHub 示例库中的步骤开发 Spark 连接器，该库位于 [https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/development/Spark/README.md](https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/development/Spark/README.md)。
## 开发 Athena 连接器
您可以创建 Athena 连接器，供 AWS Glue 和 AWS Glue Studio 查询自定义数据源。
**若要创建自定义 Athena 连接器**
按照 AWS Glue GitHub 示例库中的步骤开发 Athena 连接器，该库位于 [https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/development/Athena](https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/development/Athena)。
## 开发 JDBC 连接器
您可以创建使用 JDBC 访问数据存储的连接器。
**创建自定义 JDBC 连接器**
1. 在本地开发环境中安装 AWS Glue Spark 运行时库。请参阅 AWS Glue GitHub 示例库中的说明，该库位于 [ https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/development/GlueSparkRuntime/README.md](https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/development/GlueSparkRuntime/README.md)。
1. 实施负责从数据源检索数据的 JDBC 驱动程序。请参阅适用于 Java SE 8 的 [Java 文档](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/)。
在您的代码内创建入口点，AWS Glue Studio 将其用于查找您的连接器。**Class name (类名称)** 字段应该是 JDBC 驱动程序的完整路径。
1. 借助连接器使用 `GlueContext` API 读取数据。用户可以在 AWS Glue Studio 控制台中添加更多输入选项，配置与数据源的连接（如有必要）。有关演示如何使用自定义 JDBC 连接器读取和写入 JDBC 数据库的代码示例，请参阅[自定义和 AWS Marketplace connectionType 值](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-connect.html#aws-glue-programming-etl-connect-market)。
## 将自定义连接器与 AWS Glue Studio 结合使用的示例
有关使用自定义连接器的示例，您可以参考以下博客：
+ [为带有 AWS Glue 的数据存储开发、测试和部署自定义连接器](https://aws.amazon.com/blogs/big-data/developing-testing-and-deploying-custom-connectors-for-your-data-stores-with-aws-glue/)
+ Apache Hudi：[使用 AWS Glue 自定义连接器写入 Apache Hudi 表](https://aws.amazon.com/blogs/big-data/writing-to-apache-hudi-tables-using-aws-glue-connector/)
+ Google BigQuery：[使用 AWS Glue 自定义连接器，将数据从 Google BigQuery 迁移到 Amazon S3](https://aws.amazon.com/blogs/big-data/migrating-data-from-google-bigquery-to-amazon-s3-using-aws-glue-custom-connectors/)
+ Snowflake（JDBC）：[使用 Snowflake 和 AWS Glue 执行数据转换](https://aws.amazon.com/blogs/big-data/performing-data-transformations-using-snowflake-and-aws-glue/)
+ SingleStore：[使用 SingleStore 和 AWS Glue 构建快速 ETL](https://aws.amazon.com/blogs/big-data/building-fast-etl-using-singlestore-and-aws-glue/)
+ Salesforce：[使用 CData JDBC 自定义连接器和 AWS Glue 将 Salesforce 数据提取到 Amazon S3](https://aws.amazon.com/blogs/big-data/ingest-salesforce-data-into-amazon-s3-using-the-cdata-jdbc-custom-connector-with-aws-glue) -
+ MongoDB：[使用 Amazon DocumentDB（与 MongoDB 兼容）和 MongoDB 构建 AWS Glue Spark ETL 任务](https://aws.amazon.com/blogs/big-data/building-aws-glue-spark-etl-jobs-using-amazon-documentdb-with-mongodb-compatibility-and-mongodb/)
+ Amazon Relational Database Service（Amazon RDS）：[使用您自己的适用于 Amazon RDS 的 JDBC 驱动程序构建 AWS Glue Spark ETL 任务 ](https://aws.amazon.com/blogs/big-data/building-aws-glue-spark-etl-jobs-by-bringing-your-own-jdbc-drivers-for-amazon-rds/)
+ MySQL（JDBC）：[https://github.com/aws-samples/aws-glue-samples/blob/master/GlueCustomConnectors/development/Spark/SparkConnectorMySQL.scala](https://github.com/aws-samples/aws-glue-samples/blob/master/GlueCustomConnectors/development/Spark/SparkConnectorMySQL.scala)
## 为 AWS Marketplace 开发 AWS Glue 连接器
作为 AWS 合作伙伴，您可以创建自定义连接器并将其上载到 AWS Marketplace 以销售给 AWS Glue 客户。
开发连接器代码的过程与自定义连接器相同，但上载和验证连接器代码的过程更为详细。请参阅 GitHub 网站上[为 AWS Marketplace 创建连接器](https://github.com/aws-samples/aws-glue-samples/tree/master/GlueCustomConnectors/marketplace/publishGuide.pdf)中的说明。
# AWS Glue Studio 中连接器和连接的使用限制
当您从 AWS Marketplace 使用自定义连接器或连接器，请注意以下限制：
+ 为自定义连接器创建的连接不支持 testConnection API。
+ 自定义连接器不支持数据目录连接密码加密。
+ 如果为使用 JDBC 连接器的数据源节点指定筛选条件谓语，则无法使用任务书签。
+ 不支持在 AWS Glue Studio 用户界面之外创建 Marketplace 连接。
# 测试 AWS Glue 连接
作为最佳实践，在您在 ETL 作业中使用 AWS Glue 连接之前，最好先使用 AWS Glue 控制台测试该连接。AWS Glue 会使用连接中的参数来确认该连接是否可以访问数据存储，并报告任何错误。有关 AWS Glue 连接的信息，请参阅[连接到数据](glue-connections.md)。
**测试 AWS Glue 连接**
1. 登录 AWS 管理控制台，然后打开 AWS Glue 控制台，网址为：[https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)。
1. 在导航窗格的 **Data Catalog** 下，选择**连接**。您也可以在导航窗格中选择 **Data Catalog** 上方的**数据连接**。
1. 在**连接**中选中所需连接旁边的复选框，然后选择**操作**。在下拉菜单中，选择**测试连接**。
1. 在 **Test connection (测试连接)** 对话框中，选择一个角色，或选择 **Create IAM role (创建 IAM 角色)**，以转到 AWS Identity and Access Management（IAM）控制台并创建一个新角色。该角色必须拥有相关数据存储的权限。
1. 选择**确认**。
开始测试，测试可能需要几分钟才能完成。如果测试失败，请选择**故障排除**以查看解决问题的步骤。
1. 选择**日志**查看 CloudWatch 中的日志。您必须拥有所需的 IAM 权限才能查看日志。有关更多信息，请参阅*《Amazon CloudWatch Logs 用户指南》*中的 [AWS Managed (Predefined) Policies for CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-identity-based-access-control-cwl.html#managed-policies-cwl)。
# 将 AWS 调用配置为通过 VPC
特殊作业参数 `disable-proxy-v2` 将允许您将调用通过 VPC 路由到服务，如 Amazon S3、CloudWatch 和 AWS Glue。默认情况下，AWS Glue 将使用本地代理通过 AWS Glue VPC 发送流量，以从 Amazon S3 下载脚本和库；向 CloudWatch 发送请求，以发布日志和指标；以及向 AWS Glue 发送请求，以访问数据目录。即使您的 VPC 没有将正确的路由配置到其他 AWS 服务，如 Amazon S3、CloudWatch 和 AWS Glue，此代理也会允许任务正常运行。AWS Glue 现在为您提供参数，以关闭此行为。有关更多信息，请参阅 [AWS Glue 所使用的作业参数](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-glue-arguments.html)。AWS Glue 将继续使用本地代理发布您的 AWS Glue 作业的 CloudWatch 日志。
**注意**
使用 AWS Glue 版本 2.0 及更高版本的 AWS Glue 任务支持此功能。使用此功能时，您需要确保您的 VPC 已通过 NAT 或服务 VPC 终端节点将路由配置到 Simple Storage Service (Amazon S3)。
已弃用的任务参数 `disable-proxy` 仅会将您的调用路由到 Amazon S3，以便通过 VPC 下载脚本和库。建议改用新参数 `disable-proxy-v2`。
**示例用法**
创建带有 `disable-proxy-v2` 的 AWS Glue 任务：
```
aws glue create-job \
--name no-proxy-job \
--role GlueDefaultRole \
--command "Name=glueetl,ScriptLocation=s3://my-bucket/glue-script.py" \
--connections Connections="traffic-monitored-connection" \
--default-arguments '{"--disable-proxy-v2" : "true"}'
```
# 在 VPC 中连接到 JDBC 数据存储
通常，您在 Amazon Virtual Private Cloud（Amazon VPC）内部创建资源，以便这些资源不能通过公共 Internet 访问。默认情况下，AWS Glue 无法访问 VPC 中的资源。要让 AWS Glue 能够访问 VPC 中的资源，您必须提供包括 VPC 子网 ID 和安全组 ID 在内的其他 VPC 特定的配置信息。AWS Glue 使用此信息设置[弹性网络接口](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_ElasticNetworkInterfaces.html)，此接口可让您的函数安全连接到私有 VPC 中的其他资源。
使用 VPC 端点时，请将其添加到您的路由表中。有关更多信息，请参阅 [Creating an interface VPC endpoint for AWS Glue](https://docs.aws.amazon.com/glue/latest/dg/vpc-interface-endpoints.html#vpc-endpoint-create) 和 [先决条件](connection-S3-VPC.md#connection-S3-VPC-prerequisites)。
在 Data Catalog 中使用加密时，请创建 KMS 接口端点并将其添加到您的路由表中。有关更多信息，请参阅 [Creating a VPC endpoint for AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html#vpce-create-endpoint)。
## 使用弹性网络接口访问 VPC 数据
当 AWS Glue 连接到 VPC 中的 JDBC 数据存储时，AWS Glue 会在您的账户中创建弹性网络接口（使用前缀 `Glue_`）以访问您的 VPC 数据。只要此网络接口连接到 AWS Glue，您就不能删除它。作为创建弹性网络接口的一部分，AWS Glue 将一个或多个安全组关联到它。要使 AWS Glue 创建网络接口，与该资源关联的安全组必须允许具有源规则的入站访问。此规则包含与资源相关联的安全组。这将为具有相同安全组的数据存储提供弹性网络接口访问。
要允许 AWS Glue 与其组件通信，请为所有 TCP 端口指定一个具有自引用入站规则的安全组。通过创建自引用规则，您可以将源限制为 VPC 中的同一安全组，而不将其对所有网络打开。VPC 的默认安全组可能已经为 `ALL Traffic` 设置了自引用入站规则。
您可以在 Amazon VPC 控制台中创建规则。要通过 AWS 管理控制台 更新规则设置，请导航到 VPC 控制台（[https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)），然后选择相应的安全组。为 `ALL TCP` 指定入站规则，使其源具有相同的安全组名称。有关组规则的更多信息，请参阅[您的 VPC 的安全组](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html)。
每个弹性网络接口都会从您指定子网中的 IP 地址范围分到一个私有 IP 地址。网络接口不会分到任何公有 IP 地址。AWS Glue 需要 Internet 访问（例如，访问没有 VPC 终端节点的 AWS 服务）。您可以在 VPC 中配置网络地址转换（NAT）实例，也可以使用 Amazon VPC NAT 网关。有关更多信息，请参阅《Amazon VPC 用户指南》**中的 [NAT 网关](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)。您不能直接使用连接到 VPC 的 Internet 网关作为子网路由表中的路由，因为这需要网络接口具有公有 IP 地址。
VPC 网络属性 `enableDnsHostnames` 和 `enableDnsSupport` 必须设置为 true。有关更多信息，请参阅[将 DNS 与您的 VPC 一起使用](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html)。
**重要**
不要将数据存储在未接入 Internet 的公有子网或私有子网中。相反，仅通过 NAT 实例或 Amazon VPC NAT 网关将它附加到接入了 Internet 的私有子网。
## 弹性网络接口属性
要创建弹性网络接口时，您必须提供以下属性：
**VPC**
包含您的数据存储的 VPC 的名称。
**子网**
包含您的数据存储的 VPC 中的子网。
**安全组**
与您的数据存储关联的安全组。AWS Glue 将这些安全组与连接到您的 VPC 的子网的弹性网络接口关联。要允许 AWS Glue 组件进行通信并阻止来自其他网络的访问，则至少必须有一个选定的安全组指定针对所有 TCP 端口的自引用入站规则。
有关使用 Amazon Redshift 管理 VPC 的信息，请参阅[在 Amazon Virtual Private Cloud（VPC）中管理集群](https://docs.aws.amazon.com/redshift/latest/mgmt/managing-clusters-vpc.html)。
有关使用 Amazon Relational Database Service（Amazon RDS）管理 VPC 的信息，请参阅[在 VPC 中使用 Amazon RDS 数据库实例](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_VPC.WorkingWithRDSInstanceinaVPC.html)。
# 使用 MongoDB 或 MongoDB Atlas 连接
为 MongoDB 或 MongoDB Atlas 创建连接后，您可以在 ETL 作业中使用该连接。您可以在 AWS Glue Data Catalog 中创建一个表，并为该表的 `connection` 属性指定 MongoDB Atlas 连接。
AWS Glue 在 MongoDB 连接中存储您的连接 `url` 和凭证。连接 URI 格式如下：
+ 对于 MongoDB：mongodb://host:port/database。主机可以是主机名、IP 地址或 UNIX 域套接字。如果连接字符串未指定端口，则使用默认的 MongoDB 端口 27017。
+ 对于 MongoDB Atlas：mongodb\$1srv://server.example.com/database。主机可以是后面对应于 DNS SRV 记录的主机名。SRV 格式不需要端口，将使用默认的 MongoDB 端口 27017。
此外，您可以在作业脚本中指定选项。有关更多信息，请参阅 [MongoDB 连接选项参考](aws-glue-programming-etl-connect-mongodb-home.md#aws-glue-programming-etl-connect-mongodb)。
# 使用 VPC 终端节点网络爬取 Amazon S3 数据存储
出于安全、审计或控制目的，您可能希望您的 Amazon S3 数据存储或 Amazon S3 支持的数据目录表只能通过 Amazon Virtual Private Cloud 环境（Amazon VPC）访问。本主题介绍如何使用 `Network` 连接类型在 VPC 终端节点中创建和测试与 Amazon S3 数据存储或 Amazon S3 支持的数据目录表的连接。
执行以下任务以在数据存储中运行爬网程序：
+ [先决条件](#connection-S3-VPC-prerequisites)
+ [创建到 Amazon S3 的连接](#connection-S3-VPC-create-connection)
+ [测试 Amazon S3 的连接](#connection-S3-VPC-test-connection)
+ [为 Amazon S3 数据存储创建爬网程序](#connection-S3-VPC-create-crawler)
+ [运行爬网程序](#connection-S3-VPC-run-crawler)
## 先决条件
检查您是否满足设置 Amazon S3 数据存储或 Amazon S3 支持的数据目录表以通过 Amazon Virtual Private Cloud 环境（Amazon VPC）访问的先决条件。
+ 已配置的 VPC。例如：vpc-01685961063b0d84b。有关更多信息，请参阅《Amazon VPC 用户指南》**中的 [Amazon VPC 入门](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-getting-started.html)。
+ 附加到 VPC 的 Amazon S3 端点。例如：vpc-01685961063b0d84b。有关更多信息，请参阅《Amazon VPC 用户指南》**中的 [Amazon S3 端点](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-s3.html)。
![\[附加到 VPC 的 Amazon S3 端点示例。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/network_s3_vpc_s3_endpoint_attached.png)
+ 指向 VPC 终端节点的路由条目。例如，VPC endpoint(vpce-0ec5da4d265227786) 使用的路由表中的 vpce-0ec5da4d265227786。
![\[指向 VPC 终端节点的路由条目示例。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/network_s3_vpc_route_entry.png)
+ 附加到 VPC 的网络 ACL 允许流量。
+ 附加到 VPC 的安全组允许流量。
## 创建到 Amazon S3 的连接
通常，您在 Amazon Virtual Private Cloud（Amazon VPC）内部创建资源，以便这些资源不能通过公共 Internet 访问。默认情况下，AWS Glue 无法访问 VPC 中的资源。要让 AWS Glue 能够访问 VPC 中的资源，您必须提供包括 VPC 子网 ID 和安全组 ID 在内的其他 VPC 特定的配置信息。要创建 `Network` 连接，您需要指定以下信息：
+ VPC ID
+ VPC 内的子网
+ 安全组
设置 `Network` 连接
1. 选择 AWS Glue 控制台导航窗格中的 **Add connection (添加连接)**。
1. 输入连接名称，选择 **Network (网络)** 作为连接类型。选择**下一步**。
![\[选择连接类型。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/network_s3_vpc_add_network_1.png)
1. 配置 VPC、子网和安全组信息。
+ VPC：选择包含您的数据存储的 VPC 名称。
+ 子网：选择 VPC 内的子网。
+ 安全组：选择允许访问 VPC 中数据存储的一个或多个安全组。
![\[选择连接类型。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/network_s3_vpc_add_network_2.png)
1. 选择**下一步**。
1. 验证连接信息并选择 **Finish (完成)**。
![\[选择连接类型。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/network_s3_vpc_add_network_3.png)
## 测试 Amazon S3 的连接
创建 `Network` 连接后，您可以在 VPC 终端节点中测试 Amazon S3 数据存储的连接。
测试连接时可能会发生以下错误：
+ INTERNET CONNECTION ERROR：表示互联网连接问题
+ INVALID BUCKET ERROR：表示 Amazon S3 存储桶存在问题
+ S3 CONNECTION ERROR：表示未能连接到 Amazon S3
+ INVALID CONNECTION TYPE：表示连接类型不具有预期值 `NETWORK`
+ INVALID CONNECTION TEST TYPE：表示网络连接测试类型存在问题
+ INVALID TARGET：表示未正确指定 Amazon S3 存储桶
测试 `Network` 连接：
1. 选择 AWS Glue 控制台中的 **Network (网络)** 连接。
1. 选择 **Test connection (测试连接)**。
1. 选择您在上一步中创建的 IAM 角色并指定 Amazon S3 存储桶。
1. 选择 **Test connection (测试连接)**，开始测试。显示结果可能需要一些时间。
![\[测试连接。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/network_s3_vpc_test_network.png)
如果收到错误，请检查以下几点：
+ 为所选角色提供正确的权限。
+ 提供了正确的 Amazon S3 存储桶。
+ 安全组和网络 ACL 允许所需的传入和传出流量。
+ 您指定的 VPC 已连接到 Amazon S3 VPC 终端节点。
成功测试连接后，您便可创建爬网程序。
## 为 Amazon S3 数据存储创建爬网程序
现在，您可以创建一个爬网程序来指定您已创建的 `Network` 连接。有关创建爬网程序的更多详细信息，请参阅[配置爬网程序](define-crawler.md)。
1. 首先在 AWS Glue 控制台上的导航窗格中选择 **Crawlers (爬网程序)**。
1. 选择 **添加爬网程序**。
1. 指定爬网程序名称，选择 **Next (下一步)**。
1. 当询问数据源时，选择 **S3**，并指定 Amazon S3 存储桶前缀和您先前创建的连接。
![\[测试连接。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/network_s3_vpc_add_crawler_1.png)
1. 如果需要，请在同一网络连接上添加另一个数据存储。
1. 选择 IAM 角色。IAM 角色必须允许访问 AWS Glue 服务和 Amazon S3 存储桶。有关更多信息，请参阅 [配置爬网程序](define-crawler.md)。
![\[测试连接。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/network_s3_vpc_add_crawler_2.png)
1. 定义爬网程序的计划。
1. 在数据目录中选择一个现有数据库或创建一个新的数据库条目。
![\[测试连接。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/network_s3_vpc_add_crawler_3.png)
1. 完成剩余的设置。
## 为 Amazon S3 支持的数据目录表创建网络爬取程序
现在，您可以创建指定您已创建 `Network` 连接的爬取程序和目录源类型。有关创建爬网程序的更多详细信息，请参阅[配置爬网程序](define-crawler.md)。
1. 首先在 AWS Glue 控制台上的导航窗格中选择 **Crawlers (爬网程序)**。
1. 选择 **添加爬网程序**。
1. 指定爬网程序名称，选择 **Next (下一步)**。
1. 当询问网络爬取程序源类型时，选择**现有目录表**，然后指定要从可用表列表中网络爬取的现有目录表。
![\[选择网络爬取源类型。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/catalog-vpc-1.png)
1. 选择 IAM 角色。IAM 角色必须允许访问 AWS Glue 服务和 Amazon S3 存储桶。有关更多信息，请参阅 [配置爬网程序](define-crawler.md)。
1. 定义爬网程序的计划。
1. 在数据目录中选择一个现有数据库或创建一个新的数据库条目。
1. 完成剩余的设置并查看步骤。
![\[选择网络爬取程序源类型。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/catalog-vpc-2.png)
## 运行爬网程序
运行您的爬网程序。
![\[按需运行您的爬网程序。\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/network_s3_vpc_s3_endpoint_run_crawler.png)
## 问题排查
对于与使用 VPC 网关的 Amazon S3 存储桶相关的故障排除，请参阅[为什么我无法使用网关 VPC 终端节点连接到 S3 存储桶？](https://aws.amazon.com/premiumsupport/knowledge-center/connect-s3-vpc-endpoint/)
# 使用由 AWS Lake Formation 保护的数据
## 完整的表访问权限
AWS Glue 支持为由 AWS Lake Formation 保护的表启用全表访问（FTA），从而让 ETL 作业可以使用完全的表权限读写数据。
### 先决条件
+ 适当的 IAM 角色和权限
+ 为您的数据目录配置的 AWS Lake Formation
+ 兼容的表类型（Hive 或 Iceberg）
### 重要注意事项
#### 所需的权限
+ `lakeformation:GetDataAccess` IAM 权限
+ AWS Lake Formation 表权限
+ Amazon S3 存储桶访问权限
#### 支持的表类型
+ Hive 表
+ Iceberg 表
#### 限制
+ 不兼容 Spark Streaming
+ 不能与精细访问控制模式同时使用
+ 不支持 Delta 或 Hudi 表
### 最佳实践
1. 务必要在执行作业前正确配置 IAM 角色
1. 在开发环境中测试访问权限
1. 监控作业执行日志，以识别与权限相关的问题
1. 保存清晰的访问模式记录
### 故障排除
常见问题包括：
+ 缺少 IAM 权限
+ AWS Lake Formation 配置不正确
+ 表类型兼容性问题
有关完整的设置说明和配置详细信息，请参阅[将 AWS Lake Formation 与全表访问结合使用](https://docs.aws.amazon.com/emr/latest/EMR-Serverless-UserGuide/lake-formation-unfiltered-access.html)。
# 解决 AWS Glue 中的连接问题
当 AWS Glue 爬网程序或任务使用连接属性访问数据存储时，您在尝试连接时可能会遇到错误。AWS Glue 在您指定的 Virtual Private Cloud（VPC）和子网中创建弹性网络接口时，会在子网中使用私有 IP 地址。在 连接中指定的安全组应用于每个弹性网络接口上。请检查安全组是否允许出站访问，以及是否允许连接到数据库集群。
此外，Apache Spark 需要驱动程序和执行器节点之间的双向连接。其中一个安全组需要在所有 TCP 端口上允许入口规则。通过使用自引用安全组将安全组的源限制为自身，可以防止它对世界开放。
以下是您为解决连接问题可以采取的一些典型操作：
+ 检查连接的端口地址。
+ 检查连接或密钥中的用户名和密码字符串。
+ 对于 JDBC 数据存储，验证其是否允许传入连接。
+ 验证是否可以在您的 VPC 中访问您的数据存储。
+ 如果您使用 AWS Secrets Manager 存储连接凭证，请确保 AWS Glue 的 IAM 角色拥有访问密钥的权限。有关更多信息，请参阅《AWS Secrets Manager 用户指南》中的[示例：检索密钥值的权限](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_examples.html#auth-and-access_examples_read)。根据网络设置，您可能还需要创建一个 VPC 端点，以在 VPC 与 Secrets Manager 之间建立私有连接。有关更多信息，请参阅[使用 AWS Secrets Manager VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)。
# 教程：使用 AWS Glue Connector for Elasticsearch
Elasticsearch 是一个流行的开源搜索和分析引擎，其用例包括日志分析、实时应用程序监控和点击流分析等。您可以在 AWS Glue Studio 中配置 AWS Glue Connector for Elasticsearch，从而将 OpenSearch 用作提取、转换、加载（ETL）任务的数据存储。此连接器在 [AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-v5ygernwn2gb6) 中免费提供。
**注意**
[AWS Marketplace Elasticsearch Spark Connector](https://aws.amazon.com/marketplace/pp/B08PPT2V5J) 已被弃用。请改用 [AWS Glue Connector for Elasticsearch ](https://aws.amazon.com/marketplace/pp/prodview-v5ygernwn2gb6)。
在本教程中，我们将展示如何以最少的步骤连接到您的 Amazon OpenSearch Service 节点。
**Topics**
+ [先决条件](#tutorial-prerequisites)
+ [步骤 1：（可选）为您的 OpenSearch 集群信息创建 AWS 密钥](#tutorial-step1)
+ [步骤 2：订阅连接器](#tutorial-step2)
+ [步骤 3：激活 AWS Glue Studio 并创建连接](#tutorial-step3)
+ [步骤 4：为您的 ETL 任务配置 IAM 角色](#tutorial-step4)
+ [步骤 5：创建使用 OpenSearch 连接的任务](#tutorial-step5)
+ [步骤 6：运行任务](#tutorial-step6)
## 先决条件
要使用本教程，您必须具备以下内容：
+ 对 AWS Glue Studio 的访问权限
+ 对 AWS 云中访问 OpenSearch 集群的访问权限
+ （可选）对 AWS Secrets Manager 的访问权限。
## 步骤 1：（可选）为您的 OpenSearch 集群信息创建 AWS 密钥
要安全地存储和使用您的连接凭证，请将您的凭证保存在 AWS Secrets Manager 中。您创建的密钥将在本教程稍后的连接中使用。凭证键值对将作为普通连接选项注入 AWS Glue Connector for Elasticsearch。
有关创建密钥的更多信息，请参阅 [使用、创建和管理密钥 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) 于 *《AWS Secrets Manager 用户指南》*。
**创建 AWS 密钥**
1. 登录 [AWS Secrets Manager 控制台](https://console.aws.amazon.com/secretsmanager/)。
1. 在服务介绍页面或**密钥**列表页面上，选择 **Store a new secret (存储新密钥)**。
1. 在 **Store a new secret**（存储新密钥）页上，选择 **Other type of secret**（其他密钥类型）。此选项意味着您必须提供您的密钥的结构和详细信息。
1. 为 OpenSearch 集群用户名添加 **Key**（密钥）和 **Value**（值）对。例如：
`es.net.http.auth.user`：*username*（用户名）
1. 选择 **\$1 Add row**（\$1 添加行），然后为密码输入另一个键/值对。例如：
`es.net.http.auth.pass`：*password*
1. 选择 **Next**（下一步）。
1. 输入密钥名称。例如：**my-es-secret**。您可以选择性地添加描述。
记录本教程稍后使用的密钥名称，然后选择 **Next**（下一步）。
1. 再次选择 **Next**（下一步），然后选择 **Store**（存储）创建密钥。
### 后续步骤
[步骤 2：订阅连接器](#tutorial-step2)
## 步骤 2：订阅连接器
[AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-v5ygernwn2gb6#pdp-pricing) 中免费提供 AWS Glue Connector for Elasticsearch。
**在 AWS Marketplace 中订阅 AWS Glue Connector for Elasticsearch**
1. 如果您尚未配置 AWS 账户使用 License Manager，请执行以下操作：
1. 访问 [https://console.aws.amazon.com/license-manager](https://console.aws.amazon.com/license-manager)，打开 AWS License Manager 控制台。
1. 选择 **Create customer managed license (创建客户托管式许可证)**。
1. 在 **IAM permissions (one-time setup) (IAM 权限 (一次性设置))** 窗口中，选择 **I grant AWS License Manager the required permissions (我为 Amazon License Manager 授予所需的权限)**，然后选择 **Grant permissions (授予权限)**。
如果未看到此窗口，则表示您已配置所需的权限。
1. 请访问 [https://console.aws.amazon.com/gluestudio/](https://console.aws.amazon.com/gluestudio/) 打开 AWS Glue Studio 控制台。
1. 在 AWS Glue Studio 控制台，展开菜单图标（![\[\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/images/nav-menu-icon.png)），然后在导航窗格中选择 **Connectors (连接器)**。
1. 在 **Connectors (连接器)** 页面上，选择 **Go to AWS Marketplace (转到 Amazon Web Services Marketplace)**。
1. 在 AWS Marketplace 的 **Search AWS Glue Studio products**（搜索产品）部分中，在搜索字段中输入 **AWS Glue Connector for Elasticsearch**，然后按 Enter 键。
1. 选择连接器的名称，**AWS Glue Connector for Elasticsearch**。
1. 在连接器的产品页面上，使用选项卡查看有关连接器的信息。准备好继续使用后，选择 **Continue to Subscribe (继续订阅)**。
1. 查看软件的使用条款。单击 **Accept Terms**（接受条款）。
1. 订阅过程完成后，您将看到一条通知：“Thank you for subscribing to this product\$1 You can now configure your software.”（感谢您订阅此产品！现在您可以配置软件。） 横幅上方将是按钮 **Continue to Configuration**（继续配置）。选择**继续配置**。
1. 在 **Configure this software**（配置此软件）页面上，选择“Fulfillment”（执行）选项。您可以选择 AWS Glue 1.0/2.0 或 AWS Glue 3.0。然后选择 **Continue to Launch**（继续启动）。
### 后续步骤
[步骤 3：激活 AWS Glue Studio 并创建连接](#tutorial-step3)
## 步骤 3：激活 AWS Glue Studio 并创建连接
在您选择 **Continue to Launch (继续启动)** 后，您可以在 AWS Marketplace 中看到 **Launch this software (启动此软件)** 页面。您在 AWS Glue Studio 中使用链接激活连接器后，创建连接。
**要在 AWS Glue Studio 中部署连接器并创建连接**
1. 在 AWS Marketplace 控制台的 **Launch this software (启动此软件)** 页面上，选择 **Usage Instructions (使用说明)**，然后选择在窗口中显示的链接。
您的浏览器将重新定向到 AWS Glue Studio 控制台 **Create marketplace connection (创建 Marketplace 连接)** 页面。
1. 为连接输入名称。例如：**my-es-connection**。
1. 在 **Connection access (连接访问)** 部分，为 **Connection credential type (连接凭证类型)** 选择 **User name and password (用户名和密码)**。
1. 对于 **AWS secret (Amazon 密钥)**，输入您的密钥名称。例如：**my-es-secret**。
1. 在 **Network options**（网络选项）部分中，输入 VPC 信息，以连接到 OpenSearch 集群。
1. 选择 **Create connection and activate connector (创建连接并激活连接器)**。
### 后续步骤
[步骤 4：为您的 ETL 任务配置 IAM 角色](#tutorial-step4)
## 步骤 4：为您的 ETL 任务配置 IAM 角色
在创建 AWS Glue ETL 任务时，您可以指定 AWS Identity and Access Management（IAM）角色以供任务使用。角色必须授予对任务使用的所有资源的访问权限，包括 Amazon S3（任何源、目标、脚本、驱动程序文件和临时目录）以及 AWS Glue Data Catalog 对象。
AWS Glue ETL 任务所担任的 IAM 角色还必须具有对在上一部分创建的密钥的访问权限。预设情况下，亚马逊云科技托管式角色 `AWSGlueServiceRole` 无法访问该密钥。要设置密钥的访问控制，请参阅 [AWS Secrets Manager 的身份验证和访问控制](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access.html)以及[限制对特定密钥的访问](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html#permissions_grant-limited-resources)。
**要为您的 ETL 任务配置 IAM 角色**
1. 配置[审核 ETL 任务所需的 IAM 权限](getting-started-min-privs-job.md)中所述的权限。
1. 配置如[使用连接器所需的权限](getting-started-min-privs-job.md#getting-started-min-privs-connectors)中所述的使用 AWS Glue Studio 连接器时所需的其他权限。
### 后续步骤
[步骤 5：创建使用 OpenSearch 连接的任务](#tutorial-step5)
## 步骤 5：创建使用 OpenSearch 连接的任务
为您的 ETL 任务创建角色后，您可以在 AWS Glue Studio 中创建一个任务，改任务使用 Open Spark ElasticSearch 的连接和连接器。
如果您的任务在 Amazon Virtual Private Cloud（Amazon VPC）中运行，请确保 VPC 配置正确。有关更多信息，请参阅 [为 ETL 任务配置 VPC](getting-started-vpc-config.md)。
**要创建使用 Elasticsearch Spark Connector 的任务**
1. 在 AWS Glue Studio 中，选择 **Connectors**（连接器）。
1. 在 **Your connections (您的连接)** 列表中，选定您刚才创建的连接并选择 **Create job (创建任务)**。
1. 在可视任务编辑器中，选择数据源节点。在右侧 **Data source properties - Connector (数据源属性 – 连接器)** 选项卡上，配置连接器的其他信息。
1. 选择 **Add schema (添加架构)**，然后输入数据源中的数据集架构。连接不使用存储在数据目录中的表，这意味着 AWS Glue Studio 不了解数据架构。您必须手动提供此架构信息。有关如何使用架构编辑器的说明，请参阅[编辑自定义转换节点的架构](transforms-custom.md#transforms-custom-editschema)。
1. 展开 **Connection options (连接选项)**。
1. 选择 **Add new option (添加新选项)**，然后输入尚未在 AWS 密钥中输入的连接器所需的信息：
+ **es.nodes**: https://**
+ **es.port**: 443
+ **path**: test
+ **es.nodes.wan.only.**: true
有关这些连接选项的说明，请参阅：[https://www.elastic.co/guide/en/elasticsearch/hadoop/current/configuration.html](https://www.elastic.co/guide/en/elasticsearch/hadoop/current/configuration.html)。
1. 将目标节点添加至图表中。
您的数据目标可以是 Amazon S3，也可以使用 AWS Glue Data Catalog 或连接器的信息将数据写入其他位置。例如，您可以使用数据目录表将数据库写入 Amazon RDS，也可以将连接器用作数据目标来写入 AWS Glue 中不支持的数据存储。
如果为数据目标选择连接器，则您必须选择为该连接器创建的连接。此外，如果连接器提供程序需要，则您必须添加选项以向连接器提供其他信息。如果您使用包含 AWS 密钥信息的连接，则无需在连接选项中提供用户名和密码身份验证。
1. （可选）添加如[使用 AWS Glue 托管转换转换数据](edit-jobs-transforms.md)中所述的其他数据源和一个或多个转换节点。
1. 从步骤 3 开始，配置如[修改任务属性](managing-jobs-chapter.md#edit-jobs-properties)中所述的任务属性，然后保存任务。
### 后续步骤
[步骤 6：运行任务](#tutorial-step6)
## 步骤 6：运行任务
保存任务后，您可以运行任务来执行 ETL 操作。
**运行您为 AWS Glue Connector for Elasticsearch 创建的任务**
1. 使用 AWS Glue Studio 控制台，在可视编辑器页面上，选择 **Run (运行)**。
1. 在成功横幅中，选择 **Run Details (运行详细信息)**，也可以选择可视化编辑器的 **Runs (运行)** 选项卡查看有关任务运行的信息。