Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Menggunakan RDS Data API

Dengan menggunakan RDS Data API (Data API), Anda dapat bekerja dengan antarmuka layanan web ke cluster Aurora DB Anda. Data API tidak memerlukan koneksi persisten ke cluster DB. Sebaliknya, ia menyediakan titik akhir HTTP yang aman dan integrasi dengan AWS SDKs. Anda dapat menggunakan titik akhir untuk menjalankan pernyataan SQL tanpa mengelola koneksi.

Pengguna tidak perlu meneruskan kredensil dengan panggilan ke Data API, karena Data API menggunakan kredenal database yang disimpan di dalamnya. AWS Secrets Manager Untuk menyimpan kredensil di Secrets Manager, pengguna harus diberikan izin yang sesuai untuk menggunakan Secrets Manager, dan juga Data API. Lihat informasi selengkapnya tentang mengizinkan pengguna di Mengotorisasi akses ke RDS Data API.

Anda juga dapat menggunakan Data API untuk mengintegrasikan Amazon Aurora dengan AWS aplikasi lain seperti AWS Lambda, AWS AppSync, dan. AWS Cloud9 Data API menyediakan cara yang lebih aman untuk digunakan AWS Lambda. API ini memungkinkan Anda mengakses klaster basis data tanpa perlu mengonfigurasi fungsi Lambda untuk mengakses sumber daya di cloud privat virtual (VPC). Lihat informasi selengkapnya di AWS Lambda, AWS AppSync, dan AWS Cloud9.

Anda dapat mengaktifkan Data API saat membuat cluster Aurora DB. Anda juga dapat mengubah konfigurasinya di lain waktu. Untuk informasi selengkapnya, lihat Mengaktifkan API Data RDS.

Setelah mengaktifkan Data API, Anda juga dapat menggunakan editor kueri untuk menjalankan kueri ad hoc tanpa mengonfigurasi alat kueri untuk mengakses Aurora di VPC. Untuk informasi selengkapnya, lihat Menggunakan editor kueri Aurora.

Wilayah dan ketersediaan versi

Untuk informasi tentang Wilayah dan versi engine yang tersedia untuk Data API, lihat bagian berikut.

Jika Anda memerlukan modul kriptografi yang divalidasi oleh FIPS 140-2 saat mengakses Data API melalui antarmuka baris perintah atau API, gunakan titik akhir FIPS. Lihat informasi selengkapnya tentang titik akhir FIPS yang tersedia di Standar Pemrosesan Informasi Federal (FIPS) 140-2.

Keterbatasan dengan API Data RDS

RDS Data API memiliki batasan sebagai berikut:

Perbandingan RDS Data API dengan Serverless v2 dan provisioned, dan Aurora Serverless v1

Peningkatan terbaru untuk RDS Data API membuatnya tersedia untuk cluster yang menggunakan versi terbaru dari mesin PostgreSQL atau MySQL. Cluster tersebut dapat dikonfigurasi untuk digunakan Aurora Serverless v2, atau kelas instance yang disediakan seperti db.r6g atau. db.r6i

Tabel berikut menjelaskan perbedaan antara RDS Data API (Data API) dengan Aurora Serverless v2 dan kluster DB yang disediakan, dan Aurora Serverless v1 klaster DB. Aurora Serverless v1 Cluster DB menggunakan mode serverless mesin. Cluster DB yang disediakan menggunakan mode mesin. provisioned Sesi Aurora Serverless v2 Cluster DB juga menggunakan mode provisioned mesin, dan berisi satu atau lebih Aurora Serverless v2 Instance DB dengan kelas db.serverless instance.

Mengotorisasi akses ke RDS Data API

Pengguna dapat menjalankan operasi RDS Data API (Data API) hanya jika mereka berwenang untuk melakukannya. Anda dapat memberikan izin kepada pengguna untuk menggunakan Data API dengan melampirkan kebijakan AWS Identity and Access Management (IAM) yang menentukan hak istimewa mereka. Anda juga dapat melampirkan kebijakan ini pada peran jika Anda menggunakan peran IAM. Kebijakan AWS terkelolaAmazonRDSDataFullAccess, termasuk izin untuk API Data.

AmazonRDSDataFullAccessKebijakan ini juga mencakup izin bagi pengguna untuk mendapatkan nilai rahasia. AWS Secrets Manager Pengguna perlu menggunakan Secrets Manager untuk menyimpan rahasia yang dapat mereka gunakan dalam panggilan mereka ke Data API. Menggunakan rahasia berarti bahwa pengguna tidak perlu menyertakan kredensi database untuk sumber daya yang mereka targetkan dalam panggilan mereka ke Data API. Data API secara transparan memanggil Secrets Manager, yang memungkinkan (atau menolak) permintaan pengguna untuk rahasia tersebut. Untuk informasi tentang menyiapkan rahasia yang akan digunakan dengan Data API, lihatMenyimpan kredensi database di AWS Secrets Manager.

AmazonRDSDataFullAccessKebijakan ini menyediakan akses lengkap (melalui Data API) ke sumber daya. Anda dapat mempersempit cakupan dengan menentukan kebijakan Anda sendiri yang menentukan Amazon Resource Name (ARN) sumber daya.

