Oracle Cloud Infrastructureドキュメント

DynamoDBでのAutonomous AI APIの使用

Autonomous AI Database API for DynamoDBを使用すると、キーバリュー形式を使用して、Autonomous AI Databaseでデータを格納、管理および取得できます。

DynamoDBでのAutonomous AI APIの使用について

Oracle Autonomous AI Databaseは、Oracleの完全管理型Autonomous AI Databaseを備えたDynamoDB用のAutonomous AI Database APIを提供し、既存のDynamoDBツールおよびSDKを使用してAutonomous AI Databaseとシームレスに連携できるようにします。

Oracle Autonomous AI Database API for DynamoDB互換APIを使用すると、既存のDynamoDBクライアントを引き続き使用し、Autonomous AI Databaseと連携するためのアプリケーションを最小限に変更できます。標準のDynamoDB SDKを使用して、既存のDynamoDBアプリケーションをAutonomous AI Databaseと統合できます。このAPIは、GetItem、DeleteItem、CreateTable、DeleteTableなどの使い慣れたDynamoDB操作を提供し、DynamoDBアプリケーションをAutonomous AI Databaseに移行できるようにします。

詳細は、Amazon DynamoDBを参照してください。

前提条件

Autonomous AI DatabaseでAutonomous AI Database API for DynamoDBを使用するための前提条件をリストします。

データベースのDynamoDBに対してAutonomous AI Database APIを有効にする前に、次の点に注意してください:

  • Autonomous AI Database API for DynamoDBでは、DynamoDB表へのアクセスを管理するために、ワークロード・タイプがTransaction ProcessingのAutonomous AI Databaseが必要です。その他のワークロード・タイプはサポートされていません。

  • Autonomous AI Databaseインスタンスの管理は、エラスティック・プールの一部にしないでください。エラスティック・グループの一部であるAutonomous AI DatabaseでAutonomous AI Database API for DynamoDBを有効にしようとした場合、またはこれらのAPIが有効なデータベースをエラスティック・グループに追加しようとすると、エラーが表示されます。Autonomous AI Database API for DynamoDBが有効になっているAutonomous AI Databaseは、エラスティック・グループのメンバーにはできません。

Autonomous AI DatabaseでDynamoDBのAutonomous AI APIを有効化

Autonomous AI DatabaseインスタンスからDynamoDBのAPIを呼び出すためのアクセス・キーおよび秘密キーを生成するステップについて説明します。

必要に応じて、次の前提条件ステップを実行します:

  • Oracle Cloud Infrastructure Consoleを開くには、クラウドの横にあるナビゲーション・アイコンをクリックします。

  • Oracle Cloud Infrastructureの左側のナビゲーション・メニューから、「Oracle AI Database」をクリックし、「Autonomous AI Database」をクリックします。

  • 「Autonomous AI Database」ページで、「表示名」列の下のリンクからAutonomous AI Databaseを選択します。

Autonomous AI DatabaseインスタンスでDynamoDBのAPIを有効にするには、次のステップに従います:

  1. 「その他のアクション」ドロップダウン・リストで、「タグの管理」を選択します。

    「タグの追加」ページが表示されます。

  2. 次の値を指定して、Autonomous AI Databaseにタグを割り当てます。

    • ネームスペース:フリー・フロントのタグを追加するには、値を空白のままにします。

    • キー: adb$feature

    • 値: {"name":"DynamoDB_API","enable":true}

    「追加」をクリックして、タグを追加します。

    「追加」をクリックすると、「ライフサイクル状態」フィールドに「更新中」が表示され、Autonomous AI Databaseによって「Autonomous AIデータベース・タグの更新」作業リクエストが生成されます。リクエストを表示するには、詳細ページで「作業リクエスト」タブを選択します。

    DynamoDBのAutonomous AI Database APIを有効にするには、最大10分かかる場合があります。

    Autonomous AI DatabaseでDynamoDBのAPIを有効にした後、https://dataaccess.adb.{oci-region_name}.oraclecloudapps.com/adb/keyvaluestore/v1/{database-ocid} RESTエンドポイントを使用してDynamoDB操作を実行します。DynamoDBのAPIにアクセスするには、有効なアクセス・キーID、シークレット・アクセス・キー、および操作に必要な権限が必要です。たとえば、DynamoDB表を作成するにはCREATE_TABLE権限が必要です。

    DynamoDB操作のAPIのURIは、次のとおりです。

    https://dataaccess.adb.{oci-region_name}.oraclecloudapps.com/adb/keyvaluestore/v1/{database-ocid}

    たとえば:

    https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/keyvaluestore/v1/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE

DynamoDBのAutonomous AI Database APIを起動するためのアクセスの構成

この項では、Autonomous AIデータベースを有効にした後、DynamoDBのAPIを認証して使用するために必要なアクセス・キーを作成および管理するステップを示します。

