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

# 將 Snowflake 連接為 Amazon DataZone 中的資料來源
<a name="snowflake-data-source"></a>

Amazon DataZone 支援 Snowflake 作為第三方資料來源。將 Snowflake 連線至 Amazon DataZone 專案後，目錄可以為 Snowflake 資料庫和結構描述編製索引、從 Snowflake 的查詢歷史記錄擷取資料欄層級歷程記錄，以及讓您透過聯合從 查詢 Snowflake 資料表。此頁面會逐步引導您使用 CLI 建立 Snowflake AWS 連線。

## 先決條件
<a name="snowflake-data-source-prerequisites"></a>

開始之前，請確認下列項目已就緒：
+ Amazon DataZone 網域和您希望 Snowflake 資料編製目錄的專案。請參閱 [Amazon DataZone 中的網域和使用者存取權](working-with-domains-users.md) 和 [Amazon DataZone 專案和環境](working-with-projects.md)。
+ Snowflake 帳戶，具有在您要編目的資料庫、結構描述和倉儲中建立角色和授予權限的許可。
+ 在與您的 Amazon DataZone 網域 AWS Secrets Manager 相同的 AWS 帳戶中存取 。
+ 如果您打算從 查詢 Snowflake 資料，則為查詢溢出的 Amazon S3 儲存貯體。

您將依此順序執行步驟：建立 Snowflake 角色、將 Snowflake 登入資料存放在其中 AWS Secrets Manager、尋找 Amazon DataZone 專案環境 ID，然後呼叫 `aws datazone create-connection`。

## 步驟 1：為 Amazon DataZone 建立 Snowflake 角色
<a name="snowflake-data-source-step1"></a>

Amazon DataZone 會使用您建立的角色連線至 Snowflake，並授予特定權限。角色授予分為四個類別：
+ **中繼資料同步** — Amazon DataZone 會讀取資料表和檢視的結構，以填入目錄。
+ **譜系同步** — Amazon DataZone 讀取 Snowflake 的 QUERY\_HISTORY 和 ACCESS\_HISTORY，以衍生資料欄層級譜系。
+ **查詢存取** — 透過 Amazon DataZone 發出的查詢需要，包括來自 的查詢。
+ **倉儲用量** - 角色執行的任何查詢都需要。

在 Snowflake 中執行下列陳述式，將預留位置取代為您的值：

```
CREATE ROLE <role_name>;

-- Metadata: database and schema access
GRANT USAGE ON DATABASE <database_name> TO ROLE <role_name>;
GRANT USAGE ON SCHEMA <database_name>.<schema_name> TO ROLE <role_name>;

-- Metadata: table and view structure (no data access)
GRANT REFERENCES ON ALL TABLES IN SCHEMA <database_name>.<schema_name> TO ROLE <role_name>;
GRANT REFERENCES ON ALL VIEWS IN SCHEMA <database_name>.<schema_name> TO ROLE <role_name>;
GRANT REFERENCES ON FUTURE TABLES IN SCHEMA <database_name>.<schema_name> TO ROLE <role_name>;
GRANT REFERENCES ON FUTURE VIEWS IN SCHEMA <database_name>.<schema_name> TO ROLE <role_name>;

-- Lineage: access to QUERY_HISTORY and ACCESS_HISTORY
GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE <role_name>;

-- Query access
GRANT SELECT ON ALL TABLES IN SCHEMA <database_name>.<schema_name> TO ROLE <role_name>;

-- Optional: include tables created after the role is granted
GRANT SELECT ON FUTURE TABLES IN SCHEMA <database_name>.<schema_name> TO ROLE <role_name>;

-- Warehouse access
GRANT USAGE ON WAREHOUSE <warehouse_name> TO ROLE <role_name>;

-- Assign the role to the Snowflake user whose credentials DataZone will use
GRANT ROLE <role_name> TO USER <snowflake_username>;
```

**重要**  
`GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE` 歷程記錄需要 。如果沒有，中繼資料同步會成功，但不會擷取任何歷程記錄。

## 步驟 2：將 Snowflake 登入資料存放在 AWS Secrets Manager
<a name="snowflake-data-source-step2"></a>

在與您的 Amazon DataZone 網域 AWS Secrets Manager相同的 AWS 帳戶中建立秘密。Amazon DataZone 支援兩種身分驗證方法：使用者名稱和密碼，或金鑰對。

對於使用者名稱和密碼身分驗證，請使用此 JSON 內文：

