本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon RDS 資料 API
透過使用 RDS 資料 API (資料 API)，您可以使用網路服務界面來操作 Aurora 資料庫叢集。資料 API 不需要資料庫叢集的持續連線。而是提供安全的 HTTP 端點並與 AWS SDKs整合。您可以使用端點來執行 SQL 陳述式，而不需管理連線。
使用者不需要透過呼叫資料 API 來傳遞登入資料，因為資料 API 會使用存放於 中的資料庫登入資料 AWS Secrets Manager。若要將憑證儲存在 Secrets Manager 中，必須授與使用者使用 Secrets Manager 以及資料 API 的適當許可。如需授權使用者的詳細資訊，請參閱[授權 Amazon RDS 資料 API 的存取](data-api.access.md)。
您也可以使用資料 API 將 Amazon Aurora 與其他 AWS 應用程式整合，例如 AWS Lambda AWS AppSync、 和 AWS Cloud9。資料 API 會提供更安全的 AWS Lambda使用方式。這可讓您存取資料庫叢集，而不需將 Lambda 函數設定為在 Virtual Private Cloud (VPC) 存取資源。如需詳細資訊，請參閱[AWS Lambda](https://aws.amazon.com/lambda/)、[AWS AppSync](https://aws.amazon.com/appsync/)及[AWS Cloud9](https://aws.amazon.com/cloud9/)。
您可以在建立 Aurora 資料庫叢集時啟用資料 API。您也可以稍後修改組態。如需詳細資訊，請參閱[啟用 Amazon RDS 資料 API](data-api.enabling.md)。
啟用資料 API 之後，您也可以使用查詢編輯器執行臨機操作查詢，而無需設定查詢工具，來存取 VPC 中的 Aurora。如需詳細資訊，請參閱[使用 Aurora 查詢編輯器](query-editor.md)。
**Topics**
+ [Amazon RDS 資料 API 的區域和版本可用性](data-api.regions.md)
+ [搭配 Amazon RDS 資料 API 使用 IPv6](data-api.ipv6.md)
+ [Amazon RDS 資料 API 的限制](data-api.limitations.md)
+ [使用 Aurora Serverless v1 叢集比較 Aurora Serverless v2 和佈建叢集的 Amazon RDS 資料 API 行為](data-api.differences.md)
+ [授權 Amazon RDS 資料 API 的存取](data-api.access.md)
+ [啟用 Amazon RDS 資料 API](data-api.enabling.md)
+ [建立 Amazon RDS 資料 API 的 Amazon VPC 端點 (AWS PrivateLink)](data-api.vpc-endpoint.md)
+ [呼叫 Amazon RDS 資料 API](data-api.calling.md)
+ [使用適用於 RDS 資料 API 的 Java 用戶端程式庫](data-api.java-client-library.md)
+ [以 JSON 格式處理 Amazon RDS 資料 API 查詢結果](data-api-json.md)
+ [針對 Amazon RDS 資料 API 進行疑難排解](data-api.troubleshooting.md)
+ [使用 記錄 Amazon RDS Data API 呼叫 AWS CloudTrail](logging-using-cloudtrail-data-api.md)
+ [使用 Performance Insights 監控 RDS 資料 API 查詢](monitoring-using-performance-insights-data-api.md)
# Amazon RDS 資料 API 的區域和版本可用性
如需資料 API 可用區域和引擎版本的相關資訊，請參閱下列各節。
| 叢集類型 | 區域和版本可用性 |
| --- | --- |
| Aurora PostgreSQL 已佈建和 Serverless 第 2 版 | [具有 Aurora PostgreSQL Serverless 第 2 版和佈建的資料 API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg) |
| Aurora MySQL 已佈建和 Serverless 第 2 版 | [具有 Aurora MySQL Serverless 第 2 版和佈建的資料 API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.ams) |
| Aurora PostgreSQL Serverless 第 1 版 | [具有 Aurora PostgreSQL Serverless 第 1 版的資料 API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg-sv1) |
| Aurora MySQL Serverless 第 1 版 | [具有 Aurora MySQL Serverless 第 1 版的資料 API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.amy) |
如果您在透過命令列界面或 API 存取資料 API 時，需要 FIPS 140-2 驗證的加密模組，請使用 FIPS 端點。如需有關 FIPS 和 FIPS 端點的更多相關資訊，請參閱[聯邦資訊處理標準 (FIPS) 140-2 概觀](https://aws.amazon.com/compliance/fips/)。
# 搭配 Amazon RDS 資料 API 使用 IPv6
Amazon RDS 資料 API 透過雙堆疊端點支援 IPv6 連線。這可讓您使用 IPv6 地址連線至資料 API，同時保持與 IPv4 的回溯相容性。
## IPv6 端點支援
資料 API 提供同時支援 IPv4 和 IPv6 連線的雙堆疊端點。這些端點使用 `.aws` 網域 (而非傳統`.amazonaws.com`網域)。
### 可用的端點類型
公有雙堆疊端點
格式：`rds-data.region.api.aws`
範例：`rds-data.us-east-1.api.aws`
FIPS 雙堆疊端點
格式：`rds-data-fips.region.api.aws`
範例：`rds-data-fips.us-east-1.api.aws`
PrivateLink IPv6 端點
透過支援 IPv6 的 VPC 端點提供
允許 VPC 內的私有 IPv6 連線
### 舊版僅 IPv4 端點
現有 `.amazonaws.com` 端點繼續支援僅 IPv4 連線：
+ `rds-data.region.amazonaws.com`
+ `rds-data-fips.region.amazonaws.com`
**注意**
舊版端點保持不變，以確保與現有應用程式的回溯相容性。
## 使用 IPv6 端點
若要搭配資料 API 使用 IPv6，請更新應用程式以使用新的雙堆疊端點。如果可用，應用程式會自動使用 IPv6，或回復為 IPv4。
如需在 VPC 中設定 IPv6 的一般指引，請參閱《Amazon VPC 使用者指南》**中的[遷移至 IPv6](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6.html)。
您可以透過兩種方式設定 IPv6 端點：
+ **使用環境變數**：在 IPv6 環境中設定 `AWS_USE_DUALSTACK_ENDPOINT=true`。 AWS CLI AWS SDKs 會自動建構適當的`api.aws`端點，而不需要您手動指定端點 URLs。
+ **使用明確的端點 URLs**：直接在 AWS CLI 命令或 SDK 組態中指定雙堆疊端點 URL，如以下範例所示。
### AWS CLI 組態
透過指定端點 URL，將 AWS CLI 設定為使用 IPv6 端點：
對於 Linux、macOS 或 Unix：
```
aws rds-data execute-statement \
--endpoint-url https://rds-data.us-east-1.api.aws \
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" \
--database "mydb" \
--sql "SELECT * FROM users LIMIT 10"
```
在 Windows 中：
```
aws rds-data execute-statement ^
--endpoint-url https://rds-data.us-east-1.api.aws ^
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" ^
--database "mydb" ^
--sql "SELECT * FROM users LIMIT 10"
```
### AWS SDK 組態
AWS SDKs使用雙堆疊端點：
------
#### [ Python ]
```
import boto3
# Create RDS Data API client with IPv6 dual-stack endpoint
client = boto3.client(
'rds-data',
endpoint_url='https://rds-data.us-east-1.api.aws'
)
# Execute a SQL statement
response = client.execute_statement(
resourceArn='arn:aws:rds:us-east-1:123456789012:cluster:my-cluster',
secretArn='arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret',
database='mydb',
sql='SELECT * FROM users LIMIT 10'
)
print(response['records'])
```
------
#### [ Java ]
```
import software.amazon.awssdk.services.rdsdata.RdsDataClient;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementRequest;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementResponse;
import java.net.URI;
// Create RDS Data API client with IPv6 dual-stack endpoint
RdsDataClient client = RdsDataClient.builder()
.endpointOverride(URI.create("https://rds-data.us-east-1.api.aws"))
.build();
// Execute a SQL statement
ExecuteStatementRequest request = ExecuteStatementRequest.builder()
.resourceArn("arn:aws:rds:us-east-1:123456789012:cluster:my-cluster")
.secretArn("arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret")
.database("mydb")
.sql("SELECT * FROM users LIMIT 10")
.build();
ExecuteStatementResponse response = client.executeStatement(request);
System.out.println(response.records());
```
------
#### [ JavaScript ]
```
const { RDSDataClient, ExecuteStatementCommand } = require("@aws-sdk/client-rds-data");
// Create RDS Data API client with IPv6 dual-stack endpoint
const client = new RDSDataClient({
endpoint: "https://rds-data.us-east-1.api.aws"
});
// Execute a SQL statement
const command = new ExecuteStatementCommand({
resourceArn: "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster",
secretArn: "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret",
database: "mydb",
sql: "SELECT * FROM users LIMIT 10"
});
const response = await client.send(command);
console.log(response.records);
```
------
## AWS PrivateLink 搭配 IPv6 使用
您可以為支援 VPC 內 IPv6 連線的資料 API 建立 VPC 端點。如需為資料 API 建立 VPC 端點的詳細指示，請參閱[建立 Amazon RDS 資料 API 的 Amazon VPC 端點 (AWS PrivateLink)](data-api.vpc-endpoint.md)。
為 IPv6 支援建立 VPC 端點時，請確保：
+ VPC 和子網路已設定為支援 IPv6
+ 安全群組允許在必要連接埠的 IPv6 流量 (HTTPS 通常是 443)
+ 網路 ACL 已設定為允許 IPv6 流量
## 遷移考量事項
遷移至 IPv6 端點時，請考慮下列事項：
+ **逐步遷移**：您可以透過一次更新一個應用程式的端點 URL 來逐步遷移應用程式。
+ **網路相容性**：確保網路基礎設施在遷移之前支援 IPv6。
+ **安全政策**：視需要更新安全群組規則和網路 ACL，以允許 IPv6 流量。
+ **監控**：更新監控和記錄組態以處理 IPv6 地址。
**注意**
**資料庫連線地址**：使用資料 API 的 IPv6 端點時，基礎資料庫連線和資料庫日誌仍會顯示 IPv4 地址。這是預期的行為，不會影響已啟用 IPv6 的應用程式功能。
## 針對 IPv6 連線進行疑難排解
如果您遇到 IPv6 連線問題，請檢查下列項目：
網路組態
確認網路支援 IPv6 且 IPv6 路由的設定都正確。
DNS 解析
確保 DNS 解析程式可以解析雙堆疊端點的 AAAA 記錄。
Security groups (安全群組)
更新安全群組規則，以允許在必要連接埠的 IPv6 流量 (HTTPS 通常是 443)。
用戶端程式庫
確認 HTTP 用戶端程式庫支援 IPv6 和雙堆疊連線。
# Amazon RDS 資料 API 的限制
RDS 資料 API 具有下列限制：
+ 您只能在資料庫叢集中的寫入器執行個體上執行資料 API 查詢。不過，寫入器執行個體可以同時接受寫入和讀取查詢。
+ 使用 Aurora 全域資料庫，您就可以在主要和次要資料庫叢集啟用資料 API。不過，次要叢集在提升為主要叢集之前，都不具備寫入器執行個體。資料 API 需要存取寫入器執行個體以進行查詢處理，即使是讀取查詢也是如此。因此，傳送至次要叢集的讀取和寫入查詢會在缺少寫入器執行個體時失敗。一旦次要叢集受到提升並具有可用的寫入器執行個體，該資料庫執行個體上的資料 API 查詢就會成功。
+ T 資料庫執行個體類別上不支援資料 API。
+ 對於 Aurora Serverless v2 和佈建的資料庫叢集，RDS 資料 API 不支援某些資料類型。如需支援的類型清單，請參閱[使用 Aurora Serverless v1 叢集比較 Aurora Serverless v2 和佈建叢集的 Amazon RDS 資料 API 行為](data-api.differences.md)。
+ 對於 Aurora PostgreSQL 第 14 版及更新版本的資料庫，資料 API 僅支援 `scram-sha-256` 來進行密碼加密。
+ 回應大小限制為 1 MiB。若呼叫傳回的回應資料超過 1 MiB，系統就會終止呼叫。
+ 對於 Aurora Serverless v1，每秒請求數上限為 1,000。對於所有其他支援的資料庫，沒有限制。
+ 針對資料庫傳回結果集中的每個資料列，資料 API 的大小上限為每個資料列 64 KB。請確定結果集的每個列都是 64 KB 或更小。
# 使用 Aurora Serverless v1 叢集比較 Aurora Serverless v2 和佈建叢集的 Amazon RDS 資料 API 行為
Amazon RDS 資料 API 的最新增強功能可讓使用最新版 PostgreSQL 或 MySQL 引擎的叢集使用資料 API。這些叢集可設定為使用 Aurora Serverless v2 或佈建執行個體類別，例如 `db.r6g` 或 `db.r6i`。
下列各節說明 Aurora Serverless v2 和佈建資料庫叢集和 Aurora Serverless v1 資料庫叢集之間的 Amazon RDS 資料 API 差異。Aurora Serverless v1資料庫叢集使用 `serverless` 引擎模式。佈建的資料庫叢集使用 `provisioned` 引擎模式。Aurora Serverless v2 資料庫叢集也會使用 `provisioned` 引擎模式，且包含一或多個具有 `db.serverless` 執行個體類別的 Aurora Serverless v2 資料庫執行個體。
## 每秒請求數上限
**Aurora Serverless v1**
資料 API 每秒最多可提出 1,000 個請求。
**Aurora Serverless v2**
資料 API 每秒可以提出不限數量的請求。
## 在現有資料庫啟用或停用 Amazon RDS 資料 API
**Aurora Serverless v1**
+ **使用 Amazon RDS API**：使用 `ModifyCluster` 操作，然後指定 `EnableHttpEndpoint` 參數的 `True`或 `False` (如適用)。
+ **搭配 AWS CLI**：使用 `modify-db-cluster` 操作搭配 `--enable-http-endpoint` 或 `--no-enable-http-endpoint` 選項 (如適用)。
**Aurora Serverless v2**
+ **搭配 Amazon RDS API**：使用 `EnableHttpEndpoint` 和 `DisableHttpEndpoint` 操作。
+ **搭配 AWS CLI**：使用 `enable-http-endpoint` 和 `disable-http-endpoint` 操作。
## CloudTrail 事件
**Aurora Serverless v1**
資料 API 呼叫中的事件是管理事件。根據預設，這些事件會自動包含在線索中。如需更多詳細資訊，請參閱 [從 AWS CloudTrail 追蹤中排除資料 API 事件 (Aurora Serverless v1僅限 )](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.excluding-cloudtrail-events)。
**Aurora Serverless v2**
資料 API 呼叫中的事件是資料事件。預設會在線索中自動排除這些事件。如需更多詳細資訊，請參閱 [在 AWS CloudTrail 追蹤中包含資料 API 事件](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.including-cloudtrail-events)。
## 多陳述式支援
**Aurora Serverless v1**
+ 對於 Aurora MySQL，不支援多陳述式。
+ 對於 Aurora PostgreSQL，多陳述式只會傳回第一個查詢回應。
**Aurora Serverless v2**
不支援多陳述式。嘗試在單一 API 呼叫中執行多個陳述式會傳回 `“An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.”`。若要執行多個陳述式，請分別進行 `ExecuteStatement` API 呼叫或使用 `BatchExecuteStatement` 進行批次處理。
下列範例顯示 API 呼叫所產生的錯誤訊息，此 API 呼叫會嘗試執行多陳述式。
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table; Select * FROM next_table;
"An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.
```
下列範例會使用不同的 `ExecuteStatement` API 呼叫執行多個陳述式。
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table;"
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM next_table;"
```
## 相同交易 ID 的並行請求
**Aurora Serverless v1**
後續請求會等到目前的請求完成。如果等待期間過長，應用程式需要處理逾時錯誤。
**Aurora Serverless v2**
當資料 API 收到具有相同交易 ID 的多個請求時，其會立即傳回此錯誤：
`DatabaseErrorException: Transaction is still running a query`
此錯誤會在兩種情況下發生：
+ 應用程式會使用相同的交易 ID 提出異步請求 (例如 JavaScript 承諾)。
+ 具有該交易 ID 的先前請求仍在處理中。
下列範例顯示與 `promise.all()` 平行執行的所有請求。
```
const api_calls = [];
for (let i = 0; i < 10; i++) {
api_calls.push(
client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
)
);
}
await Promise.all(api_calls);
```
若要解決此錯誤，請等待目前的請求完成，再傳送另一個具有相同交易 ID 的請求，或移除交易 ID 以允許平行請求。
下列範例顯示的 API 呼叫會使用具有相同交易 ID 的循序執行。
```
for (let i = 0; i < 10; i++) {
await client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
).promise()
);
}
```
## BatchExecuteStatement 行為
如需 `BatchExecuteStatement` 的詳細資訊，請參閱 [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html)。
**Aurora Serverless v1**
更新結果中產生的欄位物件包含插入的值。
**Aurora Serverless v2**
+ 對於 Aurora MySQL，更新結果中產生的欄位物件包含插入的值。
+ 對於 Aurora PostgreSQL，產生的欄位物件是空的。
## ExecuteSQL 行為
如需 `ExecuteSQL` 的詳細資訊，請參閱 [ExecuteSQL](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteSql.html)。
**Aurora Serverless v1**
`ExecuteSQL` 操作已棄用。
**Aurora Serverless v2**
不支援 `ExecuteSQL` 操作。
## ExecuteStatement 行為
如需 `ExecuteStatement` 的詳細資訊，請參閱 [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html)。
**Aurora Serverless v1**
`ExecuteStatement` 參數支援擷取多維陣列欄和所有進階資料類型。
**Aurora Serverless v2**
`ExecuteStatement` 參數不支援多維陣列欄。其也不支援某些 PostgreSQL 資料類型 (包括幾何和貨幣類型)。當資料 API 遇到不支援的資料類型時，其會傳回此錯誤：`UnsupportedResultException: The result contains the unsupported data type data_type`。
若要解決此問題，請將不支援的資料類型轉換為 `TEXT`。下列範例會將不支援的資料類型轉換為 `TEXT`。
```
SELECT custom_type::TEXT FROM my_table;--
ORSELECT CAST(custom_type AS TEXT) FROM my_table;
```
如需每個 Aurora 資料庫引擎支援的資料類型清單，請參閱[資料 API 操作參考](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html#data-api-operations)。
## 結構描述參數行為
**Aurora Serverless v1**
不支援 `Schema` 參數。當您在 API 呼叫中包含 `Schema` 參數時，資料 API 會忽略此參數。
**Aurora Serverless v2**
`Schema` 參數已棄用。當您在 API 呼叫中包含 `Schema` 參數時，資料 API 會傳回此錯誤：`ValidationException: The schema parameter isn't supported`。下列範例顯示傳回 `ValidationException` 錯誤的資料 API 呼叫。
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--schema "your_schema" \
--sql "SELECT * FROM your_table LIMIT 10"
```
若要解決此問題，請從 API 呼叫中移除 `Schema` 參數。
下列範例顯示已移除 `Schema` 參數的資料 API 呼叫。
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table LIMIT 10"
```
# 授權 Amazon RDS 資料 API 的存取
使用者獲得授權後才能調用 Amazon RDS 資料 API (資料 API) 作業。您可以連接定義其權限的 AWS Identity and Access Management (IAM) 政策，授予使用者使用資料 API 的許可。如果您使用的是 IAM 角色，也可以將政策連接至角色。 AWS 受管政策 `AmazonRDSDataFullAccess`包含資料 API 的許可。
此`AmazonRDSDataFullAccess`政策也包含使用者從中取得秘密值的許可 AWS Secrets Manager。使用者需要使用 Secrets Manager 來儲存可在呼叫資料 API 時使用的秘密。使用秘密表示使用者不需要在呼叫資料 API 時包含其目標資源的資料庫登入資料。資料 API 會透明地呼叫 Secrets Manager，以允許 (或拒絕) 使用者對秘密的請求。如需設定秘密以搭配資料 API 使用的相關資訊，請參閱[在 中存放資料庫登入資料 AWS Secrets Manager](#data-api.secrets)。
`AmazonRDSDataFullAccess` 政策提供資源的完整存取 (透過資料 API)。您可以透過定義自己的政策來指定資源的 Amazon Resource Name (ARN)，藉以縮小範圍。
例如，下列政策顯示使用者存取其 ARN 所識別之資料庫叢集之資料 API 的最低所需許可範例。該政策包括存取 Secrets Manager 和取得使用者資料庫執行個體授權所需的許可。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerDbCredentialsAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*"
},
{
"Sid": "RDSDataServiceAccess",
"Effect": "Allow",
"Action": [
"rds-data:BatchExecuteStatement",
"rds-data:BeginTransaction",
"rds-data:CommitTransaction",
"rds-data:ExecuteStatement",
"rds-data:RollbackTransaction"
],
"Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod"
}
]
}
```
------
我們建議您針對政策陳述式中的「資源」元素使用特定 ARN (如範例所示)，而不是萬用字元 (\$1)。
## 使用標籤型授權
RDS 資料 API (資料 API) 和 Secrets Manager 都支援標籤型授權。*標籤*是用來標示資源 (例如 RDS 叢集) 的索引鍵值配對，並具有額外的字串值，例如：
+ `environment:production`
+ `environment:development`
您可以將標籤套用至資源，以進行成本配置、作業支援、存取控制和許多其他原因。(如果您的資源上還沒有標籤，而您想要套用標籤，您可至[標記 Amazon RDS 資源](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_Tagging.html)中進一步了解。) 您可以在政策陳述式中使用標籤來限制對以這些標籤標示之 RDS 叢集的存取。舉例來說，Aurora 資料庫叢集可能具有用來將其環境標識為生產或開發的標籤。
下列範例顯示如何在政策陳述式中使用標籤。此陳述式要求叢集和資料 API 要求中傳遞的秘密都有一個 `environment:production` 標籤。
以下是套用政策的方式：當使用者使用資料 API 進行呼叫時，會將要求傳送至服務。資料 API 首先驗證在請求中傳遞的叢集 ARN 是否標記了 `environment:production`。然後，它會呼叫 Secrets Manager 擷取請求中的使用者秘密值。Secrets Manager 還會驗證使用者的秘密是否被標記為 `environment:production`。如果有，資料 API 接著會使用使用者資料庫密碼的擷取值。最後，如果這也是正確的，則會為使用者成功地呼叫資料 API 請求。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerDbCredentialsAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
},
{
"Sid": "RDSDataServiceAccess",
"Effect": "Allow",
"Action": [
"rds-data:*"
],
"Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
}
]
}
```
------
此範例顯示適用於資料 API 和 Secrets Manager 之 `rds-data` 和 `secretsmanager` 的個別動作。但是，您可以合併動作並以許多不同的方式定義標籤條件，以支援您的特定使用案例。如需詳細資訊，請參閱[針對 Secrets Manager 使用以身分為基礎的政策 (IAM 政策)](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html#permissions_grant-limited-condition)。
在政策的「條件」元素中，您可以從以下選項中選擇標籤鍵：
+ `aws:TagKeys`
+ `aws:ResourceTag/${TagKey}`
若要進一步了解資源標籤和如何使用 `aws:TagKeys`，請參閱[使用 AWS 資源標籤控制對資源的存取](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys)。
**注意**
資料 API 和 都會 AWS Secrets Manager 授權使用者。如果您沒有政策中定義之所有動作的許可，您會收到 `AccessDeniedException` 錯誤訊息。
## 在 中存放資料庫登入資料 AWS Secrets Manager
當您呼叫 Amazon RDS 資料 API (資料 API) 時，您可以在 Secrets Manager 中使用秘密來傳遞Aurora 資料庫叢集的憑證。若要這樣傳遞登入資料，請指定秘密的名稱或秘密的 Amazon Resource Name (ARN)。
**在秘密中存放資料庫叢集登入資料**
1. 使用 Secrets Manager 建立秘密，其中含有 Aurora 資料庫叢集的登入資料。
如需說明，請參閱《*AWS Secrets Manager 使用者指南*》中的[建立資料庫機密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_database_secret.html)。
1. 使用 Secrets Manager 主控台來檢視您建立之秘密的詳細資訊，或執行 `aws secretsmanager describe-secret` AWS CLI 命令。
記下秘密的名稱和 ARN。在呼叫資料 API 時即可派上用場。
如需使用 Secrets Manager 的詳細資訊，請參閱 [AWS Secrets Manager 使用者指南](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。
若要了解 Amazon Aurora 如何管理身分識別和存取管理，請參閱 [Amazon Aurora 如何搭配 IAM使用](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/security_iam_service-with-iam.html)。
如需有關建立 IAM 政策的詳細資訊，請參閱*IAM 使用者指南*中的[建立 IAM 政策](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)。如需有關將 IAM 政策新增給使用者的資訊，請參閱 *IAM 使用者指南*中的[新增和移除 IAM 身分許可](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
# 啟用 Amazon RDS 資料 API
若要使用 Amazon RDS 資料 API (資料 API)，請為 Aurora 資料庫叢集將其啟用。您可以在建立或修改資料庫叢集時啟用資料 API。
**注意**
叢集是否可使用資料 API，取決於您的 Aurora 版本、資料庫引擎和 AWS 區域。對於較舊的 Aurora 版本，資料 API 僅適用於 Aurora Serverless v1 叢集。對於較新的 Aurora 版本，資料 API 適用於同時使用佈建和 Aurora Serverless v2 執行個體的叢集。若要檢查叢集是否可以使用資料 API，請參閱 [RDS 資料 API 的支援區域和 Aurora 資料庫引擎](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md)。
**Topics**
+ [建立資料庫時啟用 RDS 資料 API](#data-api.enabling.creating)
+ [在現有資料庫啟用 RDS 資料 API](#data-api.enabling.modifying)
## 建立資料庫時啟用 RDS 資料 API
當您建立的是支援 RDS 資料 API (資料 API) 的資料庫時，您可以啟用此功能。下列程序說明如何在使用 AWS 管理主控台 AWS CLI、 或 RDS API 時執行此操作。
### 主控台
如下列螢幕擷取畫面所示，若要在建立資料庫叢集時啟用資料 API，請選取**建立資料庫**頁面的**連線**區段中**啟用 RDS 資料 API** 核取方塊。
![\[[建立資料庫] 頁面上的 [連線] 區段，其中已選取 [啟用 RDS 資料 API] 核取方塊。\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-on-create.png)
如需如何建立可使用 RDS 資料 API 的 Aurora 資料庫叢集的說明，請參閱下文：
+ 對於 Aurora Serverless v2 和佈建的叢集：[建立 Amazon Aurora 資料庫叢集](Aurora.CreateInstance.md)
+ 對於 Aurora Serverless v1：[建立 Aurora Serverless v1 資料庫叢集](aurora-serverless.create.md)
### AWS CLI
若要在建立 Aurora 資料庫叢集時啟用資料 API，請使用 `--enable-http-endpoint`選項執行 [create-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-cluster.html) AWS CLI 命令。
下列範例會建立已啟用資料 API 的 Aurora PostgreSQL 資料庫叢集。
對於 Linux、macOS 或 Unix：
```
aws rds create-db-cluster \
--db-cluster-identifier my_pg_cluster \
--engine aurora-postgresql \
--enable-http-endpoint
```
在 Windows 中：
```
aws rds create-db-cluster ^
--db-cluster-identifier my_pg_cluster ^
--engine aurora-postgresql ^
--enable-http-endpoint
```
### RDS API
若要在建立 Aurora 資料庫叢集時啟用資料 API，請使用 [CreateDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBCluster.html) 操作，並將 `EnableHttpEndpoint` 參數的值設為 `true`。
## 在現有資料庫啟用 RDS 資料 API
您可以修改支援 RDS 資料 API (資料 API) 的資料庫叢集，即可啟用或停用此功能。
**Topics**
+ [啟用或停用資料 API (Aurora Serverless v2 和已佈建)](#data-api.enabling.modifying.all)
+ [啟用或停用資料 API (僅限 Aurora Serverless v1)](#data-api.enabling.modifying.sv1)
### 啟用或停用資料 API (Aurora Serverless v2 和已佈建)
使用下列程序啟用或停用 Aurora Serverless v2 和佈建資料庫的資料 API。若要啟用或停用在 Aurora Serverless v1 資料庫的資料 API，請使用 [啟用或停用資料 API (僅限 Aurora Serverless v1)](#data-api.enabling.modifying.sv1) 中的程序。
#### 主控台
您可以使用支援此功能之資料庫叢集的 RDS 主控台，來啟用或停用資料 API。若要這樣做，請開啟您要啟用或停用資料 API 之資料庫的叢集詳細資訊頁面，然後在**連線與安全**索引標籤，前往 **RDS 資料 API** 區段。本節顯示資料 API 的狀態，並允許您將其啟用或停用。
下列螢幕擷取畫面顯示未啟用的 **RDS 資料 API**。
![\[資料庫叢集詳細資訊頁面的 [連線和安全] 索引標籤上的 [RDS 資料 API] 區段。資料 API 的狀態會顯示為已停用，並且存在 [啟用 RDS 資料 API] 按鈕。\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-from-details.png)
#### AWS CLI
若要啟用或停用現有資料庫上的資料 API，請執行 [enable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/enable-http-endpoint.html) 或 [disable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/disable-http-endpoint.html) AWS CLI 命令，並指定資料庫叢集的 ARN。
下列範例會啟用資料 API。
對於 Linux、macOS 或 Unix：
```
aws rds enable-http-endpoint \
--resource-arn cluster_arn
```
在 Windows 中：
```
aws rds enable-http-endpoint ^
--resource-arn cluster_arn
```
#### RDS API
若要啟用或停用現有資料庫上的資料 API，請使用 [EnableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_EnableHttpEndpoint.html) 和 [DisableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DisableHttpEndpoint.html) 操作。
### 啟用或停用資料 API (僅限 Aurora Serverless v1)
使用下列程序來啟用或停用現有 Aurora Serverless v1 資料庫的資料 API。若要在 Aurora Serverless v2 和佈建的資料庫啟用或停用資料 API，請使用 [啟用或停用資料 API (Aurora Serverless v2 和已佈建)](#data-api.enabling.modifying.all) 中的程序。
#### 主控台
修改 Aurora Serverless v1 資料庫叢集時，在 RDS 主控台的**連線** 區段中啟用資料 API。
下列螢幕擷取畫面顯示修改 Aurora DB 資料庫叢集時啟用的**資料 API**。
![\[[修改資料庫叢集] 頁面上的 [連線] 區段，已選取 [資料 API] 核取方塊。\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/AuroraUserGuide/images/data-api-modify-serverlessv1.png)
如需如何修改 Aurora Serverless v1 資料庫叢集的指示，請參閱[修改 Aurora Serverless v1 資料庫叢集](aurora-serverless.modifying.md)。
#### AWS CLI
若要啟用或停用資料 API，`--no-enable-http-endpoint`請視需要使用 `--enable-http-endpoint`或 執行 [modify-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-cluster.html) AWS CLI 命令。
下列範例會在 `sample-cluster` 啟用資料 API。
對於 Linux、macOS 或 Unix：
```
aws rds modify-db-cluster \
--db-cluster-identifier sample-cluster \
--enable-http-endpoint
```
在 Windows 中：
```
aws rds modify-db-cluster ^
--db-cluster-identifier sample-cluster ^
--enable-http-endpoint
```
#### RDS API
若要啟用資料 API，請使用 [ModifyDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBCluster.html) 操作，以及視需要將 `EnableHttpEndpoint` 的值設為 `true` 或 `false`。
# 建立 Amazon RDS 資料 API 的 Amazon VPC 端點 (AWS PrivateLink)
Amazon VPC 可讓您在虛擬私有雲端 (VPC) 中啟動 AWS 資源，例如 Aurora 資料庫叢集和應用程式。 AWS PrivateLink 在 Amazon 網路上提供具有高安全性VPCs AWS 和服務之間的私有連線。您可以使用 AWS PrivateLink建立 Amazon VPC 端點，讓您根據 Amazon VPC 連線到不同帳戶和 VPCs 的服務。如需 AWS PrivateLink的相關資訊，請參閱《Amazon Virtual Private Cloud 使用者指南》**中的 [VPC 端點服務 (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html)。
您可以使用 Amazon VPC 端點呼叫 RDS 資料 API (資料 API)。使用 Amazon VPC 端點可在 Amazon VPC 中的應用程式與 AWS 網路中的資料 API 之間保留流量，而無需使用公有 IP 地址。Amazon VPC 端點能協助您符合與限制公有網際網路連線相關的合規和法律需求。舉例來說，若使用 Amazon VPC 端點，就能讓在 Amazon EC2 執行個體上執行之應用程式和資料 API 的流量只在包含兩者的 VPC 中傳送。
建立 Amazon VPC 端點之後就能開始使用，而不需要在應用程式中進行任何程式碼或組態變更。
**建立資料 API 的 Amazon VPC 端點**
1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)：// 開啟 Amazon VPC 主控台。
1. 選擇 **Endpoints (端點)**，然後選擇 **Create Endpoint (建立端點)**。
1. 在 **Create Endpoint** (建立端點) 頁面上，針對 **Service category** (服務類別) 選擇 **AWS services** ( 服務)。針對 **Service Name (服務名稱)**，選擇 **rds-data**。
![\[為資料 API 建立 Amazon VPC 端點\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/AuroraUserGuide/images/data-api-create-endpoint.png)
1. 針對 **VPC**，選擇要在其中建立端點的 VPC。
選擇包含進行資料 API 呼叫之應用程式的 VPC。
1. 針對**子網路**，選擇執行您應用程式之 AWS 服務所使用的每個可用區域 (AZ) 的子網路。
![\[為 Amazon VPC 端點選擇子網路\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-subnets.png)
若要建立 Amazon VPC 端點，請指定可存取端點的私有 IP 地址範圍。若要執行此作業，請選擇每個可用區域的子網路。這麼做會將 VPC 端點限制為每個可用區域專屬的私有 IP 地址範圍，並且也會在每個可用區域中建立 Amazon VPC 端點。
1. 針對 **Enable DNS name (啟用 DNS 名稱)**，選取 **Enable for this endpoint (為此端點啟用)**。
![\[啟用 Amazon VPC 端點的 DNS 名稱\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-enable-endpoint.png)
私有 DNS 會將標準資料 API DNS 主機名稱 (`https://rds-data.region.amazonaws.com`) 解析為與您 Amazon VPC 端點專用 DNS 主機名稱相關的私有 IP 地址。因此，您可以使用 AWS CLI AWS SDKs存取資料 API VPC 端點，而不需要進行任何程式碼或組態變更來更新資料 API 的端點 URL。
1. 針對 **Security group (安全群組)**，選擇要與 Amazon VPC 端點建立關聯的安全群組。
選擇允許存取執行您應用程式之 AWS 服務的安全群組。舉例來說，若有 Amazon EC2 執行個體在執行您的應用程式，請選擇要允許存取 Amazon EC2 執行個體的安全群組。安全群組能讓您控制 VPC 中，資源流向 Amazon VPC 端點的流量。
1. 針對 **Policy (政策)**，請選擇 **Full Access (完整存取)** 讓 Amazon VPC 中的所有人都能透過此端點存取資料 API。或者選擇 **Custom (自訂)**，來指定限制存取的政策。
如果您選擇 **Custom (自訂)**，請在政策建立工具中輸入政策。
1. 選擇 **Create endpoint (建立端點)**。
建立端點之後，請選擇 中的連結 AWS 管理主控台 以檢視端點詳細資訊。
![\[Amazon VPC 端點詳細資訊的連結\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-link-to-details.png)
端點 **Details (詳細資訊)** 標籤會顯示建立 Amazon VPC 端點時產生的 DNS 主機名稱。
![\[Amazon VPC 端點詳細資訊的連結\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-dns-names.png)
您可以使用標準端點 (`rds-data.region.amazonaws.com`) 或其中一個 VPC 專用端點，來在 Amazon VPC 中呼叫資料 API。標準資料 API 端點會自動路由至 Amazon VPC 端點。因為私有 DNS 主機名稱在 Amazon VPC 端點建立時已啟用，所以會發生此路由。
當您在資料 API 呼叫中使用 Amazon VPC 端點時，應用程式與資料 API 間的所有流量都會維持在包含兩者的 Amazon VPC 中。您可以使用 Amazon VPC 端點進行任何類型的資料 API 呼叫。如需呼叫資料 API 的詳細資訊，請參閱[呼叫 Amazon RDS 資料 API](data-api.calling.md)。
# 呼叫 Amazon RDS 資料 API
在 Aurora 資料庫叢集啟用 Amazon RDS 資料 API (資料 API) 後，您可以使用資料 API 或 AWS CLI，在 Aurora 資料庫叢集執行 SQL 陳述式。資料 API 支援 AWS 開發套件支援的程式設計語言。如需詳細資訊，請參閱[在 AWS 上建置的工具](https://aws.amazon.com/tools/)。
**Topics**
+ [Amazon RDS 資料 API 操作參考](data-api-operations.md)
+ [使用 AWS CLI 呼叫 Amazon RDS 資料 API](data-api.calling.cli.md)
+ [透過 Python 應用程式呼叫 Amazon RDS 資料 API](data-api.calling.python.md)
+ [透過 Java 應用程式呼叫 Amazon RDS 資料 API](data-api.calling.java.md)
+ [控制資料 API 逾時行為](data-api-timeouts.md)
# Amazon RDS 資料 API 操作參考
Amazon RDS 資料 API 會提供以下操作來執行 SQL 陳述式。
****
| 資料 API 操作 | AWS CLI 命令 | Description |
| --- | --- | --- |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html) | 在資料庫上執行 SQL 陳述式。 |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html) | 透過對資料陣列執行批次 SQL 陳述式來進行大量更新和插入操作。您可以使用參數集陣列來執行資料處理語言 (DML) 陳述式。批次 SQL 陳述式可針對個別插入和更新陳述式提供明顯的效能改善。 |
您可以使用任一操作來執行個別 SQL 陳述式或執行交易。針對交易，資料 API 會提供以下操作。
****
| 資料 API 操作 | AWS CLI 命令 | Description |
| --- | --- | --- |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html) | 開始 SQL 交易。 |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html) | 結束 SQL 交易並遞交變更。 |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html) | 執行交易轉返。 |
執行 SQL 陳述式和支援交易的操作具有下列常見的資料 API 參數和 AWS CLI 選項。有些操作支援其他參數或選項。
****
| 資料 API 操作參數 | AWS CLI 命令選項 | 必要 | 描述 |
| --- | --- | --- | --- |
| `resourceArn` | `--resource-arn` | 是 | Aurora 資料庫叢集的 Amazon Resource Name (ARN)。叢集必須與叫用資料 API AWS 帳戶 的 IAM 角色或使用者位於相同的 中。若要存取不同帳戶中的叢集，請擔任該帳戶中的角色。 |
| `secretArn` | `--secret-arn` | 是 | 用來允許存取資料庫叢集之秘密的名稱或 ARN。 |
RDS 資料 API 支援 Aurora MySQL 的下列資料類型：
+ `TINYINT(1)`, `BOOLEAN`, `BOOL`
+ `TINYINT`
+ `SMALLINT` [`SIGNED` \$1 `UNSIGNED`]
+ `MEDIUMINT` [`SIGNED` \$1 `UNSIGNED`]
+ `INT` [`SIGNED` \$1 `UNSIGNED`]
+ `BIGINT` [`SIGNED` \$1 `UNSIGNED`]
+ `FLOAT`
+ `DOUBLE`
+ `VARCHAR`, `CHAR`, `TEXT`, `ENUM`
+ `VARBINARY`, `BINARY`, `BLOB`
+ `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`
+ `DECIMAL`
+ `JSON`
+ `BIT`, `BIT(N)`
RDS 資料 API 支援下列 Aurora PostgreSQL 純量類型：
+ `BOOL`
+ `BYTEA`
+ `DATE`
+ `CIDR`
+ `DECIMAL`, `NUMERIC`
+ `ENUM`
+ `FLOAT8`, `DOUBLE PRECISION`
+ `INET`
+ `INT`, `INT4`, `SERIAL`
+ `INT2`, `SMALLINT`, `SMALLSERIAL`
+ `INT8`, `BIGINT`, `BIGSERIAL`
+ `JSONB`, `JSON`
+ `REAL`, `FLOAT`
+ `TEXT`, `CHAR(N)`, `VARCHAR`, `NAME`
+ `TIME`
+ `TIMESTAMP`
+ `UUID`
+ `VECTOR`
RDS 資料 API 支援下列 Aurora PostgreSQL 陣列類型：
+ `BOOL[]`, `BIT[]`
+ `DATE[]`
+ `DECIMAL[]`, `NUMERIC[]`
+ `FLOAT8[]`, `DOUBLE PRECISION[]`
+ `INT[]`, `INT4[]`
+ `INT2[]`
+ `INT8[]`, `BIGINT[]`
+ `JSON[]`
+ `REAL[]`, `FLOAT[]`
+ `TEXT[]`, `CHAR(N)[]`, `VARCHAR[]`, `NAME[]`
+ `TIME[]`
+ `TIMESTAMP[]`
+ `UUID[]`
您可以在對 `ExecuteStatement`和 進行資料 API 呼叫`BatchExecuteStatement`，以及在執行 AWS CLI 命令`execute-statement`和 時使用參數`batch-execute-statement`。若要使用參數，請在 `SqlParameter` 資料類型中指定名稱/值對。您使用 `Field` 資料類型來指定值。下表會將 Java Database Connectivity (JDBC) 資料類型映射至您在資料 API 呼叫中指定的資料類型。
****
| JDBC 資料類型 | 資料 API 資料類型 |
| --- | --- |
| `INTEGER, TINYINT, SMALLINT, BIGINT` | `LONG` – 、 或 `STRING` |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY, VARBINARY` | `BLOB` |
| `CLOB` | `STRING` |
| 其他類型 (包含與日期和時間相關的類型) | `STRING` |
**注意**
您可以在 `LONG` 資料 API 呼叫中，針對資料庫傳回的 `STRING` 值指定 `LONG` 或資料類型。我們建議您這麼做，以避免失去極大數字的精確度，您在使用 JavaScript 時可能會發生這種情況。
某些類型 (例如 `DECIMAL` 和 `TIME`) 需要提示，以便資料 API 以正確的類型將 `String` 值傳遞給資料庫。若要使用提示，請在 `typeHint` 資料類型中包含 `SqlParameter` 的值。`typeHint` 可能的值如下：
+ `DATE` – 對應的 `String` 參數值以 `DATE` 類型的物件傳送至資料庫。接受的格式為 `YYYY-MM-DD`。
+ `DECIMAL` – 對應的 `String` 參數值以 `DECIMAL` 類型的物件傳送至資料庫。
+ `JSON` – 對應的 `String` 參數值以 `JSON` 類型的物件傳送至資料庫。
+ `TIME` – 對應的 `String` 參數值以 `TIME` 類型的物件傳送至資料庫。接受的格式為 `HH:MM:SS[.FFF]`。
+ `TIMESTAMP` – 對應的 `String` 參數值以 `TIMESTAMP` 類型的物件傳送至資料庫。接受的格式為 `YYYY-MM-DD HH:MM:SS[.FFF]`。
+ `UUID` – 對應的 `String` 參數值以 `UUID` 類型的物件傳送至資料庫。
**注意**
目前，資料 API 不支援通用唯一識別符 (UUID) 的陣列。
**注意**
對於 Amazon Aurora PostgreSQL，資料 API 始終以 UTC 時區返回 Aurora PostgreSQL 資料類型 `TIMESTAMPTZ`。
# 使用 AWS CLI 呼叫 Amazon RDS 資料 API
您可以使用 AWS CLI 呼叫 RDS 資料 API(資料 API)。
下列範例會使用 AWS CLI 來呼叫資料 API。如需詳細資訊，請參閱[資料 API 的 AWS CLI 參考](https://docs.aws.amazon.com/cli/latest/reference/rds-data/index.html)。
在每個範例中，將資料庫叢集的 Amazon Resource Name (ARN) 取代為 Aurora 資料庫叢集的 ARN。同時也將秘密 ARN 取代為 Secrets Manager 中允許存取資料庫叢集的秘密 ARN。
**注意**
AWS CLI 可以將回應設為 JSON 格式。
**Topics**
+ [開始 SQL 交易](#data-api.calling.cli.begin-transaction)
+ [執行 SQL 陳述式](#data-api.calling.cli.execute-statement)
+ [透過資料陣列來執行批次 SQL 陳述式](#data-api.calling.cli.batch-execute-statement)
+ [遞交 SQL 交易](#data-api.calling.cli.commit-transaction)
+ [復原 SQL 交易](#data-api.calling.cli.rollback-transaction)
## 開始 SQL 交易
您可以使用 `aws rds-data begin-transaction` CLI 命令來開始 SQL 交易。此呼叫會傳回交易識別符。
**重要**
在資料 API 內，如果三分鐘內沒有使用交易 ID 的任何呼叫，交易就會逾時。如果交易在遞交前就逾時，則資料 API 會自動將其復原。
交易中的 MySQL 資料定義語言 (DDL) 陳述式會導致隱含遞交。我們建議您使用 `execute-statement` 選項在個別的 `--continue-after-timeout` 命令中執行每個 MySQL DDL 陳述式。
除了常用選項之外，還將指定 `--database` 選項，其提供資料庫的名稱。
例如，以下 CLI 命令會開始 SQL 交易。
對於 Linux、macOS 或 Unix：
```
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
```
在 Windows 中：
```
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
```
以下是回應的範例。
```
{
"transactionId": "ABC1234567890xyz"
}
```
## 執行 SQL 陳述式
您可以使用 `aws rds-data execute-statement` CLI 命令來執行 SQL 陳述式。
您可以透過使用 `--transaction-id` 選項指定交易識別符，來在交易中執行 SQL 陳述式。您可以使用 `aws rds-data begin-transaction` CLI 命令來開始交易。您可以使用 `aws rds-data commit-transaction` CLI 命令來結束和遞交交易。
**重要**
如果您沒有指定 `--transaction-id` 選項，系統就會自動遞交呼叫造成的變更。
除了常用的選項，請指定以下選項：
+ `--sql` (必要) – 在資料庫叢集上執行的 SQL 陳述式。
+ `--transaction-id` (選用) – 使用 `begin-transaction` CLI 命令開始的交易識別符。指定您要在其中包含 SQL 陳述式的交易 ID。
+ `--parameters` (選用) – SQL 陳述式的參數。
+ `--include-result-metadata | --no-include-result-metadata` (選用) – 此值會指出是否在結果中包含中繼資料。預設值為 `--no-include-result-metadata`。
+ `--database` (選用) – 資料庫的名稱。
當您在先前請求中執行 `--sql "use database_name;"` 之後執行 SQL 陳述式時，`--database` 選項可能無法運作。建議您使用 `--database` 選項，而不是執行 `--sql "use database_name;"` 陳述式。
+ `--continue-after-timeout | --no-continue-after-timeout` (選用)：此值會指出在呼叫超過 45 秒的資料 API 逾時間隔後是否繼續執行陳述式。預設值為 `--no-continue-after-timeout`。
對於資料定義語言 (DDL) 陳述式，我們建議在呼叫逾時後繼續執行陳述式，來避免錯誤和資料結構毀損的可能性。
+ `--format-records-as "JSON"|"NONE"` – 選用值，指定是否將結果集格式化為 JSON 字串。預設值為 `"NONE"`。如需處理 JSON 結果集的使用情況資訊，請參閱[以 JSON 格式處理 Amazon RDS 資料 API 查詢結果](data-api-json.md)。
資料庫叢集會傳回呼叫的回應。
**注意**
回應大小限制為 1 MiB。若呼叫傳回的回應資料超過 1 MiB，系統就會終止呼叫。
對於 Aurora Serverless v1，每秒請求數上限為 1,000。對於所有其他支援的資料庫，沒有限制。
例如，以下 CLI 命令會執行單一 SQL 陳述式並省略結果中的中繼資料 (預設值)。
對於 Linux、macOS 或 Unix：
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "select * from mytable"
```
在 Windows 中：
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "select * from mytable"
```
以下是回應的範例。
```
{
"numberOfRecordsUpdated": 0,
"records": [
[
{
"longValue": 1
},
{
"stringValue": "ValueOne"
}
],
[
{
"longValue": 2
},
{
"stringValue": "ValueTwo"
}
],
[
{
"longValue": 3
},
{
"stringValue": "ValueThree"
}
]
]
}
```
以下 CLI 命令會透過指定 `--transaction-id` 選項來在交易中執行單一 SQL 陳述式。
對於 Linux、macOS 或 Unix：
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
```
在 Windows 中：
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
```
以下是回應的範例。
```
{
"numberOfRecordsUpdated": 1
}
```
以下 CLI 命令會執行含參數的單一 SQL 陳述式。
對於 Linux、macOS 或 Unix：
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
```
在 Windows 中：
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
```
以下是回應的範例。
```
{
"numberOfRecordsUpdated": 1
}
```
以下 CLI 命令會執行資料定義語言 (DDL) SQL 陳述式。DDL 陳述式會將 `job` 欄重新命名為欄 `role`。
**重要**
對於 DDL 陳述式，我們建議在呼叫逾時後繼續執行陳述式。當 DDL 陳述式在完成執行前而終止時，可能會發生錯誤且資料結構可能毀損。若要在呼叫超過 45 秒的 RDS 資料 API 逾時間隔後繼續執行陳述式，請指定 `--continue-after-timeout` 選項。
對於 Linux、macOS 或 Unix：
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
```
在 Windows 中：
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
```
以下是回應的範例。
```
{
"generatedFields": [],
"numberOfRecordsUpdated": 0
}
```
**注意**
Aurora PostgreSQL 不支援 `generatedFields` 資料。若要取得所產生欄位的值，請使用 `RETURNING` 子句。如需詳細資訊，請參閱 PostgreSQL 中的[從修改後的資料列傳回資料](https://www.postgresql.org/docs/10/dml-returning.html)。
## 透過資料陣列來執行批次 SQL 陳述式
您可以透過使用 `aws rds-data batch-execute-statement` CLI 命令，透過資料陣列來執行批次 SQL 陳述式。您可以使用此命令來執行大量匯入或更新操作。
您可以透過使用 `--transaction-id` 選項指定交易識別符，來在交易中執行 SQL 陳述式。您可以透過使用 `aws rds-data begin-transaction` CLI 命令來開始交易。您可以透過使用 `aws rds-data commit-transaction` CLI 命令來結束和遞交交易。
**重要**
如果您沒有指定 `--transaction-id` 選項，系統就會自動遞交呼叫造成的變更。
除了常用的選項，請指定以下選項：
+ `--sql` (必要) – 在資料庫叢集上執行的 SQL 陳述式。
**提示**
對於 MySQL 相容的陳述句，請不要在 `--sql` 參數結尾包含分號。結尾分號可能會導致語法錯誤。
+ `--transaction-id` (選用) – 使用 `begin-transaction` CLI 命令開始的交易識別符。指定您要在其中包含 SQL 陳述式的交易 ID。
+ `--parameter-set` (選用) – 批次操作的參數組。
+ `--database` (選用) – 資料庫的名稱。
資料庫叢集會傳回呼叫的回應。
**注意**
參數組數目並無固定上限。不過，透過資料 API 提交的 HTTP 請求大小上限為 4 MiB。若請求超過此限制，資料 API 會傳回錯誤，不會處理請求。此 4 MiB 限制包括 HTTP 標頭的大小和請求中的 JSON 標記法。因此，您可包含的參數集數目取決於因素組合，例如 SQL 陳述式的大小和每個參數集的大小。
回應大小限制為 1 MiB。若呼叫傳回的回應資料超過 1 MiB，系統就會終止呼叫。
對於 Aurora Serverless v1，每秒請求數上限為 1,000。對於所有其他支援的資料庫，沒有限制。
例如，以下 CLI 命令會透過含參數組的資料陣列來執行批次 SQL 陳述式。
對於 Linux、macOS 或 Unix：
```
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" \
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
```
在 Windows 中：
```
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" ^
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
```
**注意**
請勿在 `--parameter-sets` 選項中包含分行符號。
## 遞交 SQL 交易
您可以使用 `aws rds-data commit-transaction` CLI 命令，來結束您透過 `aws rds-data begin-transaction` 開始的 SQL 交易和遞交變更。
除了常用的選項，請指定以下選項：
+ `--transaction-id` (必要) – 使用 `begin-transaction` CLI 命令開始的交易識別符。指定您要結束和遞交的交易 ID。
例如，以下 CLI 命令會結束 SQL 交易和遞交變更。
對於 Linux、macOS 或 Unix：
```
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"
```
在 Windows 中：
```
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"
```
以下是回應的範例。
```
{
"transactionStatus": "Transaction Committed"
}
```
## 復原 SQL 交易
您可以使用 `aws rds-data rollback-transaction` CLI 命令，來復原您透過 `aws rds-data begin-transaction` 開始的 SQL 交易。復原交易會取消其變更。
**重要**
如果交易 ID 已過期，系統會自動復原此交易。在這個情況下，指定此過期交易 ID 的 `aws rds-data rollback-transaction` 命令會傳回錯誤。
除了常用的選項，請指定以下選項：
+ `--transaction-id` (必要) – 使用 `begin-transaction` CLI 命令開始的交易識別符。指定您要復原的交易 ID。
例如，以下 AWS CLI 命令會復原 SQL 交易。
對於 Linux、macOS 或 Unix：
```
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"
```
在 Windows 中：
```
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"
```
以下是回應的範例。
```
{
"transactionStatus": "Rollback Complete"
}
```
# 透過 Python 應用程式呼叫 Amazon RDS 資料 API
您可以透過 Python 應用程式呼叫 Amazon RDS 資料 API (資料 API)。
以下範例會使用適用於 Python 的 AWS 開發套件 (Boto)。如需 Boto 的更多詳細資訊，請參閱[適用於 Python 的 AWS 開發套件 (Boto 3) 文件](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)。
在每個範例中，將資料庫叢集的 Amazon Resource Name (ARN) 取代為 Aurora 資料庫叢集的 ARN。同時也將秘密 ARN 取代為 Secrets Manager 中允許存取資料庫叢集的秘密 ARN。
**Topics**
+ [執行 SQL 查詢](#data-api.calling.python.run-query)
+ [執行 DML SQL 陳述式](#data-api.calling.python.run-inert)
+ [執行 SQL 交易](#data-api.calling.python.run-transaction)
## 執行 SQL 查詢
您可以執行 `SELECT` 陳述式並使用 Python 應用程式擷取結果。
以下範例會執行 SQL 查詢。
```
import boto3
rdsData = boto3.client('rds-data')
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
response1 = rdsData.execute_statement(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb',
sql = 'select * from employees limit 3')
print (response1['records'])
[
[
{
'longValue': 1
},
{
'stringValue': 'ROSALEZ'
},
{
'stringValue': 'ALEJANDRO'
},
{
'stringValue': '2016-02-15 04:34:33.0'
}
],
[
{
'longValue': 1
},
{
'stringValue': 'DOE'
},
{
'stringValue': 'JANE'
},
{
'stringValue': '2014-05-09 04:34:33.0'
}
],
[
{
'longValue': 1
},
{
'stringValue': 'STILES'
},
{
'stringValue': 'JOHN'
},
{
'stringValue': '2017-09-20 04:34:33.0'
}
]
]
```
## 執行 DML SQL 陳述式
您可以執行資料處理語言 (DML) 陳述式來插入、更新或刪除資料庫中的資料。您也可以在 DML 陳述式中使用參數。
**重要**
如果某個呼叫不包含 `transactionID` 參數而不屬於某個交易，則系統會自動遞交該呼叫造成的變更。
以下範例會執行插入 SQL 陳述式和使用參數。
```
import boto3
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
rdsData = boto3.client('rds-data')
param1 = {'name':'firstname', 'value':{'stringValue': 'JACKSON'}}
param2 = {'name':'lastname', 'value':{'stringValue': 'MATEO'}}
paramSet = [param1, param2]
response2 = rdsData.execute_statement(resourceArn=cluster_arn,
secretArn=secret_arn,
database='mydb',
sql='insert into employees(first_name, last_name) VALUES(:firstname, :lastname)',
parameters = paramSet)
print (response2["numberOfRecordsUpdated"])
```
## 執行 SQL 交易
您可以開始 SQL 交易、執行一或多個 SQL 陳述式，接著使用 Python 應用程式遞交變更。
**重要**
如果三分鐘內沒有使用交易 ID 的任何呼叫，交易就會逾時。如果交易在遞交前就逾時，則系統會自動將其復原。
如果您沒有指定交易 ID，系統就會自動遞交呼叫造成的變更。
以下範例執行的 SQL 交易會在資料表中插入資料列。
```
import boto3
rdsData = boto3.client('rds-data')
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
tr = rdsData.begin_transaction(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb')
response3 = rdsData.execute_statement(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb',
sql = 'insert into employees(first_name, last_name) values('XIULAN', 'WANG')',
transactionId = tr['transactionId'])
cr = rdsData.commit_transaction(
resourceArn = cluster_arn,
secretArn = secret_arn,
transactionId = tr['transactionId'])
cr['transactionStatus']
'Transaction Committed'
response3['numberOfRecordsUpdated']
1
```
**注意**
如果您執行的是資料定義語言 (DDL) 陳述式，我們建議在呼叫逾時後繼續執行陳述式。當 DDL 陳述式在完成執行前而終止時，可能會發生錯誤且資料結構可能毀損。若要在呼叫超過 45 秒的 RDS 資料 API 逾時間隔後繼續執行陳述式，請將 `continueAfterTimeout` 參數設為 `true`。
# 透過 Java 應用程式呼叫 Amazon RDS 資料 API
您可以透過 Java 應用程式呼叫 Amazon RDS 資料 API (資料 API)。
以下範例會使用適用於 Java 的 AWS 開發套件。如需詳細資訊，請參閱 [適用於 Java 的 AWS SDK 開發人員指南](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/welcome.html)。
在每個範例中，將資料庫叢集的 Amazon Resource Name (ARN) 取代為 Aurora 資料庫叢集的 ARN。同時也將秘密 ARN 取代為 Secrets Manager 中允許存取資料庫叢集的秘密 ARN。
**Topics**
+ [執行 SQL 查詢](#data-api.calling.java.run-query)
+ [執行 SQL 交易](#data-api.calling.java.run-transaction)
+ [執行批次 SQL 操作](#data-api.calling.java.run-batch)
## 執行 SQL 查詢
您可以執行 `SELECT` 陳述式並使用 Java 應用程式擷取結果。
以下範例會執行 SQL 查詢。
```
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementResult;
import com.amazonaws.services.rdsdata.model.Field;
import java.util.List;
public class FetchResultsExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
ExecuteStatementRequest request = new ExecuteStatementRequest()
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withDatabase("mydb")
.withSql("select * from mytable");
ExecuteStatementResult result = rdsData.executeStatement(request);
for (List fields: result.getRecords()) {
String stringValue = fields.get(0).getStringValue();
long numberValue = fields.get(1).getLongValue();
System.out.println(String.format("Fetched row: string = %s, number = %d", stringValue, numberValue));
}
}
}
```
## 執行 SQL 交易
您可以開始 SQL 交易、執行一或多個 SQL 陳述式，接著使用 Java 應用程式遞交變更。
**重要**
如果三分鐘內沒有使用交易 ID 的任何呼叫，交易就會逾時。如果交易在遞交前就逾時，則系統會自動將其復原。
如果您沒有指定交易 ID，系統就會自動遞交呼叫造成的變更。
以下範例會執行 SQL 交易。
```
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BeginTransactionRequest;
import com.amazonaws.services.rdsdata.model.BeginTransactionResult;
import com.amazonaws.services.rdsdata.model.CommitTransactionRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
public class TransactionExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
BeginTransactionRequest beginTransactionRequest = new BeginTransactionRequest()
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withDatabase("mydb");
BeginTransactionResult beginTransactionResult = rdsData.beginTransaction(beginTransactionRequest);
String transactionId = beginTransactionResult.getTransactionId();
ExecuteStatementRequest executeStatementRequest = new ExecuteStatementRequest()
.withTransactionId(transactionId)
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withSql("INSERT INTO test_table VALUES ('hello world!')");
rdsData.executeStatement(executeStatementRequest);
CommitTransactionRequest commitTransactionRequest = new CommitTransactionRequest()
.withTransactionId(transactionId)
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN);
rdsData.commitTransaction(commitTransactionRequest);
}
}
```
**注意**
如果您執行的是資料定義語言 (DDL) 陳述式，我們建議在呼叫逾時後繼續執行陳述式。當 DDL 陳述式在完成執行前而終止時，可能會發生錯誤且資料結構可能毀損。若要在呼叫超過 45 秒的 RDS 資料 API 逾時間隔後繼續執行陳述式，請將 `continueAfterTimeout` 參數設為 `true`。
## 執行批次 SQL 操作
您可以使用 Java 應用程式，透過資料陣列來執行大量插入和更新操作。您可以使用參數集陣列來執行 DML 陳述式。
**重要**
如果您沒有指定交易 ID，系統就會自動遞交呼叫造成的變更。
以下範例會執行批次插入操作。
```
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BatchExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.Field;
import com.amazonaws.services.rdsdata.model.SqlParameter;
import java.util.Arrays;
public class BatchExecuteExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
BatchExecuteStatementRequest request = new BatchExecuteStatementRequest()
.withDatabase("test")
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withSql("INSERT INTO test_table2 VALUES (:string, :number)")
.withParameterSets(Arrays.asList(
Arrays.asList(
new SqlParameter().withName("string").withValue(new Field().withStringValue("Hello")),
new SqlParameter().withName("number").withValue(new Field().withLongValue(1L))
),
Arrays.asList(
new SqlParameter().withName("string").withValue(new Field().withStringValue("World")),
new SqlParameter().withName("number").withValue(new Field().withLongValue(2L))
)
));
rdsData.batchExecuteStatement(request);
}
}
```
# 控制資料 API 逾時行為
對資料 API 的所有呼叫都是同步。假設您執行的是執行 SQL 陳述式的資料 API 操作，例如 `INSERT` 或 `CREATE TABLE`。如果資料 API 呼叫成功傳回，則 SQL 處理會在呼叫傳回時完成。
根據預設，如果操作未在 45 秒內完成處理，則資料 API 會取消操作並傳回逾時錯誤。在這種情況下，資料不會插入，資料表也不會建立，以此類推。
您可以使用資料 API，來執行無法在 45 秒內完成的長時間執行操作。如果您預期對大型資料表執行大量 `INSERT` 或 DDL 操作之類的操作需要超過 45 秒，您可以指定 `ExecuteStatement` 操作的 `continueAfterTimeout` 參數。應用程式仍會收到逾時錯誤。不過，操作會繼續執行，不會取消。如需範例，請參閱「[執行 SQL 交易](data-api.calling.java.md#data-api.calling.java.run-transaction)」。
如果程式設計語言 AWS 開發套件有自己的 API 呼叫或 HTTP 通訊端連線逾時期間，請確定所有這類逾時期間都超過 45 秒。對於某些 SDK，逾時期間預設為少於 45 秒。我們建議將任何 SDK 特定或用戶端特定逾時期間設定為至少一分鐘。這樣做可避免應用程式在資料 API 操作仍然成功完成時收到逾時錯誤的可能性。如此一來，您就可以確定是否要重試操作。
例如，假設 SDK 將逾時錯誤傳回至應用程式，但資料 API 操作仍在資料 API 逾時間隔內完成。在這種情況下，重試操作可能會插入重複的資料，否則會產生不正確的結果。開發套件可能會自動重試操作，導致資料有誤，而不需要來自應用程式的任何動作。
逾時間隔對於 Java 2 開發套件特別重要。在該開發套件中，API 呼叫逾時和 HTTP 通訊端逾時預設為 30 秒。以下是將這些逾時設為更高值的範例：
```
public RdsDataClient createRdsDataClient() {
return RdsDataClient.builder()
.region(Region.US_EAST_1) // Change this to your desired Region
.overrideConfiguration(createOverrideConfiguration())
.httpClientBuilder(createHttpClientBuilder())
.credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider
.build();
}
private static ClientOverrideConfiguration createOverrideConfiguration() {
return ClientOverrideConfiguration.builder()
.apiCallTimeout(Duration.ofSeconds(60))
.build();
}
private HttpClientBuilder createHttpClientBuilder() {
return ApacheHttpClient.builder() // Change this to your desired HttpClient
.socketTimeout(Duration.ofSeconds(60));
}
```
以下是使用異步資料用戶端的同等範例：
```
public static RdsDataAsyncClient createRdsDataAsyncClient() {
return RdsDataAsyncClient.builder()
.region(Region.US_EAST_1) // Change this to your desired Region
.overrideConfiguration(createOverrideConfiguration())
.credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider
.build();
}
private static ClientOverrideConfiguration createOverrideConfiguration() {
return ClientOverrideConfiguration.builder()
.apiCallAttemptTimeout(Duration.ofSeconds(60))
.build();
}
private HttpClientBuilder createHttpClientBuilder() {
return NettyNioAsyncHttpClient.builder() // Change this to your desired AsyncHttpClient
.readTimeout(Duration.ofSeconds(60));
}
```
# 使用適用於 RDS 資料 API 的 Java 用戶端程式庫
您可以下載與使用適用於 RDS 資料 API (資料 API) 的 Java 用戶端程式庫。此 Java 用戶端程式庫提供另一種使用資料 API 的方式。您可以使用此程式庫，將用戶端類別映射至資料 API 的要求和回應。此映射支援可以與某些特定的 Java 類型輕鬆整合，例如 `Date`、`Time` 和 `BigDecimal`。
## 下載適用於資料 API 的 Java 用戶端程式庫
資料 API Java 用戶端程式庫已在 GitHub 開放原始碼，並且可在以下位置取得：
[ https://github.com/awslabs/rds-data-api-client-library-java](https://github.com/awslabs/rds-data-api-client-library-java)
您可以從原始檔案手動建置程式庫，但最佳實務是使用 Apache Maven 相依性管理來取用程式庫。將以下相依性新增到您的 Maven POM 檔案。
對於與 AWS SDK 2.x 相容的 2.x 版，請使用下列項目：
```
software.amazon.rdsdata
rds-data-api-client-library-java
2.0.0
```
對於與 AWS SDK 1.x 相容的 1.x 版，請使用下列項目：
```
software.amazon.rdsdata
rds-data-api-client-library-java
1.0.8
```
## Java 用戶端程式庫範例
接下來，您可以找到一些關於使用資料 API Java 用戶端程式庫的常見範例。這些範例假設您有一個資料表 `accounts`，而資料表有兩欄：`accountId` 和 `name`。您還有下列資料傳輸物件 (DTO)。
```
public class Account {
int accountId;
String name;
// getters and setters omitted
}
```
用戶端程式可讓您以輸入參數傳遞 DTO。下列範例顯示客戶 DTO 如何映射至輸入參數集。
```
var account1 = new Account(1, "John");
var account2 = new Account(2, "Mary");
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParamSets(account1, account2)
.execute();
```
在某些情況下，以輸入參數處理簡單值比較輕鬆。作法是採用下列語法。
```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParameter("accountId", 3)
.withParameter("name", "Zhang")
.execute();
```
以下是另一個以輸入參數處理簡單值的範例。
```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
.execute();
```
用戶端程式庫可以在結果傳回時自動映射至 DTO。下列範例顯示結果如何映射至 DTO。
```
List result = client.forSql("SELECT * FROM accounts")
.execute()
.mapToList(Account.class);
Account result = client.forSql("SELECT * FROM accounts WHERE account_id = 1")
.execute()
.mapToSingle(Account.class);
```
在許多情況下，資料庫結果集只包含單一值。為了簡化擷取這些結果，用戶端程式庫提供以下 API：
```
int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
.execute()
.singleValue(Integer.class);
```
**注意**
`mapToList` 函數會將 SQL 結果集轉換為使用者定義的物件清單。我們並不支援在 Java 用戶端程式庫的 `ExecuteStatement` 呼叫中使用 `.withFormatRecordsAs(RecordsFormatType.JSON)` 陳述式，因為其具有相同目的。如需詳細資訊，請參閱[以 JSON 格式處理 Amazon RDS 資料 API 查詢結果](data-api-json.md)。
# 以 JSON 格式處理 Amazon RDS 資料 API 查詢結果
當您呼叫 `ExecuteStatement` 操作，可以選擇以 JSON 格式的字串形式傳回查詢結果。這樣，您就可以使用程式設計語言的 JSON 剖析功能來解讀和重新格式化結果集。這樣做有助於避免編寫額外的程式碼來對結果集執行迴圈並解讀每個欄值。
若要以 JSON 格式請求結果集，請傳遞選用 `formatRecordsAs` 參數並搭配 `JSON` 值。JSON 格式的結果集會在 `ExecuteStatementResponse` 結構的 `formattedRecords` 欄位中傳回。
`BatchExecuteStatement` 動作不會傳回結果集。因此，JSON 選項不適用於該動作。
若要自訂 JSON 雜湊結構中的鍵，請在結果集中定義欄別名。若要這麼做，請在 SQL 查詢的欄清單中使用 `AS` 子句。
您可以使用 JSON 功能讓結果集更易於閱讀，並將其內容映射到語言特定的架構。由於 ASCII 編碼的結果集的量大於預設表示形式，您可以為傳回大量列或大型欄值的查詢 (這些查詢消耗的記憶體超過應用程式可用的記憶體) 選擇預設表示法。
**Topics**
+ [以 JSON 格式擷取查詢結果](#data-api-json-querying)
+ [資料類型映射](#data-api-json-datatypes)
+ [故障診斷](#data-api-json-troubleshooting)
+ [範例](#data-api-json-examples)
## 以 JSON 格式擷取查詢結果
若要以 JSON 字串形式接收結果集，請在 `ExecuteStatement` 呼叫中加入 `.withFormatRecordsAs(RecordsFormatType.JSON)`。傳回值會以 `formattedRecords` 欄位中的 JSON 字串傳回。在本案例中，`columnMetadata` 為 `null`。欄標籤是表示每列物件的鍵。結果集中的每一列都會重複這些欄名。欄值為帶引號的字串、數字值或表示`true`、`false`, 或 `null` 的特殊值。欄中繼資料 (如長度限制以及數字和字串的精確類型) 不會保留在 JSON 回應中。
如果省略 `.withFormatRecordsAs()` 呼叫或指定 `NONE` 的參數，則結果集將使用 `Records` 和 `columnMetadata` 欄位以二進位格式傳回。
## 資料類型映射
結果集中的 SQL 值映射至一組較小的 JSON 類型。這些值在 JSON 中表示為字串、數字和一些特殊的常數，例如 `true`、`false`，和 `null`。您可以將這些值轉換為應用程式中的變數，根據您的程式設計語言使用強式或弱式輸入。
****
| JDBC 資料類型 | JSON 資料類型 |
| --- | --- |
| `INTEGER`, `TINYINT`, `SMALLINT`, `BIGINT` | 預設為數字。如果 `LongReturnType` 選項設定為 `STRING` 則為字串。 |
| `FLOAT`, `REAL`, `DOUBLE` | 數字 |
| `DECIMAL` | 預設為字串。如果 `DecimalReturnType` 選項設定為 `DOUBLE_OR_LONG` 則為數字。 |
| `STRING` | 字串 |
| `BOOLEAN`, `BIT` | Boolean |
| `BLOB`, `BINARY`, `VARBINARY`, `LONGVARBINARY` | base64 編碼的字串。 |
| `CLOB` | 字串 |
| `ARRAY` | 陣列 |
| `NULL` | `null` |
| 其他類型 (包含與日期和時間相關的類型) | 字串 |
## 故障診斷
JSON 回應限制為 10 MB。若回應大於此限制，您的程式會收到 `BadRequestException` 錯誤。於此狀況下，您可使用下列其中一種方法解決此錯誤：
+ 減少結果集中的列數量。若要執行此作業，請新增 `LIMIT` 子句。您可使用 `LIMIT` 和 `OFFSET` 子句提交多個查詢，將一個較大結果集分割為多個較小的結果集。
如果結果集包含按應用程式邏輯過濾掉的列，則可以透過在 `WHERE` 子句中新增更多條件來從結果集中移除這些列。
+ 減少結果集中的欄數量。若要執行此作業，請從查詢的選取清單中移除項目。
+ 在查詢中使用欄別名，來縮短欄標籤。對於結果集中的每一列，每個欄名稱都會在 JSON 字串中重複。因此，具有冗長欄名稱和許多列的查詢結果，可能會超出大小限制。特別是，對複雜的表達式使用欄別名，以避免在 JSON 字串中重複整個表達式。
+ 雖然搭配 SQL 可以使用欄別名來產生具有多個相同名稱之欄的結果集，但 JSON 中不允許重複的鍵名稱。如果您請求 JSON 格式的結果集，並且多個欄具有相同的名稱，則 RDS Data API 會傳回錯誤。因此，請確保所有欄標籤都具有唯一的名稱。
## 範例
以下 Java 範例示範如何呼叫 `ExecuteStatement` 並搭配 JSON 格式字串的回應，然後解讀結果集。以適當的值來取代 *databaseName*、*secretStoreArn* 以及 *clusterArn* 參數。
以下 Java 範例示範了在結果集中傳回十進位數值的查詢。`assertThat` 呼叫測試回應的欄位是否具有根據 JSON 結果集規則的預期屬性。
此範例適用於以下結構描述和範例資料：
```
create table test_simplified_json (a float);
insert into test_simplified_json values(10.0);
```
```
public void JSON_result_set_demo() {
var sql = "select * from test_simplified_json";
var request = new ExecuteStatementRequest()
.withDatabase(databaseName)
.withSecretArn(secretStoreArn)
.withResourceArn(clusterArn)
.withSql(sql)
.withFormatRecordsAs(RecordsFormatType.JSON);
var result = rdsdataClient.executeStatement(request);
}
```
前面程式中 `formattedRecords` 欄位的值為：
```
[{"a":10.0}]
```
`Records` 和 `ColumnMetadata` 欄位都為 null，因為存在 JSON 結果集。
以下 Java 範例示範了在結果集中傳回整數值的查詢。範例會呼叫 `getFormattedRecords` 以僅傳回 JSON 格式的字串，並忽略其他空白或 null 的回應欄位。範例會將結果還原序列化為表示記錄清單的結構。每個記錄都具有其名稱對應於結果集中的欄別名的欄位。此技術簡化了用於剖析結果集的程式碼。您的應用程式不必循環對結果集的列和欄執行迴圈，以及將每個值轉換為適當的類型。
此範例適用於以下結構描述和範例資料：
```
create table test_simplified_json (a int);
insert into test_simplified_json values(17);
```
```
public void JSON_deserialization_demo() {
var sql = "select * from test_simplified_json";
var request = new ExecuteStatementRequest()
.withDatabase(databaseName)
.withSecretArn(secretStoreArn)
.withResourceArn(clusterArn)
.withSql(sql)
.withFormatRecordsAs(RecordsFormatType.JSON);
var result = rdsdataClient.executeStatement(request)
.getFormattedRecords();
/* Turn the result set into a Java object, a list of records.
Each record has a field 'a' corresponding to the column
labelled 'a' in the result set. */
private static class Record { public int a; }
var recordsList = new ObjectMapper().readValue(
response, new TypeReference>() {
});
}
```
前面程式中 `formattedRecords` 欄位的值為：
```
[{"a":17}]
```
若要擷取結果列 0 的 `a` 欄，則應用程式將參考 `recordsList.get(0).a`。
相比之下，下面的 Java 範例顯示了當您不使用 JSON 格式時，建置包含結果集的資料結構所需的程式碼類型。在這種情況下，結果集的每一列都包含單一使用者相關資訊的欄位。建置表示結果集的資料結構需要在所有列中執行迴圈。對於每一列，程式碼會擷取每個欄位的值、執行適當的類型轉換，並將結果指派給代表列之物件中的相應欄位。然後，程式碼將代表每個使用者的物件新增到表示整個結果集的資料結構中。如果查詢變更為對結果集中的欄位進行重新排序、新增或移除，則應用程式的程式碼也必須變更。
```
/* Verbose result-parsing code that doesn't use the JSON result set format */
for (var row: response.getRecords()) {
var user = User.builder()
.userId(row.get(0).getLongValue())
.firstName(row.get(1).getStringValue())
.lastName(row.get(2).getStringValue())
.dob(Instant.parse(row.get(3).getStringValue()))
.build();
result.add(user);
}
```
下面的範例值顯示了具有不同欄數、欄別名和欄資料類型之結果集的 `formattedRecords` 欄位。
如果結果集包含多列，則每一列會表示為陣列元素的物件。結果集中的每一欄都將成為物件中的鍵。結果集中的每一列都會重複這些鍵。因此，對於包含許多列和欄的結果集，您可能需要定義簡短的欄別名，以避免超出整個回應的長度限制。
此範例適用於以下結構描述和範例資料：
```
create table sample_names (id int, name varchar(128));
insert into sample_names values (0, "Jane"), (1, "Mohan"), (2, "Maria"), (3, "Bruce"), (4, "Jasmine");
```
```
[{"id":0,"name":"Jane"},{"id":1,"name":"Mohan"},
{"id":2,"name":"Maria"},{"id":3,"name":"Bruce"},{"id":4,"name":"Jasmine"}]
```
如果結果集中的欄被定義為表達式，則表達式的文字將成為 JSON 索引鍵。因此，在查詢的選取清單中為每個表達式定義描述性欄別名通常很方便。例如，以下查詢在其選取清單中包括函數呼叫和算術運算等表達式。
```
select count(*), max(id), 4+7 from sample_names;
```
這些表達式會以索引鍵的形式傳遞給 JSON 結果集。
```
[{"count(*)":5,"max(id)":4,"4+7":11}]
```
新增具有描述性標籤的 `AS` 欄可讓鍵在 JSON 結果集中更易於解讀。
```
select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;
```
對於修訂後的 SQL 查詢，`AS` 子句定義的欄標籤用作鍵名稱。
```
[{"rows":5,"largest_id":4,"addition_result":11}]
```
JSON 字串中每個鍵值對的值都可以是帶引號的字串。字串可能包含 Unicode 字元。如果字串包含逸出序列或 `"` 或 `\` 字元，則這些字元前面會有反斜線逸出字元。以下 JSON 字串範例示範了這些可能性。例如，`string_with_escape_sequences` 結果包含特殊字元退格、換行字元、歸位字元、tab 鍵、表單摘要和 `\`。
```
[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}]
```
JSON 字串中每個鍵值對的值也可以表示一個數字。數字可以是整數、浮點值、負值或以指數表示法表示的值。以下 JSON 字串範例示範了這些可能性。
```
[{"integer_value":17}]
[{"float_value":10.0}]
[{"negative_value":-9223372036854775808,"positive_value":9223372036854775807}]
[{"very_small_floating_point_value":4.9E-324,"very_large_floating_point_value":1.7976931348623157E308}]
```
布林值和 null 值用未加引號的特殊關鍵字 `true`、`false` 以及 `null` 來表示。以下 JSON 字串範例示範了這些可能性。
```
[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}]
```
如果選擇 BLOB 類型的值，則結果將在 JSON 字串中表示為 base64 編碼的值。若要將值轉換回原始表示法，您可以使用應用程式語言中的適當解碼函數。例如，在 Java 中，您可以呼叫函數 `Base64.getDecoder().decode()`。以下範例輸出顯示選擇 BLOB 值 `hello world` 並將結果集作為 JSON 字串傳回。
```
[{"blob_column":"aGVsbG8gd29ybGQ="}]
```
以下 Python 範例示範如何從呼叫 Python `execute_statement` 函數的結果中存取值。結果集是欄位 `response['formattedRecords']` 中的字串值。程式碼透過呼叫 `json.loads` 函數，將 JSON 字串轉換為資料結構。然後，結果集的每一列都是資料結構中的一個清單元素，而在每一列中，您可以按名稱參考結果集的每個欄位。
```
import json
result = json.loads(response['formattedRecords'])
print (result[0]["id"])
```
以下 JavaScript 範例示範了如何從呼叫 JavaScript `executeStatement` 函數的結果中存取值。結果集是欄位 `response.formattedRecords` 中的字串值。程式碼透過呼叫 `JSON.parse` 函數，將 JSON 字串轉換為資料結構。然後，結果集的每一列都是資料結構中的一個陣列元素，而在每一列中，您可以按名稱參考結果集的每個欄位。
```
```
# 針對 Amazon RDS 資料 API 進行疑難排解
請使用下列標題包含常見錯誤訊息的章節，協助針對您在使用 Amazon RDS 資料 API (資料 API) 時所發生的問題進行疑難排解。
**Topics**
+ [找不到交易 ](#data-api.troubleshooting.tran-id-not-found)
+ [查詢封包過大](#data-api.troubleshooting.packet-too-large)
+ [資料庫回應超過大小上限](#data-api.troubleshooting.response-size-too-large)
+ [叢集 並未啟用 HttpEndpoint](#data-api.troubleshooting.http-endpoint-not-enabled)
+ [DatabaseErrorException：交易仍在執行查詢](#data-api.troubleshooting.txn-concurrent-requests-rejected)
+ [不支援的結果例外狀況](#data-api.troubleshooting.unsupported-result)
+ [不支援多陳述式](#data-api.troubleshooting.multi-statements)
+ [不支援結構描述參數](#data-api.troubleshooting.schema-parameter)
+ [IPv6 連線問題](#data-api.troubleshooting.ipv6-connectivity)
## 找不到交易
在此情況下，表示找不到資料 API 呼叫中指定的交易 ID。此問題的原因已附加至錯誤訊息中，且是下列其中一項：
+ Transaction may be expired (交易可能已過期)。
請確認每個交易呼叫都是在前一個呼叫後的三分鐘內執行。
指定的交易 ID 也可能不是由 [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html) 呼叫所建立的。請確認您的呼叫具有效的交易 ID。
+ One previous call resulted in a termination of your transaction (之前的一次呼叫導致您的交易終止)。
該交易已由您的 `CommitTransaction` 或 `RollbackTransaction` 呼叫終止。
+ Transaction has been aborted due to an error from a previous call (由於前次呼叫的錯誤，交易已中止)。
檢查您之前的呼叫是否發生任何異常。
如需執行交易的資訊，請參閱 [呼叫 Amazon RDS 資料 API](data-api.calling.md)。
## 查詢封包過大
在這種情況下，表示為資料列傳回的結果集過大。針對資料庫傳回結果集中的每個資料列，資料 API 的大小上限為每個資料列 64 KB。
若要解決此問題，請確定結果集的每個資料列都是 64 KB 或更小。
## 資料庫回應超過大小上限
在這種情況下，表示資料庫傳回結果集的大小過大。針對資料庫傳回的結果集，資料 API 的大小上限為 1 MiB。
若要解決此問題，請確認對資料 API 呼叫傳回的資料小於或等於 1 MiB。若您需要傳回超過 1 MiB，您可以在查詢中搭配 `LIMIT` 子句使用多個 [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) 呼叫。
如需 `LIMIT` 子句的詳細資訊，請參閱 MySQL 文件中的 [SELECT 語法](https://dev.mysql.com/doc/refman/8.0/en/select.html)。
## 叢集 並未啟用 HttpEndpoint
檢查此問題的下列潛在原因：
+ Aurora 資料庫叢集不支援資料 API。如需有關 RDS 資料 API 支援的資料庫叢集類型的相關資訊，請參閱 [Amazon RDS 資料 API 的區域和版本可用性](data-api.regions.md)。
+ Aurora 資料庫叢集並未啟用資料 API。若要搭配 Aurora 資料庫叢集使用資料 API，您必須為資料庫叢集啟用資料 API。如需啟用資料 API 的資訊，請參閱[啟用 Amazon RDS 資料 API](data-api.enabling.md)。
+ 資料庫叢集已在為其啟用資料 API 後重新命名。在這種情況下，請關閉該叢集的資料 API，然後再次將其啟用。
+ 您指定的 ARN 未精確地符合叢集的 ARN。檢查從其他來源傳回的 ARN 或由程序邏輯建置的 ARN 是否完全符合叢集的 ARN。例如，請確保您使用的 ARN 對於所有字母字元具有正確的字母大小寫。
## DatabaseErrorException：交易仍在執行查詢
如果應用程式傳送具有交易 ID 的請求，且該交易目前正在處理另一個請求，資料 API 會立即將此錯誤傳回給應用程式。如果應用程式使用 Javascript 中的「承諾」等機制提出異步請求，則可能會出現此情況。
若要解決此問題，請等待先前的請求完成，然後重試請求。您可以繼續重試，直到不再發生錯誤，或應用程式收到某種不同類型的錯誤。
適用於 Aurora Serverless v2 和佈建執行個體的資料 API 可能會發生此情況。在 Aurora Serverless v1 的資料 API 中，相同交易 ID 的後續請求會自動等待先前的請求完成。不過，由於先前的請求耗時太久，較舊的行為可能會遇到逾時。如果您要移植較舊資料 API 應用程式，且這類應用程式會提出並行請求，請修改例外狀況處理邏輯，以應對這種新的錯誤。
## 不支援的結果例外狀況
資料 API 不支援所有資料類型。當您執行的是傳回不支援資料類型的查詢時，就會發生此錯誤。
若要解決此問題，請將不支援的資料類型轉換為 `TEXT`。例如：
```
SELECT custom_type::TEXT FROM my_table;
-- OR
SELECT CAST(custom_type AS TEXT) FROM my_table;
```
## 不支援多陳述式
Aurora Serverless 第 2 版和佈建叢集的資料 API 不支援多陳述式。嘗試在單一 API 呼叫中執行多個陳述式會導致此錯誤。
若要執行多個陳述式，請使用個別的 `ExecuteStatement` API 呼叫或使用 `BatchExecuteStatement` API 進行批次處理。
## 不支援結構描述參數
Aurora Serverless 第 1 版以無提示的方式忽略結構描述參數。不過，Aurora Serverless 第 2 版和佈建叢集會明確拒絕內含結構描述參數的 API 呼叫。
若要解決此問題，請在使用 Aurora Serverless 第 2 版或佈建叢集時，從對資料 API 的所有呼叫中移除結構描述參數。
## IPv6 連線問題
如果您在使用 IPv6 端點連線至資料 API 時遇到問題，請確認下列潛在原因：
+ **網路不支援 IPv6**：確認網路基礎設施支援 IPv6，且 IPv6 路由的設定都正確。
+ **DNS 解析問題**：確保 DNS 解析程式可以解析雙堆疊端點的 AAAA 記錄 (例如 `rds-data.us-east-1.api.aws`)。
+ **安全群組組態**：更新安全群組規則，以允許連接埠 443 (HTTPS) 上的 IPv6 流量。新增 IPv6 CIDR 區塊的規則 (例如，所有 IPv6 地址的 `::/0`)。
+ **網路 ACL 組態**：確保網路 ACL 允許必要連接埠上的 IPv6 流量。
+ **用戶端程式庫相容性**：確認您的 HTTP 用戶端程式庫和 AWS SDKs支援 IPv6 和雙堆疊連線。
+ **VPC 端點組態**：如果使用的是 PrivateLink，請確定 VPC 端點已設定為支援 IPv6，且相關聯的子網路已指派 IPv6 CIDR 區塊。
若要針對 IPv6 連線問題進行疑難排解：
1. 使用僅 IPv4 端點 (`.amazonaws.com`) 測試連線，以確認問題是否僅限於 IPv6。
1. 使用網路診斷工具，來驗證雙堆疊端點的 IPv6 連線。
1. 使用 IPv6 端點時，請確認 CloudTrail 日誌是否有任何身分驗證或授權錯誤。
1. 確認應用程式已正確設定為使用新的雙堆疊端點 URL。
# 使用 記錄 Amazon RDS Data API 呼叫 AWS CloudTrail
RDS Data API （資料 API) 已與 服務整合 AWS CloudTrail，此服務可提供使用者、角色或 AWS 服務在資料 API 中採取之動作的記錄。CloudTrail 將資料 API 的所有 API 呼叫擷取為事件，包括來自 Amazon RDS 主控台的呼叫以及來自對資料 API 操作發出的程式碼呼叫。如果您建立線索，就可以持續將 CloudTrail 事件交付至 Amazon S3 儲存貯體，包括資料 API 的事件。使用 CloudTrail 收集的資訊，您可以判斷眾多資訊。此資訊包括對資料 API 提出的請求、提出請求的 IP 地址、何人提出請求、何時提出請求，以及其他詳細資訊。
若要進一步了解 CloudTrail，請參閱[「AWS CloudTrail 使用者指南」](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)。
## 使用 CloudTrail 中的資料 API 資訊
當您建立 AWS 帳戶時，會在您的帳戶上啟用 CloudTrail。當資料 API 中發生支援的活動 （管理事件） 時，該活動會與**事件歷史記錄**中的其他 AWS 服務事件一起記錄在 CloudTrail 事件中。您可以在 AWS 帳戶中檢視、搜尋和下載最近的管理事件。如需詳細資訊，請參閱 *AWS CloudTrail 使用者指南*中的[使用 CloudTrail 事件歷史記錄](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html)。
若要持續記錄您 AWS 帳戶中的事件，包括資料 API 的事件，請建立追蹤。*線索*能讓 CloudTrail 將日誌檔案交付至 Amazon S3 儲存貯體。根據預設，當您在主控台中建立線索時，線索會套用至所有 AWS 區域。線索會記錄 AWS 分割區中所有 AWS 區域的事件，並將日誌檔案交付至您指定的 Amazon S3 儲存貯體。此外，您可以設定其他 AWS 服務，以進一步分析和處理 CloudTrail 日誌中所收集的事件資料。如需詳細資訊，請參閱 *AWS CloudTrail 使用者指南*中的以下主題：
+ [建立追蹤的概觀](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail 支援的服務和整合](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations)
+ [設定 CloudTrail 的 Amazon SNS 通知](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)
+ [接收多個區域的 CloudTrail 日誌檔案](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html)及[接收多個帳戶的 CloudTrail 日誌檔案](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
所有資料 API 操作均由 CloudTrail 記錄，並記載於 [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html)中。例如，對 `BatchExecuteStatement`、`BeginTransaction`、`CommitTransaction` 和 `ExecuteStatement` 操作的呼叫都會在 CloudTrail 日誌檔案中產生項目。
每一筆事件或日誌項目都會包含產生請求者的資訊。身分資訊可協助您判斷下列事項：
+ 該請求是否使用根或使用者憑證提出。
+ 提出該請求時，是否使用了特定角色或聯合身分使用者的暫時安全憑證。
+ 請求是否由其他 AWS 服務提出。
如需詳細資訊，請參閱 [CloudTrail userIdentity 元素](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)。
## 從 AWS CloudTrail 追蹤中包含和排除資料 API 事件
大多數資料 API 使用者依賴 AWS CloudTrail 追蹤中的事件來提供資料 API 操作的記錄。事件資料不會在資料 API 的請求中顯示資料庫名稱、結構描述名稱或 SQL 陳述式。不過，知道哪個使用者在特定時間對特定資料庫叢集進行某種呼叫，有助於偵測異常存取模式。
### 在 AWS CloudTrail 追蹤中包含資料 API 事件
對於 Aurora PostgreSQL Serverless v2 和佈建資料庫，下列資料 API 操作會記錄 AWS CloudTrail 為*資料事件*。[資料事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events)是 CloudTrail 預設不會記錄的大容量資料平面 API 操作。資料事件需支付額外的費用。如需有關 CloudTrail 定價的資訊，請參閱 [AWS CloudTrail 定價](https://aws.amazon.com/cloudtrail/pricing/)。
+ [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html)
+ [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html)
+ [CommitTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html)
+ [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html)
+ [RollbackTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html)
您可以使用 CloudTrail 主控台、AWS CLI或 CloudTrail API 操作，來記錄這些資料 API 操作。在 CloudTrail 主控台中，為資料事件類型選擇 **RDS 資料 API：資料庫叢集**。如需詳細資訊，請參閱《AWS CloudTrail 使用者指南》**中的[使用 AWS 管理主控台記錄資料事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI)。
使用 AWS CLI執行 `aws cloudtrail put-event-selectors`命令，為您的線索記錄這些資料 API 操作。若要記錄資料庫叢集上所有資料 API 事件，請為資源類型指定 `AWS::RDS::DBCluster`。下列範例會記錄資料庫叢集上的所有資料 API 事件。如需詳細資訊，請參閱《AWS CloudTrail 使用者指南》**中的[使用 AWS Command Line Interface記錄資料事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail-by-using-the-aws-cli.html)。
```
aws cloudtrail put-event-selectors --trail-name trail_name --advanced-event-selectors \
'{
"Name": "RDS Data API Selector",
"FieldSelectors": [
{
"Field": "eventCategory",
"Equals": [
"Data"
]
},
{
"Field": "resources.type",
"Equals": [
"AWS::RDS::DBCluster"
]
}
]
}'
```
您可以設定進階事件選擇器，以額外篩選 `readOnly`、`eventName,` 和 `resources.ARN` 欄位。如需這些欄位的詳細資訊，請參閱 [AdvancedFieldSelector](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html)。
### 從 AWS CloudTrail 追蹤中排除資料 API 事件 (Aurora Serverless v1僅限 )
對於 Aurora Serverless v1，資料 API 事件是管理事件。根據預設，所有資料 API 事件都會包含在 AWS CloudTrail 追蹤中。但是，因為資料 API 會產生大量的事件，您就能夠將這些事件從 CloudTrail 線索中排除。**排除 Amazon RDS 資料 API 事件**設定會將所有資料 API 事件從線索中排除。您無法排除特定的資料 API 事件。
若要將資料 API 事件從權杖中排除，請執行下列程序：
+ 在 CloudTrail 主控台中，當您[建立權杖](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-a-trail-using-the-console-first-time.html)或[更新權杖](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-update-a-trail-console.html)時，選擇 **Exclude Amazon RDS Data API events** (排除 Amazon RDS 資料 API 事件) 設定。
+ 在 CloudTrail API 中，使用 [PutEventSelectors](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_PutEventSelectors.html) 操作。如果使用的是進階事件選擇器，您可以將 `eventSource` 欄位設定為不等於 `rdsdata.amazonaws.com`，即可排除資料 API 事件。如果使用的是基本事件選擇器，您可以將 `ExcludeManagementEventSources` 屬性的值設定為 `rdsdata.amazonaws.com` 來排除資料 API 事件。如需詳細資訊，請參閱《AWS CloudTrail 使用者指南》**中的[使用 AWS Command Line Interface記錄事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#creating-mgmt-event-selectors-with-the-AWS-CLI)。
**警告**
從 CloudTrail 日誌中排除資料 API 事件可能會遮蔽資料 API 動作。授予委託人執行此操作所需的 `cloudtrail:PutEventSelectors` 許可時時，請務必小心。
您可以變更主控台設定或權杖的事件選擇器，以隨時關閉此排除。然後，權杖即會開始記錄資料 API 事件。但無法復原排除有效期間發生過的資料 API 事件。
當您使用主控台或 API 排除資料 API 事件時，產生的CloudTrail `PutEventSelectors` API 操作也會記錄在 CloudTrail 日誌中。如果資料 API 事件未出現在 CloudTrail 日誌中，請尋找 `ExcludeManagementEventSources` 屬性設為 `rdsdata.amazonaws.com` 的 `PutEventSelectors` 事件。
如需更多詳細資訊，請參閱 *AWS CloudTrail 使用者指南*中的[記錄權杖的管理事件](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html)。
## 了解資料 API 日誌檔案項目
*權杖*是一種組態，能讓事件以日誌檔案的形式交付到您指定的 Amazon S3 儲存貯體。CloudTrail 日誌檔案包含一或多個日誌專案。一個*事件*為任何來源提出的單一請求，並包含請求動作、請求的日期和時間、請求參數等資訊。CloudTrail 日誌檔並非依公有 API 呼叫的堆疊追蹤排序，因此不會以任何特定順序出現。
**Aurora PostgreSQL Serverless 第 2 版和已佈建**
下列範例示範 CloudTrail 日誌項目，此項目會示範 Aurora PostgreSQL Serverless 第 2 版和已佈建資料庫的 `ExecuteStatement` 操作。對於這些資料庫，所有資料 API 事件都是事件來源為 **rdsdataapi.amazonaws.com** 且事件類型為 **Rds Data Service** 的資料事件。
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdataapi.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "Rds Data Service",
"recipientAccountId": "123456789012"
}
```
**Aurora Serverless v1**
下列範例示範上述範例 CloudTrail 日誌項目在 Aurora Serverless v1 會如何顯示。對於 Aurora Serverless v1，所有事件都是管理事件，其中事件來源為 **rdsdata.amazonaws.com**，而事件類型為 **AwsApiCall**。
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdata.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}
```
# 使用 Performance Insights 監控 RDS 資料 API 查詢
如果 Aurora 叢集正在執行 Aurora Serverless v2 或佈建執行個體，您可以使用 Performance Insights 搭配 RDS 資料 API。
如需如何搭配 Aurora 使用 Performance Insights 的詳細資訊，請參閱 [在 Amazon Aurora 上使用績效詳情監控資料庫負載](USER_PerfInsights.md)。
## Performance Insights 中 RDS 資料 API 查詢的呈現方式
透過資料 API，Aurora 叢集會根據您從應用程式提交的資料 API 呼叫來處理查詢。資料 API 也會執行一些 SQL 陳述式作為其內部工作的一部分，例如將超過逾時閾值的查詢取消。這兩種 SQL 操作都會顯示在 Performance Insights 統計資料和圖表中。
+ 對於您提交至 Aurora 叢集的資料 API 查詢，PI 儀表板中的**主機**欄位會標記為 **RDS 資料 API**。對於 Aurora PostgreSQL，**application\$1name** 欄位的值為 `rds-data-api`。當您使用**最高主機**或**最高應用程式**作為維度來分析資料庫負載時，請尋找這些標籤。
+ 資料 API 執行以管理資料庫層面的所有內部查詢 (例如連線集區和查詢逾時)，都會以字首 **RDS 資料 API** 標註。範例：當您依**最高 SQL** 作為維度分析資料庫負載時，`/* RDS Data API */ select * from my_table;` 會尋找這些字首。系統會以 `/* RDS Data API */` SQL 註解標註陳述式。