RESTエンドポイントhttps://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeysを使用して、DynamoDB表へのアクセスを管理します。これを行うには、データベースのユーザー名および資格証明を指定します。指定したユーザーにはPDB_DBAロールが付与されている必要があります。これらのアクセス・キーは、Autonomous AI DatabaseへのAPIコールを認証してDynamoDBのAPIを使用するために必要です。

DynamoDB互換の操作を実行するために必要な権限がアクセス・キーに割り当てられていることを確認する必要があります。これらの権限は、アクセス・キーの作成時に指定するか、既存のキーを変更して必要な権限を割り当てることができます。

ノート

ノート:アクセス・キー情報は、データベースのOracle管理のDATA_ACCESS_COMMONスキーマに格納されます。このスキーマにはアクセスできません。

アクセス・キーの権限のリストを次に示します。

権限 摘要
CREATE_TABLE 表作成を実行するためのアクセス
READ_ANY Autonomous AI Databaseに関連付けられたすべてのDynamoDB表に対して表および項目の読取り操作を実行するためのアクセス権。バックアップ、リストア、インポートおよびエクスポート操作は含まれません。
READ_WRITE_ANY Autonomous AI Databaseに関連付けられているすべてのDynamoDB表で、表およびアイテムの読取りおよび書込み操作を実行するためのアクセス権。バックアップ、リストア、インポートおよびエクスポート操作は含まれません。
ADMIN_ANY Autonomous AI Databaseに関連付けられているすべてのDynamoDBの表の作成、バックアップ、リストア、インポートおよびエクスポートなどの操作を実行するためのアクセス。
READ <Table(s)> Autonomous AI Databaseに関連付けられた特定のDynamoDB表に対して表および項目の読取り操作を実行するためのアクセス。バックアップ、リストア、インポートおよびエクスポート操作は含まれません。
READ_WRITE on <Table(s)> Autonomous AI Databaseに関連付けられた特定のDynamoDB表で、表およびアイテムの読取りおよび書込み操作を実行するためのアクセス権。バックアップ、リストア、インポートおよびエクスポート操作は含まれません。
ADMIN on <Table(s)> Autonomous AI Databaseに関連付けられた特定のDynamoDB表に対するバックアップ、リストア、インポートおよびエクスポートなどの操作を実行するためのアクセス。
<operation name> on <Table(s)>。例: GetItem on <Table(s)> Autonomous AI Databaseに関連付けられた特定のDynamoDB表に対して特定の操作を実行するためのアクセス。

アクセス・キーの作成

Autonomous AI Databaseでアクセス・キーおよび秘密キーを作成するには、ADMINユーザーとしてログインしているか、PDB_DBAロールが付与されている必要があります。

データベースにアクセス・キーを作成するための構文およびサンプル・リクエスト:

POST https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys RESTエンドポイントAPIリクエストを使用して、アクセス・キーおよび秘密キーを生成します:

構文

POST "https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys"
{
  "name"          : "{<access_key_name>}",         // Required. The name you assign to the access key.
  "description"   : "{<access_key_description>}",  // Optional. A description for the access key.
  "permissions"   : [                             // Optional. Array of permission objects.
    {
      "actions"   : [<List of permissions>],      // Required. List of permitted actions (e.g., "read", "write").
      "resources" : [<List of Tables>]            // Optional. Only applicable for permissions that get applied on Table.
    }
    // ... additional permission objects as needed
  ],
  "expiration_minutes": 120                       // Optional. The key's expiration time in minutes.
}

パス・パラメータ(適切な認証を提供し、プレースホルダを実際のOCIリージョンおよびデータベースOCIDに置き換えます):

  • name: String: アクセス・キー名

  • description: String: アクセス・キーの説明

  • permissions: Array: (オプション)この配列の各オブジェクトは、許可される操作(アクション)および(オプションで)それらのアクションを制限する表(リソース)を定義します。

    • actions: Array of Strings (必須: キーが実行できる特定の操作をリストします)。たとえば、"CREATE_TABLE"、"READ_WRITE"、"ADMIN"です。)

    • resources: Array of Strings (オプション: アクションを適用する表を指定します。この配列にresources": ["customers", "orders"]などの表名をリストする場合、アクションはそれらの表のみに制限されます。省略すると、アクションはデータベース内のすべての表に適用されます。)

  • expiration_minutes: Number: (オプション)有効期限(分)

サンプル・レスポンス形式

{
  "name": "<access_key_name>",
  "description": "<access_key_description>",
  "access_key_id": "<access_key_id>",
  "secret_access_key": "<generated secret>",
  "expiration_timestamp": "<access_key_expiration_timestamp>",
  "permissions": [
    {
      "actions"  : [<permissions list>],
      "resources": [<optional DynamoDb table list>]
    }
    // ...more permission objects
  ]
}

例

この例では、POSTリクエストをOracle Autonomous AI Database REST APIに送信して、管理権限を持つ新しいアクセス・キーを作成する方法を示します。リクエストはキー名と必要な権限を指定し、レスポンスには新しく生成されたアクセス・キーID、シークレット、有効期限および権限が含まれます。

# Request
curl -X POST 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys'\
--user "AdminUser:TestPass#" \
--header 'Request-Id: 8g89mz8qnet9ufxg4dwrus8m' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "adminkey",
    "permissions": [
        {
            "actions": [
                "ADMIN_ANY"
            ]
        }
    ],
    "expiration_minutes": 120
}'

