Pilih preferensi cookie Anda

Kami menggunakan cookie penting serta alat serupa yang diperlukan untuk menyediakan situs dan layanan. Kami menggunakan cookie performa untuk mengumpulkan statistik anonim sehingga kami dapat memahami cara pelanggan menggunakan situs dan melakukan perbaikan. Cookie penting tidak dapat dinonaktifkan, tetapi Anda dapat mengklik “Kustom” atau “Tolak” untuk menolak cookie performa.

Jika Anda setuju, AWS dan pihak ketiga yang disetujui juga akan menggunakan cookie untuk menyediakan fitur situs yang berguna, mengingat preferensi Anda, dan menampilkan konten yang relevan, termasuk iklan yang relevan. Untuk menerima atau menolak semua cookie yang tidak penting, klik “Terima” atau “Tolak”. Untuk membuat pilihan yang lebih detail, klik “Kustomisasi”.

Menggunakan API Data Amazon Redshift - Amazon Redshift

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

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

Menggunakan API Data Amazon Redshift

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

Data API tidak memerlukan koneksi persisten ke database Anda. 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. Panggilan ke API Data bersifat asinkron. Data API dapat menggunakan kredensil yang disimpan dalam AWS Secrets Manager atau kredenal database sementara. Anda tidak perlu meneruskan kata sandi dalam panggilan API 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. Anda juga dapat menggunakan AWS IAM Identity Center untuk otorisasi.

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

Untuk mempelajari API Data selengkapnya, lihat Memulai API Data Amazon Redshift di Blog AWS Big Data.

Bekerja dengan Amazon Redshift Data API

Sebelum Anda menggunakan Amazon Redshift Data API, tinjau langkah-langkah berikut:

  1. Tentukan apakah Anda, sebagai pemanggil API Data, diotorisasi. Untuk informasi selengkapnya tentang otorisasi, lihatMengotorisasi akses ke API Data Amazon Redshift.

  2. Tentukan apakah Anda berencana untuk memanggil Data API dengan kredensi otentikasi dari Secrets Manager, kredensial sementara, atau penggunaan. AWS IAM Identity Center Untuk informasi selengkapnya, lihat Memilih kredensi otentikasi database saat memanggil Amazon Redshift Data API.

  3. Siapkan rahasia jika Anda menggunakan Secrets Manager untuk kredensi otentikasi. Untuk informasi selengkapnya, lihat Menyimpan kredensi basis data di AWS Secrets Manager.

  4. Tinjau pertimbangan dan batasan saat memanggil Data API. Untuk informasi selengkapnya, lihat Pertimbangan saat memanggil Amazon Redshift Data API.

  5. Panggil API Data 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 API Data.

Pertimbangan saat memanggil Amazon Redshift Data API

Pertimbangkan hal berikut saat memanggil Data API:

  • Amazon Redshift Data API dapat mengakses database di klaster yang disediakan Amazon Redshift dan grup kerja Tanpa Server Redshift. Untuk daftar Wilayah AWS tempat API Data Redshift tersedia, lihat titik akhir yang tercantum untuk Redshift Data API di. 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 tipe node berikut:

    • dc2.large

    • dc2.8xlarge

    • ra3. besar

    • ra3.xlplus

    • ra3.4xlarge

    • ra3.16xlarge

  • Cluster harus berada di cloud pribadi virtual (VPC) berdasarkan layanan Amazon VPC.

  • Secara default, pengguna dengan peran IAM atau izin IAM yang sama dengan pelari operasi ExecuteStatement atau BatchExecuteStatement API dapat bertindak berdasarkan pernyataan yang sama denganCancelStatement,,, DescribeStatement GetStatementResultGetStatementResultV2, dan operasi API. ListStatements Untuk bertindak pada pernyataan SQL yang sama dari pengguna lain, pengguna harus dapat mengambil peran IAM dari pengguna yang menjalankan pernyataan SQL. Untuk informasi selengkapnya tentang cara mengambil peran, lihatMengotorisasi akses ke API Data Amazon Redshift.

  • Pernyataan SQL dalam Sqls parameter operasi BatchExecuteStatement API dijalankan sebagai satu transaksi. Mereka berjalan secara serial dalam urutan array. Pernyataan SQL berikutnya tidak dimulai sampai pernyataan sebelumnya dalam array selesai. Jika pernyataan SQL gagal, maka karena mereka dijalankan sebagai satu transaksi, semua pekerjaan digulirkan kembali.

  • Waktu retensi maksimum untuk token klien yang digunakan dalam ExecuteStatement atau operasi BatchExecuteStatement API adalah 8 jam.

  • Setiap API di Redshift Data API memiliki kuota transaksi per detik sebelum membatasi permintaan. Untuk kuota, lihatKuota untuk Amazon Redshift Data API. Jika tingkat permintaan melebihi kuota, a ThrottlingException dengan Kode Status HTTP: 400 dikembalikan. Untuk merespons pelambatan, gunakan strategi coba lagi seperti yang dijelaskan dalam Perilaku Coba lagi di Panduan Referensi Alat AWS SDKs dan 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 API Anda. Nilai ClientToken kebutuhan untuk bertahan di antara percobaan ulang. Dalam contoh cuplikan permintaan ExecuteStatement API berikut, ekspresi States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7) menggunakan fungsi intrinsik untuk mengekstrak bagian UUID$$.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

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

AWS IAM Identity Center

Data API dapat diakses dengan satu pengguna masuk yang terdaftar di. AWS IAM Identity Center Untuk informasi tentang langkah-langkah untuk mengatur Pusat Identitas IAM, lihatMenggunakan Data API dengan propagasi identitas tepercaya.

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 basis data di AWS Secrets Manager.

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

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 identitas IAM. 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 identitas IAM, tentukan pengidentifikasi cluster dan nama database. Nama pengguna database berasal dari identitas IAM. 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 data JDBC saat memanggil Amazon Redshift Data API

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

