# DynamoDB で動作するプログラムインターフェイス
<a name="Programming.SDKs.Interfaces"></a>

各 [AWS SDK](https://aws.amazon.com/tools) には、Amazon DynamoDB を操作するプログラミングインターフェイスが 1 つ以上用意されています。これらのインターフェイスは、シンプルな低レベルの DynamoDB ラッパーから、オブジェクト指向の永続レイヤーまで、多岐にわたります。使用可能なインターフェイスは、AWS SDK およびプログラミング言語によって異なります。

![\[DynamoDB を使用するためのさまざまな AWS SDK で利用可能なプログラミングインターフェイス。\]](http://docs.aws.amazon.com/ja_jp/amazondynamodb/latest/developerguide/images/SDKSupport.SDKInterfaces.png)


次のセクションでは、AWS SDK for Java を例として使用して、使用可能なインターフェイスをいくつかハイライトします。(すべてのインターフェイスが、どの AWS SDK でも使用できるわけではありません。)

**Topics**
+ [DynamoDB で動作する低レベルインターフェイス](#Programming.SDKs.Interfaces.LowLevel)
+ [DynamoDB で動作するドキュメントインターフェイス](#Programming.SDKs.Interfaces.Document)
+ [DynamoDB で動作するオブジェクト永続性インターフェイス](#Programming.SDKs.Interfaces.Mapper)

## DynamoDB で動作する低レベルインターフェイス
<a name="Programming.SDKs.Interfaces.LowLevel"></a>

それぞれの言語特有の AWS SDK は、低レベルの DynamoDB API リクエストによく似たメソッドを持つ、Amazon DynamoDB 用の低レベルインターフェイスを提供します。

場合によっては [データ型記述子](Programming.LowLevelAPI.md#Programming.LowLevelAPI.DataTypeDescriptors) を使用して、文字列型の `S` や、数値型の `N` など、属性のデータ型を識別する必要があります。

**注記**  
すべての言語特有の AWS SDK で、低レベルインターフェイスを使用できます。

次の Java プログラムは、AWS SDK for Java の低レベルインターフェイスを使用しています。

### 低レベルインターフェイスの例
<a name="low-level-example"></a>

```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;

/**
 * Before running this Java V2 code example, set up your development
 * environment, including your credentials.
 *
 * For more information, see the following documentation topic:
 *
 * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
 *
 * To get an item from an Amazon DynamoDB table using the AWS SDK for Java V2,
 * its better practice to use the
 * Enhanced Client, see the EnhancedGetItem example.
 */
public class GetItem {
    public static void main(String[] args) {
        final String usage = """

                Usage:
                    <tableName> <key> <keyVal>

                Where:
                    tableName - The Amazon DynamoDB table from which an item is retrieved (for example, Music3).\s
                    key - The key used in the Amazon DynamoDB table (for example, Artist).\s
                    keyval - The key value that represents the item to get (for example, Famous Band).
                """;

        if (args.length != 3) {
            System.out.println(usage);
            System.exit(1);
        }

        String tableName = args[0];
        String key = args[1];
        String keyVal = args[2];
        System.out.format("Retrieving item \"%s\" from \"%s\"\n", keyVal, tableName);
        Region region = Region.US_EAST_1;
        DynamoDbClient ddb = DynamoDbClient.builder()
                .region(region)
                .build();

        getDynamoDBItem(ddb, tableName, key, keyVal);
        ddb.close();
    }

    public static void getDynamoDBItem(DynamoDbClient ddb, String tableName, String key, String keyVal) {
        HashMap<String, AttributeValue> keyToGet = new HashMap<>();
        keyToGet.put(key, AttributeValue.builder()
                .s(keyVal)
                .build());

        GetItemRequest request = GetItemRequest.builder()
                .key(keyToGet)
                .tableName(tableName)
                .build();

        try {
            // If there is no matching item, GetItem does not return any data.
            Map<String, AttributeValue> returnedItem = ddb.getItem(request).item();
            if (returnedItem.isEmpty())
                System.out.format("No item found with the key %s!\n", key);
            else {
                Set<String> keys = returnedItem.keySet();
                System.out.println("Amazon DynamoDB table attributes: \n");
                for (String key1 : keys) {
                    System.out.format("%s: %s\n", key1, returnedItem.get(key1).toString());
                }
            }

        } catch (DynamoDbException e) {
            System.err.println(e.getMessage());
            System.exit(1);
        }
    }
}
```

## DynamoDB で動作するドキュメントインターフェイス
<a name="Programming.SDKs.Interfaces.Document"></a>

多くの AWS SDK はドキュメントインターフェイスを備えており、テーブルやインデックスに対してデータプレーンオペレーション (作成、読み取り、更新、削除) を実行できます。ドキュメントインターフェイスでは、[データ型記述子](Programming.LowLevelAPI.md#Programming.LowLevelAPI.DataTypeDescriptors) を指定する必要はありません。データ型は、データ自体のセマンティクスによって暗示されています。これらの AWS SDK には、JSON ドキュメントとネイティブの Amazon DynamoDB データ型とを簡単に変換するメソッドも用意されています。

**注記**  
ドキュメントインターフェイスは、AWS SDK for [Java](https://aws.amazon.com/sdk-for-java)、[.NET](https://aws.amazon.com/sdk-for-net)、[Node.js](https://aws.amazon.com/sdk-for-node-js)、および [JavaScript SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/) で使用できます。

次の Java プログラムは、AWS SDK for Java のドキュメントインターフェイスを使用します。プログラムが `Music` テーブルを表す `Table` オブジェクトを作成し、そのオブジェクトに `GetItem` の使用を依頼して、曲を取得します。その後プログラムが、曲がリリースされた年を出力します。

`software.amazon.dynamodb.document.DynamoDB` クラスは DynamoDB ドキュメントインターフェイスを実装します。低レベルクライアント (`AmazonDynamoDB`) のラッパーとして、`DynamoDB` がどのような役割を果たすかに注目してください。

### ドキュメントインターフェイスの例
<a name="document-level-example"></a>

```
package com.amazonaws.codesamples.gsg;

import software.amazon.dynamodb.AmazonDynamoDB;
import software.amazon.dynamodb.AmazonDynamoDBClientBuilder;
import software.amazon.dynamodb.document.DynamoDB;
import software.amazon.dynamodb.document.GetItemOutcome;
import software.amazon.dynamodb.document.Table;

public class MusicDocumentDemo {

    public static void main(String[] args) {

        AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();
        DynamoDB docClient = new DynamoDB(client);

        Table table = docClient.getTable("Music");
        GetItemOutcome outcome = table.getItemOutcome(
                "Artist", "No One You Know",
                "SongTitle", "Call Me Today");

        int year = outcome.getItem().getInt("Year");
        System.out.println("The song was released in " + year);

    }
}
```

## DynamoDB で動作するオブジェクト永続性インターフェイス
<a name="Programming.SDKs.Interfaces.Mapper"></a>

一部の AWS SDK には、データプレーンオペレーションを直接実行しない、オブジェクト永続性インターフェイスが用意されています。代わりに、Amazon DynamoDB のテーブルとインデックスの項目を表すオブジェクトを作成し、それらのオブジェクトのみとやり取りを行います。これにより、データベースを意識するのではなく、オブジェクトを中心にコードを作成していくことができます。

**注記**  
オブジェクト永続性インターフェイスは、AWS SDK for Java と for .NET で利用できます。詳細については、DynamoDB の「[DynamoDB の上位レベルのプログラミングインターフェイス](HigherLevelInterfaces.md)」を参照してください。

### オブジェクト永続性インターフェイスの例
<a name="mapper-level-example"></a>

```
import com.example.dynamodb.Customer;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
import software.amazon.awssdk.enhanced.dynamodb.Key;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
```

```
import com.example.dynamodb.Customer;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedClient;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbTable;
import software.amazon.awssdk.enhanced.dynamodb.Key;
import software.amazon.awssdk.enhanced.dynamodb.TableSchema;
import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;

/*
 * Before running this code example, create an Amazon DynamoDB table named Customer with these columns:
 *   - id - the id of the record that is the key. Be sure one of the id values is `id101`
 *   - custName - the customer name
 *   - email - the email value
 *   - registrationDate - an instant value when the item was added to the table. These values
 *                        need to be in the form of `YYYY-MM-DDTHH:mm:ssZ`, such as 2022-07-11T00:00:00Z
 *
 * Also, ensure that you have set up your development environment, including your credentials.
 *
 * For information, see this documentation topic:
 *
 * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
 */

public class EnhancedGetItem {
    public static void main(String[] args) {
        Region region = Region.US_EAST_1;
        DynamoDbClient ddb = DynamoDbClient.builder()
                .region(region)
                .build();

        DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
                .dynamoDbClient(ddb)
                .build();

        getItem(enhancedClient);
        ddb.close();
    }

    public static String getItem(DynamoDbEnhancedClient enhancedClient) {
        Customer result = null;
        try {
            DynamoDbTable<Customer> table = enhancedClient.table("Customer", TableSchema.fromBean(Customer.class));
            Key key = Key.builder()
                    .partitionValue("id101").sortValue("tred@noserver.com")
                    .build();

            // Get the item by using the key.
            result = table.getItem(
                    (GetItemEnhancedRequest.Builder requestBuilder) -> requestBuilder.key(key));
            System.out.println("******* The description value is " + result.getCustName());

        } catch (DynamoDbException e) {
            System.err.println(e.getMessage());
            System.exit(1);
        }
        return result.getCustName();
    }
}
```