Misalnya, kebijakan berikut menunjukkan contoh izin minimum yang diperlukan bagi pengguna untuk mengakses Data API untuk klaster DB yang diidentifikasi oleh ARN-nya. Kebijakan tersebut mencakup izin yang diperlukan untuk mengakses Secrets Manager dan mendapatkan otorisasi ke instans basis data untuk pengguna.

{
    "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"
        }
    ]
}

Kami menyarankan agar Anda menggunakan ARN khusus untuk elemen "Sumber Daya" dalam pernyataan kebijakan Anda (seperti yang ditunjukkan dalam contoh), bukan karakter wildcard (*).

Bekerja dengan otorisasi berbasis tag

RDS Data API (Data API) dan Secrets Manager keduanya mendukung otorisasi berbasis tag. Tag adalah pasangan nilai kunci yang melabeli sumber daya, seperti klaster RDS, dengan nilai string tambahan, misalnya:

Anda dapat menerapkan tag ke sumber daya Anda untuk alokasi biaya, dukungan operasi, kontrol akses, dan banyak alasan lainnya. (Jika Anda belum memiliki tag pada sumber daya dan ingin menerapkannya, Anda dapat mempelajari lebih lanjut di Memberi tag pada sumber daya Amazon RDS.) Anda dapat menggunakan tag dalam pernyataan kebijakan Anda untuk membatasi akses ke klaster RDS yang dilabeli tag ini. Sebagai contoh, klaster basis data Aurora mungkin memiliki tag yang mengidentifikasi lingkungannya sebagai produksi atau pengembangan.

Contoh-contoh berikut menunjukkan bagaimana Anda dapat menggunakan tag dalam pernyataan kebijakan Anda. Pernyataan ini mengharuskan klaster dan rahasia yang diteruskan dalam permintaan API Data memiliki tag environment:production.

Begini cara kebijakan diterapkan: Saat pengguna melakukan panggilan menggunakan Data API, permintaan akan dikirim ke layanan. Data API pertama-tama memverifikasi bahwa ARN cluster yang diteruskan dalam permintaan ditandai dengan. environment:production API ini kemudian memanggil Secrets Manager untuk mengambil nilai rahasia pengguna dalam permintaan tersebut. Secrets Manager juga memverifikasi bahwa rahasia pengguna ditandai dengan environment:production. Jika demikian, API Data kemudian menggunakan nilai yang diambil untuk kata sandi basis data pengguna. Terakhir, jika itu juga benar, permintaan API Data berhasil diinvokasi untuk pengguna.

{
    "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"
                                        ]
                     }
             }
         }
     ]
}

Contoh menunjukkan tindakan terpisah untuk rds-data dan secretsmanager untuk Data API dan Secrets Manager. Namun, Anda dapat menggabungkan tindakan dan menentukan kondisi tag dengan berbagai cara untuk mendukung kasus penggunaan spesifik Anda. Lihat informasi selengkapnya di Menggunakan kebijakan berbasis identitas (kebijakan IAM) untuk Secrets Manager.

Di elemen "Kondisi" kebijakan, Anda dapat memilih kunci tag dari beberapa pilihan berikut:

Untuk mempelajari lebih lanjut tentang tag sumber daya dan cara menggunakannyaaws:TagKeys, lihat Mengontrol akses ke AWS sumber daya menggunakan tag sumber daya.

Menyimpan kredensi database di AWS Secrets Manager

Saat Anda memanggil RDS Data API (Data API), Anda meneruskan kredensil untuk klaster Aurora DB dengan menggunakan rahasia di Secrets Manager. Untuk memberikan kredensial dengan cara ini, Anda menentukan nama rahasia atau Amazon Resource Name (ARN) rahasia tersebut.

Lihat informasi selengkapnya tentang menggunakan Secrets Manager di Panduan Pengguna AWS Secrets Manager.

Untuk memahami bagaimana Amazon Aurora mengelola Identity and Access Management, lihat Bagaimana Amazon Aurora bekerja dengan IAM.

Lihat informasi selengkapnya tentang pembuatan kebijakan IAM di Membuat Kebijakan IAM dalam Panduan Pengguna IAM. Lihat informasi tentang cara menambahkan kebijakan IAM ke pengguna di Menambahkan dan Menghapus Izin Identitas IAM dalam Panduan Pengguna IAM.

Mengaktifkan API Data RDS

Untuk menggunakan RDS Data API (Data API), aktifkan untuk cluster Aurora DB Anda. Anda dapat mengaktifkan Data API saat membuat atau memodifikasi cluster DB.

Mengaktifkan RDS Data API saat Anda membuat database

Saat Anda membuat database yang mendukung RDS Data API (Data API), Anda dapat mengaktifkan fitur ini. Prosedur berikut menjelaskan cara melakukannya ketika Anda menggunakan AWS Management Console, AWS CLI, atau RDS API.

Mengaktifkan API Data RDS pada database yang ada

Anda dapat memodifikasi cluster DB yang mendukung RDS Data API (Data API) untuk mengaktifkan atau menonaktifkan fitur ini.

Mengaktifkan atau menonaktifkan Data API (Aurora Serverless v2 dan disediakan)

Gunakan prosedur berikut untuk mengaktifkan atau menonaktifkan Data API Aurora Serverless v2 dan database yang disediakan. Untuk mengaktifkan atau menonaktifkan Data API Aurora Serverless v1 database, gunakan prosedur diMengaktifkan atau menonaktifkan Data API (Aurora Serverless v1 hanya).

