本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Snowflake 連線
<a name="aws-glue-programming-etl-connect-snowflake-home"></a>

您可以使用 AWS Glue for Spark 在 Glue 4.0 AWS 和更新版本中讀取和寫入 Snowflake 中的資料表。您可以使用 SQL 查詢從 Snowflake 讀取。您可以使用三種方法之一連線至 Snowflake：基本身分驗證 （使用使用者名稱和密碼）、OAuth 身分驗證或金鑰對身分驗證。您可以透過 Glue Data AWS Secrets Manager 連線參考存放在 中的 Snowflake AWS 登入資料。Glue for Spark 的 Data Connection Snowflake AWS 登入資料與爬蟲程式的 Data Catalog Snowflake 登入資料分開存放。您必須選擇 `SNOWFLAKE` 類型連線，而不是設定為連線至 Snowflake 的 `JDBC` 類型連線。

如需有關 Snowflake 的詳細資訊，請參閱 [Snowflake 網站](https://www.snowflake.com/)。如需 Snowflake on 的詳細資訊 AWS，請參閱 [Amazon Web Services 上的 Snowflake Data Warehouse](https://aws.amazon.com/financial-services/partner-solutions/snowflake/)。

## 設定 Snowflake 連線
<a name="aws-glue-programming-etl-connect-snowflake-configure"></a>

透過網際網路連線至 Snowflake 資料庫沒有 AWS 先決條件。

或者，您可以執行下列組態，以使用 Glue AWS 管理您的連線憑證。

**使用 Glue AWS 管理您的連線憑證**

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*，以便進行下一個步驟。
   + 對於 OAuth 身分驗證：
     + 選取**鍵/值對**時，請使用 鍵為 *snowflakeUser* 建立對 `sfUser`
     + 選取**鍵/值對**時，請使用鍵為 *OAUTH\$1CLIENT\$1SECRET* 建立對 `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET`
   + 對於金鑰對身分驗證：
     + 選取**鍵/值對**時，請使用 鍵為 *snowflakeUser* 建立對 `sfUser`
     + 選取**金鑰/值對**時，請使用 金鑰為*私有金鑰*建立對 `pem_private_key`
   + 針對基本身分驗證：
     + 選取**鍵/值對**時，請使用 鍵為 *snowflakeUser* 建立對 `USERNAME`
     + 選取**鍵/值對**時，請使用 鍵為 *snowflakePassword* 建立對 `PASSWORD`
   + 選取**鍵值對**時，您可以為 Snowflake 倉儲提供索引鍵 `sfWarehouse`。
   + 選取**金鑰/值對**時，您可以使用對應的 Spark 屬性名稱作為金鑰，提供額外的 Snowflake 連線屬性。支援的屬性包括：
     + `sfDatabase` – Snowflake 資料庫名稱
     + `sfSchema` – Snowflake 結構描述名稱
     + `sfRole` – Snowflake 角色名稱

1. 在 AWS Glue Studio 主控台中，選擇**資料連線**，然後選擇建立連線來**建立連線**。請遵循連線精靈中的步驟完成程序：
   + 選取**資料來源**時，選取 Snowflake，然後選擇**下一步**。
   + 輸入連線詳細資訊，例如主機和連接埠。輸入主機 **Snowflake URL** 時，提供 Snowflake 執行個體的 URL。該 URL 通常使用 `account_identifier.snowflakecomputing.com` 格式的主機名稱。不過，URL 格式可能會因您的 Snowflake 帳戶類型 （例如 AWS，Azure 或 Snowflake 託管） 而有所不同。
   + 選取 IAM 服務角色時，從下拉式功能表中選擇。這是您帳戶中的 IAM 角色，如果指定 VPC，將用於存取 AWS Secrets Manager 和指派 IP。
   + 選取 **AWS 機密**時，請提供 *secretName*。

1. 在精靈的下一步中，設定 Snowflake 連線的屬性。

1. 在精靈的最後一個步驟中，檢閱您的設定，然後完成建立連線的程序。

對於在 Amazon VPC AWS 中託管於 的 Snowflake，您可能需要下列項目：
+ 您需要為 Snowflake 進行適當的 Amazon VPC 設定。如需有關如何設定 Amazon VPC 的詳細資訊，請參閱 Snowflake 文件中的 [AWS PrivateLink & Snowflake](https://docs.snowflake.com/en/user-guide/admin-security-privatelink)。
+ 您將需要適當的 Glue Amazon VPC AWS 組態。 [配置 AWS Glue (AWS PrivateLink) 的介面 VPC 端點 (AWS PrivateLink)](vpc-interface-endpoints.md)
+ 您將需要建立提供 Amazon VPC 連線資訊的 AWS Glue Data Catalog 連線 （除了定義 Snowflake 安全登入資料的 AWS Secrets Manager 秘密 ID 之外）。您的 URL 在使用時會變更 AWS PrivateLink，如上一個項目中連結的 Snowflake 文件所述。
+ 您需要任務組態，才能將資料目錄連線納入為**其他網路連線**。

## 從 Snowflake 資料表讀取
<a name="aws-glue-programming-etl-connect-snowflake-read"></a>

**先決條件：**您想要讀取的 Snowflake 資料表。您需要 Snowflake 資料表名稱 *tableName*。如果您的 Snowflake 使用者沒有預設的命名空間集，您將需要 Snowflake 資料庫名稱 *databaseName* 和結構描述名稱 *schemaName*。此外，如果您的 Snowflake 使用者沒有預設的倉儲集，您將需要倉儲名稱 *warehouseName*。若要選取要連線**的其他網路連線**，請使用 `connectionName` 參數。

```
snowflake_read = glueContext.create_dynamic_frame.from_options(
  connection_type="snowflake",
  connection_options={
        "connectionName": "connectionName",
        "dbtable": "tableName",
        "sfDatabase": "databaseName",
        "sfSchema": "schemaName",
        "sfWarehouse": "warehouseName",
    }
)
```

 此外，您可以使用 `autopushdown` 和 `query` 參數來讀取 Snowflake 資料表的一部分。這可能比在將結果載入 Spark 後篩選結果的方式更高效。考量一個範例，其中所有銷售額都存放在同一個資料表中，但您只需分析某個商店在假日的銷售額。如果該資訊存放在資料表中，則可以使用述詞下推來擷取結果，如下所示：

```
snowflake_node = glueContext.create_dynamic_frame.from_options(
    connection_type="snowflake",
    connection_options={
        "autopushdown": "on",
        "query": "select * from sales where store='1' and IsHoliday='TRUE'",
        "connectionName": "snowflake-glue-conn",
        "sfDatabase": "databaseName",
        "sfSchema": "schemaName",
        "sfWarehouse": "warehouseName",
    }
)
```

## 寫入 Snowflake 資料表
<a name="aws-glue-programming-etl-connect-snowflake-write"></a>

**先決條件：**您想要寫入的 Snowflake 資料庫。您需要最新的或所需的資料表名稱 *tableName*。如果您的 Snowflake 使用者沒有預設的命名空間集，您將需要 Snowflake 資料庫名稱 *databaseName* 和結構描述名稱 *schemaName*。此外，如果您的 Snowflake 使用者沒有預設的倉儲集，您將需要倉儲名稱 *warehouseName*。若要選取要連線**的其他網路連線**，請使用 `connectionName` 參數。

```
glueContext.write_dynamic_frame.from_options(
    connection_type="snowflake",
    connection_options={
        "connectionName": "connectionName",
        "dbtable": "tableName",
        "sfDatabase": "databaseName",
        "sfSchema": "schemaName",
        "sfWarehouse": "warehouseName",
    },
)
```

## Snowflake 連線選項參考
<a name="aws-glue-programming-etl-connect-snowflake-reference"></a>

Snowflake 連線類型採用下列連線選項：

您可以從 Glue AWS 連線 (`sfUrl`、`sfUser`、`sfPassword`) 擷取本節中的某些參數，在這種情況下，您不需要提供這些參數。您可以提供參數 `connectionName` 來完成此操作。

您可以使用 參數從 AWS Secrets Manager 秘密擷取連線`secretId`參數。使用 Secrets Manager 時，如果機密中存在下列 Spark 屬性，則可以自動擷取這些屬性：
+ `sfUser` (使用金鑰 `USERNAME` 或 `sfUser`)
+ `sfPassword` （使用基本身分驗證時`sfPassword`，使用 金鑰`PASSWORD`或 )
+ `sfWarehouse` (使用金鑰 `sfWarehouse`)
+ `sfDatabase` (使用金鑰 `sfDatabase`)
+ `sfSchema` (使用金鑰 `sfSchema`)
+ `sfRole` (使用金鑰 `sfRole`)
+ `pem_private_key` （使用金鑰對身分驗證`pem_private_key`時使用金鑰 )
+ `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` （使用 OAuth 身分驗證時）

