Bekerja dengan Data API Pertimbangan saat memanggil Data API Menjalankan SQL pernyataan dengan token idempotensi Menjalankan SQL pernyataan dengan penggunaan kembali sesi

Menggunakan Data Amazon Redshift API

Amazon Redshift Data API menyederhanakan akses ke gudang data Amazon Redshift Anda dengan menghapus kebutuhan untuk mengelola driver database, koneksi, konfigurasi jaringan, buffering data, kredensyal, dan banyak lagi. Anda dapat menjalankan SQL pernyataan menggunakan API operasi Data dengan AWS SDK. Untuk informasi selengkapnya tentang API operasi Data, lihat Referensi Data API Amazon Redshift.

Data API tidak memerlukan koneksi persisten ke database Anda. Sebaliknya, ini menyediakan HTTP titik akhir yang aman dan integrasi dengan AWS SDKs. Anda dapat menggunakan endpoint untuk menjalankan SQL pernyataan tanpa mengelola koneksi. Panggilan ke Data API bersifat asinkron. Data API menggunakan kredensil yang disimpan dalam AWS Secrets Manager atau kredensil basis data sementara. Anda tidak perlu meneruskan kata sandi dalam API panggilan dengan salah satu metode otorisasi. Untuk informasi lebih lanjut tentang AWS Secrets Manager, lihat Apa itu AWS Secrets Manager? dalam AWS Secrets Manager User Guide.

Dengan DataAPI, Anda dapat mengakses data Amazon Redshift secara terprogram dengan aplikasi berbasis layanan web, AWS Lambda termasuk notebook Amazon, dan. SageMaker AWS Cloud9 Untuk informasi lebih lanjut tentang aplikasi ini, lihat AWS Lambda, Amazon SageMaker, dan AWS Cloud9.

Untuk mempelajari lebih lanjut tentang DataAPI, lihat Memulai Data Amazon Redshift API di Blog AWS Big Data.

Bekerja dengan Data Amazon Redshift API

Sebelum Anda menggunakan Data Amazon RedshiftAPI, tinjau langkah-langkah berikut:

Tentukan apakah Anda, sebagai penelepon DataAPI, berwenang. Untuk informasi selengkapnya tentang otorisasi, lihatMengotorisasi akses ke Data Amazon Redshift API.
Tentukan apakah Anda berencana untuk memanggil Data API dengan kredensyal otentikasi dari Secrets Manager atau kredensyal sementara. Untuk informasi selengkapnya, lihat Memilih kredensi otentikasi database saat memanggil Amazon Redshift Data API.
Siapkan rahasia jika Anda menggunakan Secrets Manager untuk kredensi otentikasi. Untuk informasi selengkapnya, lihat Menyimpan kredensi database di AWS Secrets Manager.
Tinjau pertimbangan dan batasan saat memanggil DataAPI. Untuk informasi selengkapnya, lihat Pertimbangan saat memanggil Data Amazon Redshift API.
Panggil Data API dari AWS Command Line Interface (AWS CLI), dari kode Anda sendiri, atau menggunakan editor kueri di konsol Amazon Redshift. Untuk contoh panggilan dari AWS CLI, lihatMemanggil Data API.

Pertimbangan saat memanggil Data Amazon Redshift API

Pertimbangkan hal berikut saat memanggil DataAPI:

Amazon Redshift Data API dapat mengakses database di klaster yang disediakan Amazon Redshift dan grup kerja Redshift Serverless. Untuk daftar Wilayah AWS tempat Data Pergeseran Merah API tersedia, lihat titik akhir yang terdaftar untuk Data Pergeseran Merah di. API Referensi Umum Amazon Web Services
Durasi maksimum kueri adalah 24 jam.
Jumlah maksimum kueri aktif (STARTEDdan SUBMITTED kueri) per cluster Amazon Redshift adalah 500.
Ukuran hasil kueri maksimum adalah 100 MB (setelah kompresi gzip). Jika panggilan mengembalikan lebih dari 100 MB data respons, panggilan akan berakhir.
Waktu retensi maksimum untuk hasil kueri adalah 24 jam.
Ukuran pernyataan kueri maksimum adalah 100 KB.
Data API tersedia untuk kueri cluster single-node dan multiple-node dari jenis node berikut:
- dc2.large
- dc2.8xlarge
- ra3. besar
- ra3.xlplus
- ra3.4xlarge
- ra3.16xlarge
Cluster harus berada di cloud pribadi virtual (VPC) berdasarkan VPC layanan Amazon.
Secara default, pengguna dengan IAM peran atau IAM izin yang sama dengan pelari BatchExecuteStatement API operasi ExecuteStatement atau dapat bertindak berdasarkan pernyataan yang sama denganCancelStatement,, DescribeStatementGetStatementResult, dan ListStatements API operasi. Untuk bertindak berdasarkan SQL pernyataan yang sama dari pengguna lain, pengguna harus dapat mengambil IAM peran pengguna yang menjalankan SQL pernyataan tersebut. Untuk informasi selengkapnya tentang cara mengambil peran, lihatMengotorisasi akses ke Data Amazon Redshift API.
SQLPernyataan dalam Sqls parameter BatchExecuteStatement API operasi dijalankan sebagai transaksi tunggal. Mereka berjalan secara serial dalam urutan array. SQLPernyataan selanjutnya tidak dimulai sampai pernyataan sebelumnya dalam array selesai. Jika ada SQL pernyataan yang gagal, maka karena mereka dijalankan sebagai satu transaksi, semua pekerjaan dibatalkan.
Waktu retensi maksimum untuk token klien yang digunakan dalam ExecuteStatement atau BatchExecuteStatement API operasi adalah 8 jam.
Masing-masing API dalam Redshift Data API memiliki kuota transaksi per detik sebelum membatasi permintaan. Untuk kuota, lihatKuota untuk Data Pergeseran Merah Amazon API. Jika tingkat permintaan melebihi kuota, a ThrottlingException dengan Kode HTTP Status: 400 dikembalikan. Untuk merespons pelambatan, gunakan strategi coba lagi seperti yang dijelaskan dalam Perilaku Coba lagi di Panduan Referensi Alat AWS SDKsdan Alat. Strategi ini diimplementasikan secara otomatis untuk membatasi kesalahan di beberapa. AWS SDKs
catatan
Secara default di AWS Step Functions, percobaan ulang tidak diaktifkan. Jika Anda perlu memanggil Redshift Data API di mesin status Step Functions, sertakan parameter ClientToken idempotency dalam panggilan Redshift Data Anda. API Nilai ClientToken kebutuhan untuk bertahan di antara percobaan ulang. Dalam contoh cuplikan berikut dari permintaan ke ExecuteStatementAPI, ekspresi States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7) menggunakan fungsi intrinsik untuk mengekstrak UUID bagian dari$$.Execution.Id, yang unik untuk setiap eksekusi mesin status. Untuk informasi selengkapnya, lihat Fungsi intrinsik di Panduan AWS Step Functions Pengembang.
```
{
  "Database": "dev",
  "Sql": "select 1;",
  "ClusterIdentifier": "MyCluster",
  "ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
}
```

Memilih kredensi otentikasi database saat memanggil Amazon Redshift Data API

Ketika Anda memanggil DataAPI, Anda menggunakan salah satu metode otentikasi berikut untuk beberapa API operasi. Setiap metode membutuhkan kombinasi parameter yang berbeda.

AWS Secrets Manager

Dengan metode ini, berikan rahasia secret-arn yang disimpan di AWS Secrets Manager mana memiliki username danpassword. Rahasia yang ditentukan berisi kredensil untuk terhubung ke yang database Anda tentukan. Ketika Anda menghubungkan ke cluster, Anda juga menyediakan nama database, Jika Anda memberikan identifier cluster (dbClusterIdentifier), itu harus cocok dengan identifier cluster yang disimpan dalam rahasia. Saat Anda menghubungkan ke workgroup tanpa server, Anda juga menyediakan nama database. Untuk informasi selengkapnya, lihat Menyimpan kredensi database di AWS Secrets Manager.

Kredensial sementara

Dengan metode ini, pilih salah satu opsi berikut:

Saat menghubungkan ke workgroup tanpa server, tentukan nama workgroup dan nama database. Nama pengguna database berasal dari IAM identitas. Misalnya, arn:iam::123456789012:user:foo memiliki nama pengguna databaseIAM:foo. Juga, izin untuk memanggil redshift-serverless:GetCredentials operasi diperlukan.
Saat menghubungkan ke cluster sebagai IAM identitas, tentukan pengidentifikasi cluster dan nama database. Nama pengguna database berasal dari IAM identitas. Misalnya, arn:iam::123456789012:user:foo memiliki nama pengguna databaseIAM:foo. Juga, izin untuk memanggil redshift:GetClusterCredentialsWithIAM operasi diperlukan.
Saat menghubungkan ke cluster sebagai pengguna database, tentukan pengidentifikasi cluster, nama database, dan nama pengguna database. Juga, izin untuk memanggil redshift:GetClusterCredentials operasi diperlukan. Untuk informasi tentang cara bergabung dengan grup database saat menghubungkan dengan metode ini, lihatBergabung dengan grup basis data saat menghubungkan ke klaster.

Dengan metode ini, Anda juga dapat memberikan region nilai yang menentukan di Wilayah AWS mana data Anda berada.

Memetakan tipe JDBC data saat memanggil Amazon Redshift Data API

Tabel berikut memetakan Java Database Connectivity (JDBC) tipe data ke tipe data yang Anda tentukan dalam API Panggilan data.

JDBCtipe data	Tipe API data data
`INTEGER, SMALLINT, BIGINT`	`LONG`
`FLOAT, REAL, DOUBLE`	`DOUBLE`
`DECIMAL`	`STRING`
`BOOLEAN, BIT`	`BOOLEAN`
`BLOB, BINARY, LONGVARBINARY`	`BLOB`
`VARBINARY`	`STRING`
`CLOB`	`STRING`
Tipe lainnya (termasuk tipe terkait tanggal dan waktu)	`STRING`

Nilai string diteruskan ke database Amazon Redshift dan secara implisit diubah menjadi tipe data database.

catatan

Saat ini, Data API tidak mendukung array pengidentifikasi unik universal ()UUIDs.

Menjalankan SQL pernyataan dengan parameter saat memanggil Amazon Redshift Data API

Anda dapat mengontrol SQL teks yang dikirimkan ke mesin database dengan memanggil API operasi Data menggunakan parameter untuk bagian SQL pernyataan. Parameter bernama menyediakan cara yang fleksibel untuk meneruskan parameter tanpa hardcoding mereka dalam SQL teks. Mereka membantu Anda menggunakan kembali SQL teks dan menghindari masalah SQL injeksi.

Contoh berikut menunjukkan parameter bernama dari parameters bidang execute-statement AWS CLI perintah.


--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"

Pertimbangkan hal berikut saat menggunakan parameter bernama:

Parameter bernama hanya dapat digunakan untuk mengganti nilai dalam SQL pernyataan.
- Anda dapat mengganti nilai dalam INSERT pernyataan, sepertiINSERT INTO mytable VALUES(:val1).
  
  Parameter bernama dapat dalam urutan apa pun dan parameter dapat digunakan lebih dari satu kali dalam SQL teks. Opsi parameter yang ditunjukkan dalam contoh sebelumnya, nilai-nilai 1 dan Seattle dimasukkan ke dalam kolom tabel id danaddress. Dalam SQL teks, Anda menentukan parameter bernama sebagai berikut:
```
--sql "insert into mytable values (:id, :address)"
```
- Anda dapat mengganti nilai dalam klausa kondisi, sepertiWHERE attr >= :val1,WHERE attr BETWEEN :val1 AND :val2, danHAVING COUNT(attr) > :val.
- Anda tidak dapat mengganti nama kolom dalam SQL pernyataan, sepertiSELECT column-name,ORDER BY column-name, atauGROUP BY column-name.
  
  Misalnya, SELECT pernyataan berikut gagal dengan sintaks yang tidak valid.
```
--sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]"
```
  Jika Anda menjelaskan (describe-statementoperasi) pernyataan dengan kesalahan sintaks, yang QueryString dikembalikan tidak menggantikan nama kolom untuk parameter ("QueryString": "SELECT :colname, FROM event"), dan kesalahan dilaporkan (ERROR: kesalahan sintaks di atau dekat\”FROM\”\nPosisi: 12).