# Sample Response
{
    "access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
    "secret_access_key": "NzYwZDE5M2E4NDVjZ.....FmMzBiNQ>>",
    "expiration_time": "2025-12-07T03:35:12Z",
    "permissions": [
        {
            "actions": [
                "ADMIN_ANY"
            ]
        }
    ]
}

リクエスト・パラメータ:

  • database-ocid: アクセス・キーが作成されるデータベースのOCID。

  • AdminUser: 認証に使用されるデータベース・ユーザー名。

  • TestPass#: データベース・ユーザーのパスワード。

  • Request-Id: APIリクエストの一意の識別子で、追跡またはトラブルシューティングに役立ちます。

  • Content-Type: リクエスト・ペイロードの形式をJSON (application or json)として指定します。

  • name: 新しいアクセス・キーに割り当てる名前。

  • permissions: 新しいキーに割り当てる権限を指定する配列。

    • actions: アクセス・キーに対して許可されるアクションの配列(管理権限の場合は「ADMIN_ANY」など)

  • expiration_minutes: アクセス・キーが期限切れになるまでの期間を分単位で指定します。

レスポンス・パラメータ:

  • access_key_id: 新しく作成されたアクセス・キーの一意の識別子。

  • secret_access_key: アクセス・キーに関連付けられたシークレット値。これは、将来のAPIリクエストを認証するために必要です。

  • expiration_time: アクセス・キーが失効するタイミングを示すタイムスタンプ。

  • アクセス・キーに割り当てられた権限オブジェクトの配列(リクエストで指定)。

    • actions: アクセス・キーに対して許可されるアクション(管理権限の場合は「ADMIN_ANY」など)

アクセス・キー情報の取得

アクセス・キーを作成した後、GET /accesskeys REST APIリクエストを使用して、その名前、関連付けられた権限、有効期限およびその他の関連メタデータなどの詳細を検索します。これにより、プログラムでアクセス権を確認したり、資格証明を監査したり、アクセス・キー情報を表示したりできます。

アクセス・キーの詳細を取得する構文と例:

構文

GET https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys/{access_key_id}
    Authorization: Basic <Base64-encoded
    database username and password>request-id: <optional request-id>

例

次のコールは、指定されたアクセス・キーに関する詳細情報を取得します。これにより、アクセス・キーに関連付けられている属性および権限を確認できます。

# Request
curl -X GET 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys/ak_og67ZI8bdS.....BiHCda7l' \
--user "AdminUser:TestPass#" \
--header 'Request-Id: xcz5efdb7rfrbsfkkwwl7d38' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

# Sample Response
{
    "access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
    "expiration_timestamp": "2025-12-07T03:35:12.751Z",
    "permissions": [
        {
            "actions": [
                "ADMIN_ANY"
            ]
        }
    ]
}

リクエスト・パラメータ

  • database-ocid: 問合せ対象のAutonomous AI Databaseの一意のOracle Cloud Identifier (OCID)。

  • access-key-id: 詳細がリクエストされる特定のアクセス・キーの一意の識別子。

  • AdminUser: 認証に使用されるデータベース・ユーザー名。

  • TestPass#: データベース・ユーザーのパスワード。

  • Request-Id: このAPIリクエストの一意の識別子。ロギングまたはトラブルシューティングに役立ちます。

  • Content-Type: レスポンスの予期される形式(applicationまたはjson、ヘッダーで設定)を指定します。

  • Accept: レスポンス形式を指定します。

アクセス・キーの更新

アクセス・キーを作成および取得した後、PUT /accesskeys REST APIを使用して既存のアクセス・キーの属性を更新します。

アクセス・キーを更新する構文と例:

構文

PUT https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys/{access_key_id}
    Authorization: Basic <Base64-encoded database username and password>
    request-id: <optional request-id>
    Content-Type: application/json

{
  "permissions": [<permissions array>],
  "extend_expiration_minutes_by": <integer>
}

例

次のリクエストは、アクセス・キーを更新して有効期限を120分延長します。

# Request
curl -X PUT 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys/ak_og67ZI8bdS.....BiHCda7l' \
--user "AdminUser:TestPass#" \
--header 'Request-Id: xzpqvei6e7x52ri94odpv0a4' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "extend_expiration_minutes_by" : 120
}'

# Sample Response