Jenis data JDBC

Jenis data API Data

INTEGER, SMALLINT, BIGINT

LONG

FLOAT, REAL, DOUBLE

DOUBLE

DECIMAL

STRING

BOOLEAN, BIT

BOOLEAN

BLOB, BINARY, LONGVARBINARY

BLOB

VARBINARY

STRING

CLOB

STRING

Jenis lainnya (termasuk jenis yang terkait dengan 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 pernyataan SQL dengan parameter saat memanggil Amazon Redshift Data API

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

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 pernyataan SQL.

    • Anda dapat mengganti nilai dalam pernyataan INSERT, sepertiINSERT INTO mytable VALUES(:val1).

      Parameter bernama dapat dalam urutan apa pun dan parameter dapat digunakan lebih dari satu kali dalam teks SQL. Opsi parameter yang ditunjukkan dalam contoh sebelumnya, nilai-nilai 1 dan Seattle dimasukkan ke dalam kolom tabel id danaddress. Dalam teks SQL, 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 pernyataan SQL, sepertiSELECT column-name,ORDER BY column-name, atauGROUP BY column-name.

      Misalnya, pernyataan SELECT 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 klausa JOIN.

  • 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 ke NULL. Data API menafsirkannya sebagai string NULL literal. Contoh berikut menggantikan id dengan string null literal. Bukan nilai SQL NULL.

    --parameters "[{\"name\": \"id\", \"value\": \"null\"}]"
  • Anda tidak dapat menetapkan nilai panjang nol. Pernyataan Data API SQL gagal. Contoh berikut mencoba untuk mengatur id dengan nilai panjang nol dan menghasilkan kegagalan pernyataan SQL.

    --parameters "[{\"name\": \"id\", \"value\": \"\"}]"
  • Anda tidak dapat mengatur nama tabel dalam pernyataan SQL dengan parameter. Data API mengikuti aturan JDBCPreparedStatement.

  • Output dari describe-statement operasi mengembalikan parameter query dari pernyataan SQL.

  • Hanya execute-statement operasi yang mendukung pernyataan SQL dengan parameter.

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

Saat Anda membuat permintaan API yang bermutasi, permintaan biasanya menampilkan hasil sebelum alur kerja asinkron operasi selesai. Operasi mungkin juga habis 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 permintaan API 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 mengoperasikannya dari AWS SDK, secara otomatis akan menghasilkan token klien untuk digunakan saat mencoba 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 API Data Amazon Redshift.

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

aws redshift-data execute-statement --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 permintaan API idempoten, dan memberikan rekomendasi coba ulang.

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 di Referensi API Amazon Redshift.

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

Ketika Anda membuat permintaan API untuk menjalankan pernyataan SQL, sesi di mana SQL berjalan biasanya dihentikan ketika SQL selesai. Agar sesi tetap aktif selama beberapa detik tertentu, API Data ExecuteStatement dan BatchExecuteStatement operasi memiliki SessionKeepAliveSeconds parameter opsional. Bidang SessionId respons 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 API tidak 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

Mengambil hasil pernyataan SQL

Anda menggunakan operasi Data API yang berbeda untuk mengambil hasil SQL tergantung pada format hasil. Saat Anda memanggil ExecuteStatement dan BatchExecuteStatement operasi, Anda dapat menentukan apakah hasilnya diformat sebagai JSON atau CSV. Jika Anda tidak menentukan, defaultnya adalah JSON. Untuk mengambil hasil JSON, gunakan operasi. GetStatementResult Untuk mengambil hasil CSV, gunakan operasi. GetStatementResultV2

Hasil yang dikembalikan dalam format JSON adalah catatan yang menyertakan metadata tentang setiap kolom. Setiap rekaman dalam format JSON. Misalnya, respons dari GetStatementResult terlihat mirip dengan ini:

{ "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "?column?", "name": "?column?", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "", "tableName": "", "typeName": "int4", "length": 0 } ], "NextToken": "<token>", "Records": [ [ { "longValue": 1 } ] ], "TotalNumRows": <number> }

Hasil yang dikembalikan dalam format CSV adalah catatan yang menyertakan metadata tentang setiap kolom. Hasil dikembalikan dalam potongan 1 MB, di mana setiap potongan dapat menyimpan sejumlah baris dalam format CSV. Setiap permintaan mengembalikan hasil hingga 15 MB. Jika hasilnya lebih besar dari 15 MB, maka token halaman berikutnya dikembalikan untuk melanjutkan pengambilan hasilnya. Misalnya, respons dari GetStatementResultV2 terlihat mirip dengan ini:

{ "ColumnMetadata": [ { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "?column?", "name": "?column?", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "", "tableName": "", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "?column?", "name": "?column?", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "", "tableName": "", "typeName": "int4", "length": 0 }, { "isCaseSensitive": false, "isCurrency": false, "isSigned": true, "label": "?column?", "name": "?column?", "nullable": 1, "precision": 10, "scale": 0, "schemaName": "", "tableName": "", "typeName": "int4", "length": 0 } ], "NextToken": "<token>", "Records": [ [ { "CSVRecords":"1,2,3\r\n4,5,6\r\n7,8,9\rn, .... 1MB" // First 1MB Chunk }, { "CSVRecords":"1025,1026,1027\r\n1028,1029,1030\r\n....2MB" // Second 1MB chunk } ... ] ], "ResultFormat" : "CSV", "TotalNumRows": <number> }
PrivasiSyarat situsPreferensi cookie
© 2025, Amazon Web Services, Inc. atau afiliasinya. Semua hak dilindungi undang-undang.