```
{
  "username": "<snowflake_username>",
  "password": "<snowflake_password>"
}
```

對於金鑰對身分驗證，請使用此 JSON 內文：

```
{
  "sfUser": "<snowflake_username>",
  "pem_private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}
```

標記秘密，以便 Amazon DataZone 可以探索它。這兩個標籤都是必要的：


| 標籤鍵 | Value | 
| --- | --- | 
| AmazonDataZoneDomain | 您的 Amazon DataZone 網域 ID | 
| AmazonDataZoneProject | 您的 Amazon DataZone 專案 ID | 

請注意秘密的 ARN。您將在步驟 4 `create-connection`中將其傳遞至 。

## 步驟 3：尋找您的專案環境 ID
<a name="snowflake-data-source-step3"></a>

`create-connection` API 呼叫需要連線所在的專案環境 ID。您可以從專案使用者角色 ARN 衍生此項目。

專案使用者角色 ARN 遵循此模式：

```
arn:aws:iam::<account_id>:role/datazone_usr_role_<project_id>_<environment_id>
```

最後一個區段在最後一個底線之後是環境 ID。例如，在 中：

```
arn:aws:iam::123456789012:role/datazone_usr_role_a1b2c3dfadsf_58cjkfdsjfd
```

`58cjkfdsjfd` 為環境 ID。這是要傳遞的值，如步驟 4 `--environment-identifier`所示。環境 ID 對應至專案的工具環境。

## 步驟 4：建立 Snowflake 連線
<a name="snowflake-data-source-step4"></a>

執行下列 AWS CLI 命令，將預留位置取代為您的值：

```
aws datazone create-connection \
    --domain-identifier <domain_id> \
    --environment-identifier <environment_id> \
    --name "<connection_name>" \
    --description "<optional_description>" \
    --props '{
      "snowflakeProperties": {
        "connectivityProperties": {
          "connectionProperties": {
            "HOST": "<account>.snowflakecomputing.com",
            "PORT": "443",
            "DATABASE": "<database_name>",
            "WAREHOUSE": "<warehouse_name>",
            "SCHEMA": "<schema_name>",
            "ROLE_ARN": "<project_user_role_arn>",
            "CATALOG_CASING_FILTER": "UPPERCASE_ONLY"
          },
          "athenaProperties": {
            "spill_bucket": "<project_s3_bucket_name>",
            "spill_prefix": "<domain_id>/<project_id>/dev/sys/athena"
          },
          "authenticationConfiguration": {
            "authenticationType": "BASIC",
            "secretArn": "<secret_arn_from_step_2>"
          }
        },
        "snowflakeRole": "<role_name_from_step_1>",
        "identityMapping": {
          "usernameAttribute": "EMAIL"
        }
      }
    }'
```

### 連線屬性參考
<a name="snowflake-data-source-connection-properties"></a>


| 屬性 | 說明 | 
| --- | --- | 
| HOST | 您的 Snowflake 帳戶 URL。 | 
| PORT | Snowflake 連接埠。請使用 443。 | 
| DATABASE | 要編製目錄的 Snowflake 資料庫。 | 
| WAREHOUSE | Snowflake 倉儲 Amazon DataZone 用來執行查詢。 | 
| SCHEMA | 要編目的 Snowflake 結構描述。 | 
| ROLE\_ARN | 專案使用者角色 ARN （請參閱步驟 3)。 | 
| CATALOG\_CASING\_FILTER | 控制編目識別符的案例標準化。有效值為 UPPERCASE\_ONLY 和 LOWERCASE\_ONLY。如果省略，則 預設為 UPPERCASE\_ONLY。 | 
| spill\_bucket | 查詢溢出的 S3 儲存貯體名稱。從 查詢 Snowflake 時為必要。 | 
| spill\_prefix | 溢出的 S3 字首，格式為 <domain\_id>/<project\_id>/dev/sys/athena。 | 
| authenticationType | BASIC 用於使用者名稱/密碼或金鑰對身分驗證。 | 
| secretArn | 在步驟 2 中建立之秘密的 ARN。 | 
| snowflakeRole | 步驟 1 中的 Snowflake 角色名稱。 | 
| identityMapping.usernameAttribute | 設定為 EMAIL。 | 

## 驗證連線
<a name="snowflake-data-source-verify"></a>

`aws datazone get-connection` 使用您的網域 ID 和 傳回的連線識別符呼叫 `create-connection`。在第一個中繼資料同步執行之後，分類的 Snowflake 資料表會出現在專案的 Amazon DataZone 目錄中。