陳述式執行 API：在倉儲上執行 SQL

發行項
11/16/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 個人存取令牌驗證進行驗證，請遵循工作區使用者的 Azure Databricks 個人存取令牌中的步驟。
  
  然後，若要使用 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 主機，輸入 Azure Databricks 個別工作區 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。
  3. 對於提示個人存取權杖，輸入工作區的 Azure Databricks 個人存取權杖。
  在本教學課程的 Databricks CLI 範例中，請注意下列事項：
  - 本教學課程假設您的本機開發電腦上具有環境變數 DATABRICKS_SQL_WAREHOUSE_ID。此環境變數代表 Databricks SQL 倉儲的 ID。此 ID 是倉儲 [HTTP 路徑]欄位中 /sql/1.0/warehouses/ 後面的字母和數字字串。若要了解如何取得倉儲的 HTTP 路徑值，請參閱取得 Azure Databricks 計算資源的連線詳細資料。
  - 如果您使用 Windows 命令介面，而不是 Unix、Linux 或 macOS 的命令介面，請將 \ 取代為 ^，並將 ${...} 取代為 %...%。
  - 如果您使用 Windows 命令介面，而不是 Unix、Linux 或 macOS 的命令介面，請在 JSON 文件宣告中，將開頭和結尾 ' 取代為 "，並將內部 " 取代為 \"。
- curl 是用來傳送和接收 REST API 要求和回應的命令列工具。另請參閱安裝 curl。或者，請調整本教學課程的 curl 範例，以搭配 HTTPie 等類似工具使用。
  
  在本教學課程的curl 範例中，請注意下列事項：
  - 您可以使用 .netrc 檔案，而不是 --header "Authorization: Bearer ${DATABRICKS_TOKEN}"。如果您使用 .netrc 檔案，請將 --header "Authorization: Bearer ${DATABRICKS_TOKEN}" 取代為 --netrc。
  - 如果您使用 Windows 命令介面，而不是 Unix、Linux 或 macOS 的命令介面，請將 \ 取代為 ^，並將 ${...} 取代為 %...%。
  - 如果您使用 Windows 命令介面，而不是 Unix、Linux 或 macOS 的命令介面，請在 JSON 文件宣告中，將開頭和結尾 ' 取代為 "，並將內部 " 取代為 \"。
  此外，針對本教學課程的 curl 範例，本教學課程假設您的本機開發電腦上具有下列環境變數：
  - DATABRICKS_HOST，代表 Azure Databricks 工作區的工作區執行個體名稱，例如 adb-1234567890123456.7.azuredatabricks.net。
  - DATABRICKS_TOKEN，代表 Azure Databricks 工作區使用者的 Azure Databricks 個人存取權杖。
  - DATABRICKS_SQL_WAREHOUSE_ID，代表 Databricks SQL 倉儲的 ID。此 ID 是倉儲 [HTTP 路徑]欄位中 /sql/1.0/warehouses/ 後面的字母和數字字串。若要了解如何取得倉儲的 HTTP 路徑值，請參閱取得 Azure Databricks 計算資源的連線詳細資料。
  注意
  
  作為安全性最佳做法，當您使用自動化工具、系統、指令碼和應用程式進行驗證時，Databricks 建議您使用屬於服務主體的個人存取權杖，而不是工作區使用者。若要建立服務主體的權杖，請參閱管理服務主體的權杖。
  
  若要建立 Azure Databricks 個人存取令牌，請遵循工作區使用者的 Azure Databricks 個人存取令牌中的過時。
  
  警告
  
  Databricks 強烈反對將硬式編碼資訊寫入指令，因為此敏感性資訊可以透過版本控制系統以純文字公開。 Databricks 建議您使用您在開發電腦上設定的方法，例如環境變數。從指令中移除這類硬式編碼資訊，也有助於讓這些指令更具可攜性。
本教學課程假設您也有用來查詢 JSON 回應酬載的命令列處理器 jq，其中 Databricks SQL 陳述式執行 API 會在每次呼叫 Databricks SQL 陳述式執行 API 之後傳回您。請參閱下載 jq。
您必須至少有一個資料表，才能執行 SQL 陳述式。本教學課程是以 samples 目錄內 tpch 結構描述中 (也稱為資料庫)的 lineitem 資料表為基礎。如果您無法從工作區存取此目錄、結構描述或資料表，請在本教學課程中將其替代為您自己的目錄、結構描述或資料表。

步驟 1：執行 SQL 陳述式，並將資料結果儲存為 JSON

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

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

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 陳述式 ID 及其目前狀態，而不是陳述式的結果。若要變更此行為，請將 "wait_timeout" 新增至要求，並將其設定為 "<x>s"，其中 <x> 可以介於 5 和 50 秒 (含) 之間，例如 "50s"。若要立即傳回 SQL 陳述式 ID 及其目前狀態，請將 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 或 row_limit，則回應酬載中的 truncated 欄位會設定為 true。

如果陳述式的結果在等待逾時結束之前可用，則回應如下所示：

{
  "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 陳述式的 ID 來取得該陳述式的目前執行狀態，以及如果執行成功，則取得該陳述式的結果。如果您忘記陳述式的 ID，則您可以從 Databricks SQL 主控台的 [查詢歷史記錄] 區段，或藉由呼叫 [查詢歷史記錄 API]，加以取得。例如，您可以持續輪詢此命令，每次都檢查執行是否成功。

若要取得 SQL 陳述式的目前執行狀態，而且如果執行成功，則會取得該陳述式的結果和用於取得任何下一個 JSON 資料區塊的 API 網址片段，請執行下列命令。此命令假設您在名為 SQL_STATEMENT_ID 的本機開發電腦上有環境變數，且其設定為上一個步驟中 SQL 陳述式的 ID 值。當然，您可以使用 SQL 陳述式的硬式編碼 ID 取代下列命令中的 ${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 陳述式就會關閉。在此關閉之後，您無法使用該陳述式的 ID 來取得其目前狀態或擷取任何其他區塊。

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

本節示範選用組態，其中該組態會使用 EXTERNAL_LINKS 處置來擷取大型資料集。 SQL 陳述式結果資料的預設位置 (處置) 位於回應酬載內，不過這些結果會限制為 25 MiB。藉由將 disposition 設定為 EXTERNAL_LINKS，回應會包含可用於藉助標準 HTTP 取得結果資料區塊的網址。網址指向工作區的內部 DBFS，其中會暫時儲存結果區塊。

警告

Databricks 強烈建議您保護 EXTERNAL_LINKS 處置傳回的網址和權杖。

當您使用 EXTERNAL_LINKS 處置時，會產生共用存取簽章 (SAS) 網址，可用來直接從 Azure 儲存體下載結果。由於短期 SAS 權杖內嵌在此 SAS 網址中，您應該同時保護 SAS 網址和 SAS 權杖。

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

您可以藉由建立支援案例，依要求停用 EXTERNAL_LINKS 處置。

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

注意

一旦針對特定SQL 陳述式 ID 設定回應酬載輸出格式和行為，就無法變更。

在此模式中，API 可讓您以 JSON 格式 (JSON)、CSV 格式 (CSV) 或 Apache Arrow 格式 (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 物件中的網址執行下列 curl 命令，並指定您要下載檔案的位置。請勿在此命令中包含您的 Azure Databricks 權杖：

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

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

下一個區塊的回應酬載中的 next_chunk_index 值 (如果存在下一個區塊)。
如果有多個區塊，則回應酬載資訊清單中的其中一個區塊索引可用於任何可用的區塊。

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

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 網址。

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

如需有關 Apache Arrow 格式的詳細資訊，請參閱：

步驟 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 個人存取權杖、OAuth 存取權杖或 Microsoft Entra ID (先前稱為 Azure Active Directory) 權杖進行驗證，其中該權杖會對應至有權使用 Databricks SQL 的使用者。此使用者必須具有所使用的特定 SQL 倉儲的 [可使用] 存取權，而且可以使用 IP 存取清單來限制存取權。這適用於 Databricks SQL 陳述式執行 API 的所有要求。此外，若要執行陳述式，已驗證的使用者必須具有每個陳述式中使用的資料物件 (例如資料表、檢視和函式) 的權限。這會由 Unity 目錄中的現有存取控制機制或使用資料表 ACL 強制執行。 (如需詳細資料，請參閱使用 Unity 目錄進行資料控管。) 這也意味著只有執行陳述式的使用者才能對陳述式的結果發出擷取要求。

每當您使用 Databricks SQL 陳述式執行 API 以及 EXTERNAL_LINKS 配置來擷取大型資料集時，Databricks 建議採用以下安全最佳做法：

移除 Azure 儲存體要求的 Databricks 授權標頭
保護 SAS 網址和 SAS 權杖

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

移除 Azure 儲存體要求的 Databricks 授權標頭

使用 curl 對 Databricks SQL 陳述式執行 API 的所有呼叫都必須包含包含 Azure Databricks 存取認證的 Authorization 標頭。當您從 Azure 儲存體下載資料時，請勿包含此 Authorization 標頭。此標頭並非必需，而且可能會無意中公開您的 Azure Databricks 存取認證。

保護 SAS 網址和 SAS 權杖

每當使用 EXTERNAL_LINKS 處置時，都會產生一個短暫的 SAS 網址，而呼叫者可以使用該網址透過 TLS 直接從 Azure 儲存體下載結果。由於短期 SAS 權杖內嵌在此 SAS 網址中，您應該同時保護 SAS 網址和 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 網址和 SAS 權杖

意見反應

其他資源