Aracılığıyla paylaş

Sorgu Yürütme API'si: Veri Ambarlarında 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 referansını 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 curl kullanarak aş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'te kişisel erişim belirteciyle kimlik doğrulaması yapmak için çalışma alanı kullanıcıları için kişisel erişim belirteçleri oluşturma adımlarını 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, Databricks CLI'yi kullanarak adı olan bir Azure Databricks yapılandırma profili oluşturmak için kullanılı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.

      DEFAULT dışında bir ada sahip bir yapılandırma profili oluşturmak için, aşağıdaki DEFAULT komutunda --profile DEFAULT kısmını yapılandırma profili için farklı bir adla değiştirindatabricks configure.

      1. Databricks CLI kullanarak, olarak adlandırılan ve Azure Databricks kişisel erişim belirteci kimlik doğrulamasını kullanan bir Azure Databricks DEFAULT oluşturun. Bunu yapmak için aşağıdaki komutu çalıştırın:

        databricks configure --profile DEFAULT

      2. Databricks Ana Bilgisayar istemi için Azure Databricks çalışma alanı başına URL'nizi girin, örneğin .

      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 /sql/1.0/warehouses/ alanındaki sonrasındaki 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.
      • Windows Komut kabuğunu, Unix, Linux veya macOS komut kabuğu yerine kullanıyorsanız, \'yi ^ ile ve ${...}'yi %...% 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çılış ve kapanış ' etiketlerini " ile ve içteki " etiketini \" 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ükle. İsterseniz, bu öğreticideki curl örnekleri HTTPie gibi benzer araçlarla kullanabilirsiniz.

      Bu öğreticinin curl örneklerinde aşağıdakilere dikkat edin:

      • --header "Authorization: Bearer ${DATABRICKS_TOKEN}"yerine bir .netrc dosyası kullanabilirsiniz. Eğer bir .netrc dosyası kullanıyorsanız, --header "Authorization: Bearer ${DATABRICKS_TOKEN}"'i --netrc ile değiştirin.
      • Windows Komut kabuğunu, Unix, Linux veya macOS komut kabuğu yerine kullanıyorsanız, \'yi ^ ile ve ${...}'yi %...% 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çılış ve kapanış ' etiketlerini " ile ve içteki " etiketini \" 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, Azure Databricks çalışma alanınız için, örneğ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 /sql/1.0/warehouses/ alanındaki sonrasındaki 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 jetonu oluşturmak için çalışma alanı kullanıcıları için kişisel erişim jetonları oluşturma bölümünde yer alan adımları izleyin.

      Uyarı

      Databricks, hassas bilgilerin sürüm denetim sistemleri aracılığıyla düz metin olarak açığa çıkabileceği için, bilgilerin betiklerinize sabit kodlanmasını şiddetle önermez. 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, lineitem kataloğundaki tpch şemasındaki (veritabanı olarak da bilinir) samples 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, lineitem kataloğundaki tcph şemasındaki samples 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. sql-execution-response.json dosyasının içeriğini 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 Komut Satırı Arayüzü (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.

Kıvrım

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 iki nokta üst üste (örneğin, :extended_price) ve name, value nesnesiyle parameters dizisinde eşleşecek şekilde oluşur. İ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. SQL deyimini zaman aşımı süresine ulaşıldığında iptal etmek için, istek yüküne "on_wait_timeout":"CANCEL" ekleyin.

  • 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, LIMIT'e statement 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"
  }
}

İfadenin sonucu hazır olmadan önce bekleme zaman aşımı sonlanıyorsa, yanıt aşağıdaki gibi olur:

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

Eğer deyimin sonuç verileri çok büyükse (örneğin, SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000 komutunu çalıştırarak), sonuç verileri öbeklenir ve bunun yerine bö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 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, ${SQL_STATEMENT_ID} ifadesini aşağıdaki komutta SQL deyiminin sabit kodlanmış kimliğiyle değiştirebilirsiniz.

Databricks Komut Satırı Arayüzü (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.

Kıvrım

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 Komut Satırı Arayüzü (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.

Kıvrım

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 kapatma işleminden sonra, mevcut durumunu sorgulamak veya daha fazla parça getirmek için bu deyimin kimliğini kullanamazsınız.

Bu bölümde, EXTERNAL_LINKS dispozisyonunu kullanarak büyük veri kümelerini almak için 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. disposition değerini EXTERNAL_LINKS olarak ayarlayarak, yanıt standart HTTP ile sonuç verilerinin parçalarını almak 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, EXTERNAL_LINKS durumunun döndüreceği URL'leri ve belirteçleri korumanızı şiddetle tavsiye eder.

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 ekli geçici SAS belirteçleriyle zaten oluşturulduğundan, indirme isteklerinde bir Authorization üst bilgisi ayarlamamalısınız.

EXTERNAL_LINKS düzenlemesinin devre dışı bırakılması, istek üzerine bir destek talebi oluşturularak yapı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, EXTERNAL_LINKS ve Apache Ok biçiminin kullanımını gösterir. 1. Adımda belirtilen benzer sorgu yerine bu deseni kullanın:

Databricks Komut Satırı Arayüzü (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.

Kıvrım

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 Komut Satırı Arayüzü (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.

Kıvrım

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, nesnedeki URL'yi curl kullanarak ve dosyayı indirmek istediğiniz yeri belirterek aşağıdaki external_link 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:

  • Sıradaki next_chunk_index öbek için yanıt yükünden alınan değer (eğer sıradaki öbek varsa).
  • Birden fazla öbek varsa, herhangi bir kullanılabilir öbeğin yanıt yükü bildirimindeki öbek indekslerinden biri.

Örneğin, önceki yanıttan chunk_index değeri 10 olan parçayı almak için aşağıdaki komutu çalıştırın:

Databricks Komut Satırı Arayüzü (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.

Kıvrım

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 Komut Satırı Arayüzü (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.

Kıvrım

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 bkz. Azure Databricks 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 EXTERNAL_LINKS parametresiyle birlikte Databricks SQL Deyimi Yürütme API'sini 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

EXTERNAL_LINKS düzenlemesinin devre dışı bırakılması, istek üzerine bir destek talebi oluşturularak yapı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

EXTERNAL_LINKS yapılandırmasını her kullandığınızda, çağıranın sonuçları doğrudan Azure depolamadan TLS kullanarak indirebileceğ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.

  • Last updated on