本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Amazon Athena Oracle 連接器 適用於 Oracle 的 Amazon Athena 連接器可讓 Amazon Athena 能夠對內部部署或在 Amazon EC2 或 Amazon RDS 上執行的 Oracle 中存放的資料執行 SQL 查詢。您也可以使用連接器來查詢 [Oracle exadata](https://www.oracle.com/engineered-systems/exadata/) 上的資料。 此連接器可以作為聯合目錄向 Glue Data Catalog 註冊。它可在目錄、資料庫、資料表、資料欄、資料列和標籤層級支援 Lake Formation 中定義的資料存取控制。此連接器使用 Glue 連線來集中 Glue 中的組態屬性。 ## 先決條件 + 使用 Athena 主控台或 AWS Serverless Application Repository，將連接器部署到您的 AWS 帳戶 。如需詳細資訊，請參閱 [建立資料來源連線](connect-to-a-data-source.md) 或 [使用 AWS Serverless Application Repository 部署資料來源連接器](connect-data-source-serverless-app-repo.md) 。 ## 限制 + 不支援寫入 DDL 操作。 + 在多工器設定中，在所有資料庫執行個體之間共用溢出儲存貯體和字首。 + 任何相關的 Lambda 限制。如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的 [Lambda 配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)。 + 僅支援 12.1.0.2 版 Oracle 資料庫。 + 如果 Oracle 連接器沒有使用 Glue 連線，則連接器會將資料庫、資料表和資料欄名稱轉換為大寫。 如果 Oracle 連接器使用了 Glue 連線，則連接器不會將資料庫、資料表和資料欄名稱預設為大寫。若要變更此大小寫行為，請視需要將 Lambda 的環境變數 `casing_mode` 變更為 `upper` 或 `lower` 。 使用 Glue 連線的 Oracle 連接器不支援使用多工處理常式。 + 當使用 Oracle `NUMBER` 而未定義精確度與小數位數，Athena 會將此視為 `BIGINT`。若要在 Athena 中取得所需的小數位數，請在 Lambda 環境變數中指定 `default_scale=<{{number of decimal places}}>`。 ## 條款 下列術語與 Oracle 連接器相關。 + **資料庫執行個體** - 在內部部署、Amazon EC2 或 Amazon RDS 上部署的任何資料庫執行個體。 + **處理常式** - 存取資料庫執行個體的 Lambda 處理常式。處理常式可以用於中繼資料或資料記錄。 + **中繼資料處理常式** - 從資料庫執行個體中擷取中繼資料的 Lambda 處理常式。 + **記錄處理常式** - 從資料庫執行個體中擷取資料記錄的 Lambda 處理常式。 + **複合處理常式** - 從資料庫執行個體中擷取中繼資料和資料記錄的 Lambda 處理常式。 + **屬性或參數** - 處理常式用來擷取資料庫資訊的資料庫屬性。您可以將這些屬性設定為 Lambda 環境變數。 + **連接字串** - 用來建立資料庫執行個體連線的文字字串。 + **Catalog** – 向 Athena 註冊的非AWS Glue 目錄，是 `connection_string` 屬性的必要字首。 + **多工處理常式** - 可以接受和使用多個資料庫連接的 Lambda 處理常式。 ## Parameters 使用本節中的參數來設定 Oracle 連接器。 ### AWS Glue Data Catalog 聯合連接器 我們建議您使用 Glue 連線物件來設定 Oracle 連接器。為此，請將 Oracle 連接器 Lambda 的 `glue_connection` 環境變數設定為要使用的 Glue 連線名稱。 **Glue 連線屬性** 使用下列命令來取得 Glue 連線物件的結構描述。此結構描述包含可用於控制連線的所有參數。 ``` aws glue describe-connection-type --connection-type ORACLE ``` **Lambda 環境屬性** 下列 Lambda 環境屬性僅適用於在帳戶中搭配 Lambda 函數使用連接器時。 + **glue\_connection** – 指定與聯合連接器關聯的 Glue 連線名稱。 + **is\_fips\_enabled** – (選用) 啟用 FIPS 模式時，設定為 true。預設值為 false。 + **casing\_mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為： + **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。這是具有關聯 Glue 連線的連接器的預設值。 + **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。這是沒有關聯 Glue 連線的連接器的預設值。 + **case\_insensitive\_search** – 針對 Oracle 中的結構描述和資料表名稱執行不區分大小寫搜尋。如果查詢包含不符合連接器預設大小寫的結構描述或資料表名稱，請使用此值。 **注意** 使用聯合連線的所有連接器都必須使用 AWS Glue Data Catalog AWS Secrets Manager 來存放登入資料。 使用 AWS Glue Data Catalog 聯合連線建立的 Oracle 連接器不支援使用多工處理常式。 使用 AWS Glue Data Catalog 聯合連線建立的 Oracle 連接器僅支援 `ConnectionSchemaVersion` 2。 ### Athena 資料目錄聯合連接器 **注意** 2024 年 12 月 3 日及更新版本建立的 Athena 資料來源連接器會使用 AWS Glue 連線。 下方列出的參數名稱和定義適用於未使用關聯 Glue 連線建立的 Athena 資料來源連接器。只有在您[手動部署](connect-data-source-serverless-app-repo.md)舊版 Athena 資料來源連接器或未指定 `glue_connection` 環境屬性時，才會使用下列參數。 **Lambda 環境屬性** + **default** – 用來連線至 Oracle 資料庫執行個體的 JDBC 連線字串。例如 `oracle://${jdbc_connection_string}` + **catalog\_connection\_string** – 由多工處理常式使用 (使用 Glue 連線時不支援)。資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 myoraclecatalog，則環境變數名稱為 myoraclecatalog\_connection\_string。 + **spill\_bucket** - 針對超過 Lambda 函數限制的資料，指定 Amazon S3 儲存貯體。 + **spill\_prefix** - (選用) 預設為指定的 `spill_bucket` 中名為 `athena-federation-spill` 的子資料夾。我們建議您在此位置設定 Amazon S3 [儲存生命週期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)，以刪除超過預定天數或小時數的溢出。 + **spill\_put\_request\_headers** – (選用) 用於溢出的 Amazon S3 `putObject` 請求的請求標頭和值的 JSON 編碼映射 (例如，`{"x-amz-server-side-encryption" : "AES256"}`)。如需其他可能的標頭，請參閱《Amazon Simple Storage Service API 參考**》中的 [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)。 + **kms\_key\_id** - (選用) 依預設，任何溢出到 Amazon S3 的資料都會使用 AES-GCM 驗證加密模式和隨機產生的金鑰進行加密。為了讓您的 Lambda 函數使用 KMS 產生的更強大的加密金鑰，例如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`，您可以指定 KMS 金鑰 ID。 + **disable\_spill\_encryption** - (選用) 當設定為 `True` 時，停用溢出加密。預設為 `False`，因此溢出 S3 的資料會使用 AES-GCM 進行加密 — 使用隨機產生的金鑰或 KMS 來產生金鑰。停用溢出加密可以提高效能，尤其是如果溢出位置使用[伺服器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)。 + **is\_fips\_enabled** – (選用) 啟用 FIPS 模式時，設定為 true。預設值為 false。 + **casing\_mode** – (選用) 指定如何處理結構描述和資料表名稱的大小寫。`casing_mode` 參數使用下列值來指定大小寫的行為： + **lower** – 將所有指定的結構描述和資料表名稱轉換為小寫。這是具有關聯 Glue 連線的連接器的預設值。 + **upper** – 將所有指定的結構描述和資料表名稱轉換為大寫。這是沒有關聯 Glue 連線的連接器的預設值。 + **case\_insensitive\_search** – 針對 Oracle 中的結構描述和資料表名稱執行不區分大小寫搜尋。如果查詢包含不符合連接器預設大小寫的結構描述或資料表名稱，請使用此值。 #### 連接字串 使用下列格式的 JDBC 連接字串來連接資料庫執行個體。 ``` oracle://${{{jdbc_connection_string}}} ``` **注意** 如果您的密碼包含特殊字元 (例如，`some.password`)，當您將密碼傳遞給連線字串時，請以雙引號括住密碼 (例如，`"some.password"`)。如果沒有這樣做，會導致指定的 Oracle URL 無效錯誤。 #### 使用單一連接處理常式 您可以使用下列單一連接中繼資料和記錄處理常式來連接至單一 Oracle 執行個體。 **** | 處理常式類型 | 類別 | | --- | --- | | 複合處理常式 | OracleCompositeHandler | | 中繼資料處理常式 | OracleMetadataHandler | | 記錄處理常式 | OracleRecordHandler | ##### 單一連接處理常式參數 **** | 參數 | Description | | --- | --- | | default | 必要. 預設的連接字串。 | | IsFIPSEnabled | 選用。啟用 FIPS 模式時，設定為 true。預設值為 false。 | 單一連接處理常式支援一個資料庫執行個體，並且必須提供 `default` 連接字串參數。忽略所有其他連接字串。 該連接器支援基於 SSL 的 Amazon RDS 執行個體連接。支援範圍僅限於 Transport Layer Security (TLS) 通訊協定，以及用戶端對伺服器執行的身分驗證作業。Amazon RDS 中不支援相互身分驗證。下表中的第二列顯示使用 SSL 的語法。 下列範例屬性適用於 Lambda 函數所支援的單一 Oracle 執行個體。 **** | 屬性 | Value | | --- | --- | | default | oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@//hostname:port/servicename | | | oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS) (HOST=)(PORT=))(CONNECT\_DATA=(SID=))(SECURITY=(SSL\_SERVER\_CERT\_DN=))) | #### 提供憑證 要在 JDBC 連接字串中提供資料庫的使用者名稱和密碼，可以使用連接字串屬性或 AWS Secrets Manager。 + **連接字串** - 可以將使用者名稱和密碼指定為 JDBC 連接字串中的屬性。 **重要** 作為安全最佳實務，請勿在您的環境變數或連線字串中使用硬式編碼憑證。如需有關將硬式編碼秘密移至 的資訊 AWS Secrets Manager，請參閱*AWS Secrets Manager 《 使用者指南*》中的[將硬式編碼秘密移至 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) 。 + **AWS Secrets Manager** – 若要搭配 使用 Athena 聯合查詢功能 AWS Secrets Manager，連接至 Lambda 函數的 VPC 應具有[網際網路存取](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)或 [VPC 端點](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)，以連接至 Secrets Manager。 您可以將秘密的名稱放入 JDBC 連線字串 AWS Secrets Manager 中的 。連接器將秘密名稱取代為 Secrets Manager 中的 `username` 和 `password` 值。 對於 Amazon RDS 資料庫執行個體，已緊密整合此支援。如果您使用 Amazon RDS，強烈建議使用 AWS Secrets Manager 和 登入資料輪換。如果您的資料庫不使用 Amazon RDS，請以下列格式將憑證儲存為 JSON： ``` {"username": "${username}", "password": "${password}"} ``` **注意** 如果您的密碼包含特殊字元 (例如，`some.password`)，當您將密碼儲存在 Secrets Manager 時，請以雙引號括住密碼 (例如，`"some.password"`)。如果沒有這樣做，會導致指定的 Oracle URL 無效錯誤。 **帶有秘密名稱的連接字串範例** 以下字串具有秘密名稱 `${Test/RDS/Oracle}`。 ``` oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@//hostname:port/servicename ``` 連接器會使用秘密名稱來擷取秘密並提供使用者名稱和密碼，如下列範例所示。 ``` oracle://jdbc:oracle:thin:username/password@//hostname:port/servicename ``` 目前，Oracle 連接器可辨識 `UID` 和 `PWD` JDBC 屬性。 #### 使用多工處理常式 您可以使用多工器透過單一 Lambda 函數連接到多個資料庫執行個體。按目錄名稱路由請求。在 Lambda 中使用下列類別。 **** | 處理常式 | 類別 | | --- | --- | | 複合處理常式 | OracleMuxCompositeHandler | | 中繼資料處理常式 | OracleMuxMetadataHandler | | 記錄處理常式 | OracleMuxRecordHandler | ##### 多工處理常式參數 **** | 參數 | Description | | --- | --- | | ${{catalog}}\_connection\_string | 必要. 資料庫執行個體連接字串。在環境變數前面加上 Athena 中使用的目錄名稱。例如，如果向 Athena 註冊的目錄為 myoraclecatalog，則環境變數名稱為 myoraclecatalog\_connection\_string。 | | default | 必要. 預設的連接字串。目錄為 lambda:${{{AWS\_LAMBDA\_FUNCTION\_NAME}}} 時，使用此字串。 | 下列範例屬性適用於支援兩個資料庫執行個體的 Oracle MUX Lambda 函數：`oracle1` (預設) 和 `oracle2`。 **** | 屬性 | Value | | --- | --- | | default | oracle://jdbc:oracle:thin:${Test/RDS/Oracle1}@//oracle1.hostname:port/servicename | | oracle\_catalog1\_connection\_string | oracle://jdbc:oracle:thin:${Test/RDS/Oracle1}@//oracle1.hostname:port/servicename | | oracle\_catalog2\_connection\_string | oracle://jdbc:oracle:thin:${Test/RDS/Oracle2}@//oracle2.hostname:port/servicename | ## 支援的資料類型 下表顯示 JDBC、Oracle 和 Arrow 的相應資料類型。 **** | JDBC | Oracle | Arrow | | --- | --- | --- | | Boolean | boolean | 位元 | | Integer | N/A | Tiny | | Short | smallint | Smallint | | Integer | integer | Int | | Long | bigint | Bigint | | float | float4 | Float4 | | Double | float8 | Float8 | | Date | date | DateDay | | 時間戳記 | timestamp | DateMilli | | String | text | Varchar | | 位元組 | 位元組 | Varbinary | | BigDecimal | numeric(p,s) | Decimal (小數) | | ARRAY | N/A (請參閱備註) | 清單 | ## 分割區和分隔 分割區用於決定如何產生連接器的分割。Athena 建構了類型 `varchar` 的合成資料欄，表示資料表的分割結構，以幫助連接器產生分割。連接器不會修改實際的資料表定義。 ## 效能 Oracle 支援原生分割區。Athena Oracle 連接器可以平行地從這些分割區中擷取資料。如果您想要查詢具有統一分割區分佈的非常大的資料集，強烈建議使用原生分割。選取資料欄子集可大幅加速查詢執行期，並減少掃描的資料。Oracle 連接器由於並行而對限流保有彈性。但是，查詢執行時間往往會很長。 Athena Oracle 連接器執行述詞下推，以減少查詢掃描的資料。簡單述詞和複雜表達式會下推至連接器，以減少掃描的資料量並減少查詢執行時間。 ### 述詞 述詞是 SQL 查詢的 `WHERE` 子句中的一種表達式，它會評估為布林值，並根據多個條件篩選資料列。Athena Oracle 連接器可以合併這些表達式，並將其直接推送至 Oracle，以增強功能並減少掃描的資料量。 下列 Athena Oracle 連接器運算子支援述詞下推： + **布林值：**AND、OR、NOT + **等式：**EQUAL、NOT\_EQUAL、LESS\_THAN、LESS\_THAN\_OR\_EQUAL、GREATER\_THAN、GREATER\_THAN\_OR\_EQUAL、IS\_NULL + **算術：**ADD、SUBTRACT、MULTIPLY、DIVIDE、NEGATE + **其他：**LIKE\_PATTERN、IN ### 合併下推範例 如需增強的查詢功能，請合併下推類型，如以下範例所示： ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## 傳遞查詢 Oracle 連接器支援[傳遞查詢](federated-query-passthrough.md)。傳遞查詢使用資料表函式，可將您的完整查詢下推到資料來源以便執行。 若要透過 Oracle 使用傳遞查詢，您可以使用下列語法： ``` SELECT * FROM TABLE( system.query( query => '{{query string}}' )) ``` 下列範例查詢會將查詢下推到 Oracle 中的資料來源。查詢會選取 `customer` 資料表中的所有資料欄。 ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer' )) ``` ## 授權資訊 使用此連接器，即表示您確認已包含第三方元件，可在此連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) 檔案中找到其清單，並同意 GitHub.com 上 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/LICENSE.txt) 檔案中提供的相應第三方授權中的條款。 ## 其他資源 如需最新的 JDBC 驅動程式版本資訊，請參閱 GitHub.com 上 Oracle 連接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) 檔案。 如需此連接器的其他資訊，請造訪 GitHub.com 上的[相應網站](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-oracle)。