Mengaktifkan atau menonaktifkan Data API (Aurora Serverless v1 hanya)

Gunakan prosedur berikut untuk mengaktifkan atau menonaktifkan Data API pada yang sudah ada Aurora Serverless v1 basis data. Untuk mengaktifkan atau menonaktifkan Data API Aurora Serverless v2 dan database yang disediakan, gunakan prosedur di. Mengaktifkan atau menonaktifkan Data API (Aurora Serverless v2 dan disediakan)

Membuat endpoint Amazon VPC untuk RDS Data API ()AWS PrivateLink

Amazon VPC memungkinkan Anda meluncurkan AWS sumber daya, seperti cluster dan aplikasi Aurora DB, ke cloud pribadi virtual (VPC). AWS PrivateLink menyediakan konektivitas pribadi antara VPCs dan AWS layanan dengan keamanan tinggi di jaringan Amazon. Dengan menggunakan AWS PrivateLink, Anda dapat membuat titik akhir VPC Amazon, yang memungkinkan Anda terhubung ke layanan di berbagai akun dan VPCs berdasarkan Amazon VPC. Lihat informasi selengkapnya tentang AWS PrivateLink di Layanan Titik Akhir VPC (AWS PrivateLink) dalam Panduan Pengguna Amazon Virtual Private Cloud.

Anda dapat memanggil RDS Data API (Data API) dengan titik akhir Amazon VPC. Menggunakan endpoint Amazon VPC menjaga lalu lintas antar aplikasi di Amazon VPC dan Data API di AWS jaringan, tanpa menggunakan alamat IP publik. Titik akhir Amazon VPC dapat membantu Anda memenuhi persyaratan kepatuhan dan peraturan yang berkaitan dengan membatasi konektivitas internet publik. Misalnya, jika Anda menggunakan titik akhir VPC Amazon, Anda dapat menjaga lalu lintas antara aplikasi yang berjalan pada EC2 instans Amazon dan API Data di VPCs dalamnya.

Setelah membuat titik akhir Amazon VPC, Anda dapat mulai menggunakannya tanpa membuat kode atau perubahan konfigurasi apa pun di aplikasi Anda.

Setelah titik akhir dibuat, pilih tautan di AWS Management Console untuk melihat detail titik akhir.

Tab Detail titik akhir menunjukkan nama host DNS yang dibuat saat membuat titik akhir Amazon VPC.

Anda dapat menggunakan titik akhir standar (rds-data.region.amazonaws.com) atau salah satu titik akhir khusus VPC untuk memanggil API Data dalam Amazon VPC. Titik akhir API Data standar secara otomatis merutekan ke titik akhir Amazon VPC. Perutean ini terjadi karena nama host DNS Pribadi diaktifkan saat titik akhir Amazon VPC dibuat.

Saat Anda menggunakan titik akhir VPC Amazon dalam panggilan API Data, semua lalu lintas antara aplikasi Anda dan Data API tetap berada di Amazon VPCs yang mengandungnya. Anda dapat menggunakan titik akhir Amazon VPC untuk semua jenis panggilan API Data. Untuk informasi tentang memanggil Data API, lihatMemanggil RDS Data API.

Memanggil RDS Data API

Dengan RDS Data API (Data API) diaktifkan pada cluster Aurora DB Anda, Anda dapat menjalankan pernyataan SQL pada cluster Aurora DB dengan menggunakan Data API atau file. AWS CLI Data API mendukung bahasa pemrograman yang didukung oleh AWS SDKs. Untuk informasi selengkapnya, lihat Alat untuk dibangun AWS.

Referensi operasi API data

Data API menyediakan operasi berikut untuk melakukan pernyataan SQL.

Anda dapat menggunakan operasi mana pun untuk menjalankan pernyataan SQL individual atau untuk menjalankan transaksi. Untuk transaksi, Data API menyediakan operasi berikut.

Operasi untuk melakukan pernyataan SQL dan transaksi pendukung memiliki parameter dan AWS CLI opsi API Data umum berikut. Beberapa operasi mendukung parameter atau opsi lain.

RDS Data API mendukung tipe data berikut untuk Aurora MySQL:

RDS Data API mendukung jenis skalar Aurora PostgreSQL berikut:

RDS Data API mendukung tipe array Aurora PostgreSQL berikut:

Anda dapat menggunakan parameter dalam panggilan Data API ke ExecuteStatement danBatchExecuteStatement, dan ketika Anda menjalankan AWS CLI perintah execute-statement danbatch-execute-statement. Untuk menggunakan parameter, tentukan pasangan nama-nilai di tipe data SqlParameter. Tentukan nilai dengan tipe data Field. Tabel berikut memetakan tipe data Java Database Connectivity (JDBC) ke tipe data yang Anda tentukan dalam panggilan API Data.

Tipe tertentu, seperti DECIMAL danTIME, memerlukan petunjuk agar Data API meneruskan String nilai ke database sebagai tipe yang benar. Untuk menggunakan petunjuk, sertakan nilai untuk typeHint di tipe data SqlParameter. Berikut adalah nilai-nilai yang mungkin untuk typeHint:

Memanggil RDS Data API dengan AWS CLI

Anda dapat memanggil RDS Data API (Data API) menggunakan file. AWS CLI

Contoh berikut menggunakan AWS CLI for Data API. Lihat informasi selengkapnya di Referensi AWS CLI untuk API Data.