- Anda tidak dapat mengganti nama kolom dalam fungsi agregat, sepertiCOUNT(column-name),AVG(column-name), atauSUM(column-name).
- Anda tidak dapat mengganti nama kolom dalam JOIN klausa.
Ketika SQL berjalan, data secara implisit dilemparkan ke tipe data. Untuk informasi selengkapnya tentang casting tipe data, lihat Tipe data di Panduan Pengembang Database Amazon Redshift.
Anda tidak dapat menetapkan nilai keNULL. Data API menafsirkannya sebagai string NULL literal. Contoh berikut menggantikan id dengan string null literal. Bukan SQL NULL nilainya.
```
--parameters "[{\"name\": \"id\", \"value\": \"null\"}]"
```
Anda tidak dapat menetapkan nilai panjang nol. APISQLPernyataan data gagal. Contoh berikut mencoba untuk mengatur id dengan nilai panjang nol dan menghasilkan kegagalan SQL pernyataan.
```
--parameters "[{\"name\": \"id\", \"value\": \"\"}]"
```
Anda tidak dapat mengatur nama tabel dalam SQL pernyataan dengan parameter. Data API mengikuti aturan JDBCPreparedStatement.
Output dari describe-statement operasi mengembalikan parameter query dari SQL pernyataan.
Hanya execute-statement operasi yang mendukung SQL pernyataan dengan parameter.

Menjalankan SQL pernyataan dengan token idempotensi saat memanggil Amazon Redshift Data API

Saat Anda membuat API permintaan bermutasi, permintaan biasanya mengembalikan hasil sebelum alur kerja asinkron operasi selesai. Operasi mungkin juga habis waktu atau mengalami masalah server lain sebelum selesai, meskipun permintaan telah mengembalikan hasilnya. Hal ini dapat membuat sulit untuk menentukan apakah permintaan berhasil atau tidak, dan dapat menyebabkan beberapa percobaan ulang untuk memastikan bahwa operasi selesai dengan sukses. Namun, jika permintaan asli dan percobaan ulang berikutnya berhasil, operasi selesai beberapa kali. Ini berarti Anda dapat memperbarui lebih banyak sumber daya daripada yang Anda inginkan.

Idempotency memastikan bahwa API permintaan selesai tidak lebih dari satu kali. Dengan permintaan idempoten, jika permintaan asli berhasil diselesaikan, percobaan ulang berikutnya berhasil diselesaikan tanpa melakukan tindakan lebih lanjut. Data API ExecuteStatement dan BatchExecuteStatement operasi memiliki parameter ClientToken idempoten opsional. ClientTokenKedaluwarsa setelah 8 jam.

penting

Jika Anda memanggil ExecuteStatement dan BatchExecuteStatement beroperasi dari sebuah AWS SDK, secara otomatis menghasilkan token klien untuk digunakan pada coba lagi. Dalam hal ini, kami tidak menyarankan menggunakan client-token parameter dengan ExecuteStatement dan BatchExecuteStatement operasi. Lihat CloudTrail log untuk melihatClientToken. Untuk contoh CloudTrail log, lihatContoh Data Pergeseran Merah Amazon API.

execute-statement AWS CLI Perintah berikut menggambarkan client-token parameter opsional untuk idempotensi.



aws redshift-data execute-statement 
    --region us-west-2 
    --secret arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn 
    --cluster-identifier mycluster-test 
    --sql "select * from stl_query limit 1" 
    --database dev 
    --client-token b855dced-259b-444c-bc7b-d3e8e33f94g1

Tabel berikut menunjukkan beberapa tanggapan umum yang mungkin Anda dapatkan untuk API permintaan idempoten, dan memberikan rekomendasi coba lagi.

Respons	Rekomendasi	Komentar
200 (OK)	Jangan coba lagi	Permintaan asli berhasil diselesaikan. Setiap percobaan ulang berikutnya berhasil kembali.
Kode respons 400 seri	Jangan coba lagi	Ada masalah dengan permintaan, dari antara yang berikut: Ini termasuk parameter atau kombinasi parameter yang tidak valid. Ini menggunakan tindakan atau sumber daya yang Anda tidak memiliki izin. Ini menggunakan sumber daya yang sedang dalam proses mengubah keadaan. Jika permintaan melibatkan sumber daya yang sedang dalam proses mengubah status, mencoba kembali permintaan mungkin berhasil.
Kode respons 500 seri	Coba lagi	Kesalahan ini disebabkan oleh masalah AWS sisi server dan umumnya bersifat sementara. Ulangi permintaan dengan strategi backoff yang sesuai.

