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

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ükleme veya güncelleştirme ve Databricks CLI Kimlik Doğrulaması.

    Örneğin, Databricks kişisel erişim belirteci kimlik doğrulamasıyla kimlik doğrulaması yapmak için çalışma alanı kullanıcıları için Azure Databricks kişisel erişim belirteçleri'ndeki adımları izleyin.

    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, 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 DEFAULT komutta öğesinin --profile DEFAULT bölümünü yapılandırma profili için farklı bir adla değiştirindatabricks configure.

    1. Databricks CLI kullanarak oluşturun. Bunu yapmak için aşağıdaki komutu çalıştırın:

       databricks configure --profile DEFAULT
       

    2. Databricks Konağı istemi

    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 --header "Authorization: Bearer ${DATABRICKS_TOKEN}"değiştirin--netrc.
    • 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ı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, çalışma alanı kullanıcıları için Azure Databricks kişisel erişim belirteçlerindeki staps değerlerini izleyin.

    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, samples kataloğundaki tpch şemasındaki (veritabanı olarak da bilinir) lineitem tablosunu temel alır. Çalışma alanınızdan bu kataloğa, şemaya veya tabloya erişiminiz yoksa, bu öğretici boyunca bunları kendi kataloğunuz, şemanız veya tablonuzla 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:

1. curlkullanıyorsanız, samples kataloğundaki tcph şemasındaki lineitem tablosunun ilk iki satırının üç sütununu sorgulamak için belirtilen SQL ambarını ve belirtilen belirteci kullanır.
2. Yanıt yükünü geçerli çalışma dizininde adlı sql-execution-response.json bir dosyaya JSON biçiminde kaydeder.
3. Dosyanın içeriğini sql-execution-response.json yazdırır.
4. 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 databricks SQL konsolunun sorgu geçmişi bölümünden veyaSorgu Geçmişi API'sini çağırarak deyim kimliğini alabilirsiniz.
5. 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 nullolarak ayarlanır.
6. SQL_STATEMENT_ID ve NEXT_CHUNK_INTERNAL_LINK ortam değişkenlerinin 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 <profile-name> adını yazın.

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şurname.valueparameters İ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ğe "wait_timeout" ekleyin ve "<x>s"olarak ayarlayın; burada <x>5 ile 50 saniye arasında (örneğin "50s") olabilir. SQL deyimi kimliğini ve geçerli durumunu hemen döndürmek için wait_timeout0solarak ayarlayın.

• 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ğe "byte_limit" ekleyin ve bayt sayısına ayarlayın, örneğin 1000.

• Döndürülen satır sayısını sınırlamak için, statement'e LIMIT yan tümcesi eklemek yerine isteğe "row_limit" ekleyebilir ve bunu satır sayısına, örneğin "statement":"SELECT * FROM lineitem","row_limit":2olarak ayarlayabilirsiniz.

• Sonuç belirtilen byte_limit veya row_limit'den büyükse, truncated alanı yanıt yükünde true olarak 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 veyaSorgu 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 SQL_STATEMENT_IDadlı bir ortam değişkeniniz olduğunu varsayar ve bu değişken önceki adımdaki SQL deyiminin kimliği 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 <profile-name> adını yazın.

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 null olmayan bir değere ayarlanırsa, 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 <profile-name> adını yazın.

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 parça getirmek için bu ifadenin 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.

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 <profile-name> adını yazın.

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 <profile-name> adını yazın.

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, bu örnekte satır sınırı olmayan SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem çalıştırarak), 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, external_link nesnesindeki URL'yi kullanarak ve dosyayı indirmek istediğiniz yeri belirterek aşağıdaki curl komutunu ç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 10 değeri chunk_index olan parçayı 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 <profile-name> adını yazın.

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'

Depolanan öbekleri indirmek için nesnesindeki URL'yi external_link kullanın.

Apache Ok biçimi hakkında daha fazla bilgi için bkz:

• IPC Akış Biçimi
• Yazma ve Okuma Akışı Biçimi
• Akışları kullanma

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 <profile-name> adını yazın.

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. (Daha fazla ayrıntı için Unity Kataloğu ile Veri Yönetimi bölümündeki kısmına bakın.) Bu aynı zamanda yalnızca bir deyimi yürüten kullanıcının, deyiminin sonuçları için istek yapabileceğ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

curl kullanan Databricks SQL Deyimi Yürütme API'sine yapılan tüm çağrılar, Azure Databricks erişim kimlik bilgilerini içeren bir Authorization üst bilgisi içermelidir. Azure depolama alanından her veri indirdiğinizde bu Authorization üst bilgiyi eklemeyin. Bu başlık gerekli değildir ve istemeden Azure Databricks erişim kimlik bilgilerinizi açığa çıkarabilir.

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.