Deyim Yürütme API'si: Ambarlarda SQL çalıştırma
Önemli
Databricks REST API’lerine erişmek için kimlik doğrulaması yapmanız gerekir.
Bu öğreticide Databricks SQL ambarlarından SQL deyimlerini çalıştırmak için Databricks SQL Deyimi Yürütme API'sinin 2.0 nasıl kullanılacağı gösterilmektedir.
Databricks SQL Deyimi Yürütme API'si 2.0 başvurusunu görüntülemek için bkz . Deyim Yürütme.
Başlamadan önce
Bu öğreticiye başlamadan önce aşağıdakilere sahip olduğunuzdan emin olun:
Databricks CLI sürüm 0.205 veya üzeri ya da
curlaşağıdaki gibi:Databricks CLI, Databricks REST API isteklerini ve yanıtlarını göndermek ve almak için kullanılan bir komut satırı aracıdır. Databricks CLI sürüm 0.205 veya üzerini kullanmayı seçerseniz, Azure Databricks çalışma alanınızla kimlik doğrulaması için yapılandırılmalıdır. Bkz. Databricks CLI'yı yükleme veya güncelleştirme ve Databricks CLI için Kimlik Doğrulaması.
Örneğin, Databricks kişisel erişim belirteci kimlik doğrulamasıyla kimlik doğrulaması yapmak için aşağıdaki gibi bir kişisel erişim belirteci oluşturun:
- Azure Databricks çalışma alanınızda üst çubukta Azure Databricks kullanıcı adınıza tıklayın ve açılan listeden Ayarlar seçin.
- Geliştirici'ye tıklayın.
- Erişim belirteçleri'nin yanındaki Yönet'e tıklayın.
- Yeni belirteç oluştur'a tıklayın.
- (İsteğe bağlı) Gelecekte bu belirteci tanımlamanıza yardımcı olacak bir açıklama girin ve belirtecin varsayılan 90 günlük ömrünü değiştirin. Yaşam süresi olmayan bir belirteç oluşturmak için (önerilmez), Yaşam Süresi (gün) kutusunu boş (boş) bırakın.
- Generate (Oluştur) düğmesine tıklayın.
- Görüntülenen belirteci güvenli bir konuma kopyalayın ve bitti'ye tıklayın.
Not
Kopyalanan belirteci güvenli bir konuma kaydettiğinizden emin olun. Kopyalanan belirtecinizi başkalarıyla paylaşmayın. Kopyalanan belirteci kaybederseniz, tam olarak aynı belirteci yeniden oluşturamazsınız. Bunun yerine, yeni bir belirteç oluşturmak için bu yordamı yinelemeniz gerekir. Kopyalanan belirteci kaybederseniz veya belirtecin gizliliğinin ihlal edildiğini düşünüyorsanız Databricks, Erişim belirteçleri sayfasındaki belirtecin yanındaki çöp kutusu (İptal Et) simgesine tıklayarak bu belirteci çalışma alanınızdan hemen silmenizi kesinlikle önerir.
Çalışma alanınızda belirteç oluşturamıyor veya kullanamıyorsanız, bunun nedeni çalışma alanı yöneticinizin belirteçleri devre dışı bırakmış olması veya size belirteç oluşturma veya kullanma izni vermemiş olması olabilir. Çalışma alanı yöneticinize veya aşağıdakilere bakın:
Ardından Databricks CLI kullanarak kişisel erişim belirteciniz için bir Azure Databricks yapılandırma profili oluşturmak üzere aşağıdakileri yapın:
Not
Aşağıdaki yordam, adlı
DEFAULTbir Azure Databricks yapılandırma profili oluşturmak için Databricks CLI'sini kullanır. Zaten birDEFAULTyapılandırma profiliniz varsa, bu yordam mevcutDEFAULTyapılandırma profilinizin üzerine yazar.Zaten bir
DEFAULTyapılandırma profiliniz olup olmadığını denetlemek ve varsa bu profilin ayarlarını görüntülemek için Databricks CLI'sini kullanarak komutunudatabricks auth env --profile DEFAULTçalıştırın.dışında
DEFAULTbir ada sahip bir yapılandırma profili oluşturmak için, aşağıdakidatabricks configurekomutta öğesinin--profile DEFAULTbölümünü yapılandırma profili için farklı bir adla değiştirinDEFAULT.Databricks CLI kullanarak Azure Databricks kişisel erişim belirteci kimlik doğrulamasını kullanan adlı
DEFAULTbir Azure Databricks yapılandırma profili oluşturun. Bunu yapmak için aşağıdaki komutu çalıştırın:databricks configure --profile DEFAULTDatabricks Konağı istemi için çalışma alanı başına Azure Databricks URL'nizi girin, örneğin
https://adb-1234567890123456.7.azuredatabricks.net.Kişisel Erişim Belirteci istemi için çalışma alanınız için Azure Databricks kişisel erişim belirtecini girin.
Bu öğreticinin Databricks CLI örneklerinde aşağıdakilere dikkat edin:
- Bu öğreticide, yerel geliştirme makinenizde bir ortam değişkeninin
DATABRICKS_SQL_WAREHOUSE_IDolduğu varsayılır. Bu ortam değişkeni Databricks SQL ambarınızın kimliğini temsil eder. Bu kimlik, ambarınızın HTTP yolu alanında takip/sql/1.0/warehouses/edilen harf ve sayı dizesidir. Ambarınızın HTTP yolu değerini nasıl alacağınızı öğrenmek için bkz . Azure Databricks işlem kaynağı için bağlantı ayrıntılarını alma. - Unix, Linux veya macOS için komut kabuğu yerine Windows Komut kabuğunu kullanıyorsanız,
\^yerine ve yerine ile değiştirin${...}%...%. - Unix, Linux veya macOS için komut kabuğu yerine Windows Komut kabuğunu kullanıyorsanız, JSON belge bildirimlerinde açma ve kapatmayı
'ile"değiştirin ve iç"öğesini ile\"değiştirin.
curl , REST API isteklerini ve yanıtlarını göndermeye ve almaya yönelik bir komut satırı aracıdır. Ayrıca bkz. Curl yükleme. Alternatif olarak, bu öğreticinin
curlörneklerini Postman veya HTTPie gibi benzer araçlarla kullanmak üzere uyarlayabilirsiniz.Bu öğreticinin
curlörneklerinde aşağıdakilere dikkat edin:--header "Authorization: Bearer ${DATABRICKS_TOKEN}"yerine bir .netrc dosyası kullanabilirsiniz. Bir.netrcdosya kullanıyorsanız değerini ile--netrcdeğiştirin--header "Authorization: Bearer ${DATABRICKS_TOKEN}".- Unix, Linux veya macOS için komut kabuğu yerine Windows Komut kabuğunu kullanıyorsanız,
\^yerine ve yerine ile değiştirin${...}%...%. - Unix, Linux veya macOS için komut kabuğu yerine Windows Komut kabuğunu kullanıyorsanız, JSON belge bildirimlerinde açma ve kapatmayı
'ile"değiştirin ve iç"öğesini ile\"değiştirin.
Ayrıca, bu öğreticinin
curlörnekleri için bu öğreticide yerel geliştirme makinenizde aşağıdaki ortam değişkenleri olduğu varsayılır:DATABRICKS_HOST, örneğin Azure Databricks çalışma alanınız için çalışma alanı örneği adınıadb-1234567890123456.7.azuredatabricks.nettemsil eder.DATABRICKS_TOKEN, Azure Databricks çalışma alanı kullanıcınız için bir Azure Databricks kişisel erişim belirtecini temsil eder.DATABRICKS_SQL_WAREHOUSE_ID, Databricks SQL ambarınızın kimliğini temsil eder. Bu kimlik, ambarınızın HTTP yolu alanında takip/sql/1.0/warehouses/edilen harf ve sayı dizesidir. Ambarınızın HTTP yolu değerini nasıl alacağınızı öğrenmek için bkz . Azure Databricks işlem kaynağı için bağlantı ayrıntılarını alma.
Not
En iyi güvenlik uygulaması olarak otomatik araçlar, sistemler, betikler ve uygulamalarla kimlik doğrulaması yaptığınızda Databricks, çalışma alanı kullanıcıları yerine hizmet sorumlularına ait kişisel erişim belirteçlerini kullanmanızı önerir. Hizmet sorumlularına yönelik belirteçler oluşturmak için bkz . Hizmet sorumlusu için belirteçleri yönetme.
Azure Databricks kişisel erişim belirteci oluşturmak için aşağıdakileri yapın:
- Azure Databricks çalışma alanınızda üst çubukta Azure Databricks kullanıcı adınıza tıklayın ve açılan listeden Ayarlar seçin.
- Geliştirici'ye tıklayın.
- Erişim belirteçleri'nin yanındaki Yönet'e tıklayın.
- Yeni belirteç oluştur'a tıklayın.
- (İsteğe bağlı) Gelecekte bu belirteci tanımlamanıza yardımcı olacak bir açıklama girin ve belirtecin varsayılan 90 günlük ömrünü değiştirin. Yaşam süresi olmayan bir belirteç oluşturmak için (önerilmez), Yaşam Süresi (gün) kutusunu boş (boş) bırakın.
- Generate (Oluştur) düğmesine tıklayın.
- Görüntülenen belirteci güvenli bir konuma kopyalayın ve bitti'ye tıklayın.
Not
Kopyalanan belirteci güvenli bir konuma kaydettiğinizden emin olun. Kopyalanan belirtecinizi başkalarıyla paylaşmayın. Kopyalanan belirteci kaybederseniz, tam olarak aynı belirteci yeniden oluşturamazsınız. Bunun yerine, yeni bir belirteç oluşturmak için bu yordamı yinelemeniz gerekir. Kopyalanan belirteci kaybederseniz veya belirtecin gizliliğinin ihlal edildiğini düşünüyorsanız Databricks, Erişim belirteçleri sayfasındaki belirtecin yanındaki çöp kutusu (İptal Et) simgesine tıklayarak bu belirteci çalışma alanınızdan hemen silmenizi kesinlikle önerir.
Çalışma alanınızda belirteç oluşturamıyor veya kullanamıyorsanız, bunun nedeni çalışma alanı yöneticinizin belirteçleri devre dışı bırakmış olması veya size belirteç oluşturma veya kullanma izni vermemiş olması olabilir. Çalışma alanı yöneticinize veya aşağıdakilere bakın:
Uyarı
Databricks, bu hassas bilgiler sürüm denetim sistemleri aracılığıyla düz metin olarak kullanıma sunulduğundan, betiklerinize sabit kodlama bilgilerini kesinlikle önerilmez. Databricks bunun yerine geliştirme makinenizde ayarladığınız ortam değişkenleri gibi yaklaşımları kullanmanızı önerir. Bu tür sabit kodlanmış bilgilerin betiklerinizden kaldırılması, bu betiklerin de daha taşınabilir olmasını sağlar.
Bu öğreticide ayrıca Databricks SQL Deyimi Yürütme API'sine yaptığınız her çağrıdan sonra Databricks SQL Deyimi Yürütme API'sinin size döndürdüğü JSON yanıt yüklerini sorgulamaya yönelik bir komut satırı işlemcisi olan jq'nuz olduğu varsayılır. Bkz. jq'yı indirme.
SQL deyimlerini yürütebileceğiniz en az bir tablonuz olmalıdır. Bu öğretici, katalogdaki
lineitemşemadakitpchtabloyu (veritabanı olarak da bilinir)samplestemel alır. Çalışma alanınızdan bu kataloğa, şemaya veya tabloya erişiminiz yoksa, bu öğretici boyunca bunları kendinizle değiştirin.
1. Adım: SQL deyimi yürütme ve veri sonucunu JSON olarak kaydetme
Aşağıdaki komutu çalıştırarak aşağıdakileri yapın:
- kullanıyorsanız
curl, katalogdaki şemadakisamplestablonun ilk iki satırına ait üç sütunu sorgulamak için belirtilen SQL ambarınılineitemtcphve belirtilen belirteci kullanır. - Yanıt yükünü geçerli çalışma dizininde adlı
sql-execution-response.jsonbir dosyaya JSON biçiminde kaydeder. - Dosyanın içeriğini
sql-execution-response.jsonyazdırır. - adlı
SQL_STATEMENT_IDbir yerel ortam değişkeni ayarlar. Bu değişken, karşılık gelen SQL deyiminin kimliğini içerir. Bu SQL deyimi kimliğini, 2. Adım'da gösterilen bu deyim hakkında daha sonra gerektiği gibi bilgi almak için kullanabilirsiniz. Ayrıca bu SQL deyimini görüntüleyebilir ve deyiminin kimliğini Databricks SQL konsolunun sorgu geçmişi bölümünden veya Sorgu Geçmişi API'sini çağırarak alabilirsiniz. - JSON verilerinin sonraki öbeklerini almak için API URL'si parçası içeren adlı
NEXT_CHUNK_EXTERNAL_LINKek bir yerel ortam değişkeni ayarlar. Yanıt verileri çok büyükse Databricks SQL Deyimi Yürütme API'si yanıtı öbekler halinde sağlar. 2. Adımda gösterilen bir sonraki veri öbeği almak için bu API URL'si parçasını kullanabilirsiniz. Sonraki öbek yoksa, bu ortam değişkeni olaraknullayarlanır. - ve
NEXT_CHUNK_INTERNAL_LINKortam değişkenlerininSQL_STATEMENT_IDdeğerlerini yazdırır.
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
yerine kimlik doğrulaması için Azure Databricks yapılandırma profilinizin adını yazın<profile-name>.
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
Önceki istekte:
Parametreli sorgular, her sorgu parametresinin adından önce dizide eşleşen ve nesnesi olan iki nokta üst üste (örneğin,
:extended_price) oluşurparameters.valuenameİsteğe bağlıtypeolarak, belirtilmezse varsayılan değeriyleSTRINGde belirtilebilir.Uyarı
Databricks, SQL deyimleriniz için en iyi yöntem olarak parametreleri kullanmanızı kesinlikle önerir.
Databricks SQL Deyimi Yürütme API'sini SQL'i dinamik olarak oluşturan bir uygulamayla kullanırsanız bu, SQL ekleme saldırılarına neden olabilir. Örneğin, bir kullanıcının kullanıcı arabirimindeki seçimlerini temel alarak SQL kodu oluşturursanız ve uygun önlemleri almazsanız, saldırgan ilk sorgunuzun mantığını değiştirmek, böylece hassas verileri okumak, değiştirmek veya silmek için kötü amaçlı SQL kodu ekleyebilirsiniz.
Parametreli sorgular, giriş bağımsız değişkenlerini SQL kodunuzun geri kalanından ayrı olarak işleyerek ve bu bağımsız değişkenleri değişmez değer olarak yorumlayarak SQL ekleme saldırılarına karşı korumaya yardımcı olur. Parametreler, kodun yeniden kullanılabilirliğine de yardımcı olur.
Varsayılan olarak, döndürülen tüm veriler JSON dizi biçimindedir ve SQL deyiminin veri sonuçlarından herhangi birinin varsayılan konumu yanıt yükü içindedir. Bu davranışı açıkça ifade etmek için istek yüküne ekleyin
"format":"JSON_ARRAY","disposition":"INLINE". Yanıt yükünde 25 MiB'den büyük veri sonuçları döndürmeye çalışırsanız, hata durumu döndürülür ve SQL deyimi iptal edilir. 25 MiB'tan büyük veri sonuçları için, 3. Adımda gösterilen yanıt yükünde döndürmeye çalışmak yerine dış bağlantıları kullanabilirsiniz.komut, yanıt yükünün içeriğini yerel bir dosyaya depolar. Yerel veri depolama, Databricks SQL Deyimi Yürütme API'sinde doğrudan desteklenmez.
Varsayılan olarak, 10 saniye sonra SQL deyiminin ambar üzerinden yürütülmesi henüz tamamlanmadıysa Databricks SQL Deyimi Yürütme API'si, deyimin sonucu yerine yalnızca SQL deyimi kimliğini ve geçerli durumunu döndürür. Bu davranışı değiştirmek için isteğine ekleyin
"wait_timeout"ve olarak ayarlayın"<x>s"; örneğin<x>,"50s"ile saniyeler arasında550olabilir. SQL deyimi kimliğini ve geçerli durumunu hemen döndürmek için olarak0sayarlayınwait_timeout.Varsayılan olarak, zaman aşımı süresine ulaşılırsa SQL deyimi çalışmaya devam eder. Bunun yerine zaman aşımı süresine ulaşılırsa sql deyimini iptal etmek için istek yüküne ekleyin
"on_wait_timeout":"CANCEL".Döndürülen bayt sayısını sınırlamak için isteğine ekleyin
"byte_limit"ve bayt sayısı olarak ayarlayın, örneğin1000.döndürülen satır sayısını sınırlamak için, öğesine yan
LIMITtümcestatementeklemek yerine isteğine ekleyebilir"row_limit"ve satır sayısına ayarlayabilirsiniz, örneğin"statement":"SELECT * FROM lineitem","row_limit":2.Sonuç belirtilen
byte_limitveyarow_limittruncateddeğerinden büyükse, alan yanıt yükünde olaraktrueayarlanır.
Deyimin sonucu bekleme zaman aşımı sona ermeden kullanılabilir durumdaysa yanıt aşağıdaki gibidir:
{
"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"
}
}
Deyimin sonucu kullanılabilir duruma gelmeden önce bekleme zaman aşımı sona eriyorsa yanıt şu şekilde görünür:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Deyimin sonuç verileri çok büyükse (örneğin, komutunu çalıştırarak SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), sonuç verileri öbeklenmiş ve bunun yerine şöyle görünür. "...": "..." Kısa süre için burada atlanmış sonuçların belirtildiğine dikkat edin:
{
"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"
}
}
2. Adım: Bir deyimin geçerli yürütme durumunu ve veri sonucunu JSON olarak alma
Bir SQL deyiminin kimliğini kullanarak bu deyimin geçerli yürütme durumunu ve yürütme başarılı olursa bu deyimin sonucunu alabilirsiniz. Deyimin kimliğini unutursanız, bunu Databricks SQL konsolunun sorgu geçmişi bölümünden veya Sorgu Geçmişi API'sini çağırarak alabilirsiniz. Örneğin, bu komutu yoklamayı sürdürebilir ve her seferinde yürütmenin başarılı olup olmadığını kontrol edebilirsiniz.
Bir SQL deyiminin geçerli yürütme durumunu almak ve yürütme başarılı olursa bu deyimin sonucu ve JSON verilerinin sonraki öbeklerini almak için bir API URL parçası almak için aşağıdaki komutu çalıştırın. Bu komut, yerel geliştirme makinenizde adlı SQL_STATEMENT_IDbir ortam değişkeniniz olduğunu varsayar. Bu değişken, önceki adımdaki SQL deyiminin kimliğinin değerine ayarlanır. Elbette, aşağıdaki komutta SQL deyiminin sabit kodlanmış kimliğiyle değiştirebilirsiniz ${SQL_STATEMENT_ID} .
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
yerine kimlik doğrulaması için Azure Databricks yapılandırma profilinizin adını yazın<profile-name>.
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 değeri olmayannull bir değere ayarlanırsa, bir sonraki veri öbeklerini almak için bunu kullanabilirsiniz, örneğin aşağıdaki komutla:
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
yerine kimlik doğrulaması için Azure Databricks yapılandırma profilinizin adını yazın<profile-name>.
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
Sonraki öbekleri almak için önceki komutu tekrar tekrar çalıştırmaya devam edebilirsiniz. Son öbek getirildiğinde SQL deyiminin kapatıldığını unutmayın. Bu kapatmadan sonra, geçerli durumunu almak veya daha fazla öbek getirmek için bu deyimin kimliğini kullanamazsınız.
3. Adım: Dış bağlantıları kullanarak büyük sonuçları getirme
Bu bölümde, büyük veri kümelerini almak için değerlendirmeyi EXTERNAL_LINKS kullanan isteğe bağlı bir yapılandırma gösterilmektedir. SQL deyimi sonuç verilerinin varsayılan konumu (bırakma) yanıt yükü içindedir, ancak bu sonuçlar 25 MiB ile sınırlıdır. olarak ayarlayarak dispositionEXTERNAL_LINKSyanıt, standart HTTP ile sonuç verilerinin öbeklerini getirmek için kullanabileceğiniz URL'leri içerir. URL'ler, sonuç öbeklerinin geçici olarak depolandığı çalışma alanınızın iç DBFS'sine işaret eder.
Uyarı
Databricks, değerlendirme tarafından EXTERNAL_LINKS döndürülen URL'leri ve belirteçleri korumanızı kesinlikle önerir.
Değerlendirmeyi EXTERNAL_LINKS kullandığınızda, sonuçları doğrudan Azure depolama alanından indirmek için kullanılabilecek bir paylaşılan erişim imzası (SAS) URL'si oluşturulur. Bu SAS URL'sine kısa süreli bir SAS belirteci eklendiğinden hem SAS URL'sini hem de SAS belirtecini korumanız gerekir.
SAS URL'leri eklenmiş geçici SAS belirteçleriyle zaten oluşturulduğundan, indirme isteklerinde üst Authorization bilgi ayarlamamalısınız.
Değerlendirme EXTERNAL_LINKS , istek üzerine devre dışı bırakılabilir. Bu isteği göndermek için bir destek olayı oluşturun.
Ayrıca bkz. En iyi güvenlik yöntemleri.
Not
Yanıt yükü çıkış biçimi ve davranışı, belirli bir SQL deyimi kimliği için ayarlandıktan sonra değiştirilemez.
Bu modda API, sonuç verilerini HTTP ile ayrı olarak sorgulanması gereken JSON biçiminde (JSON), CSV biçiminde (CSV) veya Apache Ok biçiminde (ARROW_STREAM ) depolamanıza olanak tanır. Ayrıca, bu modu kullanırken, sonuç verilerini yanıt yükü içinde satır içine almak mümkün değildir.
Aşağıdaki komut, ve Apache Ok biçiminin kullanılmasını EXTERNAL_LINKS gösterir. 1. Adımda belirtilen benzer sorgu yerine bu deseni kullanın:
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
yerine kimlik doğrulaması için Azure Databricks yapılandırma profilinizin adını yazın<profile-name>.
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
Yanıt aşağıdaki gibidir:
{
"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"
}
}
İstek zaman aşımına uğradıysa yanıt şu şekilde görünür:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Bu deyimin geçerli yürütme durumunu almak ve yürütme başarılı olursa bu deyimin sonucunu almak için aşağıdaki komutu çalıştırın:
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'
yerine kimlik doğrulaması için Azure Databricks yapılandırma profilinizin adını yazın<profile-name>.
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'
Yanıt yeterince büyükse (örneğin, satır sınırı olmadan çalıştırarak SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem ), aşağıdaki örnekte olduğu gibi yanıtın birden çok öbekleri olur. "...": "..." Kısa süre için burada atlanmış sonuçların belirtildiğine dikkat edin:
{
"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"
}
}
Depolanan içeriğin sonuçlarını indirmek için, nesnedeki URL'yi external_link kullanarak ve dosyayı indirmek istediğiniz yeri belirterek aşağıdaki curl komutu çalıştırabilirsiniz. Bu komuta Azure Databricks belirtecinizi eklemeyin:
curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"
Akışa alınan içeriğin sonuçlarının belirli bir öbeklerini indirmek için aşağıdakilerden birini kullanabilirsiniz:
- Sonraki
next_chunk_indexöbek için yanıt yükündeki değer (bir sonraki öbek varsa). - Birden çok öbek varsa, kullanılabilir öbekler için yanıt yükünün bildirimindeki öbek dizinlerinden biri.
Örneğin, önceki yanıttan bir chunk_index10 ile öbek almak için aşağıdaki komutu çalıştırın:
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'
yerine kimlik doğrulaması için Azure Databricks yapılandırma profilinizin adını yazın<profile-name>.
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'
Not
Önceki komutu çalıştırmak yeni bir SAS URL'si döndürür.
Depolanan öbekleri indirmek için nesnesindeki URL'yi external_link kullanın.
Apache Ok biçimi hakkında daha fazla bilgi için bkz:
4. Adım: SQL deyiminin yürütülmesini iptal etme
Henüz başarılı olmayan bir SQL deyimini iptal etmeniz gerekiyorsa aşağıdaki komutu çalıştırın:
Databricks cli
databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'
yerine kimlik doğrulaması için Azure Databricks yapılandırma profilinizin adını yazın<profile-name>.
Curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"
En iyi güvenlik uygulamaları
Databricks SQL Deyimi Yürütme API'si, uçtan uca aktarım katmanı güvenliği (TLS) şifrelemesini ve SAS belirteçleri gibi kısa süreli kimlik bilgilerini kullanarak veri aktarımlarının güvenliğini artırır.
Bu güvenlik modelinde birkaç katman vardır. Aktarım katmanında, yalnızca TLS 1.2 veya üzerini kullanarak Databricks SQL Deyimi Yürütme API'sini çağırmak mümkündür. Ayrıca Databricks SQL Deyimi Yürütme API'sini çağıranların, Databricks SQL kullanma yetkisine sahip bir kullanıcıyla eşlenen geçerli bir Azure Databricks kişisel erişim belirteci veya Microsoft Entra Kimliği (eski adıYla Azure Active Directory) belirteci ile kimlik doğrulaması yapılması gerekir. Bu kullanıcı, kullanılmakta olan belirli SQL ambarı için CAN USE erişimine sahip olmalıdır ve erişim IP erişim listeleriyle kısıtlanabilir. Bu, Databricks SQL Deyimi Yürütme API'sine yönelik tüm istekler için geçerlidir. Ayrıca, deyimleri yürütmek için kimliği doğrulanmış kullanıcının her deyimde kullanılan veri nesneleri (tablolar, görünümler ve işlevler gibi) için izni olmalıdır. Bu, Unity Kataloğu'ndaki mevcut erişim denetimi mekanizmaları veya tablo ACL'leri kullanılarak uygulanır. (Bkz. Daha fazla ayrıntı için Unity Kataloğu ile veri idaresi.) Bu aynı zamanda yalnızca bir deyimi yürüten kullanıcının deyiminin sonuçları için getirme isteklerinde bulunabileceği anlamına gelir.
Databricks, büyük veri kümelerini almak için edat ile birlikte Databricks SQL Deyimi Yürütme API'sini EXTERNAL_LINKS her kullandığınızda aşağıdaki en iyi güvenlik uygulamalarını önerir:
- Azure depolama istekleri için Databricks yetkilendirme üst bilgisini kaldırma
- SAS URL'lerini ve SAS belirteçlerini koruma
Bir EXTERNAL_LINKS destek olayı oluşturularak istek üzerine değerlendirme devre dışı bırakılabilir. Bu isteği göndermek için Azure Databricks hesap ekibinize başvurarak bir destek olayı oluşturun.
Azure depolama istekleri için Databricks yetkilendirme üst bilgisini kaldırma
Databricks SQL Deyimi Yürütme API'sine yapılan ve kullanan curl tüm çağrıların Azure Databricks erişim kimlik bilgilerini içeren bir Authorization üst bilgi içermesi gerekir. Azure depolama alanından her veri indirdiğinizde bu Authorization üst bilgiyi eklemeyin. Bu üst bilgi gerekli değildir ve istemeden Azure Databricks erişim kimlik bilgilerinizi kullanıma verebilir.
SAS URL'lerini ve SAS belirteçlerini koruma
Değerlendirmeyi EXTERNAL_LINKS her kullandığınızda, çağıranın sonuçları doğrudan Azure depolamadan TLS kullanarak indirmek için kullanabileceği kısa süreli bir SAS URL'si oluşturulur. Bu SAS URL'sine kısa süreli bir SAS belirteci eklendiğinden hem SAS URL'sini hem de SAS belirtecini korumanız gerekir.
Geri Bildirim
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz. https://aka.ms/ContentUserFeedback.
Gönderin ve geri bildirimi görüntüleyin