Dalam setiap contoh, ganti Amazon Resource Name (ARN) untuk cluster DB dengan ARN untuk cluster Aurora DB Anda. Selain itu, ganti ARN rahasia dengan ARN rahasia di Secrets Manager yang mengizinkan akses ke klaster basis data.

Memulai transaksi SQL

Anda dapat memulai transaksi SQL menggunakan perintah CLI aws rds-data begin-transaction. Panggilan ini menghasilkan pengidentifikasi transaksi.

Selain opsi umum, tentukan opsi --database yang menyediakan nama basis data.

Misalnya, perintah CLI berikut memulai transaksi SQL.

Untuk Linux, macOS, atau 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"

Untuk 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"

Berikut ini adalah contoh responsnya.

{
    "transactionId": "ABC1234567890xyz"
}

Menjalankan pernyataan SQL

Anda dapat menjalankan pernyataan SQL menggunakan perintah CLI aws rds-data execute-statement.

Anda dapat menjalankan pernyataan SQL dalam transaksi dengan menentukan pengidentifikasi transaksi dengan opsi --transaction-id. Anda dapat memulai transaksi menggunakan perintah CLI aws rds-data begin-transaction. Anda dapat mengakhiri dan menerapkan transaksi menggunakan perintah CLI aws rds-data commit-transaction.

Selain opsi umum, tentukan opsi-opsi berikut:

Klaster basis data menghasilkan respons untuk panggilan.

Misalnya, perintah CLI berikut menjalankan satu pernyataan SQL dan menghilangkan metadata dalam hasil (default).

Untuk Linux, macOS, atau 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"

Untuk 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"

Berikut adalah contoh respons tersebut.

{
    "numberOfRecordsUpdated": 0,
    "records": [
        [
            {
                "longValue": 1
            },
            {
                "stringValue": "ValueOne"
            }
        ],
        [
            {
                "longValue": 2
            },
            {
                "stringValue": "ValueTwo"
            }
        ],
        [
            {
                "longValue": 3
            },
            {
                "stringValue": "ValueThree"
            }
        ]
    ]
}

Perintah CLI berikut menjalankan satu pernyataan SQL dalam transaksi dengan menentukan opsi --transaction-id.

Untuk Linux, macOS, atau 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"

Untuk 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"

Berikut adalah contoh respons tersebut.

{
    "numberOfRecordsUpdated": 1
}

Perintah CLI berikut menjalankan satu pernyataan SQL dengan parameter.

Untuk Linux, macOS, atau 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\"}}]"

Untuk 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\"}}]"

Berikut adalah contoh respons tersebut.

{
    "numberOfRecordsUpdated": 1
}

Perintah CLI berikut menjalankan pernyataan SQL bahasa definisi data (DDL). Pernyataan DDL mengganti nama kolom job menjadi kolom role.

Untuk Linux, macOS, atau 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

Untuk 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

Berikut adalah contoh respons tersebut.

{
    "generatedFields": [],
    "numberOfRecordsUpdated": 0
}

Menjalankan pernyataan SQL batch pada array data

Anda dapat menjalankan pernyataan SQL batch pada array data dengan menggunakan perintah CLI aws rds-data batch-execute-statement. Anda dapat menggunakan perintah ini untuk melakukan impor massal atau operasi pembaruan.

Anda dapat menjalankan pernyataan SQL dalam transaksi dengan menentukan pengidentifikasi transaksi dengan opsi --transaction-id. Anda dapat memulai transaksi menggunakan perintah CLI aws rds-data begin-transaction. Anda dapat mengakhiri dan menerapkan transaksi menggunakan perintah CLI aws rds-data commit-transaction.

Selain opsi umum, tentukan opsi-opsi berikut:

Klaster basis data menghasilkan respons untuk panggilan.

Misalnya, perintah CLI berikut menjalankan pernyataan SQL batch pada array data dengan satu set parameter.

Untuk Linux, macOS, atau 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\"}}]]"

Untuk 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\"}}]]"

Menerapkan transaksi SQL

Dengan menggunakan perintah CLI aws rds-data commit-transaction, Anda dapat mengakhiri transaksi SQL yang Anda mulai dengan aws rds-data begin-transaction dan menerapkan perubahan.

Selain opsi umum, tentukan opsi-opsi berikut:

Misalnya, perintah CLI berikut mengakhiri transaksi SQL dan menerapkan perubahan.

Untuk Linux, macOS, atau 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"

Untuk 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"

Berikut adalah contoh respons tersebut.

{
    "transactionStatus": "Transaction Committed"
}

Membatalkan transaksi SQL

Dengan menggunakan perintah CLI aws rds-data rollback-transaction, Anda dapat membatalkan transaksi SQL yang Anda mulai dengan aws rds-data begin-transaction. Membatalkan transaksi akan membatalkan perubahannya.

Selain opsi umum, tentukan opsi-opsi berikut:

Misalnya, AWS CLI perintah berikut memutar kembali transaksi SQL.

Untuk Linux, macOS, atau 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"

Untuk 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"

Berikut adalah contoh respons tersebut.

{
    "transactionStatus": "Rollback Complete"
    }

Memanggil RDS Data API dari aplikasi Python

Anda dapat memanggil RDS Data API (Data API) dari aplikasi Python.

Contoh berikut menggunakan AWS SDK untuk Python (Boto). Lihat informasi selengkapnya tentang Boto, lihat Dokumentasi AWS SDK for Python (Boto 3).

Dalam setiap contoh, ganti Amazon Resource Name (ARN) cluster DB dengan ARN untuk cluster Aurora DB Anda. Selain itu, ganti ARN rahasia dengan ARN rahasia di Secrets Manager yang mengizinkan akses ke klaster basis data.

Menjalankan kueri SQL

Anda dapat menjalankan pernyataan SELECT dan mengambil hasilnya dengan aplikasi Python.

Contoh berikut menjalankan kueri 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'
        }
    ]
]

Menjalankan pernyataan SQL DML

Anda dapat menjalankan pernyataan bahasa manipulasi data (DML) untuk memasukkan, memperbarui, atau menghapus data dalam basis data Anda. Anda juga dapat menggunakan parameter dalam pernyataan DML.

Contoh berikut menjalankan pernyataan penyisipan SQL dan menggunakan parameter.

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"])

Menjalankan transaksi SQL

Anda dapat memulai transaksi SQL, menjalankan satu atau beberapa pernyataan SQL, lalu menerapkan perubahan dengan aplikasi Python.

Contoh berikut menjalankan transaksi SQL yang menyisipkan baris dalam tabel.

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

Memanggil RDS Data API dari aplikasi Java

Anda dapat memanggil RDS Data API (Data API) dari aplikasi Java.

Contoh berikut menggunakan AWS SDK for Java. Lihat informasi selengkapnya di Panduan Developer AWS SDK for Java.

Dalam setiap contoh, ganti Amazon Resource Name (ARN) cluster DB dengan ARN untuk cluster Aurora DB Anda. Selain itu, ganti ARN rahasia dengan ARN rahasia di Secrets Manager yang mengizinkan akses ke klaster basis data.

Menjalankan kueri SQL

Anda dapat menjalankan pernyataan SELECT dan mengambil hasilnya dengan aplikasi Java.

Contoh berikut menjalankan kueri 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<Field> 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));
    }
  }
}

Menjalankan transaksi SQL

Anda dapat memulai transaksi SQL, menjalankan satu atau beberapa pernyataan SQL, lalu menerapkan perubahan dengan aplikasi Java.

Contoh berikut menjalankan transaksi 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);
  }
}

Menjalankan operasi SQL batch

Anda dapat menjalankan operasi penyisipan dan pembaruan massal pada array data dengan aplikasi Java. Anda dapat menjalankan pernyataan DML dengan array set parameter.

Contoh berikut menjalankan operasi penyisipan batch.

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);
  }
}

Mengontrol perilaku batas waktu API Data

Semua panggilan ke Data API sinkron. Misalkan Anda melakukan operasi API Data yang menjalankan pernyataan SQL seperti INSERT atauCREATE TABLE. Jika panggilan Data API berhasil kembali, pemrosesan SQL selesai saat panggilan kembali.

Secara default, Data API membatalkan operasi dan mengembalikan kesalahan batas waktu jika operasi tidak selesai diproses dalam waktu 45 detik. Dalam hal ini, data tidak dimasukkan, tabel tidak dibuat, dan sebagainya.

Anda dapat menggunakan Data API untuk melakukan operasi jangka panjang yang tidak dapat diselesaikan dalam waktu 45 detik. Jika Anda berharap bahwa operasi seperti operasi massal INSERT atau DDL pada tabel besar membutuhkan waktu lebih dari 45 detik, Anda dapat menentukan continueAfterTimeout parameter untuk ExecuteStatement operasi tersebut. Aplikasi Anda masih menerima kesalahan batas waktu. Namun, operasi terus berjalan dan tidak dibatalkan. Sebagai contoh, lihat Menjalankan transaksi SQL.

Jika AWS SDK untuk bahasa pemrograman Anda memiliki periode batas waktu sendiri untuk panggilan API atau koneksi soket HTTP, pastikan bahwa semua periode batas waktu tersebut lebih dari 45 detik. Bagi sebagian orang SDKs, periode batas waktu kurang dari 45 detik secara default. Sebaiknya setel periode batas waktu khusus SDK atau khusus klien menjadi setidaknya satu menit. Melakukannya menghindari kemungkinan bahwa aplikasi Anda menerima kesalahan batas waktu sementara operasi Data API masih berhasil diselesaikan. Dengan begitu, Anda dapat yakin apakah akan mencoba kembali operasi atau tidak.

Misalnya, SDK mengembalikan kesalahan batas waktu ke aplikasi Anda, tetapi operasi Data API masih selesai dalam interval batas waktu API Data. Dalam hal ini, mencoba kembali operasi mungkin menyisipkan data duplikat atau menghasilkan hasil yang salah. SDK mungkin mencoba ulang operasi secara otomatis, menyebabkan data yang salah tanpa tindakan apa pun dari aplikasi Anda.

Interval batas waktu sangat penting untuk SDK Java 2. Dalam SDK tersebut, batas waktu panggilan API dan batas waktu soket HTTP keduanya 30 detik secara default. Berikut adalah contoh pengaturan batas waktu tersebut ke nilai yang lebih tinggi:

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));
}

Berikut adalah contoh yang setara menggunakan klien data asinkron:

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));
}

Menggunakan pustaka klien Java untuk RDS Data API

