# 连接到 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 中，无法按排序依据筛选。