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
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.
Topik
Wilayah dan ketersediaan versi
Untuk informasi tentang Wilayah dan versi engine yang tersedia untuk Data API, lihat bagian berikut.
Jenis cluster | Wilayah dan ketersediaan versi |
---|---|
Aurora PostgreSQL disediakan dan Serverless v2 |
Data API dengan Aurora PostgreSQL Serverless v2 dan disediakan |
Aurora MySQL disediakan dan Serverless v2 |
|
Aurora PostgreSQL Tanpa Server v1 |
|
Aurora MySQL Tanpa Server v1 |
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:
Anda hanya dapat menjalankan kueri Data API pada instance penulis di cluster DB. Namun, instance penulis dapat menerima kueri tulis dan baca.
-
Dengan database global Aurora, Anda dapat mengaktifkan Data API pada cluster DB primer dan sekunder. Namun, cluster sekunder tidak memiliki instance penulis sampai dipromosikan menjadi yang utama. Data API memerlukan akses ke instance penulis untuk pemrosesan kueri, bahkan untuk kueri baca. Akibatnya, kueri baca dan tulis yang dikirim ke cluster sekunder gagal sementara tidak memiliki instance penulis. Setelah cluster sekunder dipromosikan dan memiliki instance penulis yang tersedia, kueri Data API pada instans DB tersebut berhasil.
Data API tidak didukung pada kelas instans T DB.
Untuk Aurora Serverless v2 dan kluster DB yang disediakan, RDS Data API tidak mendukung beberapa tipe data. Untuk daftar tipe yang didukung, lihatPerbandingan RDS Data API dengan Serverless v2 dan provisioned, dan Aurora Serverless v1.
Untuk Aurora PostgreSQL versi 14 dan database yang lebih tinggi, Data API hanya mendukung enkripsi kata sandi.
scram-sha-256
-
Batas ukuran respons adalah 1 MiB. Jika panggilan menghasilkan data respons dengan ukuran lebih dari 1 MiB, panggilan tersebut akan diakhiri.
-
Untuk Aurora Serverless v1, jumlah maksimum permintaan per detik adalah 1.000. Untuk semua database lain yang didukung, tidak ada batasan.
-
Batas ukuran API Data adalah 64 KB per baris dalam set hasil yang ditampilkan oleh basis data. Pastikan bahwa setiap baris dalam set hasil adalah 64 KB atau kurang.
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.
Perbedaan | Aurora Tanpa Server v2 dan disediakan | Aurora Serverless v1 |
---|---|---|
Jumlah maksimum permintaan per detik | Tidak terbatas. | 1.000 |
Mengaktifkan atau menonaktifkan Data API pada database yang ada dengan menggunakan RDS API atau AWS CLI |
|
|
CloudTrail acara | Peristiwa dari panggilan API Data adalah peristiwa data. Peristiwa ini secara otomatis dikecualikan dalam jejak secara default. Untuk informasi selengkapnya, lihat Termasuk API peristiwa Data dalam AWS CloudTrail jejak. | Peristiwa dari panggilan API Data adalah peristiwa manajemen. Peristiwa ini secara otomatis disertakan dalam jejak secara default. Untuk informasi selengkapnya, lihat Mengecualikan API peristiwa Data dari AWS CloudTrail jejak (Aurora Serverless v1 hanya). |
Dukungan multistatement | Multistatement tidak didukung. Dalam hal ini, Data API melemparValidationException: Multistatements aren't
supported . |
Untuk Aurora PostgreSQL, multistatement hanya mengembalikan respons kueri pertama. Untuk Aurora MySQL, multistatement tidak didukung. |
Permintaan bersamaan untuk ID transaksi yang sama | Data API melempar kesalahanDatabaseErrorException: Transaction is still running a query . Tunggu dan coba lagi permintaannya. |
Permintaan selanjutnya menunggu hingga permintaan saat ini selesai. Aplikasi Anda perlu menangani kesalahan batas waktu jika masa tunggu terlalu lama. |
BatchExecuteStatement | Di Aurora MySQL, objek bidang yang dihasilkan dalam hasil pembaruan mencakup nilai yang disisipkan. Di Aurora PostgreSQL, objek bidang yang dihasilkan kosong. | Objek bidang yang dihasilkan dalam hasil pembaruan mencakup nilai yang disisipkan. |
EksekusiQL | Tidak didukung | Dihentikan |
ExecuteStatement |
Data API tidak mendukung beberapa tipe data, seperti tipe geometris dan moneter. Dalam hal ini, Data API melempar Untuk daftar tipe data yang didukung RDS Data API dari setiap mesin database Aurora, lihat. Referensi operasi API data |
ExecuteStatement mendukung pengambilan kolom array multidimensi dan semua tipe data lanjutan. |
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.
AmazonRDSDataFullAccess
Kebijakan 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.
AmazonRDSDataFullAccess
Kebijakan 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:
environment:production
environment:development
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:
aws:TagKeys
aws:ResourceTag/${TagKey}
Untuk mempelajari lebih lanjut tentang tag sumber daya dan cara menggunakannyaaws:TagKeys
, lihat Mengontrol akses ke AWS sumber daya menggunakan tag sumber daya.
catatan
Baik Data API dan AWS Secrets Manager otorisasi pengguna. Jika Anda tidak memiliki izin untuk semua tindakan yang ditentukan dalam kebijakan, Anda akan mendapatkan kesalahan AccessDeniedException
.
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.
Menyimpan kredensial klaster basis data dalam rahasia
-
Gunakan Secrets Manager untuk membuat rahasia yang berisi kredensial untuk klaster basis data Aurora.
Lihat petunjuknya di Membuat rahasia basis data dalam Panduan Pengguna AWS Secrets Manager .
-
Gunakan konsol Secrets Manager untuk melihat detail rahasia yang Anda buat, atau jalankan
aws secretsmanager describe-secret
AWS CLI perintah.Catat nama dan ARN rahasia. Anda dapat menggunakannya dalam panggilan ke Data API.
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.
catatan
Apakah Data API tersedia untuk klaster Anda tergantung pada versi Aurora, mesin database, dan AWS Wilayah Anda. Untuk versi Aurora yang lebih lama, Data API hanya berfungsi dengan Aurora Serverless v1 klaster. Untuk versi Aurora yang lebih baru, Data API bekerja dengan cluster yang menggunakan provisioned dan Aurora Serverless v2 contoh. Untuk memeriksa apakah klaster Anda dapat menggunakan Data API, lihatDaerah yang Didukung dan engine Aurora DB untuk RDS Data API.
Topik
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.
Untuk mengaktifkan Data API saat Anda membuat cluster DB, pilih kotak centang Aktifkan API Data RDS di bagian Konektivitas pada halaman Buat database, seperti pada tangkapan layar berikut.

