# 连接到 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 不支持基于字段的分区或基于记录的分区。