{
    "access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
    "expiration_timestamp": "2025-12-07T05:35:12.751Z",
    "permissions": [
        {
            "actions": [
                "ADMIN_ANY"
            ]
        }
    ],
    "message": "Expiration extended by 120 min"
}

リクエスト・パラメータ

  • database-ocid: 問合せ対象のAutonomous AI Databaseの一意のOracle Cloud Identifier (OCID)。

  • access-key-id: 詳細がリクエストされる特定のアクセス・キーの一意の識別子。

  • AdminUser: 認証に使用されるデータベース・ユーザー名。

  • TestPass#: データベース・ユーザーのパスワード。

  • Request-Id: このAPIリクエストの一意の識別子。ロギングまたはトラブルシューティングに役立ちます。

  • Content-Type: レスポンスの予期される形式(applicationまたはjson、ヘッダーで設定)を指定します。

  • Accept: レスポンス形式を指定します。

  • extend_expiration_minutes_by: (本文)アクセス・キーの有効期限を延長する分数。

応答パラメータ

  • access_key_id: 更新されたアクセス・キーの一意の識別子。

  • expiration_timestamp: アクセス・キーの新しい有効期限タイムスタンプ。

  • permissions: アクセス・キーに関連付けられた権限を記述する配列。

    • actions: 許可されるアクションのリスト(例: "ADMIN_ANY")。

  • message: 実行されたアクションを示す確認メッセージ。

アクセス・キーの削除

既存のアクセス・キーが不要になった場合は削除できます。DELETE /accesskeys REST APIを使用して、データベースからアクセス・キーを削除します。

データベースからアクセス・キーを削除する構文と例:

構文

DELETE https://dataaccess.adb.{oci-region-name}.oraclecloudapps.com/adb/auth/v1/databases/{database-ocid}/accesskeys/{access_key_id}
    Authorization: Basic <Base64-encoded database username and password>
    request-id: <optional request-id>

例

次のリクエストは、指定されたアクセス・キーをAutonomous AIデータベースから削除します。削除されたキーは、認証またはデータベース・アクセスに使用できなくなります。削除に成功すると、HTTPステータス・コード204 No Contentまたは200 OKが返され、レスポンス本文はありません。

# Request
curl -X DELETE 'https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/auth/v1/databases/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE/accesskeys/ak_og67ZI8bdS.....BiHCda7l' \
--user "AdminUser:TestPass#" \
--header 'Request-Id: xzpqvei6e7x52ri94odpv0a4' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
# Sample Response

{
    "message": "Access key deleted successfully.",
    "access_key_id": "ak_og67ZI8bdS.....BiHCda7l",
    "status": "DELETED"
}

リクエスト・パラメータ

  • database-ocid: 問合せ対象のAutonomous AI Databaseの一意のOracle Cloud Identifier (OCID)。

  • access-key-id: 詳細がリクエストされる特定のアクセス・キーの一意の識別子。

  • AdminUser: 認証に使用されるデータベース・ユーザー名。

  • TestPass#: データベース・ユーザーのパスワード。

  • Request-Id: このAPIリクエストの一意の識別子。ロギングまたはトラブルシューティングに役立ちます。

  • Content-Type: レスポンスの予期される形式(applicationまたはjson、ヘッダーで設定)を指定します。

応答パラメータ

  • message: 削除操作の結果を示す確認メッセージ。

  • access_key_id: 更新されたアクセス・キーの一意の識別子。

  • status: 削除後のアクセス・キーの最終ステータス(「DELETED」など)。

DynamoDBのAPIを呼び出す手順

DynamoDBのAPIを有効にし、アクセス・キーを作成した後、DynamoDBクライアントSDKを使用して、DynamoDBのOracle AI Database APIを起動できます。

次のステップに従って、DynamoDBのAutonomous AI Database APIを起動するようにDynamoDBクライアントを構成します。

Autonomous AI Database DynamoDBエンドポイントを使用したDynamoDbClientの構成**

  • AWS資格証明ファイルの更新

    ~/.aws/credentialsにあるAWS資格証明ファイルにナビゲートし、ファイルが存在しない場合は作成します。資格証明ファイルを、Autonomous AI Database API for DynamoDBに対して生成されたアクセス・キーIDおよびシークレット・アクセス・キーで更新します。次に例を示します。

    aws_access_key_id=<Your ADB-S DynamoDB Compatible APIs Access Key ID>
aws_secret_access_key=<Your ADB-S DynamoDB Compatible APIs Secret Access Key>

  • Autonomous AI Databaseエンドポイントを使用するようにDynamoDBクライアント・コードを更新します。

    たとえば、次のコードでは、Autonomous AI Databaseエンドポイントを指すようにJava SDKを使用してDynamoDBクライアントを構成します:

    import java.net.URI;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;

// Set the appropriate region and endpoint.
//Region name is optional and will be overridden by the region value specified in the REST API endpoint.
Region region = Region.US_EAST_1;
String endpoint = "https://dataaccess.adb.us-phoenix-1.oraclecloudapps.com/adb/keyvaluestore/v1/OCID1.AUTONOMOUSDATABASE.OC1.PHX.ANYHQLJRGDV...EXAMPLE";