Untuk petunjuk tentang cara membuat klaster Aurora DB yang dapat menggunakan API Data RDS, lihat berikut ini:
Untuk Aurora Serverless v2 dan kluster yang disediakan - Membuat klaster DB Amazon Aurora
Untuk Aurora Serverless v1 – Membuat Aurora Serverless v1 klaster DB.
Untuk mengaktifkan Data API saat Anda membuat cluster Aurora DB, jalankan create-db-cluster AWS CLI perintah dengan opsi. --enable-http-endpoint
Contoh berikut membuat cluster Aurora PostgreSQL DB dengan Data API diaktifkan.
Untuk Linux, macOS, atau Unix:
aws rds create-db-cluster \ --db-cluster-identifier
my_pg_cluster
\ --engine aurora-postgresql \ --enable-http-endpoint
Untuk Windows:
aws rds create-db-cluster ^ --db-cluster-identifier
my_pg_cluster
^ --engine aurora-postgresql ^ --enable-http-endpoint
Untuk mengaktifkan Data API saat Anda membuat cluster Aurora DB, gunakan DBCluster operasi Create dengan nilai EnableHttpEndpoint
parameter yang disetel ke. true
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.
Topik
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).
Anda dapat mengaktifkan atau menonaktifkan Data API dengan menggunakan konsol RDS untuk cluster DB yang mendukung fitur ini. Untuk melakukannya, buka halaman detail cluster dari database tempat Anda ingin mengaktifkan atau menonaktifkan Data API, dan pada tab Konektivitas & keamanan, buka bagian API Data RDS. Bagian ini menampilkan status Data API, dan memungkinkan Anda untuk mengaktifkan atau menonaktifkannya.
Screenshot berikut menunjukkan bahwa RDS Data API tidak diaktifkan.

