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

# 使用適用於 RDS 資料 API 的 Java 用戶端程式庫
<a name="data-api.java-client-library"></a>

您可以下載與使用適用於 RDS 資料 API (資料 API) 的 Java 用戶端程式庫。此 Java 用戶端程式庫提供另一種使用資料 API 的方式。您可以使用此程式庫，將用戶端類別映射至資料 API 的要求和回應。此映射支援可以與某些特定的 Java 類型輕鬆整合，例如 `Date`、`Time` 和 `BigDecimal`。

## 下載適用於資料 API 的 Java 用戶端程式庫
<a name="data-api.java-client-library.downloading"></a>

資料 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 版，請使用下列項目：

```
<dependency>
   <groupId>software.amazon.rdsdata</groupId>
   <artifactId>rds-data-api-client-library-java</artifactId>
   <version>2.0.0</version>
</dependency>
```

 對於與 AWS SDK 1.x 相容的 1.x 版，請使用下列項目：

```
<dependency>
    <groupId>software.amazon.rdsdata</groupId>
    <artifactId>rds-data-api-client-library-java</artifactId>
    <version>1.0.8</version>
</dependency>
```

## Java 用戶端程式庫範例
<a name="data-api.java-client-library.examples"></a>

接下來，您可以找到一些關於使用資料 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<Account> 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)。