// Build the DynamoDB client using a custom endpoint
DynamoDbClient ddb = DynamoDbClient.builder()
    .region(region)
    .endpointOverride(URI.create(endpoint))
    .build();

    この例では、クライアントがDynamoDB RESTエンドポイントのAutonomous AI Database APIを指すように、デフォルトのエンドポイントをオーバーライドします。

コード エレメント

  • DynamoDbClient.builder(): 新しいDynamoDbClient.Builderインスタンスを初期化します。このビルダーは、AWS SDK for Javaの一部であり、DynamoDBクライアント・インスタンスの作成に使用されます。

  • region(Region region): クライアントが動作するAWSリージョンを指定します。このリージョン名はオプションであり、REST APIエンドポイントで指定されたリージョン値によってオーバーライドされることに注意してください。

  • endpointOverride(URI endpoint): デフォルトのAWSサービス・エンドポイントではなく、指定されたDynamoDB互換HTTPエンドポイントと通信するようにクライアントを構成します。

  • build(): ビルダー構成をファイナライズし、指定された設定で新しいDynamoDbClientインスタンスを作成します。

Python (Boto3を使用)、C++など、他のプログラミング言語および対応するAWS SDKを使用して、DynamoDBクライアント・エンドポイントを構成またはオーバーライドすることもできます。

言語別のDynamoDB SDK参照を参照してください。

自律型AIデータベースでのDynamoDBのAPIの使用

次のコードは、DynamoDB表movieを作成し、カスタム・エンドポイントを含むJava AWS SDK v2を使用してアイテムを記述、リスト、挿入、更新および削除する基本的な操作を実行する方法を示しています。

import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.*;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import java.net.URI;
import java.util.Map;

public class DynamoDBMovieExample {
    public static void main(String[] args) {
        // Set the region and endpoint
        //Region name is optional and will be overridden by the region value specified in the REST API endpoint.
        Region region = Region.US_WEST_1;
        String endpoint = "https://region.us-phoenix-1.adb.oraclecloud.com";

        // Build the DynamoDB client using a custom endpoint
        DynamoDbClient ddb = DynamoDbClient.builder()
            .region(region)
            .endpointOverride(URI.create(endpoint))
            .build();

        // Create table
        CreateTableRequest createTableRequest = CreateTableRequest.builder()
            .tableName("movie")
            .keySchema(
                KeySchemaElement.builder().attributeName("PK").keyType(KeyType.HASH).build(),
                KeySchemaElement.builder().attributeName("SK").keyType(KeyType.RANGE).build()
            )
            .attributeDefinitions(
                AttributeDefinition.builder().attributeName("PK").attributeType(ScalarAttributeType.S).build(),
                AttributeDefinition.builder().attributeName("SK").attributeType(ScalarAttributeType.S).build()
            )
            .provisionedThroughput(
                ProvisionedThroughput.builder().readCapacityUnits(5L).writeCapacityUnits(5L).build()
            )
            .build();
        ddb.createTable(createTableRequest);

        // Describe the table
        DescribeTableRequest descRequest = DescribeTableRequest.builder().tableName("movie").build();
        DescribeTableResponse descResponse = ddb.describeTable(descRequest);

        // List all tables
        ListTablesRequest listRequest = ListTablesRequest.builder().build();
        ListTablesResponse listResponse = ddb.listTables(listRequest);

        // Insert (PutItem)
        ddb.putItem(PutItemRequest.builder()
            .tableName("movie")
            .item(Map.of(
                "PK", AttributeValue.builder().s("001").build(),
                "SK", AttributeValue.builder().s("MOVIE").build(),
                "Title", AttributeValue.builder().s("Inception").build()))
            .build()
        );

        // Update (UpdateItem)
        ddb.updateItem(UpdateItemRequest.builder()
            .tableName("movie")
            .key(Map.of(
                "PK", AttributeValue.builder().s("001").build(),
                "SK", AttributeValue.builder().s("MOVIE").build()))
            .updateExpression("SET #T = :t")
            .expressionAttributeNames(Map.of("#T", "Title"))
            .expressionAttributeValues(Map.of(":t", AttributeValue.builder().s("Inception (2010)").build()))
            .build()
        );

        // Delete (DeleteItem)
        ddb.deleteItem(DeleteItemRequest.builder()
            .tableName("movie")
            .key(Map.of(
                "PK", AttributeValue.builder().s("001").build(),
                "SK", AttributeValue.builder().s("MOVIE").build()))
            .build()
        );
    }
}

使用上のノート

DynamoDBのAutonomous AI Database APIの無効化

自律型AIデータベースのDynamoDB APIを無効にするステップを示します。