Anda dapat mengunduh dan menggunakan pustaka klien Java untuk RDS Data API (Data API). Pustaka klien Java ini menyediakan cara alternatif untuk menggunakan Data API. Dengan menggunakan pustaka ini, Anda dapat memetakan kelas sisi klien Anda ke permintaan dan respons Data API. Dukungan pemetaan ini dapat memudahkan integrasi dengan beberapa jenis Java tertentu, seperti Date, Time, dan BigDecimal.

Mengunduh pustaka klien Java untuk API Data

Pustaka klien Java Data API adalah open source GitHub di lokasi berikut:

https://github.com/awslabs/rds-data-api-client-perpustakaan-java

Anda dapat membuat pustaka secara manual dari file sumber, tetapi praktik terbaiknya adalah memanfaatkan pustaka tersebut menggunakan manajemen dependensi Apache Maven. Tambahkan dependensi berikut ke file Maven POM Anda:

Untuk versi 2.x, yang kompatibel dengan AWS SDK 2.x, gunakan yang berikut ini:

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

Untuk versi 1.x, yang kompatibel dengan AWS SDK 1.x, gunakan yang berikut ini:

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

Contoh pustaka klien Java

Di bawah ini Anda dapat menemukan beberapa contoh umum penggunaan pustaka klien Java API Data. Contoh berikut mengasumsikan bahwa Anda memiliki tabel accounts dengan dua kolom: accountId dan name. Anda juga memiliki data transfer object (DTO) berikut.

public class Account {
    int accountId;
    String name;
    // getters and setters omitted
}

Pustaka klien memungkinkan Anda untuk lulus DTOs sebagai parameter input. Contoh berikut menunjukkan bagaimana pelanggan DTOs dipetakan ke set parameter masukan.

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();

Dalam beberapa kasus, bekerja dengan nilai sederhana sebagai parameter input akan terasa lebih mudah. Anda dapat melakukannya dengan sintaksis berikut.

client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
         .withParameter("accountId", 3)
         .withParameter("name", "Zhang")
         .execute();

Berikut adalah contoh lain yang bekerja dengan nilai sederhana sebagai parameter input.

client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
         .execute();
                

Pustaka klien menyediakan pemetaan otomatis DTOs saat hasil dikembalikan. Contoh berikut menunjukkan bagaimana hasilnya dipetakan ke Anda DTOs.

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);

Dalam banyak kasus, kumpulan hasil basis data hanya berisi satu nilai. Untuk menyederhanakan pengambilan hasil tersebut, pustaka klien menawarkan API berikut:

int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
          .execute()
          .singleValue(Integer.class);

Memproses hasil kueri API Data RDS dalam format JSON

Ketika Anda memanggil operasi ExecuteStatement, Anda dapat memilih untuk menampilkan hasil kueri sebagai string dalam format JSON. Dengan demikian, Anda dapat menggunakan kemampuan parsing JSON bahasa pemrograman Anda untuk menafsirkan dan memformat ulang set hasil. Dengan melakukan ini, Anda dapat membantu menghindari penulisan kode tambahan untuk mengulang set hasil dan menafsirkan setiap nilai kolom.

Untuk meminta set hasil dalam format JSON, teruskan parameter formatRecordsAs opsional dengan nilai JSON. Set hasil yang diformat JSON ditampilkan di bidang formattedRecords struktur ExecuteStatementResponse.

Tindakan BatchExecuteStatement tidak menampilkan set hasil. Dengan demikian, opsi JSON tidak berlaku untuk tindakan itu.

Untuk menyesuaikan kunci dalam struktur hash JSON, tentukan alias kolom dalam set hasil. Anda dapat melakukannya dengan menggunakan klausa AS dalam daftar kolom kueri SQL Anda.

Anda dapat menggunakan kemampuan JSON untuk membuat set hasil lebih mudah dibaca dan memetakan kontennya ke kerangka kerja khusus bahasa. Karena volume set hasil berenkode ASCII lebih besar dari representasi default, Anda dapat memilih representasi default untuk kueri yang menampilkan sejumlah besar baris atau nilai kolom besar yang menghabiskan lebih banyak memori daripada yang tersedia untuk aplikasi Anda.

Mengambil hasil kueri dalam format JSON

Untuk menerima hasil yang ditetapkan sebagai string JSON, sertakan .withFormatRecordsAs(RecordsFormatType.JSON) dalam ExecuteStatement panggilan. Nilai pengembalian kembali sebagai string JSON di bidang formattedRecords. Dalam kasus ini, columnMetadata bernilai null. Label kolom adalah kunci dari objek yang mewakili setiap baris. Nama kolom ini diulang untuk setiap baris dalam set hasil. Nilai kolom adalah string berkutip, nilai numerik, atau nilai khusus yang merepresentasikan true, false, atau null. Metadata kolom seperti batasan panjang dan tipe yang tepat untuk angka dan string tidak dipertahankan dalam respons JSON.

Jika Anda menghilangkan panggilan .withFormatRecordsAs() atau menentukan parameter NONE, set hasil ditampilkan dalam format biner menggunakan bidang Records dan columnMetadata.

Pemetaan Tipe Data

