Deyim Yürütme API'si: Ambarlarda SQL çalıştırma

Makale
08/29/2024

Ö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 kullanıyorsanız, 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:
  1. 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.
  2. Geliştirici'ye tıklayın.
  3. Erişim belirteçleri'nin yanındaki Yönet'e tıklayın.
  4. Yeni belirteç oluştur'a tıklayın.
  5. (İ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.
  6. Generate (Oluştur) düğmesine tıklayın.
  7. 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ğıdaki konulara bakın:
  - Çalışma alanı için kişisel erişim belirteci kimlik doğrulamasını etkinleştirme veya devre dışı bırakma
  - Kişisel erişim belirteci izinleri
  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 bir DEFAULT yapılandırma profiliniz varsa, bu yordam mevcut DEFAULT yapılandırma profilinizin üzerine yazar.
  
  Zaten bir DEFAULT yapılandırma profiliniz olup olmadığını denetlemek ve varsa bu profilin ayarlarını görüntülemek için Databricks CLI'sini kullanarak komutunu databricks auth env --profile DEFAULTçalıştırın.
  
  dışında DEFAULTbir ada sahip bir yapılandırma profili oluşturmak için, aşağıdaki databricks configure komutta öğesinin --profile DEFAULT bölümünü yapılandırma profili için farklı bir adla değiştirinDEFAULT.
  1. Databricks CLI kullanarak Azure Databricks kişisel erişim belirteci kimlik doğrulamasını kullanan adlı DEFAULT bir Azure Databricks yapılandırma profili oluşturun. Bunu yapmak için aşağıdaki komutu çalıştırın:
```
databricks configure --profile DEFAULT
```
  2. Databricks Konağı istemi için çalışma alanı başına Azure Databricks URL'nizi girin, örneğinhttps://adb-1234567890123456.7.azuredatabricks.net.
  3. 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_ID olduğ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. İsterseniz, bu öğreticinin curl örneklerini HTTPie gibi benzer araçlarla kullanmak için uyarlarsınız.
  
  Bu öğreticinin curl örneklerinde aşağıdakilere dikkat edin:
  - --header "Authorization: Bearer ${DATABRICKS_TOKEN}"yerine bir .netrc dosyası kullanabilirsiniz. Bir .netrc dosya 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.net temsil 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:
  1. 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.
  2. Geliştirici'ye tıklayın.
  3. Erişim belirteçleri'nin yanındaki Yönet'e tıklayın.
  4. Yeni belirteç oluştur'a tıklayın.
  5. (İ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.
  6. Generate (Oluştur) düğmesine tıklayın.
  7. 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ğıdaki konulara bakın:
  - Çalışma alanı için kişisel erişim belirteci kimlik doğrulamasını etkinleştirme veya devre dışı bırakma
  - Kişisel erişim belirteci izinleri
  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 şemadaki tpch tabloyu (veritabanı olarak da bilinir) samples temel 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ızcurl, katalogdaki şemadaki samples tablonun ilk iki satırına ait üç sütunu sorgulamak için belirtilen SQL ambarını lineitem tcph ve belirtilen belirteci kullanır.
Yanıt yükünü geçerli çalışma dizininde adlı sql-execution-response.json bir dosyaya JSON biçiminde kaydeder.
Dosyanın içeriğini sql-execution-response.json yazdı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_LINK ek 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 olarak nullayarlanır.
ve NEXT_CHUNK_INTERNAL_LINK ortam değişkenlerinin SQL_STATEMENT_ID değ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.value name İsteğe bağlı type olarak, belirtilmezse varsayılan değeriyle STRING de 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ında 5 50 olabilir. SQL deyimi kimliğini ve geçerli durumunu hemen döndürmek için olarak 0sayarlayı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ğin 1000.
döndürülen satır sayısını sınırlamak için, öğesine yan LIMIT tümce statementeklemek 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_limit veya row_limittruncated değerinden büyükse, alan yanıt yükünde olarak true ayarlanı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 disposition EXTERNAL_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.

Bir EXTERNAL_LINKS destek olayı oluşturularak istek üzerine değerlendirme devre dışı bırakılabilir.

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_index 10 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, OAuth 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şvurun.

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.

Aracılığıyla paylaş

Deyim Yürütme API'si: Ambarlarda SQL çalıştırma

Başlamadan önce

1. Adım: SQL deyimi yürütme ve veri sonucunu JSON olarak kaydetme

Databricks CLI

Curl

2. Adım: Bir deyimin geçerli yürütme durumunu ve veri sonucunu JSON olarak alma

Databricks CLI

Curl

Databricks CLI

Curl

3. Adım: Dış bağlantıları kullanarak büyük sonuçları getirme

Databricks CLI

Curl

Databricks CLI

Curl

Databricks CLI

Curl

4. Adım: SQL deyiminin yürütülmesini iptal etme

Databricks CLI

Curl

En iyi güvenlik uygulamaları

Azure depolama istekleri için Databricks yetkilendirme üst bilgisini kaldırma

SAS URL'lerini ve SAS belirteçlerini koruma

Geri Bildirim

Ek kaynaklar