必要に応じて、次の前提条件ステップを実行します:

  • Oracle Cloud Infrastructure Consoleを開くには、クラウドの横にあるナビゲーション・アイコンをクリックします。

  • Oracle Cloud Infrastructureの左側のナビゲーション・メニューから、「Oracle AI Database」をクリックし、「Autonomous AI Database」をクリックします。

  • 「Autonomous AI Database」ページで、「表示名」列の下のリンクからAutonomous AI Databaseを選択します。

Autonomous AI DatabaseインスタンスでDynamoDBのAPIを無効にするには、次のステップに従います:

  1. 「その他のアクション」ドロップダウン・リストで、「タグの管理」を選択します。

    「タグの追加」ページが表示されます。

  2. 次の値を指定して、Autonomous AI Databaseにタグを割り当てます。

    • ネームスペース:フリー・フロントのタグを追加するには、値を空白のままにします。

    • キー: adb$feature

    • 値: {"name":"DynamoDB_API","enable": false}

    タグを追加するには、「追加」をクリックします。

    「追加」をクリックすると、「ライフサイクル状態」フィールドに「更新中」が表示され、Autonomous AI Databaseによって「Autonomous AIデータベース・タグの更新」作業リクエストが生成されます。リクエストを表示するには、詳細ページで「作業リクエスト」タブを選択します。

Oracle AI Database API for DynamoDBの使用に関するノートと制限事項

Autonomous AI DatabaseでOracle AI Database API for DynamoDBを使用するためのノートと制限事項を示します。

Autonomous AI DatabaseでOracle AI Database API for DynamoDBを使用する場合は、次の点に注意してください。

使用上のノート

  • Oracle AI Database API for DynamoDBが有効になっているAutonomous AI Databaseが削除されると、関連するすべてのDynamoDB互換表も削除され、請求が停止します。

  • DynamoDBのAPIが有効になっているAutonomous AI Databaseが停止した場合、関連するすべてのDynamoDB表は、停止した期間中はECPU消費に対して請求されませんが、Autonomous AI Databaseの管理が停止している間は使用できません。データベースが停止している間も、ストレージ料金は引き続き適用されます。

  • 関連付けられたすべてのDynamoDB表は、前述の削除操作または停止操作の影響を受けます。

制限事項

  • 開発者向けの無料Autonomous AI DatabaseおよびAutonomous AI Databaseごとに最大2つのDynamoDBテーブルが許可されます。

  • DynamoDBテーブル当たり最大4個のECPUが、開発者向けの無料Autonomous AI DatabaseおよびAutonomous AI Databaseごとに許可されます。

  • 表名の長さは3文字から255文字の間である必要があります。

  • グローバル表APIおよびPartiQL APIはサポートされていません。

Amazon DynamoDBとのトランザクション互換性

Amazon DynamoDBとAutonomous AI Database API for DynamoDBはどちらも原子性トランザクションをサポートしています。ただし、同じアイテムに対する同時操作を管理するには、様々な方法を使用します。トランザクションの競合または関連する例外を使用するアプリケーションを移行して同時作業を調整する場合は、これらの違いを確認します。

Amazon DynamoDBトランザクション動作

TransactWriteItemsおよびTransactGetItems操作は、最大100個のアイテム(最大4MBの集計サイズ)を単一のオール・オア・ナッシング操作にグループ化します。Amazon DynamoDBは、2段階のサーバー側プロトコルを使用して各トランザクションを処理します。トランザクションは、両方のフェーズが成功し、クライアント・アプリケーションがどちらのフェーズも制御しない場合にのみ成功します。

Amazon DynamoDBは、オプティミスティックな同時実行性制御を使用します。トランザクションの期間中はロックを保持しません。かわりに、競合する同時操作が検出され、他の操作の完了を待機するのではなく、影響を受けるリクエストが取り消されます。

次のポイントでは、Amazon DynamoDBが同時トランザクションを処理する方法について説明します。

  • 競合するトランザクションは、キューに入れられるのではなく取り消されます。 TransactWriteItemsリクエストが、同じアイテムに対して進行中の別のTransactWriteItemsリクエストと競合する場合、影響を受けるリクエストはTransactionCanceledExceptionで失敗します。2つのトランザクションが競合し、1つまたは両方のリクエストを取り消すことができる場合、保証ウィナーはありません。AWS SDKはTransactionCanceledExceptionを自動的に再試行しないため、アプリケーションはリクエストを再試行する必要があります。

  • 標準書込みは、進行中のトランザクションと競合する場合に拒否できます。 PutItem、UpdateItemまたはDeleteItemリクエストが、同じアイテムに対する進行中のTransactWriteItemsリクエストと競合する場合、標準書込みはTransactionConflictExceptionで失敗します。標準書込みでは、トランザクションは取り消されません。

  • 読取りではコミットされたデータが返されますが、複数項目読取りではアトミック・ビューが返されない場合があります。 トランザクションおよび単一のGetItem操作には、シリアライズ可能な分離があります。トランザクションおよび複数項目読取り(Query、Scan、BatchGetItem、複数の個別のGetItemリクエストなど)には、読取りコミットされた分離があります。読取りではコミットされていないデータは返されませんが、トランザクションの進行中に一部のアイテムの新しい状態および他のアイテムの前の状態を戻すことができます。アプリケーションで複数のアイテムのアトミック・ビューが必要な場合は、TransactGetItemsを使用します。