Untuk mengaktifkan atau menonaktifkan Data API pada database yang ada, jalankan disable-http-endpoint AWS CLI perintah enable-http-endpointor, dan tentukan ARN cluster DB Anda.
Contoh berikut memungkinkan Data API.
Untuk Linux, macOS, atau Unix:
aws rds enable-http-endpoint \ --resource-arn
cluster_arn
Untuk Windows:
aws rds enable-http-endpoint ^ --resource-arn
cluster_arn
Untuk mengaktifkan atau menonaktifkan Data API pada database yang ada, gunakan EnableHttpEndpointdan DisableHttpEndpointoperasi.
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)
Saat Anda memodifikasi Aurora Serverless v1 Cluster DB, Anda mengaktifkan Data API di bagian Konektivitas konsol RDS.
Tangkapan layar berikut menunjukkan API Data yang diaktifkan saat memodifikasi cluster Aurora DB.

Untuk petunjuk tentang cara memodifikasi Aurora Serverless v1 Cluster DB, lihatMemodifikasi Aurora Serverless v1 Klaster DB.
Untuk mengaktifkan atau menonaktifkan Data API, jalankan modify-db-cluster AWS CLI perintah, dengan --enable-http-endpoint
atau--no-enable-http-endpoint
, sebagaimana berlaku.
Contoh berikut memungkinkan Data API aktifsample-cluster
.
Untuk Linux, macOS, atau Unix:
aws rds modify-db-cluster \ --db-cluster-identifier sample-cluster \ --enable-http-endpoint
Untuk Windows:
aws rds modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --enable-http-endpoint
Untuk mengaktifkan Data API, gunakan DBCluster operasi Modify, dan tetapkan nilai EnableHttpEndpoint
ke true
ataufalse
, sebagaimana berlaku.
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.
Untuk membuat titik akhir VPC Amazon untuk Data API
Masuk ke AWS Management Console dan buka konsol VPC Amazon di. https://console.aws.amazon.com/vpc/
-
Pilih Titik Akhir, lalu pilih Buat Titik Akhir.
-
Di halaman Buat Titik Akhir, untuk Kategori layanan, pilih Layanan AWS . Untuk Nama Layanan, pilih rds-data.
-
Untuk VPC, pilih VPC tempat membuat titik akhir.
Pilih VPC yang berisi aplikasi yang membuat panggilan API Data.
-
Untuk Subnet, pilih subnet untuk setiap Availability Zone (AZ) yang digunakan oleh AWS layanan yang menjalankan aplikasi Anda.
Untuk membuat titik akhir Amazon VPC, tentukan rentang alamat IP pribadi yang dapat mengakses titik akhir. Untuk melakukannya, pilih subnet untuk setiap Zona Ketersediaan. Hal tersebut membatasi titik akhir VPC ke rentang alamat IP pribadi khusus untuk setiap Zona Ketersediaan dan membuat titik akhir Amazon VPC di setiap Zona Ketersediaan.
-
Untuk Aktifkan nama DNS, pilih Aktifkan untuk titik akhir ini.
DNS Pribadi menyelesaikan nama host DNS API Data standar (
https://rds-data.
) ke alamat IP pribadi yang dikaitkan dengan nama host DNS khusus untuk titik akhir Amazon VPC Anda. Akibatnya, Anda dapat mengakses titik akhir VPC API Data menggunakan AWS CLI atau AWS SDKs tanpa membuat perubahan kode atau konfigurasi apa pun untuk memperbarui URL titik akhir Data API.region
.amazonaws.com -
Untuk Grup keamanan, pilih satu grup keamanan untuk dikaitkan dengan titik akhir Amazon VPC.
Pilih grup keamanan yang memungkinkan akses ke AWS layanan yang menjalankan aplikasi Anda. Misalnya, jika EC2 instans Amazon menjalankan aplikasi Anda, pilih grup keamanan yang memungkinkan akses ke EC2 instans Amazon. Grup keamanan memungkinkan Anda mengontrol lalu lintas ke titik akhir Amazon VPC dari sumber daya di VPC Anda.
-
Untuk Kebijakan, pilih Akses Penuh untuk mengizinkan siapa pun di dalam Amazon VPC mengakses API Data melalui titik akhir ini. Atau, pilih Kustom untuk menentukan kebijakan yang membatasi akses.
Jika Anda memilih Kustom, masukkan kebijakan di alat pembuatan kebijakan.
-
Pilih Create endpoint.
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.
) 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.region
.amazonaws.com
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
Topik
Referensi operasi API data
Data API menyediakan operasi berikut untuk melakukan pernyataan SQL.
Operasi API Data |
AWS CLI perintah |
Deskripsi |
---|---|---|
Menjalankan pernyataan SQL pada basis data. |
||
Menjalankan pernyataan SQL batch pada array data untuk pembaruan massal dan operasi penyisipan. Anda dapat menjalankan pernyataan bahasa manipulasi data (DML) dengan array set parameter. Pernyataan SQL batch dapat memberikan peningkatan performa yang signifikan atas pernyataan penyisipan dan pembaruan individu. |
Anda dapat menggunakan operasi mana pun untuk menjalankan pernyataan SQL individual atau untuk menjalankan transaksi. Untuk transaksi, Data API menyediakan operasi berikut.
Operasi API Data |
AWS CLI perintah |
Deskripsi |
---|---|---|
Memulai transaksi SQL. |
||
Mengakhiri transaksi SQL dan menerapkan perubahan. |
||
Melakukan pembatalan transaksi. |
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.
Parameter operasi API Data |
AWS CLI opsi perintah |
Wajib |
Deskripsi |
---|---|---|---|
|
|
Ya |
Nama Sumber Daya Amazon (ARN) dari cluster Aurora DB. |
|
|
Ya |
Nama atau ARN rahasia yang memungkinkan akses ke klaster basis data. |
RDS Data API mendukung tipe data berikut untuk Aurora MySQL:
TINYINT(1)
,BOOLEAN
,BOOL
TINYINT
SMALLINT
[SIGNED
|UNSIGNED
]MEDIUMINT
[SIGNED
|UNSIGNED
]INT
[SIGNED
|UNSIGNED
]BIGINT
[SIGNED
|UNSIGNED
]FLOAT
DOUBLE
VARCHAR
,CHAR
,TEXT
,ENUM
VARBINARY
,BINARY
,BLOB
DATE
,TIME
,DATETIME
,TIMESTAMP
DECIMAL
JSON
BIT
,BIT(N)
RDS Data API mendukung jenis skalar Aurora PostgreSQL berikut:
BOOL
BYTEA
DATE
CIDR
DECIMAL
,NUMERIC
ENUM
FLOAT8
,DOUBLE PRECISION
INET
INT
,INT4
,SERIAL
INT2
,SMALLINT
,SMALLSERIAL
INT8
,BIGINT
,BIGSERIAL
JSONB
,JSON
REAL
,FLOAT
TEXT
,CHAR(N)
,VARCHAR
,NAME
TIME
TIMESTAMP
UUID
VECTOR
RDS Data API mendukung tipe array Aurora PostgreSQL berikut:
BOOL[]
,BIT[]
DATE[]
DECIMAL[]
,NUMERIC[]
FLOAT8[]
,DOUBLE PRECISION[]
INT[]
,INT4[]
INT2[]
INT8[]
,BIGINT[]
JSON[]
REAL[]
,FLOAT[]
TEXT[]
,CHAR(N)[]
,VARCHAR[]
,NAME[]
TIME[]
TIMESTAMP[]
UUID[]
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 data JDBC |
Tipe data API Data |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Tipe lainnya (termasuk tipe terkait tanggal dan waktu) |
|
catatan
Anda dapat menentukan tipe data LONG
atau STRING
dalam panggilan API Data Anda untuk nilai LONG
yang dihasilkan oleh basis data. Kami menyarankan Anda melakukannya untuk menghindari kehilangan presisi untuk jumlah yang sangat besar, yang dapat terjadi ketika Anda bekerja dengan JavaScript.
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
:
-
DATE
– Nilai parameterString
yang sesuai dikirim sebagai objek tipeDATE
ke basis data. Format yang diterima adalahYYYY-MM-DD
. -
DECIMAL
– Nilai parameterString
yang sesuai dikirim sebagai objek tipeDECIMAL
ke basis data. -
JSON
– Nilai parameterString
yang sesuai dikirim sebagai objek tipeJSON
ke basis data. -
TIME
– Nilai parameterString
yang sesuai dikirim sebagai objek tipeTIME
ke basis data. Format yang diterima adalahHH:MM:SS[.FFF]
. -
TIMESTAMP
– Nilai parameterString
yang sesuai dikirim sebagai objek tipeTIMESTAMP
ke basis data. Format yang diterima adalahYYYY-MM-DD HH:MM:SS[.FFF]
. -
UUID
– Nilai parameterString
yang sesuai dikirim sebagai objek tipeUUID
ke basis data.catatan
Saat ini, Data API tidak mendukung array Universal Unique Identifiers ()UUIDs.
catatan
Untuk Amazon Aurora PostgreSQL, Data API selalu menampilkan tipe data Aurora PostgreSQL di zona waktu UTC. TIMESTAMPTZ
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.
catatan
Kaleng AWS CLI memformat tanggapan di JSON.
Topik
Memulai transaksi SQL
Anda dapat memulai transaksi SQL menggunakan perintah CLI aws rds-data
begin-transaction
. Panggilan ini menghasilkan pengidentifikasi transaksi.
penting
Dalam Data API, transaksi akan habis jika tidak ada panggilan yang menggunakan ID transaksinya dalam tiga menit. Jika waktu transaksi habis sebelum dilakukan, Data API akan mengembalikannya secara otomatis.
Pernyataan bahasa definisi data MySQL (DDL) di dalam transaksi menyebabkan komit implisit. Kami menyarankan Anda menjalankan setiap pernyataan MySQL DDL dalam perintah execute-statement
terpisah dengan opsi. --continue-after-timeout
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
.
penting
Jika Anda tidak menentukan opsi --transaction-id
, perubahan yang dihasilkan dari panggilan akan diterapkan secara otomatis.
Selain opsi umum, tentukan opsi-opsi berikut:
-
--sql
(wajib) – Pernyataan SQL untuk dijalankan pada klaster basis data. -
--transaction-id
(opsional) – Pengidentifikasi transaksi yang dimulai menggunakan perintah CLIbegin-transaction
. Tentukan ID transaksi yang ingin Anda sertakan pernyataan SQL-nya. -
--parameters
(opsional) – Parameter untuk pernyataan SQL. -
--include-result-metadata | --no-include-result-metadata
(opsional) – Nilai yang menunjukkan apakah metadata disertakan dalam hasil. Default-nya adalah--no-include-result-metadata
. -
--database
(opsional) – Nama basis data.Opsi
--database
mungkin tidak berfungsi ketika Anda menjalankan pernyataan SQL setelah menjalankan--sql "use
di permintaan sebelumnya. Kami merekomendasikan agar Anda menggunakandatabase_name
;"--database
opsi, bukan menjalankan pernyataan--sql "use
.database_name
;" -
--continue-after-timeout | --no-continue-after-timeout
(opsional) — Nilai yang menunjukkan apakah akan terus menjalankan pernyataan setelah panggilan melebihi interval batas waktu API Data 45 detik. Default-nya adalah--no-continue-after-timeout
.Untuk pernyataan bahasa definisi data (DDL), kami merekomendasikan agar Anda terus menjalankan pernyataan setelah waktu panggilan habis untuk menghindari kesalahan dan kemungkinan struktur data rusak.
-
--format-records-as "JSON"|"NONE"
– Nilai opsional yang menentukan apakah hasil yang ditetapkan akan diformat sebagai string JSON. Default-nya adalah"NONE"
. Lihat informasi penggunaan tentang pemrosesan set hasil JSON di Memproses hasil kueri API Data RDS dalam format JSON.
Klaster basis data menghasilkan respons untuk panggilan.
catatan
Batas ukuran respons adalah 1 MiB. Jika panggilan menghasilkan data respons dengan ukuran lebih dari 1 MiB, panggilan tersebut akan diakhiri.
Untuk Aurora Serverless v1, jumlah maksimum permintaan per detik adalah 1.000. Untuk semua database lain yang didukung, tidak ada batasan.
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 intomytable
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 intomytable
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
.
penting
Untuk pernyataan DDL, kami merekomendasikan agar Anda terus menjalankan pernyataan tersebut setelah waktu panggilan habis. Ketika pernyataan DDL dihentikan sebelum selesai dijalankan, hal ini dapat mengakibatkan kesalahan dan kemungkinan struktur data rusak. Untuk terus menjalankan pernyataan setelah panggilan melebihi interval batas waktu API Data RDS 45 detik, tentukan opsi. --continue-after-timeout
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
}
catatan
Data generatedFields
tidak didukung oleh Aurora PostgreSQL. Untuk mendapatkan nilai-nilai bidang yang dihasilkan, gunakan klausa RETURNING
. Lihat informasi selengkapnya di Returning data from modified rows
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
.
penting
Jika Anda tidak menentukan opsi --transaction-id
, perubahan yang dihasilkan dari panggilan akan diterapkan secara otomatis.
Selain opsi umum, tentukan opsi-opsi berikut:
-
--sql
(wajib) – Pernyataan SQL untuk dijalankan pada klaster basis data.Tip
Untuk pernyataan yang kompatibel dengan MySQL, jangan sertakan titik koma di akhir parameter
--sql
. Titik koma di belakang dapat menyebabkan kesalahan sintaksis. -
--transaction-id
(opsional) – Pengidentifikasi transaksi yang dimulai menggunakan perintah CLIbegin-transaction
. Tentukan ID transaksi yang ingin Anda sertakan pernyataan SQL-nya. -
--parameter-set
(opsional) – Set parameter untuk operasi batch. -
--database
(opsional) – Nama basis data.
Klaster basis data menghasilkan respons untuk panggilan.
catatan
Tidak ada batas atas tetap pada jumlah set parameter. Namun, ukuran maksimum permintaan HTTP yang dikirimkan melalui Data API adalah 4 MiB. Jika permintaan melebihi batas ini, Data API mengembalikan kesalahan dan tidak memproses permintaan. Batas 4 MiB ini mencakup ukuran header HTTP dan notasi JSON dalam permintaan. Dengan demikian, jumlah set parameter yang dapat Anda sertakan tergantung pada kombinasi faktor, seperti ukuran pernyataan SQL dan ukuran setiap set parameter.
Batas ukuran respons adalah 1 MiB. Jika panggilan menghasilkan data respons dengan ukuran lebih dari 1 MiB, panggilan tersebut akan diakhiri.
Untuk Aurora Serverless v1, jumlah maksimum permintaan per detik adalah 1.000. Untuk semua database lain yang didukung, tidak ada batasan.
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 intomytable
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 intomytable
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
\"}}]]"
catatan
Jangan sertakan jeda baris di opsi --parameter-sets
.
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:
-
--transaction-id
(wajib) – Pengidentifikasi transaksi yang dimulai menggunakan perintah CLIbegin-transaction
. Tentukan ID transaksi yang ingin Anda akhiri dan terapkan.
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.
penting
Jika ID transaksi telah kedaluwarsa, transaksi dibatalkan secara otomatis. Dalam kasus ini, perintah aws rds-data rollback-transaction
yang menentukan ID transaksi yang kedaluwarsa akan menghasilkan kesalahan.
Selain opsi umum, tentukan opsi-opsi berikut:
-
--transaction-id
(wajib) – Pengidentifikasi transaksi yang dimulai menggunakan perintah CLIbegin-transaction
. Tentukan ID transaksi yang ingin Anda batalkan.
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.
penting
Jika panggilan bukan bagian dari transaksi karena tidak menyertakan parameter transactionID
, perubahan yang dihasilkan dari panggilan tersebut diterapkan secara otomatis.
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.
penting
Waktu transaksi habis jika tidak ada panggilan yang menggunakan ID transaksinya dalam tiga menit. Jika waktu transaksi habis sebelum diterapkan, transaksi akan dibatalkan secara otomatis.
Jika Anda tidak menentukan ID transaksi, perubahan yang dihasilkan dari panggilan akan diterapkan secara otomatis.
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
catatan
Jika Anda menjalankan pernyataan bahasa definisi data (DDL), kami merekomendasikan agar Anda terus menjalankan pernyataan setelah waktu panggilan habis. Ketika pernyataan DDL dihentikan sebelum selesai dijalankan, hal ini dapat mengakibatkan kesalahan dan kemungkinan struktur data rusak. Untuk terus menjalankan pernyataan setelah panggilan melebihi interval batas waktu API Data RDS 45 detik, setel continueAfterTimeout
parameter ke. true
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.
penting
Waktu transaksi habis jika tidak ada panggilan yang menggunakan ID transaksinya dalam tiga menit. Jika waktu transaksi habis sebelum diterapkan, transaksi akan dibatalkan secara otomatis.
Jika Anda tidak menentukan ID transaksi, perubahan yang dihasilkan dari panggilan akan diterapkan secara otomatis.
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);
}
}
catatan
Jika Anda menjalankan pernyataan bahasa definisi data (DDL), kami merekomendasikan agar Anda terus menjalankan pernyataan setelah waktu panggilan habis. Ketika pernyataan DDL dihentikan sebelum selesai dijalankan, hal ini dapat mengakibatkan kesalahan dan kemungkinan struktur data rusak. Untuk terus menjalankan pernyataan setelah panggilan melebihi interval batas waktu API Data RDS 45 detik, setel continueAfterTimeout
parameter ke. true
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.
penting
Jika Anda tidak menentukan ID transaksi, perubahan yang dihasilkan dari panggilan akan diterapkan secara otomatis.
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);
catatan
Fungsi mapToList
mengonversi set hasil SQL ke dalam daftar objek yang ditentukan pengguna. Kami tidak mendukung penggunaan pernyataan .withFormatRecordsAs(RecordsFormatType.JSON)
dalam panggilan ExecuteStatement
untuk pustaka klien Java karena fungsinya sama. Untuk informasi selengkapnya, lihat Memproses hasil kueri API Data RDS dalam format JSON.
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.
Tipe data JDBC |
Tipe data JSON |
---|---|
|
Angka secara default. String jika opsi |
|
Angka |
|
String secara default. Angka jika opsi |
|
String |
|
Boolean |
|
String dalam enkode base64. |
|
String |
|
Array |
|
|
Tipe lainnya (termasuk tipe terkait tanggal dan waktu) |
String |
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:
-
Kurangi jumlah baris di set hasil. Untuk melakukannya, tambahkan klausa
LIMIT
. Anda dapat membagi set hasil besar menjadi beberapa set yang lebih kecil dengan mengirimkan beberapa kueri dengan klausaLIMIT
danOFFSET
.Jika set hasil menyertakan baris yang difilter oleh logika aplikasi, Anda dapat menghapus baris tersebut dari set hasil dengan menambahkan kondisi lainnya dalam klausa
WHERE
. -
Kurangi jumlah kolom di set hasil. Untuk melakukannya, hapus item dari daftar pilih kueri.
-
Persingkat label kolom dengan menggunakan alias kolom dalam kueri. Setiap nama kolom diulang dalam string JSON untuk setiap baris dalam set hasil. Oleh karena itu, hasil kueri dengan nama kolom panjang dan banyak baris dapat melebihi batas ukuran. Khususnya, gunakan alias kolom untuk ekspresi rumit agar seluruh ekspresi tidak diulang dalam string JSON.
-
Meskipun Anda dapat menggunakan alias kolom dengan SQL untuk menghasilkan set hasil yang memiliki beberapa kolom dengan nama yang sama, nama kunci duplikat tidak diperbolehkan di JSON. RDS API Data menampilkan kesalahan jika Anda meminta set hasil dalam format JSON dan beberapa kolom memiliki nama yang sama. Jadi, pastikan semua label kolom memiliki nama yang unik.
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).
Topik
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:
-
Transaksi mungkin kedaluwarsa.
Pastikan setiap panggilan transaksional berjalan dalam tiga menit sejak panggilan sebelumnya berjalan.
Mungkin juga ID transaksi yang ditentukan tidak dibuat oleh BeginTransactionpanggilan. Pastikan panggilan Anda memiliki ID transaksi yang valid.
-
Satu panggilan sebelumnya mengakibatkan penghentian transaksi Anda.
Transaksi telah diakhiri oleh panggilan
CommitTransaction
atauRollbackTransaction
Anda. -
Transaksi telah dibatalkan karena kesalahan dari panggilan sebelumnya.
Periksa apakah panggilan Anda sebelumnya telah memberikan pengecualian apa pun.
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
HttpEndpoint tidak diaktifkan untuk klaster <cluster_ID>
Periksa penyebab potensial berikut untuk masalah ini:
-
Cluster Aurora DB tidak mendukung Data API. Untuk informasi tentang jenis cluster DB yang didukung RDS Data API, lihat. Wilayah dan ketersediaan versi
-
Data API tidak diaktifkan untuk cluster Aurora DB. Untuk menggunakan Data API dengan cluster Aurora DB, Data API harus diaktifkan untuk cluster DB. Untuk informasi tentang mengaktifkan Data API, lihatMengaktifkan API Data RDS.
-
Cluster DB diganti namanya setelah Data API diaktifkan untuknya. Dalam hal ini, matikan Data API untuk cluster itu dan kemudian aktifkan lagi.
-
ARN yang Anda tentukan tidak sama persis dengan ARN klaster. Periksa apakah ARN yang ditampilkan dari sumber lain atau dibangun oleh logika program cocok dengan ARN klaster secara tepat. Misalnya, pastikan ARN yang Anda gunakan memiliki kapitalisasi huruf yang benar untuk semua karakter alfabet.
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.