**屬性優先順序：**在多個位置指定相同的屬性時， AWS Glue 會使用下列優先順序 （從最高到最低）：

1. 任務程式碼中明確提供的連線選項

1. Glue 連線屬性

1. AWS Secrets Manager 秘密值 `secretId` （指定 時）

1. Snowflake 使用者預設值

連線到 Snowflake 時，通常使用以下參數。
+ `sfDatabase`：未在 Snowflake 中設定使用者預設值時需要。用於讀取/寫入。連線後用於工作階段的資料庫。
+ `sfSchema`：未在 Snowflake 中設定使用者預設值時需要。用於讀取/寫入。連線後用於工作階段的結構描述。
+ `sfWarehouse`：未在 Snowflake 中設定使用者預設值時需要。用於讀取/寫入。連線後用於工作階段的預設虛擬倉儲。
+ `sfRole`：未在 Snowflake 中設定使用者預設值時需要。用於讀取/寫入。連線後用於工作階段的預設安全角色。
+ `sfUrl`：(必要) 用於讀取/寫入。以下列格式指定帳戶的主機名稱：`account_identifier.snowflakecomputing.com`。如需有關帳戶識別碼的詳細資訊，請參閱 Snowflake 文件中的 [Account Identifiers](https://docs.snowflake.com/en/user-guide/admin-account-identifier)。
+ `sfUser`：(必要) 用於讀取/寫入。Snowflake 使用者的登入名稱。
+ `sfPassword` — （使用基本身分驗證時必填） 用於讀取/寫入。Snowflake 使用者的密碼。
+ `dbtable`：使用完整資料表時需要。用於讀取/寫入。要讀取之資料表或向其寫入資料之資料表的名稱。讀取時，將擷取所有資料欄和記錄。
+ `pem_private_key` — （使用金鑰對身分驗證時必填） 用於讀取/寫入。未加密的 b64 編碼私有金鑰字串。Snowflake 使用者的私有金鑰。通常將其從 PEM 檔案中複製出來。如需詳細資訊，請參閱 Snowflake 文件中的[金鑰對驗證和金鑰對輪換](https://docs.snowflake.com/en/user-guide/key-pair-auth)。
+ `USER_MANAGED_CLIENT_APPLICATION_CLIENT_SECRET` — （使用 OAuth 身分驗證時必填） 用於讀取和寫入操作。此值對應至 OAUTH\$1CLIENT\$1SECRET，可從設定為為您的帳戶啟用 OAuth 型身分驗證的 Snowflake 安全整合取得。如需詳細資訊，請參閱您的 Snowflake OAuth 安全整合設定文件 - [為自訂用戶端設定 Snowflake OAuth](https://docs.snowflake.com/en/user-guide/oauth-custom)。
+ `query`：使用查詢讀取時需要。用於讀取。要執行的確切查詢 (`SELECT` 陳述式)

以下選項用於在連線到 Snowflake 過程中設定特定行為。
+ `preactions`：用於讀取/寫入。有效值：以分號分隔的 SQL 陳述式清單作為字串。SQL 陳述式會在 Glue AWS 和 Snowflake 之間傳輸資料之前執行。如果陳述式包含 `%s`，則 `%s` 會以操作參考的資料表名稱取代。
+ `postactions`：用於讀取/寫入。SQL 陳述式會在 Glue AWS 和 Snowflake 之間傳輸資料後執行。如果陳述式包含 `%s`，則 `%s` 會以操作參考的資料表名稱取代。
+ `autopushdown`：預設：`"on"`。有效值：`"on"`、`"off"`。此參數控制是否啟用自動查詢下推。如果下推已啟用，則在 Spark 上執行查詢時，若查詢的一部分可以「向下推」到 Snowflake 伺服器，它便會被下推。這可改善某些查詢的效能。如需有關是否可以下推查詢的資訊，請參閱 Snowflake 文件中的 [Pushdown](https://docs.snowflake.com/en/user-guide/spark-connector-use#pushdown)。

此外，Glue AWS 可能支援 Snowflake Spark 連接器上的一些可用選項。如需有關 Snowflake Spark 連接器上可用選項的詳細資訊，請參閱 Snowflake 文件中的 [Setting Configuration Options for the Connector](https://docs.snowflake.com/en/user-guide/spark-connector-use#setting-configuration-options-for-the-connector)。

## Snowflake 身分驗證方法
<a name="aws-glue-programming-etl-connect-snowflake-authentication"></a>

AWS Glue 支援下列身分驗證方法來連線至 Snowflake：
+ **基本身分驗證：**提供 `sfUser`和 `sfPassword` 參數。
+ **金鑰對身分驗證：**提供 `sfUser`和 `pem_private_key` 參數。使用金鑰對身分驗證時，`sfPassword` 參數不是必需的。
+ **OAuth 身分驗證：**Snowflake 連接器支援 AUTHORIZATION\$1CODE 授予類型，以請求存取您的 Snowflake 資料。此授予類型稱為「3 邊 OAuth」，因為它涉及將使用者重新導向到第三方授權伺服器，他們可以在其中驗證和核准存取權。透過 Glue AWS 主控台建立連線時，會使用此方法。
  + **先決條件：**若要使用此身分驗證方法，請確定下列設定已完成：
    + 遵循官方 **Snowflake 文件為自訂用戶端設定 Snowflake OAuth**：[為自訂用戶端設定 Snowflake OAuth。](https://docs.snowflake.com/en/user-guide/oauth-custom)
    + **在建立 Snowflake 安全整合時設定正確的重新導向 URI**。例如：如果您要在 DUB (eu-west-1) 區域中建立連線，您的重新導向 URI 應該是： `https://eu-west-1.console.aws.amazon.com/gluestudio/oauth`
    + 建立安全整合之後，請保留以下資訊，以供建立 Glue 連線時使用：
      + OAUTH\$1CLIENT\$1ID：此值應在 Glue 連線建立頁面上提供為使用者受管用戶端應用程式用戶端 ID。
      + OAUTH\$1CLIENT\$1SECRET：此值應存放在用於連線的 AWS 秘密中，在金鑰 USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET 下。
  + OAuth 範圍 — （選用） 定義從 Snowflake 帳戶請求的特定許可或存取層級。例如，範圍可能會限制對特定資源或操作的存取。
    + 此值可以下列格式指定： `session:role:Snowflake_Role_Name`
    + 範例：`session:role:ANALYST_ROLE`
  + 授權碼 URL — （必要） 使用者重新導向至登入並授予授權的端點。
    + 範例：`https://host/oauth/authorize`
  + 授權字符 URL — （必要） 用來交換存取字符授權碼的端點。
    + 範例：`https://host/oauth/token-request`
  + 使用者受管用戶端應用程式用戶端 ID — （必要） Snowflake 中已註冊 OAuth 用戶端應用程式的唯一識別符
  + AWS 秘密 — （必要） 是指包含下列鍵/值對的 AWS Secrets Manager 秘密：
    + sfUser - Snowflake 使用者名稱
    + USER\$1MANAGED\$1CLIENT\$1APPLICATION\$1CLIENT\$1SECRET - 與 OAuth 用戶端應用程式相關聯的用戶端秘密

完全支援這三種身分驗證方法，並且可以使用連線選項、Glue 連線或 AWS Secrets Manager 秘密的任意組合進行設定。

## Snowflake 連接器限制
<a name="aws-glue-programming-etl-connect-snowflake-limitations"></a>

使用 Glue for Spark AWS 連線至 Snowflake 受下列限制約束。
+ 此連接器不支援任務書籤。如需有關任務書籤的詳細資訊，請參閱 [使用任務書籤追蹤處理的資料](monitor-continuations.md)。
+ 此連接器不支援 Snowflake 使用 和 `write_dynamic_frame.from_catalog`方法來讀取`create_dynamic_frame.from_catalog`和寫入 AWS Glue Data Catalog 中的資料表。
+ 此連接器支援基本身分驗證、金鑰對身分驗證和 OAuth 身分驗證。目前不支援其他身分驗證方法 （例如 SAML)。
+ 串流任務不支援此連接器。
+ 擷取資訊 (例如使用 `query` 參數擷取) 時，此連接器支援 `SELECT` 陳述式型查詢。不支援其他類型的查詢 (例如 `SHOW`、`DESC` 或 DML 陳述式)。
+ Snowflake 會將透過 Snowflake 用戶端提交的查詢文字 (例如 SQL 陳述式) 的大小限制為每個陳述式 1 MB。如需詳細資訊，請參閱 [Limits on Query Text Size](https://docs.snowflake.com/en/user-guide/query-size-limits)。