ClientRequestTokenを介した条件式、オール・オア・ナッシングのアトミック性、取消し理由およびオプションの冪等性は、DynamoDB API契約の一部のままです。ただし、同時実行性関連のキャンセルは、Amazon DynamoDBとAutonomous AI Database API for DynamoDBで異なります。

DynamoDBトランザクション動作のためのAutonomous AI Database API

Autonomous AI Database API for DynamoDBは、Oracle AI DatabaseのデフォルトのREAD COMMITTED分離レベルを使用してトランザクション操作を実行します。これにより、トランザクションの原子性が保持され、ダーティ読取りが防止されます。

主な違いは、同時実行性モデルです。Oracle AI Databaseでは、行レベルのロックと悲観的な同時実行性制御を使用します。同時操作が同じ項目を変更すると、通常、後の操作は前の操作が完了するまで待機してから続行します。通常、この操作は競合のために取り消されません。

その結果、同じアイテムに対する同時操作は、拒否されるのではなく、完了する可能性が高くなります。ただし、操作はロックを待機できます。循環ロック依存のまれなケースでは、Oracle AI Databaseはデッドロックを検出し、1つのトランザクションを被害者として選択してロールバックします。

READ COMMITTEDは互換性のデフォルトです。これは、Amazon DynamoDBアプリケーションが、最初にコミットされた2つの同時トランザクション、または特定の競合結果に依存できないためです。Amazon DynamoDBは、トランザクション順序を内部的に決定します。同時操作がAutonomous AI Databaseでシリアライズおよび完了した場合、その順序に依存しないアプリケーションには互換性があります。

トランザクション動作比較

同じアイテムに対する同時操作 Amazon DynamoDB Autonomous AI Database API for DynamoDB 移行の考慮事項
TransactWriteItemsと別の競合するTransactWriteItems オプティミスティック競合検出では、影響を受けるトランザクションがTransactionCanceledExceptionで取り消されます。1つまたは両方のトランザクションを取り消すことができ、クライアントはリクエストを再試行する必要があります。 行レベルのロックによって、トランザクションがシリアライズされます。通常、両方のトランザクションはコミット順に完了します。循環依存が原因でデッドロックが発生し、その場合は1つのトランザクションがロールバックされます。 作業を拒否または調整するために、トランザクションの競合に依存しないでください。
TransactWriteItemsおよびPutItem、UpdateItemまたはDeleteItem 標準書込みはTransactionConflictExceptionで拒否されます。トランザクションは続行されます。 標準書込みは行ロックを待機し、通常はトランザクションの後に完了します。トランザクションの競合のため、否認されません。 拒否された標準書込みを別のトランザクションが進行中であることを示すシグナルとして処理するアプリケーション・ロジックをレビューします。
TransactGetItemsおよび進行中のTransactWriteItems 読取りトランザクションは、TransactionCanceledExceptionを使用して取り消すことができます。単一のGetItemリクエストは取り消されません。どちらの操作も成功できます。 通常、読取りは、分離競合が原因で失敗するのではなく、読取りコミットされた分離を使用して完了します。 データがロックされていることを示す取消を解釈する読者を確認します。
進行中のトランザクション中の複数アイテム非トランザクション読取り Query、Scan、BatchGetItemまたは複数のGetItemリクエストは、読取りコミットされた分離を使用します。結果には、トランザクションの前後の品目状態の組合せを含めることができます。アトミック・ビューが必要な場合は、TransactGetItemsを使用します。 読取りではREAD COMMITTED分離が使用され、コミットされていないデータは返されません。また、Oracle AI Databaseでは、文が開始された時点での文ごとに一貫性のあるビューが提供されます。 どちらの実装もダーティ読取りを防止します。アプリケーションで原子性複数項目ビューが必要な場合は、TransactGetItemsを使用します。
TransactWriteItemsおよびBatchWriteItem バッチは単一のシリアライズ可能操作ではありません。その個々の書込みはトランザクションでシリアライズ可能であり、部分的に成功する可能性があります。 個々のバッチは、行ロックに対してシリアライズを書き込み、一般に完了します。 最終状態を検証し、アプリケーションが部分バッチの失敗を処理することを確認します。
条件式とオール・オア・ナッシング原子性 条件が施行されます。失敗した条件は、トランザクション取消事由でレポートされます。 条件が適用され、引き続きAPI契約の一部となります。 条件式、取消事由および部分的な結果に対する保護のテストを続行します。

