本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 連線至 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 支援智慧資料表，如下所示：
**支援作為來源？**
是。您可以使用 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
您必須先符合下列要求，才能使用 從 Smartsheet AWS Glue 傳輸：
## 最低需求
+ 您擁有一個帶有電子郵件和密碼的 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)。
若要設定 Smartsheet 連線：
1. 在 AWS Secrets Manager 中，建立包含下列詳細資訊的秘密：
對於客戶管理的連線應用程式，機密應包含以 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` 作為金鑰的連線應用程式消費者機密。
**注意**
必須在 AWS Glue中為每個連線建立機密。
1. 在 中 AWS Glue Studio，依照下列步驟在 **Data Connections 下建立連線**：
1. 選取**連線類型**時，請選取 Smartsheet。
1. 提供您要連線之 Smartsheet 的 `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. 選取您要用於此連線`secretName`的 AWS Glue ，以放置字符。
1. 如果想要使用您的網路，請選取網路選項。
1. 授予與您的 AWS Glue 任務相關聯的 IAM 角色讀取 的許可`secretName`。
# 從 Smartsheet 實體中讀取
**先決條件**
您要從中讀取的 `Smartsheet` 物件。請參閱以下支援的實體表格，以檢查可用實體。
**支援的實體**
| 實體 | 可以篩選 | 支援限制 | 支援排序依據 | 支援選取 \$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_tw/glue/latest/dg/smartsheet-reading-from-entities.html)
**具有動態中繼資料的實體：**
對於下列實體，Smartsheet 提供端點以動態擷取中繼資料，允許在資料類型層級擷取運算子支援。
| 實體 | 資料類型 | 支援的運算子 |
| --- | --- | --- |
| 工作表資料 | String | NA |
| 工作表資料 | Long | "=" |
| 工作表資料 | Integer | NA |
| 工作表資料 | DateTime | > |
**範例**
```
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`(String) - (必要) 用於讀取/寫入。Smartsheet 中的物件名稱。
+ `API_VERSION`(String) - (必要) 用於讀取/寫入。您想要使用的 Smartsheet Rest API 版本。例如，V2.0。
+ `INSTANCE_URL`(String) – (必要) 用於讀取。Smartsheet 執行個體 URL。
+ `SELECTED_FIELDS`(List) - 預設：empty(SELECT \$1)。用於讀取。您要為物件選取的資料欄。
+ `FILTER_PREDICATE`(String) - 預設：空白。用於讀取。其應該為 Spark SQL 格式。
+ `QUERY`(String) - 預設：空白。用於讀取。完整的 Spark SQL 查詢。
# 建立 Smartsheet 帳戶
1. 存取 [Smartsheet 註冊頁面](https://app.smartsheet.com/home)以註冊 Smartsheet 帳戶。
1. 選擇**建立帳戶**以建立新帳戶，或使用已註冊的 Google、Microsoft 或 Apple 帳戶登入。
1. 出現提示時，輸入工作電子郵件地址。
1. 選擇**繼續**，並視需要驗證您的身分。
1. 從 Smartsheet 中開啟確認電子郵件，然後選擇確認連結以驗證您的帳戶。
根據預設，您將會訂閱試驗計畫。
1. 在左下角，選擇**帳戶**圖示，然後選擇**新增授權/升級**以升級定價計劃。
**注意**
這是存取**事件報告**所必需的，其是**企業**計劃中的附加元件。
1. 在**企業**計劃下，選擇**聯絡我們**，向支援團隊請求帳戶升級。
1. 在支援請求表單中，提供必要的詳細資訊以及您升級該計劃的需求。
如此即完成 **Enterprise** 計劃升級。
**建立 `OAuth2.0` 憑證**
1. 升級帳戶的定價計劃以取得**開發人員工具**的存取權後，請存取 [Smartsheet 開發人員](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 不支援欄位型或記錄型分區。