Nilai SQL dalam set hasil dipetakan ke set tipe JSON yang lebih kecil. Nilai direpresentasikan dalam JSON sebagai string, angka, dan beberapa konstanta khusus seperti true, false, dan null. Anda dapat mengonversi nilai-nilai ini menjadi berbagai variabel dalam aplikasi Anda, dengan menggunakan pengetikan kuat atau lemah yang sesuai untuk bahasa pemrograman Anda.

Pemecahan Masalah

Respons JSON dibatasi hingga 10 megabyte. Jika responsnya lebih besar dari batas ini, program Anda menerima kesalahan BadRequestException. Dalam kasus ini, Anda dapat mengatasi kesalahan menggunakan salah satu teknik berikut:

Contoh

Contoh Java berikut menunjukkan cara memanggil ExecuteStatement dengan respons sebagai string berformat JSON, lalu menafsirkan set hasil. Gantikan nilai yang sesuai untukdatabaseName,secretStoreArn, dan clusterArn parameter.

Contoh Java berikut menunjukkan kueri yang menampilkan nilai numerik desimal di set hasil. Panggilan assertThat menguji apakah bidang respons memiliki properti yang diharapkan berdasarkan aturan untuk set hasil JSON.

Contoh ini bekerja dengan skema dan data sampel berikut:

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);
}

Nilai bidang formattedRecords dari program sebelumnya adalah:

[{"a":10.0}]

Bidang Records dan ColumnMetadata dalam respons keduanya bernilai null karena adanya set hasil JSON.

Contoh Java berikut menunjukkan kueri yang menampilkan nilai numerik integer di set hasil. Contoh panggilan getFormattedRecords untuk menampilkan hanya string berformat JSON dan mengabaikan bidang respons lain yang kosong atau bernilai null. Contoh ini melakukan deserialisasi hasil ke dalam struktur yang merepresentasikan daftar catatan. Setiap catatan memiliki bidang yang namanya sesuai dengan alias kolom dari set kumpulan. Teknik ini menyederhanakan kode yang mem-parsing set hasil. Aplikasi Anda tidak harus mengulang baris dan kolom dari set hasil dan mengonversi setiap nilai ke tipe yang sesuai.

Contoh ini bekerja dengan skema dan data sampel berikut:

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<List<Record>>() {
        });
}

Nilai bidang formattedRecords dari program sebelumnya adalah:

[{"a":17}]

Untuk mengambil kolom a baris hasil 0, aplikasi akan merujuk ke recordsList.get(0).a.

Sebaliknya, contoh Java berikut menunjukkan tipe kode yang diperlukan untuk membangun struktur data yang mempertahankan set hasil ketika Anda tidak menggunakan format JSON. Dalam kasus ini, setiap baris dari set hasil berisi bidang dengan informasi tentang satu pengguna. Membangun struktur data untuk merepresentasikan set hasil membutuhkan perulangan melalui baris. Untuk setiap baris, kode mengambil nilai setiap bidang, melakukan konversi tipe yang sesuai, dan menetapkan hasilnya ke bidang yang sesuai dalam objek yang mewakili baris. Kemudian, kode menambahkan objek yang merepresentasikan setiap pengguna ke struktur data yang mewakili seluruh set hasil. Jika kueri diubah untuk menyusun ulang, menambah, atau menghapus bidang dalam set hasil, kode aplikasi juga harus diubah.