どちらの実装の場合も、有効な順序はデータベースが操作を実行する順序であり、APIがリクエストを受信する順序とは異なる場合があります。アプリケーションは、どのコンカレント要求がどのコンカレント要求に勝つかを想定したり、コミットされた結果を決定したりしないでください。

移行前のトランザクション動作の確認

アプリケーションを移行する前に、Amazon DynamoDB競合応答を使用して作業を調整するロジックを確認します。これには、オプティミスティック・ロック、ジョブ要求、インベントリの予約、一意性の実施、およびTransactionConflictExceptionまたはTransactionCanceledExceptionに基づく再試行の決定が含まれます。

Autonomous AI Database API for DynamoDBでは、同じアイテムに対する同時操作は通常、拒否されるのではなく待機して完了します。次の同時操作をテストします。

  • 2つの競合するTransactWriteItemsリクエスト。

  • TransactWriteItemsリクエストと、標準のPutItem、UpdateItemまたはDeleteItemリクエスト。

  • 進行中のトランザクション書込み中のTransactGetItemsリクエスト。

  • 進行中のトランザクション中の複数アイテム読取りおよびバッチ書込み。

アプリケーションが次のようになっていることを確認します。

  • 作業の調整にトランザクション競合例外のみに依存しません。

  • 再試行、ロック待機、および可能なデッドロックロールバックを処理します。

  • 条件式、冪等性トークンおよび結果の状態の検証を使用して、正確性を強制します。

  • 複数のアイテムのアトミック・ビューが必要な場合、TransactGetItemsを使用します。

  • 同時または部分的に完了したバッチ操作の後の最終状態を検証します。

Autonomous AI Database DynamoDBテーブルへのデータのインポートとエクスポート

既存のAmazon DynamoDBテーブルからAutonomous AI Database DynamoDBテーブルにデータをインポートし、他のシステムで使用するためにAutonomous AI Database DynamoDBテーブルからデータをエクスポートできます。

インポートおよびエクスポートに必要なOCIポリシー

インポートまたはエクスポート操作を実行する前に、Autonomous AI Database API for DynamoDBがデータ転送に使用されるOCIオブジェクト・ストレージ・バケットにアクセスできるようにする動的グループおよびIAMポリシーを作成します。

動的グループの作成

Autonomous AI Databaseの管理のリソースIDを指定する動的グループを作成します:

resource.id = '<database-ocid>'

IAMポリシーの作成

動的グループがインポートおよびエクスポート操作に使用されるOCIオブジェクト・ストレージ・バケットにアクセスできるようにするポリシーを作成します:

allow dynamic-group <dynamic-group> to use buckets in compartment <bucket-compartment> where target.resource.id = <bucket-ocid>

allow dynamic-group <dynamic-group> to use objects in compartment <bucket-compartment> where target.resource.id = <bucket-ocid>

詳細は、リソース・プリンシパルを使用したOracle Cloud Infrastructureリソースへのアクセスを参照してください。

DynamoDBテーブルのインポート

ImportTable操作により、既存のAmazon DynamoDBのお客様は、Amazon DynamoDB表からAutonomous AI Database DynamoDB表にデータを移行できます。

インポート・プロセスは次のステップで構成されます。

  1. 既存の Amazon DynamoDBテーブルから Amazon S3バケットにデータをエクスポートします。詳細は、DynamoDB data export to Amazon S3を参照してください。

  2. エクスポートされたデータをAmazon S3バケットからOCI Object Storageバケットにコピーします。

  3. ImportTable APIを使用して、OCIオブジェクト・ストレージ・バケットからAutonomous AI Database DynamoDBTableにデータをインポートします。

    ImportTableリクエストの例

    {
  "TableCreationParameters": {
    "TableName": "importExampleTable",
    "AttributeDefinitions": [
      {
        "AttributeName": "p",
        "AttributeType": "S"
      }
    ],
    "KeySchema": [
      {
        "AttributeName": "p",
        "KeyType": "HASH"
      }
    ],
    "ProvisionedThroughput": {
      "ReadCapacityUnits": 200,
      "WriteCapacityUnits": 200
    }
  },
  "S3BucketSource": {
    "S3Bucket": "<object-storage-private-bucket-url>"
  },
  "InputFormat": "JSON"
}

次の入力形式がサポートされています:

  • JSON

  • CSV

DynamoDBテーブルのエクスポート

ExportTable操作を使用すると、他のシステムで使用するためにAutonomous AI Database DynamoDB表からデータをエクスポートできます。

エクスポートされたデータは、リクエストで指定したOCIオブジェクト・ストレージ・バケットに書き込まれます。

{
  "ClientToken"  : "anewone5",
  "ExportFormat" : "JSON",
  "TableArn"     : "<table-arn>",
  "S3Bucket"     : "<object-storage-private-bucket-url>"
}

サポートされている形式は次のとおりです。

  • JSON

  • CSV