API Eksekusi Pernyataan: Jalankan SQL di gudang
Penting
Untuk mengakses API Databricks REST, Anda harus melakukan autentikasi.
Tutorial ini menunjukkan kepada Anda cara menggunakan Databricks SQL Statement Execution API 2.0 untuk menjalankan pernyataan SQL dari gudang Databricks SQL.
Untuk melihat referensi Databricks SQL Statement Execution API 2.0, lihat Eksekusi Pernyataan.
Sebelum Anda mulai
Sebelum memulai tutorial ini, pastikan Anda memiliki:
Baik Databricks CLI versi 0.205 atau lebih tinggi atau
curl, sebagai berikut:Databricks CLI adalah alat baris perintah untuk mengirim dan menerima permintaan dan respons Databricks REST API. Jika Anda memilih untuk menggunakan Databricks CLI versi 0.205 atau lebih tinggi, data tersebut harus dikonfigurasi untuk mengautentikasi dengan ruang kerja Azure Databricks Anda. Lihat Menginstal atau memperbarui Databricks CLI dan Autentikasi untuk Databricks CLI.
Misalnya, untuk mengautentikasi dengan autentikasi token akses pribadi Databricks, buat token akses pribadi sebagai berikut:
- Di ruang kerja Azure Databricks Anda, klik nama pengguna Azure Databricks Anda di bilah atas, lalu pilih Pengaturan dari menu drop-down.
- Klik Pengembang.
- Di samping Token akses, klik Kelola.
- Klik Buat token baru.
- (Opsional) Masukkan komentar yang membantu Anda mengidentifikasi token ini di masa mendatang, dan mengubah masa pakai default token selama 90 hari. Untuk membuat token tanpa masa pakai (tidak disarankan), biarkan kotak Seumur Hidup (hari) kosong (kosong).
- Klik Buat.
- Salin token yang ditampilkan ke lokasi aman, lalu klik Selesai.
Catatan
Pastikan untuk menyimpan token yang disalin di lokasi yang aman. Jangan bagikan token yang Anda salin dengan orang lain. Jika Anda kehilangan token yang disalin, Anda tidak dapat meregenerasi token yang sama persis. Sebagai gantinya, Anda harus mengulangi prosedur ini untuk membuat token baru. Jika Anda kehilangan token yang disalin, atau Anda yakin bahwa token telah disusupi, Databricks sangat menyarankan agar Anda segera menghapus token tersebut dari ruang kerja Anda dengan mengklik ikon tempat sampah (Cabut) di samping token di halaman Token akses.
Jika Anda tidak dapat membuat atau menggunakan token di ruang kerja, ini mungkin karena administrator ruang kerja Anda telah menonaktifkan token atau belum memberi Anda izin untuk membuat atau menggunakan token. Lihat administrator ruang kerja Anda atau berikut ini:
Lalu untuk menggunakan Databricks CLI untuk membuat profil konfigurasi Azure Databricks untuk token akses pribadi Anda, lakukan hal berikut:
Catatan
Prosedur berikut menggunakan Databricks CLI untuk membuat profil konfigurasi Azure Databricks dengan nama
DEFAULT. Jika Anda sudah memilikiDEFAULTprofil konfigurasi, prosedur ini akan menimpa profil konfigurasi yang adaDEFAULT.Untuk memeriksa apakah Anda sudah memiliki
DEFAULTprofil konfigurasi, dan untuk melihat pengaturan profil ini jika ada, gunakan Databricks CLI untuk menjalankan perintahdatabricks auth env --profile DEFAULT.Untuk membuat profil konfigurasi dengan nama selain
DEFAULT, gantiDEFAULTbagian--profile DEFAULTdalam perintah berikutdatabricks configuredengan nama yang berbeda untuk profil konfigurasi.Gunakan Databricks CLI untuk membuat profil konfigurasi Azure Databricks bernama
DEFAULTyang menggunakan autentikasi token akses pribadi Azure Databricks. Untuk melakukannya, jalankan perintah berikut:databricks configure --profile DEFAULTUntuk Permintaan Host Databricks, masukkan URL per ruang kerja Azure Databricks Anda, misalnya
https://adb-1234567890123456.7.azuredatabricks.net.Untuk perintah Token Akses Pribadi, masukkan token akses pribadi Azure Databricks untuk ruang kerja Anda.
Dalam contoh Databricks CLI tutorial ini, perhatikan hal berikut:
- Tutorial ini mengasumsikan bahwa Anda memiliki variabel
DATABRICKS_SQL_WAREHOUSE_IDlingkungan pada komputer pengembangan lokal Anda. Variabel lingkungan ini mewakili ID gudang Databricks SQL Anda. ID ini adalah string huruf dan angka yang mengikuti/sql/1.0/warehouses/di bidang jalur HTTP untuk gudang Anda. Untuk mempelajari cara mendapatkan nilai jalur HTTP gudang Anda, lihat Mendapatkan detail koneksi untuk sumber daya komputasi Azure Databricks. - Jika Anda menggunakan shell Perintah Windows alih-alih shell perintah untuk Unix, Linux, atau macOS, ganti
\dengan^, dan ganti${...}dengan%...%. - Jika Anda menggunakan shell Perintah Windows alih-alih shell perintah untuk Unix, Linux, atau macOS, dalam deklarasi dokumen JSON, ganti pembukaan dan penutupan
'dengan", dan ganti bagian"dalam dengan\".
curl adalah alat baris perintah untuk mengirim dan menerima permintaan dan respons REST API. Lihat juga Menginstal curl. Atau, Anda dapat menyesuaikan contoh tutorial
curlini untuk digunakan dengan alat serupa seperti Postman atau HTTPie.Dalam contoh tutorial
curlini, perhatikan hal berikut:- Alih-alih
--header "Authorization: Bearer ${DATABRICKS_TOKEN}", Anda dapat menggunakan file .netrc . Jika Anda menggunakan.netrcfile, ganti--header "Authorization: Bearer ${DATABRICKS_TOKEN}"dengan--netrc. - Jika Anda menggunakan shell Perintah Windows alih-alih shell perintah untuk Unix, Linux, atau macOS, ganti
\dengan^, dan ganti${...}dengan%...%. - Jika Anda menggunakan shell Perintah Windows alih-alih shell perintah untuk Unix, Linux, atau macOS, dalam deklarasi dokumen JSON, ganti pembukaan dan penutupan
'dengan", dan ganti bagian"dalam dengan\".
Selain itu, untuk contoh tutorial
curlini, tutorial ini mengasumsikan Anda memiliki variabel lingkungan berikut pada komputer pengembangan lokal Anda:DATABRICKS_HOST, mewakili nama instans ruang kerja, misalnyaadb-1234567890123456.7.azuredatabricks.net, untuk ruang kerja Azure Databricks Anda.DATABRICKS_TOKEN, mewakili token akses pribadi Azure Databricks untuk pengguna ruang kerja Azure Databricks Anda.DATABRICKS_SQL_WAREHOUSE_ID, mewakili ID gudang Databricks SQL Anda. ID ini adalah string huruf dan angka yang mengikuti/sql/1.0/warehouses/di bidang jalur HTTP untuk gudang Anda. Untuk mempelajari cara mendapatkan nilai jalur HTTP gudang Anda, lihat Mendapatkan detail koneksi untuk sumber daya komputasi Azure Databricks.
Catatan
Sebagai praktik terbaik keamanan, saat Anda mengautentikasi dengan alat, sistem, skrip, dan aplikasi otomatis, Databricks merekomendasikan agar Anda menggunakan token akses pribadi milik perwakilan layanan, bukan pengguna ruang kerja. Untuk membuat token untuk perwakilan layanan, lihat Mengelola token untuk perwakilan layanan.
Untuk membuat token akses pribadi Azure Databricks, lakukan hal berikut:
- Di ruang kerja Azure Databricks Anda, klik nama pengguna Azure Databricks Anda di bilah atas, lalu pilih Pengaturan dari menu drop-down.
- Klik Pengembang.
- Di samping Token akses, klik Kelola.
- Klik Buat token baru.
- (Opsional) Masukkan komentar yang membantu Anda mengidentifikasi token ini di masa mendatang, dan mengubah masa pakai default token selama 90 hari. Untuk membuat token tanpa masa pakai (tidak disarankan), biarkan kotak Seumur Hidup (hari) kosong (kosong).
- Klik Buat.
- Salin token yang ditampilkan ke lokasi aman, lalu klik Selesai.
Catatan
Pastikan untuk menyimpan token yang disalin di lokasi yang aman. Jangan bagikan token yang Anda salin dengan orang lain. Jika Anda kehilangan token yang disalin, Anda tidak dapat meregenerasi token yang sama persis. Sebagai gantinya, Anda harus mengulangi prosedur ini untuk membuat token baru. Jika Anda kehilangan token yang disalin, atau Anda yakin bahwa token telah disusupi, Databricks sangat menyarankan agar Anda segera menghapus token tersebut dari ruang kerja Anda dengan mengklik ikon tempat sampah (Cabut) di samping token di halaman Token akses.
Jika Anda tidak dapat membuat atau menggunakan token di ruang kerja, ini mungkin karena administrator ruang kerja Anda telah menonaktifkan token atau belum memberi Anda izin untuk membuat atau menggunakan token. Lihat administrator ruang kerja Anda atau berikut ini:
Peringatan
Databricks sangat mencegah informasi hard-coding ke dalam skrip Anda, karena informasi sensitif ini dapat diekspos dalam teks biasa melalui sistem kontrol versi. Databricks merekomendasikan agar Anda menggunakan pendekatan seperti variabel lingkungan yang Anda tetapkan pada komputer pengembangan Anda sebagai gantinya. Menghapus informasi yang dikodekan secara permanen seperti itu dari skrip Anda juga membantu membuat skrip tersebut lebih portabel.
- Alih-alih
Tutorial ini mengasumsikan bahwa Anda juga memiliki jq, prosesor baris perintah untuk mengkueri payload respons JSON, yang dikembalikan API Eksekusi Pernyataan SQL Databricks kepada Anda setelah setiap panggilan yang Anda lakukan ke API Eksekusi Pernyataan SQL Databricks. Lihat Mengunduh jq.
Anda harus memiliki setidaknya satu tabel yang dapat Anda jalankan terhadap pernyataan SQL. Tutorial ini didasarkan pada
lineitemtabel dalamtpchskema (juga dikenal sebagai database) dalamsampleskatalog. Jika Anda tidak memiliki akses ke katalog, skema, atau tabel ini dari ruang kerja Anda, ganti di seluruh tutorial ini dengan milik Anda sendiri.
Langkah 1: Jalankan pernyataan SQL dan simpan hasil data sebagai JSON
Jalankan perintah berikut, yang melakukan hal berikut:
- Menggunakan gudang SQL yang ditentukan, bersama dengan token yang ditentukan jika Anda menggunakan , untuk mengkueri
curltiga kolom dari dua barislineitempertama tabel dalam skema dalamtcphsampleskatalog. - Menyimpan payload respons dalam format JSON dalam file bernama
sql-execution-response.jsondalam direktori kerja saat ini. - Mencetak isi
sql-execution-response.jsonfile. - Mengatur variabel lingkungan lokal bernama
SQL_STATEMENT_ID. Variabel ini berisi ID pernyataan SQL yang sesuai. Anda dapat menggunakan ID pernyataan SQL ini untuk mendapatkan informasi tentang pernyataan tersebut nanti sesuai kebutuhan, yang ditunjukkan pada Langkah 2. Anda juga dapat melihat pernyataan SQL ini dan mendapatkan ID pernyataannya dari bagian riwayat kueri konsol Databricks SQL, atau dengan memanggil API Riwayat Kueri. - Mengatur variabel lingkungan lokal tambahan bernama
NEXT_CHUNK_EXTERNAL_LINKyang berisi fragmen URL API untuk mendapatkan potongan data JSON berikutnya. Jika data respons terlalu besar, API Eksekusi Pernyataan SQL Databricks memberikan respons dalam gugus. Anda dapat menggunakan fragmen URL API ini untuk mendapatkan potongan data berikutnya, yang ditunjukkan di Langkah 2. Jika tidak ada gugus berikutnya, maka variabel lingkungan ini diatur kenull. - Mencetak nilai
SQL_STATEMENT_IDvariabel lingkungan danNEXT_CHUNK_INTERNAL_LINK.
Databricks cli
databricks api post /api/2.0/sql/statements \
--profile <profile-name> \
--json '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "2", "type": "INT" }
]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
Ganti <profile-name> dengan nama profil konfigurasi Azure Databricks Anda untuk autentikasi.
Curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "2", "type": "INT" }
]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
Dalam permintaan sebelumnya:
Kueri berparameter terdiri dari setiap nama parameter kueri yang didahului oleh titik dua (misalnya,
:extended_price) dengan pencocokannamedanvalueobjek dalamparametersarray. Opsionaltypejuga dapat ditentukan, dengan nilaiSTRINGdefault jika tidak ditentukan.Peringatan
Databricks sangat menyarankan Agar Anda menggunakan parameter sebagai praktik terbaik untuk pernyataan SQL Anda.
Jika Anda menggunakan API Eksekusi Pernyataan SQL Databricks dengan aplikasi yang menghasilkan SQL secara dinamis, ini dapat mengakibatkan serangan injeksi SQL. Misalnya, jika Anda membuat kode SQL berdasarkan pilihan pengguna di antarmuka pengguna dan tidak mengambil langkah-langkah yang sesuai, penyerang dapat menyuntikkan kode SQL berbahaya untuk mengubah logika kueri awal Anda, sehingga membaca, mengubah, atau menghapus data sensitif.
Kueri berparameter membantu melindungi dari serangan injeksi SQL dengan menangani argumen input secara terpisah dari sisa kode SQL Anda dan menafsirkan argumen ini sebagai nilai harfiah. Parameter juga membantu menggunakan kembali kode.
Secara default, setiap data yang dikembalikan dalam format array JSON, dan lokasi default untuk salah satu hasil data pernyataan SQL berada dalam payload respons. Untuk membuat perilaku ini eksplisit, tambahkan
"format":"JSON_ARRAY","disposition":"INLINE"ke payload permintaan. Jika Anda mencoba mengembalikan hasil data yang lebih besar dari 25 MiB dalam payload respons, status kegagalan dikembalikan dan pernyataan SQL dibatalkan. Untuk hasil data yang lebih besar dari 25 MiB, Anda dapat menggunakan tautan eksternal alih-alih mencoba mengembalikannya dalam payload respons, yang ditunjukkan di Langkah 3.Perintah menyimpan konten payload respons ke file lokal. Penyimpanan data lokal tidak didukung oleh API Eksekusi Pernyataan SQL Databricks secara langsung.
Secara default, setelah 10 detik, jika pernyataan SQL belum selesai dijalankan melalui gudang, API Eksekusi Pernyataan SQL Databricks hanya mengembalikan ID pernyataan SQL dan statusnya saat ini, alih-alih hasil pernyataan. Untuk mengubah perilaku ini, tambahkan
"wait_timeout"ke permintaan dan atur ke"<x>s", di mana<x>bisa antara5dan50detik inklusif, misalnya"50s". Untuk segera mengembalikan ID pernyataan SQL dan statusnya saat ini, aturwait_timeoutke0s.Secara default, pernyataan SQL terus berjalan jika periode batas waktu tercapai. Untuk membatalkan pernyataan SQL jika periode batas waktu tercapai, tambahkan
"on_wait_timeout":"CANCEL"ke payload permintaan.Untuk membatasi jumlah byte yang dikembalikan, tambahkan
"byte_limit"ke permintaan dan atur ke jumlah byte, misalnya1000.Untuk membatasi jumlah baris yang dikembalikan, alih-alih menambahkan
LIMITklausul kestatement, Anda dapat menambahkan"row_limit"ke permintaan dan mengaturnya ke jumlah baris, misalnya"statement":"SELECT * FROM lineitem","row_limit":2.Jika hasilnya lebih besar dari yang ditentukan
byte_limitataurow_limit,truncatedbidang diatur ketruedalam payload respons.
Jika hasil pernyataan tersedia sebelum batas waktu tunggu berakhir, responsnya adalah sebagai berikut:
{
"manifest": {
"chunks": [
{
"chunk_index": 0,
"row_count": 2,
"row_offset": 0
}
],
"format": "JSON_ARRAY",
"schema": {
"column_count": 3,
"columns": [
{
"name": "l_orderkey",
"position": 0,
"type_name": "LONG",
"type_text": "BIGINT"
},
{
"name": "l_extendedprice",
"position": 1,
"type_name": "DECIMAL",
"type_precision": 18,
"type_scale": 2,
"type_text": "DECIMAL(18,2)"
},
{
"name": "l_shipdate",
"position": 2,
"type_name": "DATE",
"type_text": "DATE"
}
]
},
"total_chunk_count": 1,
"total_row_count": 2,
"truncated": false
},
"result": {
"chunk_index": 0,
"data_array": [
[
"2",
"71433.16",
"1997-01-28"
],
[
"7",
"86152.02",
"1996-01-15"
]
],
"row_count": 2,
"row_offset": 0
},
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "SUCCEEDED"
}
}
Jika batas waktu tunggu berakhir sebelum hasil pernyataan tersedia, respons akan terlihat seperti ini:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Jika data hasil pernyataan terlalu besar (misalnya dalam hal ini, dengan menjalankan SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), data hasil dipotong dan terlihat seperti ini sebagai gantinya. Perhatikan bahwa menunjukkan hasil yang "...": "..." dihilangkan di sini untuk keringkasan:
{
"manifest": {
"chunks": [
{
"chunk_index": 0,
"row_count": 188416,
"row_offset": 0
},
{
"chunk_index": 1,
"row_count": 111584,
"row_offset": 188416
}
],
"format":"JSON_ARRAY",
"schema": {
"column_count":3,
"columns": [
{
"...": "..."
}
]
},
"total_chunk_count": 2,
"total_row_count": 300000,
"truncated": false
},
"result": {
"chunk_index": 0,
"data_array": [
[
"2",
"71433.16",
"1997-01-28"
],
[
"..."
]
],
"next_chunk_index": 1,
"next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=188416",
"row_count": 188416,
"row_offset": 0
},
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "SUCCEEDED"
}
}
Langkah 2: Dapatkan status eksekusi dan hasil data pernyataan saat ini sebagai JSON
Anda dapat menggunakan ID pernyataan SQL untuk mendapatkan status eksekusi pernyataan tersebut saat ini dan, jika eksekusi berhasil, hasil pernyataan tersebut. Jika Anda lupa ID pernyataan, Anda bisa mendapatkannya dari bagian riwayat kueri konsol Databricks SQL, atau dengan memanggil API Riwayat Kueri. Misalnya, Anda dapat terus melakukan polling perintah ini, memeriksa setiap kali untuk melihat apakah eksekusi telah berhasil.
Untuk mendapatkan status eksekusi pernyataan SQL saat ini dan, jika eksekusi berhasil, hasil pernyataan tersebut dan fragmen URL API untuk mendapatkan potongan data JSON berikutnya, jalankan perintah berikut. Perintah ini mengasumsikan bahwa Anda memiliki variabel lingkungan pada komputer SQL_STATEMENT_IDpengembangan lokal Bernama , yang diatur ke nilai ID pernyataan SQL dari langkah sebelumnya. Tentu saja, Anda dapat mengganti ${SQL_STATEMENT_ID} dalam perintah berikut dengan ID yang dikodekan secara permanen dari pernyataan SQL.
Databricks cli
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
Ganti <profile-name> dengan nama profil konfigurasi Azure Databricks Anda untuk autentikasi.
Curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
NEXT_CHUNK_INTERNAL_LINK Jika diatur ke non-nilainull, Anda dapat menggunakannya untuk mendapatkan potongan data berikutnya, dan sebagainya, misalnya dengan perintah berikut:
Databricks cli
databricks api get /${NEXT_CHUNK_INTERNAL_LINK} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
Ganti <profile-name> dengan nama profil konfigurasi Azure Databricks Anda untuk autentikasi.
Curl
curl --request GET \
https://${DATABRICKS_HOST}${NEXT_CHUNK_INTERNAL_LINK} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
Anda dapat terus menjalankan perintah sebelumnya, berulang-ulang, untuk mendapatkan gugus berikutnya, dan sebagainya. Perhatikan bahwa segera setelah potongan terakhir diambil, pernyataan SQL ditutup. Setelah penutupan ini, Anda tidak dapat menggunakan ID pernyataan tersebut untuk mendapatkan statusnya saat ini atau untuk mengambil gugus lagi.
Langkah 3: Ambil hasil besar menggunakan tautan eksternal
Bagian ini menunjukkan konfigurasi opsional yang menggunakan disposisi EXTERNAL_LINKS untuk mengambil himpunan data besar. Lokasi default (disposisi) untuk data hasil pernyataan SQL berada dalam payload respons, tetapi hasil ini dibatasi hingga 25 MiB. Dengan mengatur disposition ke EXTERNAL_LINKS, respons berisi URL yang dapat Anda gunakan untuk mengambil potongan data hasil dengan HTTP standar. URL menunjuk ke DBFS internal ruang kerja Anda, tempat potongan hasil disimpan sementara.
Peringatan
Databricks sangat menyarankan Agar Anda melindungi URL dan token yang dikembalikan oleh disposisi EXTERNAL_LINKS .
Saat Anda menggunakan disposisi EXTERNAL_LINKS , URL tanda tangan akses bersama (SAS) dibuat, yang dapat digunakan untuk mengunduh hasilnya langsung dari penyimpanan Azure. Karena token SAS berumur pendek disematkan dalam URL SAS ini, Anda harus melindungi URL SAS dan token SAS.
Karena URL SAS sudah dibuat dengan token SAS sementara yang disematkan, Anda tidak boleh mengatur Authorization header dalam permintaan unduhan.
Disposisi EXTERNAL_LINKS dapat dinonaktifkan berdasarkan permintaan. Untuk membuat permintaan ini, buat kasus dukungan.
Lihat juga Praktik terbaik keamanan.
Catatan
Format dan perilaku output payload respons, setelah diatur untuk ID pernyataan SQL tertentu, tidak dapat diubah.
Dalam mode ini, API memungkinkan Anda menyimpan data hasil dalam format JSON (JSON), format CSV (CSV), atau format Apache Arrow (ARROW_STREAM), yang harus dikueri secara terpisah dengan HTTP. Selain itu, saat menggunakan mode ini, tidak dimungkinkan untuk menginline data hasil dalam payload respons.
Perintah berikut menunjukkan menggunakan EXTERNAL_LINKS dan format Apache Arrow. Gunakan pola ini alih-alih kueri serupa yang ditunjukkan di Langkah 1:
Databricks cli
databricks api post /api/2.0/sql/statements/ \
--profile <profile-name> \
--json '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"format": "ARROW_STREAM",
"disposition": "EXTERNAL_LINKS",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "100000", "type": "INT" }
]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID
Ganti <profile-name> dengan nama profil konfigurasi Azure Databricks Anda untuk autentikasi.
Curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"format": "ARROW_STREAM",
"disposition": "EXTERNAL_LINKS",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "100000", "type": "INT" }
]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID
Responsnya adalah sebagai berikut:
{
"manifest": {
"chunks": [
{
"byte_count": 2843848,
"chunk_index": 0,
"row_count": 100000,
"row_offset": 0
}
],
"format": "ARROW_STREAM",
"schema": {
"column_count": 3,
"columns": [
{
"name": "l_orderkey",
"position": 0,
"type_name": "LONG",
"type_text": "BIGINT"
},
{
"name": "l_extendedprice",
"position": 1,
"type_name": "DECIMAL",
"type_precision": 18,
"type_scale": 2,
"type_text": "DECIMAL(18,2)"
},
{
"name": "l_shipdate",
"position": 2,
"type_name": "DATE",
"type_text": "DATE"
}
]
},
"total_byte_count": 2843848,
"total_chunk_count": 1,
"total_row_count": 100000,
"truncated": false
},
"result": {
"external_links": [
{
"byte_count": 2843848,
"chunk_index": 0,
"expiration": "<url-expiration-timestamp>",
"external_link": "<url-to-data-stored-externally>",
"row_count": 100000,
"row_offset": 0
}
]
},
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "SUCCEEDED"
}
}
Jika waktu permintaan habis, respons akan terlihat seperti ini sebagai gantinya:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Untuk mendapatkan status eksekusi pernyataan tersebut saat ini dan, jika eksekusi berhasil, hasil pernyataan tersebut, jalankan perintah berikut:
Databricks cli
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Ganti <profile-name> dengan nama profil konfigurasi Azure Databricks Anda untuk autentikasi.
Curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Jika respons cukup besar (misalnya dalam hal ini, dengan menjalankan SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem tanpa batas baris), respons akan memiliki beberapa gugus, seperti dalam contoh berikut di bawah ini. Perhatikan bahwa menunjukkan hasil yang "...": "..." dihilangkan di sini untuk keringkasan:
{
"manifest": {
"chunks": [
{
"byte_count": 11469280,
"chunk_index": 0,
"row_count": 403354,
"row_offset": 0
},
{
"byte_count": 6282464,
"chunk_index": 1,
"row_count": 220939,
"row_offset": 403354
},
{
"...": "..."
},
{
"byte_count": 6322880,
"chunk_index": 10,
"row_count": 222355,
"row_offset": 3113156
}
],
"format":"ARROW_STREAM",
"schema": {
"column_count": 3,
"columns": [
{
"...": "..."
}
]
},
"total_byte_count": 94845304,
"total_chunk_count": 11,
"total_row_count": 3335511,
"truncated": false
},
"result": {
"external_links": [
{
"byte_count": 11469280,
"chunk_index": 0,
"expiration": "<url-expiration-timestamp>",
"external_link": "<url-to-data-stored-externally>",
"next_chunk_index": 1,
"next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=403354",
"row_count": 403354,
"row_offset": 0
}
]
},
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "SUCCEEDED"
}
}
Untuk mengunduh hasil konten yang disimpan, Anda dapat menjalankan perintah berikut curl , menggunakan URL di external_link objek dan menentukan tempat Anda ingin mengunduh file. Jangan sertakan token Azure Databricks Anda dalam perintah ini:
curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"
Untuk mengunduh potongan tertentu dari hasil konten yang dialirkan, Anda dapat menggunakan salah satu hal berikut:
- Nilai
next_chunk_indexdari payload respons untuk gugus berikutnya (jika ada gugus berikutnya). - Salah satu indeks gugus dari manifes payload respons untuk potongan apa pun yang tersedia jika ada beberapa gugus.
Misalnya, untuk mendapatkan potongan dengan chunk_index dari 10 respons sebelumnya, jalankan perintah berikut:
Databricks cli
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Ganti <profile-name> dengan nama profil konfigurasi Azure Databricks Anda untuk autentikasi.
Curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Catatan
Menjalankan perintah sebelumnya mengembalikan URL SAS baru.
Untuk mengunduh gugus tersimpan, gunakan URL di external_link objek .
Untuk informasi selengkapnya tentang format Apache Arrow, lihat:
Langkah 4: Batalkan eksekusi pernyataan SQL
Jika Anda perlu membatalkan pernyataan SQL yang belum berhasil, jalankan perintah berikut:
Databricks cli
databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'
Ganti <profile-name> dengan nama profil konfigurasi Azure Databricks Anda untuk autentikasi.
Curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"
Praktik terbaik keamanan
API Eksekusi Pernyataan SQL Databricks meningkatkan keamanan transfer data dengan menggunakan enkripsi keamanan lapisan transportasi end-to-end (TLS) dan kredensial berumur pendek seperti token SAS.
Ada beberapa lapisan dalam model keamanan ini. Pada lapisan transportasi, hanya dimungkinkan untuk memanggil Databricks SQL Statement Execution API dengan menggunakan TLS 1.2 atau lebih tinggi. Selain itu, pemanggil Databricks SQL Statement Execution API harus diautentikasi dengan token akses pribadi Azure Databricks yang valid atau token MICROSOFT Entra ID (sebelumnya Azure Active Directory) yang memetakan ke pengguna yang memiliki hak untuk menggunakan Databricks SQL. Pengguna ini harus memiliki akses CAN USE untuk gudang SQL tertentu yang sedang digunakan, dan akses dapat dibatasi dengan daftar akses IP. Ini berlaku untuk semua permintaan ke Api Eksekusi Pernyataan SQL Databricks. Selain itu, untuk menjalankan pernyataan, pengguna yang diautentikasi harus memiliki izin ke objek data (seperti tabel, tampilan, dan fungsi) yang digunakan dalam setiap pernyataan. Ini diberlakukan oleh mekanisme kontrol akses yang ada di Unity Catalog atau dengan menggunakan ACL tabel. (Lihat Tata kelola data dengan Unity Catalog untuk detail selengkapnya.) Ini juga berarti bahwa hanya pengguna yang menjalankan pernyataan yang dapat membuat permintaan pengambilan untuk hasil pernyataan.
Databricks merekomendasikan praktik terbaik keamanan berikut setiap kali Anda menggunakan API Eksekusi Pernyataan SQL Databricks bersama dengan EXTERNAL_LINKS disposisi untuk mengambil himpunan data besar:
- Menghapus header otorisasi Databricks untuk permintaan penyimpanan Azure
- Melindungi URL SAS dan token SAS
Disposisi EXTERNAL_LINKS dapat dinonaktifkan berdasarkan permintaan dengan membuat kasus dukungan. Untuk membuat permintaan ini, hubungi tim akun Azure Databricks Anda untuk membuat kasus dukungan.
Menghapus header otorisasi Databricks untuk permintaan penyimpanan Azure
Semua panggilan ke API Eksekusi Pernyataan SQL Databricks yang digunakan curl harus menyertakan Authorization header yang berisi kredensial akses Azure Databricks. Jangan sertakan header ini Authorization setiap kali Anda mengunduh data dari penyimpanan Azure. Header ini tidak diperlukan dan mungkin secara tidak sengaja mengekspos kredensial akses Azure Databricks Anda.
Melindungi URL SAS dan token SAS
Setiap kali Anda menggunakan disposisi EXTERNAL_LINKS , URL SAS berumur pendek dihasilkan, yang dapat digunakan pemanggil untuk mengunduh hasilnya langsung dari penyimpanan Azure dengan menggunakan TLS. Karena token SAS berumur pendek disematkan dalam URL SAS ini, Anda harus melindungi URL SAS dan token SAS.
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk