語句執行 API：在倉儲上執行 SQL

發行項
05/14/2024

重要

若要存取 Databricks REST API，您必須驗證。

本教學課程說明如何使用 Databricks SQL 語句執行 API 2.0，從 Databricks SQL 倉儲執行 SQL 語句。

若要檢視 Databricks SQL 語句執行 API 2.0 參考，請參閱語句執行。

開始之前

開始本教學課程之前，請確定您有：

Databricks CLI 0.205 版或更新版本或 curl，如下所示：
- Databricks CLI 是用來傳送和接收 Databricks REST API 要求和回應的命令行工具。如果您選擇使用 Databricks CLI 0.205 版或更新版本，則必須設定它以向 Azure Databricks 工作區進行驗證。請參閱安裝或更新 Databricks CLI 和 Databricks CLI 的驗證。
  
  例如，若要使用 Databricks 個人存取令牌驗證進行驗證，請建立個人存取令牌，如下所示：
  1. 在 Azure Databricks 工作區中，按兩下頂端列中的 Azure Databricks 使用者名稱，然後從下拉式清單中選取 [設定]。
  2. 按兩下 [ 開發人員]。
  3. 按兩下 [存取令牌] 旁的 [管理]。
  4. 按兩下 [ 產生新的令牌]。
  5. （選擇性）輸入批注，協助您在未來識別此令牌，並變更令牌的預設存留期 90 天。若要建立沒有存留期的令牌（不建議），請將 [ 存留期（天）] 方塊保留空白（空白）。
  6. 按一下 [產生]。
  7. 將顯示的令牌複製到安全的位置，然後按兩下 [ 完成]。
  注意
  
  請務必將複製的令牌儲存在安全的位置。請勿與其他人共享複製的令牌。如果您遺失複製的令牌，就無法重新產生完全相同的令牌。相反地，您必須重複此程式來建立新的令牌。如果您遺失複製的令牌，或您認為令牌已遭入侵，Databricks 強烈建議您按兩下存取令牌頁面上令牌旁邊的垃圾桶（Revoke）圖示，立即從工作區中刪除該令牌。
  
  如果您無法在工作區中建立或使用令牌，這可能是因為您的工作區系統管理員已停用令牌，或未授與您建立或使用令牌的許可權。請參閱您的工作區管理員或下列專案：
  - 啟用或停用工作區的個人存取令牌驗證
  - 個人存取令牌許可權
  然後使用 Databricks CLI 建立個人存取令牌的 Azure Databricks 組態配置檔，請執行下列動作：
  
  注意
  
  下列程式會使用 Databricks CLI 來建立名稱為 DEFAULT的 Azure Databricks 組態配置檔。如果您已經有組 DEFAULT 態配置檔，此程式會覆寫現有的 DEFAULT 組態配置檔。
  
  若要檢查您是否已經有組 DEFAULT 態設定檔，以及若要檢視此設定檔的設定是否存在，請使用 Databricks CLI 來執行命令 databricks auth env --profile DEFAULT。
  
  若要使用以外的DEFAULT名稱建立組態配置檔，請將下列databricks configure命令中的部分--profile DEFAULT取代DEFAULT為組態配置檔的不同名稱。
  1. 使用 Databricks CLI 建立名為 DEFAULT 的 Azure Databricks 組態配置檔，該配置檔會使用 Azure Databricks 個人存取令牌驗證。若要這樣做，請執行下列命令：
```
databricks configure --profile DEFAULT
```
  2. 如需提示 Databricks Host，請輸入您的 Azure Databricks 個別工作區 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
  3. 針對提示 個人存取令牌，輸入工作區的 Azure Databricks 個人存取令牌。
  在本教學課程的 Databricks CLI 範例中，請注意下列事項：
  - 本教學課程假設您在本機開發計算機上有環境變數 DATABRICKS_SQL_WAREHOUSE_ID 。此環境變數代表 Databricks SQL 倉儲的標識碼。此識別元是倉儲 HTTP 路徑欄位中的/sql/1.0/warehouses/字母和數位字串。若要瞭解如何取得倉儲的 HTTP 路徑 值，請參閱取得 Azure Databricks 計算資源的連線詳細數據。
  - 如果您使用 Windows 命令殼層，而不是 Unix、Linux 或 macOS 的命令殼層，請將取代為，並以取代 \${...}%...%。^
  - 如果您在 JSON 檔宣告中使用 Windows 命令殼層，而不是 Unix、Linux 或 macOS 的命令殼層，請將開頭和結尾'取代為 "\"，並以取代內部 " 。
- curl 是用來傳送和接收 REST API 要求和回應的命令行工具。另請參閱安裝 curl。或者，您可以調整本教學課程的curl範例，以搭配Postman或 HTTPie等類似工具使用。
  
  在本教學課程的範例中 curl ，請注意下列事項：
  - --header "Authorization: Bearer ${DATABRICKS_TOKEN}"您可以使用 .netrc 檔案，而不是。如果您使用檔案 .netrc ，請將取代 --header "Authorization: Bearer ${DATABRICKS_TOKEN}" 為 --netrc。
  - 如果您使用 Windows 命令殼層，而不是 Unix、Linux 或 macOS 的命令殼層，請將取代為，並以取代 \${...}%...%。^
  - 如果您在 JSON 檔宣告中使用 Windows 命令殼層，而不是 Unix、Linux 或 macOS 的命令殼層，請將開頭和結尾'取代為 "\"，並以取代內部 " 。
  此外，針對本教學課程的 curl 範例，本教學課程假設您在本機開發計算機上有下列環境變數：
  - DATABRICKS_HOST，代表 Azure Databricks 工作區的工作區實例名稱，例如 adb-1234567890123456.7.azuredatabricks.net。
  - DATABRICKS_TOKEN，代表 Azure Databricks 工作區使用者的 Azure Databricks 個人存取令牌。
  - DATABRICKS_SQL_WAREHOUSE_ID，表示 Databricks SQL 倉儲的標識符。此識別元是倉儲 HTTP 路徑欄位中的/sql/1.0/warehouses/字母和數位字串。若要瞭解如何取得倉儲的 HTTP 路徑 值，請參閱取得 Azure Databricks 計算資源的連線詳細數據。
  注意
  
  作為安全性最佳做法，當您使用自動化工具、系統、腳本和應用程式進行驗證時，Databricks 建議您使用屬於服務主體的個人存取令牌，而不是工作區使用者。若要建立服務主體的令牌，請參閱管理服務主體的令牌。
  
  若要建立 Azure Databricks 個人存取令牌，請執行下列動作：
  1. 在 Azure Databricks 工作區中，按兩下頂端列中的 Azure Databricks 使用者名稱，然後從下拉式清單中選取 [設定]。
  2. 按兩下 [ 開發人員]。
  3. 按兩下 [存取令牌] 旁的 [管理]。
  4. 按兩下 [ 產生新的令牌]。
  5. （選擇性）輸入批注，協助您在未來識別此令牌，並變更令牌的預設存留期 90 天。若要建立沒有存留期的令牌（不建議），請將 [ 存留期（天）] 方塊保留空白（空白）。
  6. 按一下 [產生]。
  7. 將顯示的令牌複製到安全的位置，然後按兩下 [ 完成]。
  注意
  
  請務必將複製的令牌儲存在安全的位置。請勿與其他人共享複製的令牌。如果您遺失複製的令牌，就無法重新產生完全相同的令牌。相反地，您必須重複此程式來建立新的令牌。如果您遺失複製的令牌，或您認為令牌已遭入侵，Databricks 強烈建議您按兩下存取令牌頁面上令牌旁邊的垃圾桶（Revoke）圖示，立即從工作區中刪除該令牌。
  
  如果您無法在工作區中建立或使用令牌，這可能是因為您的工作區系統管理員已停用令牌，或未授與您建立或使用令牌的許可權。請參閱您的工作區管理員或下列專案：
  - 啟用或停用工作區的個人存取令牌驗證
  - 個人存取令牌許可權
  警告
  
  Databricks 強烈禁止將硬式編碼資訊寫入腳本，因為此敏感性資訊可以透過版本控制系統以純文本公開。 Databricks 建議您改用您在開發電腦上設定的環境變數等方法。從腳本中移除這類硬式編碼資訊，也有助於讓這些腳本更容易移植。
本教學課程假設您也有用來查詢 JSON 回應承載的命令行處理器 jq，Databricks SQL 語句執行 API 會在每次呼叫 Databricks SQL 語句執行 API 之後傳回您。請參閱下載 jq。
您必須至少有一個數據表，才能執行 SQL 語句。本教學課程是以lineitem目錄內的samples架構數據表tpch（也稱為資料庫）為基礎。如果您無法從工作區存取此目錄、架構或數據表，請在整個教學課程中以您自己的方式取代它們。

步驟 1：執行 SQL 語句，並將數據結果儲存為 JSON

執行下列命令，執行下列動作：

如果您使用，請使用指定的 SQL 倉儲，以及指定的curl權杖，從目錄內samples架構中tcph資料表的前兩個資料列lineitem查詢三個資料行。
將響應承載以 JSON 格式儲存在目前工作目錄中名為 sql-execution-response.json 的檔案中。
列印檔案的內容 sql-execution-response.json 。
設定名為 SQL_STATEMENT_ID的本機環境變數。此變數包含對應 SQL 語句的識別碼。您可以視需要使用此 SQL 語句識別符來取得該語句的相關信息，如步驟 2 所示。您也可以檢視此 SQL 語句，並從 Databricks SQL 控制台的查詢歷程記錄區段，或藉由呼叫查詢歷程記錄 API 來取得其語句標識符。
設定名為 NEXT_CHUNK_EXTERNAL_LINK 的其他本機環境變數，其中包含用於取得下一個 JSON 數據的 API URL 片段。如果響應數據太大，Databricks SQL 語句執行 API 會以區塊方式提供回應。您可以使用此 API URL 片段來取得下一個數據區塊，如步驟 2 所示。如果沒有下一個區塊，則此環境變數會設定為 null。
列印和 NEXT_CHUNK_INTERNAL_LINK 環境變數的值SQL_STATEMENT_ID。

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

將取代 <profile-name> 為您的 Azure Databricks 組態配置檔名稱以進行驗證。

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

在上述要求中：

參數化查詢包含每個查詢參數的名稱前面加上冒號（例如，:extended_price），陣列中有parameters相符name的和 value 物件。您也可以指定選擇性 type 的，如果未指定，則預設值 STRING 為。

警告

Databricks 強烈建議您使用參數作為 SQL 語句的最佳做法。

如果您使用 Databricks SQL 語句執行 API 搭配以動態方式產生 SQL 的應用程式，這可能會導致 SQL 插入式攻擊。例如，如果您根據使用者介面中的選取專案產生 SQL 程式代碼，但未採取適當措施，攻擊者可能會插入惡意 SQL 程式代碼來變更初始查詢的邏輯，藉此讀取、變更或刪除敏感數據。

參數化查詢可協助防止 SQL 插入式攻擊，方法是將輸入自變數與 SQL 程式代碼的其餘部分分開處理，並將這些自變數解譯為常值。參數也可協助重複使用程序代碼。
根據預設，任何傳回的數據都是 JSON 數位格式，而且任何 SQL 語句數據結果的預設位置都位於響應承載內。若要明確執行此行為，請將新增 "format":"JSON_ARRAY","disposition":"INLINE" 至要求承載。如果您嘗試傳回響應承載中大於 25 MiB 的數據結果，則會傳回失敗狀態，並取消 SQL 語句。對於大於 25 MiB 的數據結果，您可以使用外部連結，而不是嘗試在響應承載中傳回它，如步驟 3 所示。
命令會將響應承載的內容儲存至本機檔案。 Databricks SQL 語句執行 API 不支援本機數據記憶體。
根據預設，在 10 秒之後，如果 SQL 語句尚未透過倉儲完成執行，Databricks SQL 語句執行 API 只會傳回 SQL 語句識別符及其目前狀態，而不是語句的結果。若要變更此行為，請將新增"wait_timeout"至要求，並將它設定為 "<x>s"，其中 <x> 可以介於和 50 秒之間5，例如 "50s"。若要立即傳回 SQL 語句識別元及其目前狀態，請將設定 wait_timeout 為 0s。
根據預設，如果達到逾時期限，SQL 語句會繼續執行。若要改為取消 SQL 語句，如果達到逾時期限，請將新增 "on_wait_timeout":"CANCEL" 至要求承載。
若要限制傳回的位元組數目，請將新增 "byte_limit" 至要求，並將它設定為位元元數目，例如 1000。
若要限制傳回的數據列數目，而不是將子句加入 LIMIT 至 statement，您可以將它新增 "row_limit" 至要求，並將它設定為資料列數目，例如 "statement":"SELECT * FROM lineitem","row_limit":2。
如果結果大於指定的 byte_limit 或，則會truncated在響應承載中將欄位設定truerow_limit為。

如果語句的結果在等候逾時結束之前可用，回應如下所示：

{
  "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"
  }
}

如果等候逾時會在語句的結果可用之前結束，回應會改為如下所示：

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

如果語句的結果數據太大（例如，在此案例中為藉由執行 SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000），結果數據會進行區塊化，並改為看起來像這樣。請注意， "...": "..." 這裡指出省略的結果，以求簡潔：

{
  "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：取得語句的目前執行狀態和數據結果作為 JSON

您可以使用 SQL 語句的標識碼來取得該語句的目前執行狀態，以及如果執行成功，該語句的結果。如果您忘記語句的標識碼，您可以從 Databricks SQL 控制台的查詢歷程記錄區段，或呼叫查詢歷程記錄 API 來取得它。例如，您可以持續輪詢此命令，每次檢查執行是否成功。

若要取得 SQL 語句的目前執行狀態，而且如果執行成功，該語句的結果和 API URL 片段可取得任何下一個 JSON 數據區塊，請執行下列命令。此命令假設您在名為 SQL_STATEMENT_ID的本機開發電腦上有環境變數，其設定為上一個步驟中 SQL 語句的標識碼值。當然，您可以使用 SQL 語句的硬式編碼識別碼取代 ${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

將取代 <profile-name> 為您的 Azure Databricks 組態配置檔名稱以進行驗證。

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值，您可以使用它來取得下一個資料區塊，例如使用下列命令：

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

將取代 <profile-name> 為您的 Azure Databricks 組態配置檔名稱以進行驗證。

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

您可以一遍又一次地繼續執行上述命令，以取得下一個區塊等等。請注意，一旦擷取最後一個區塊，SQL 語句就會關閉。在此關閉之後，您無法使用該語句的標識碼來取得其目前狀態或擷取任何其他區塊。

步驟 3：使用外部連結擷取大型結果

本節示範選擇性組態，該組態會使用 EXTERNAL_LINKS 處置來擷取大型數據集。 SQL 語句結果數據的預設位置（處置）位於響應承載內，但這些結果限製為 25 MiB。藉由將設定 disposition 為 EXTERNAL_LINKS，回應會包含 URL，您可以使用來擷取使用標準 HTTP 擷取結果數據的區塊。 URL 指向工作區的內部 DBFS，其中結果區塊會暫時儲存。

警告

Databricks 強烈建議您保護處置所傳回的 EXTERNAL_LINKS URL 和令牌。

當您使用 EXTERNAL_LINKS 處置時，會產生共用存取簽章（SAS） URL，可用來直接從 Azure 記憶體下載結果。由於短期 SAS 令牌內嵌在此 SAS URL 中，您應該同時保護 SAS URL 和 SAS 令牌。

因為 SAS URL 已經產生內嵌暫存 SAS 令牌，因此您不得在下載要求中設定 Authorization 標頭。

EXTERNAL_LINKS您可以在要求時停用處置。若要提出此要求，請建立支援案例。

另請參閱安全性最佳做法。

注意

一旦針對特定 SQL 語句標識符設定響應承載輸出格式和行為，就無法變更。

在此模式中，API 可讓您以 JSON 格式（）、CSV 格式（JSONCSV）或 Apache 箭號格式（ARROW_STREAM）儲存結果數據，且必須使用 HTTP 個別查詢。此外，使用此模式時，無法內嵌響應承載內的結果數據。

下列命令示範如何使用 EXTERNAL_LINKS 和 Apache Arrow 格式。使用此模式，而不是步驟 1 所示的類似查詢：

Databricks cli

databricks api post /api/2.0/sql/statements/ \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "format": "ARROW_STREAM",
  "disposition": "EXTERNAL_LINKS",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "100000", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID

將取代 <profile-name> 為您的 Azure Databricks 組態配置檔名稱以進行驗證。

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

回應如下所示：

{
  "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"
  }
}

如果要求逾時，回應會改為如下所示：

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

若要取得該語句目前的執行狀態，而且如果執行成功，該語句的結果，請執行下列命令：

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'

將取代 <profile-name> 為您的 Azure Databricks 組態配置檔名稱以進行驗證。

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'

如果回應夠大（例如，在此案例中，執行 SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem 時沒有數據列限制），回應將有多個區塊，如下列範例所示。請注意， "...": "..." 這裡指出省略的結果，以求簡潔：

{
  "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"
  }
}

若要下載儲存的內容結果，您可以使用物件中的 external_link URL 執行下列curl命令，並指定您要下載檔案的位置。請勿在此命令中包含您的 Azure Databricks 令牌：

curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"

若要下載串流內容結果的特定區塊，您可以使用下列其中一項：

next_chunk_index下一個區塊的響應承載值（如果有下一個區塊）。
如果有多個區塊，則響應承載指令清單中的其中一個區塊索引可用於任何可用的區塊。

例如，若要從上一個chunk_index10回應取得的區塊，請執行下列命令：

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'

將取代 <profile-name> 為您的 Azure Databricks 組態配置檔名稱以進行驗證。

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'

注意

執行上述命令會傳回新的SAS URL。

若要下載儲存的區塊，請使用物件中的 external_link URL。

如需 Apache 箭頭格式的詳細資訊，請參閱：

步驟 4：取消 SQL 語句的執行

如果您需要取消尚未成功的 SQL 語句，請執行下列命令：

Databricks cli

databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'

將取代 <profile-name> 為您的 Azure Databricks 組態配置檔名稱以進行驗證。

Curl

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

安全性最佳做法

Databricks SQL 語句執行 API 會使用端對端傳輸層安全性（TLS）加密和短期認證，例如 SAS 令牌，以提高數據傳輸的安全性。

此安全性模型中有數個層級。在傳輸層中，只能使用 TLS 1.2 或更新版本呼叫 Databricks SQL 語句執行 API。此外，Databricks SQL 語句執行 API 的呼叫端必須使用有效的 Azure Databricks 個人存取令牌或 Microsoft Entra ID（先前稱為 Azure Active Directory）令牌進行驗證，以對應至有權使用 Databricks SQL 的使用者。此用戶必須具有所使用之特定 SQL 倉儲的 CAN USE 存取權，而且可以使用 IP 存取清單來限制存取權。這適用於 Databricks SQL 語句執行 API 的所有要求。此外，若要執行語句，已驗證的用戶必須具有每個語句中使用的數據物件（例如數據表、檢視表和函式）的許可權。這會由 Unity 目錄中的現有存取控制機制或使用資料表 ACL 強制執行。（請參閱如需詳細資訊，請參閱 Unity 目錄的數據控管。這也表示只有執行語句的使用者才能對語句的結果提出擷取要求。

每當您使用 Databricks SQL 語句執行 API 以及擷取大型數據集的 EXTERNAL_LINKS 處置時，Databricks 建議下列安全性最佳做法：

拿掉 Azure 記憶體要求的 Databricks 授權標頭
保護 SAS URL 和 SAS 令牌

EXTERNAL_LINKS您可以藉由建立支援案例，依要求停用處置。若要提出此要求，請連絡您的 Azure Databricks 帳戶小組以建立支援案例。

拿掉 Azure 記憶體要求的 Databricks 授權標頭

所有使用 curl 之 Databricks SQL 語句執行 API 的呼叫都必須包含 Authorization 包含 Azure Databricks 存取認證的標頭。當您從 Azure 記憶體下載資料時，請勿包含此 Authorization 標頭。不需要此標頭，而且可能會無意中公開您的 Azure Databricks 存取認證。

保護 SAS URL 和 SAS 令牌

每當您使用 EXTERNAL_LINKS 處置時，就會產生短期 SAS URL，呼叫者可以使用該 URL 直接從 Azure 記憶體使用 TLS 下載結果。由於短期 SAS 令牌內嵌在此 SAS URL 中，您應該同時保護 SAS URL 和 SAS 令牌。

共用方式為

語句執行 API：在倉儲上執行 SQL

開始之前

步驟 1：執行 SQL 語句，並將數據結果儲存為 JSON

Databricks cli

Curl

步驟 2：取得語句的目前執行狀態和數據結果作為 JSON

Databricks cli

Curl

Databricks cli

Curl

步驟 3：使用外部連結擷取大型結果

Databricks cli

Curl

Databricks cli

Curl

Databricks cli

Curl

步驟 4：取消 SQL 語句的執行

Databricks cli

Curl

安全性最佳做法

拿掉 Azure 記憶體要求的 Databricks 授權標頭

保護 SAS URL 和 SAS 令牌

意見反應

意見反應

其他資源