Respons

Rekomendasi

Komentar

200 (OK)

Jangan coba lagi

Permintaan asli berhasil diselesaikan. Setiap percobaan ulang berikutnya berhasil kembali.

Kode respons 400 seri

Jangan coba lagi

Ada masalah dengan permintaan, dari antara yang berikut:

Ini termasuk parameter atau kombinasi parameter yang tidak valid.
Ini menggunakan tindakan atau sumber daya yang Anda tidak memiliki izin.
Ini menggunakan sumber daya yang sedang dalam proses mengubah keadaan.

Jika permintaan melibatkan sumber daya yang sedang dalam proses mengubah status, mencoba kembali permintaan mungkin berhasil.

Kode respons 500 seri

Coba lagi

Kesalahan ini disebabkan oleh masalah AWS sisi server dan umumnya bersifat sementara. Ulangi permintaan dengan strategi backoff yang sesuai.

Untuk informasi tentang kode respons Amazon Redshift, lihat Kesalahan Umum dalam Referensi Amazon API Redshift.

Menjalankan SQL pernyataan dengan penggunaan kembali sesi saat memanggil Amazon Redshift Data API

Ketika Anda membuat API permintaan untuk menjalankan SQL pernyataan, sesi di mana SQL proses biasanya dihentikan ketika SQL selesai. Untuk menjaga sesi aktif selama beberapa detik tertentu, Data API ExecuteStatement dan BatchExecuteStatement operasi memiliki SessionKeepAliveSeconds parameter opsional. Bidang SessionId respon berisi identitas sesi yang kemudian dapat digunakan dalam BatchExecuteStatement operasi berikutnyaExecuteStatement. Dalam panggilan berikutnya Anda dapat menentukan yang lain SessionKeepAliveSeconds untuk mengubah waktu batas waktu idle. Jika SessionKeepAliveSeconds tidak diubah, pengaturan batas waktu idle awal tetap ada. Pertimbangkan hal berikut saat menggunakan penggunaan kembali sesi:

Nilai maksimum SessionKeepAliveSeconds adalah 24 jam.
Sesi ini dapat berlangsung paling lama 24 jam. Setelah 24 jam sesi ditutup secara paksa dan kueri yang sedang berlangsung dihentikan.
Jumlah maksimum sesi per cluster Amazon Redshift atau grup kerja Redshift Serverless adalah 500.
Anda hanya dapat menjalankan satu kueri pada satu waktu dalam satu sesi. Anda harus menunggu sampai kueri selesai untuk menjalankan kueri berikutnya di sesi yang sama. Artinya, Anda tidak dapat menjalankan kueri secara paralel dalam sesi yang disediakan.
Data tidak API dapat mengantri kueri untuk sesi tertentu.

Untuk mengambil SessionId yang digunakan oleh panggilan ke ExecuteStatement dan BatchExecuteStatement operasi, panggilan DescribeStatement dan ListStatements operasi.

Contoh berikut menunjukkan penggunaan SessionKeepAliveSeconds dan SessionId parameter untuk menjaga sesi tetap hidup dan digunakan kembali. Pertama, panggil execute-statement AWS CLI perintah dengan session-keep-alive-seconds parameter opsional diatur ke2.



aws redshift-data execute-statement 
    --session-keep-alive-seconds 2 
    --sql "select 1" 
    --database dev 
    --workgroup-name mywg

Respons berisi pengenal sesi.


{
    "WorkgroupName": "mywg",
    "CreatedAt": 1703022996.436,
    "Database": "dev",
    "DbUser": "awsuser",
    "Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680",
    "SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4"
}

Kemudian, panggil execute-statement AWS CLI perintah dengan yang SessionId dikembalikan dari panggilan pertama. Dan secara opsional, tentukan session-keep-alive-seconds parameter yang disetel 10 untuk mengubah nilai batas waktu idle.



aws redshift-data execute-statement 
    --sql "select 1" 
    --session-id 5a254dc6-4fc2-4203-87a8-551155432ee4
    --session-keep-alive-seconds 10

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Memecahkan masalah koneksi di Amazon Redshift

Mengizinkan akses