# 连接到 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 供选择，避免响应大小超过允许的最大有效载荷大小。