/* 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);
  } 

Nilai sampel berikut menunjukkan nilai bidang formattedRecords untuk set hasil dengan jumlah kolom, alias kolom, dan tipe data kolom yang berbeda.

Jika set hasil mencakup beberapa baris, setiap barisnya direpresentasikan sebagai objek yang merupakan elemen array. Setiap kolom dalam set hasil menjadi kunci dalam objek. Nama kolom ini diulang untuk setiap baris dalam set hasil. Oleh karena itu, untuk set hasil yang terdiri dari banyak baris dan kolom, Anda mungkin perlu menentukan alias kolom pendek agar tidak melebihi batas panjang untuk seluruh respons.

Contoh ini bekerja dengan skema dan data sampel berikut:

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"}]

Jika kolom dalam set hasil didefinisikan sebagai ekspresi, teks ekspresi menjadi kunci JSON. Oleh karena itu, praktik mudah umumnya adalah menentukan alias kolom deskriptif untuk setiap ekspresi dalam daftar pilih kueri. Misalnya, kueri berikut mencakup ekspresi seperti panggilan fungsi dan operasi aritmatika dalam daftar pilihannya.

select count(*), max(id), 4+7 from sample_names;

Ekspresi tersebut diteruskan ke set hasil JSON sebagai kunci.

[{"count(*)":5,"max(id)":4,"4+7":11}]

Menambahkan kolom AS dengan label deskriptif membuat kunci lebih sederhana untuk ditafsirkan dalam set hasil JSON.

select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;

Dengan kueri SQL yang direvisi, label kolom yang ditentukan oleh klausa AS digunakan sebagai nama kunci.

[{"rows":5,"largest_id":4,"addition_result":11}]

Nilai untuk setiap pasangan kunci-nilai dalam string JSON dapat berupa string berkutip. String dapat berisi karakter unicode. Jika string berisi urutan escape maupun karakter " atau \, karakter tersebut didahului oleh karakter escape backslash. Contoh string JSON berikut menunjukkan kemungkinan ini. Misalnya, hasil string_with_escape_sequences berisi karakter khusus backspace, newline, carriage return, tab, form feed, dan \.

[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}] 

Nilai untuk setiap pasangan kunci-nilai dalam string JSON juga dapat merepresentasikan angka. Angka tersebut dapat berupa bilangan bulat, nilai floating-point, nilai negatif, atau nilai yang direpresentasikan sebagai notasi eksponensial. Contoh string JSON berikut menunjukkan kemungkinan ini.

[{"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}] 

Nilai Boolean dan null direpresentasikan dengan kata kunci khusus tanpa kutip true, false, dan null. Contoh string JSON berikut menunjukkan kemungkinan ini.

[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}] 

Jika Anda memilih nilai tipe BLOB, hasilnya direpresentasikan dalam string JSON sebagai nilai berenkode base64. Untuk mengonversi kembali nilai ke representasi aslinya, Anda dapat menggunakan fungsi dekode yang sesuai dalam bahasa aplikasi Anda. Misalnya, Anda memanggil fungsi Base64.getDecoder().decode() di Java. Output sampel berikut menunjukkan hasil pemilihan nilai BLOB hello world dan menampilkan set hasil sebagai string JSON.

[{"blob_column":"aGVsbG8gd29ybGQ="}]

Contoh Python berikut menunjukkan cara mengakses nilai-nilai dari hasil panggilan ke fungsi execute_statement Python. Set hasil adalah nilai string di bidang response['formattedRecords']. Kode ini mengubah string JSON menjadi struktur data dengan memanggil fungsi json.loads. Kemudian, setiap baris dari set hasil adalah elemen daftar dalam struktur data, dan Anda dapat merujuk ke setiap bidang set hasil berdasarkan nama dalam setiap baris.

import json

result = json.loads(response['formattedRecords'])
print (result[0]["id"])

JavaScript Contoh berikut menunjukkan cara mengakses nilai-nilai dari hasil panggilan ke JavaScript executeStatement fungsi. Set hasil adalah nilai string di bidang response.formattedRecords. Kode ini mengubah string JSON menjadi struktur data dengan memanggil fungsi JSON.parse. Kemudian, setiap baris dari set hasil adalah elemen array dalam struktur data, dan Anda dapat merujuk ke setiap bidang set hasil berdasarkan nama dalam setiap baris.

<script>
    const result = JSON.parse(response.formattedRecords);
    document.getElementById("display").innerHTML = result[0].id;
</script> 

Memecahkan masalah RDS Data API

Gunakan bagian berikut, berjudul dengan pesan kesalahan umum, untuk membantu memecahkan masalah yang Anda miliki dengan RDS Data API (Data API).

Transaksi <transaction_ID> tidak ditemukan

Dalam kasus ini, ID transaksi yang ditentukan dalam panggilan API Data tidak ditemukan. Penyebab masalah ini ditambahkan ke pesan kesalahan, dan merupakan salah satu dari yang berikut:

Lihat informasi tentang menjalankan transaksi di Memanggil RDS Data API.

Paket untuk kueri terlalu besar

Dalam kasus ini, set hasil yang ditampilkan untuk satu baris terlalu besar. Batas ukuran API Data adalah 64 KB per baris dalam set hasil yang ditampilkan oleh basis data.

Untuk mengatasi masalah ini, pastikan setiap baris dalam set hasil berukuran 64 KB atau kurang.

Respons basis data melebihi batas ukuran

Dalam kasus ini, ukuran set hasil yang ditampilkan oleh basis data terlalu besar. Batas API Data adalah 1 MiB per baris dalam set hasil yang ditampilkan oleh basis data.

Untuk mengatasi masalah ini, pastikan panggilan ke Data API mengembalikan 1 MiB data atau kurang. Jika Anda perlu menampilkan lebih dari 1 MiB, Anda dapat menggunakan beberapa panggilan ExecuteStatement dengan klausa LIMIT di kueri Anda.

Lihat informasi selengkapnya tentang klausa LIMIT di SELECT syntax dalam dokumentasi MySQL.

HttpEndpoint tidak diaktifkan untuk klaster <cluster_ID>

Periksa penyebab potensial berikut untuk masalah ini:

DatabaseErrorException: Transaksi masih menjalankan kueri

Jika aplikasi Anda mengirimkan permintaan dengan ID transaksi dan transaksi tersebut saat ini sedang memproses permintaan lain, Data API mengembalikan kesalahan ini ke aplikasi Anda segera. Kondisi ini mungkin muncul jika aplikasi Anda membuat permintaan asinkron, menggunakan mekanisme seperti “janji” di Javascript.

Untuk mengatasi masalah ini, tunggu hingga permintaan sebelumnya selesai dan kemudian coba lagi permintaan tersebut. Anda dapat terus mencoba lagi sampai kesalahan tidak lagi terjadi, atau aplikasi menerima beberapa jenis kesalahan yang berbeda.

Kondisi ini dapat terjadi dengan Data API untuk Aurora Serverless v2 dan contoh yang disediakan. Dalam API Data untuk Aurora Serverless v1, permintaan selanjutnya untuk ID transaksi yang sama secara otomatis menunggu permintaan sebelumnya selesai. Namun, perilaku lama itu berpotensi mengalami batas waktu karena permintaan sebelumnya terlalu lama. Jika Anda mem-porting aplikasi Data API lama yang membuat permintaan bersamaan, ubah logika penanganan pengecualian Anda untuk memperhitungkan jenis kesalahan baru ini.