上運行SQL語句磚與磚SQL語句的SQL倉庫執行REST API

在你開始之前

在開始本教程之前,確保你有:

• 的工作區實例名例如,dbc-a1b2345c-d6e7.cloud.m.eheci.com為你的磚,工作區。本教程假設您有一個環境變量在本地開發機器命名DATABRICKS_HOST將這個值。學習如何設置環境變量,看你的操作係統的文檔。

  警告

  磚強烈阻礙了硬編碼的信息到您的腳本,這個敏感信息可以暴露在純文本版本控製係統。磚建議你使用方法,如您在您的開發機器上設置環境變量。刪除硬編碼的信息從你的腳本有助於使這些腳本更便攜。

• 一個磚個人訪問令牌為你的磚用戶工作區。本教程假設您有一個環境變量在本地開發機器命名DATABRICKS_TOKEN的值,設置為你的訪問令牌。

  請注意

  作為一個安全最佳實踐進行身份驗證時使用自動化工具,係統、腳本和應用程序,磚建議您使用OAuth令牌或個人訪問令牌屬於服務主體而不是用戶工作區。為服務主體,創建令牌服務主體的管理令牌。

• 至少一個表,您可以執行SQL語句。本教程采用的是基於lineitem表中tpch模式(也稱為一個數據庫)中樣品目錄。如果您沒有訪問此目錄,模式,或表從你的工作區,代替他們與自己在本教程。

• 旋度發送和接收的命令行工具REST API請求和響應。另請參閱安裝旋度。或者,您可以調整本教程的例子使用類似的工具,如郵遞員或HTTPie。

  為每個旋度本文中使用的例子:

  • 而不是——頭“授權:持票人$ {DATABRICKS_TOKEN}”,你可以使用一個. netrc文件。如果你使用一個. netrc文件,替換——頭“授權:持票人$ {DATABRICKS_TOKEN}”與——netrc。

  • 如果您使用Windows命令shell命令shell的Unix, Linux,或macOS取代\與^,替換$ {…}與%…%。

  • 如果您使用Windows命令shell命令shell的Unix, Linux,或macOS在JSON文檔聲明,取代打開和關閉”與”,取代內心”與\”。

• 金橋,一個命令行處理器查詢JSON響應有效載荷,磚的SQL語句執行API返回你每次叫你做磚的SQL語句執行API。另請參閱下載金橋。

• 一個磚SQL的倉庫。本教程假設您有一個環境變量在本地開發機器命名DATABRICKS_SQL_WAREHOUSE_ID,這是字母和數字的字符串/ sql / 1.0 /倉庫/在HTTP路徑現場為你的倉庫。學習如何讓你的倉庫的HTTP路徑價值,看到得到一個SQL的連接細節,倉庫。

• 磚的SQL倉庫必須設置使用預覽通道在高級選項。注意倉庫使用當前頻道切換到預覽通道將導致倉庫自動重啟。這個升級可能需要幾分鍾。

步驟1:執行SQL語句並保存結果為JSON的數據

運行以下命令,如下:

1. 使用SQL指定倉庫,以及指定的令牌,查詢三列的前兩行lineitem表中tcph內模式樣品目錄。

2. 節省了JSON格式的響應負載文件命名sql-execution-response.json在當前工作目錄。

3. 打印的內容sql-execution-response.json文件。

4. 設置一個本地環境變量命名SQL_STATEMENT_ID包含的ID對應的SQL語句。您可以使用此SQL語句ID獲取信息,根據需要聲明之後,在步驟2。你也可以把這個SQL語句的語句ID查詢曆史磚的SQL控製台,或者通過調用查詢曆史API。

5. 設置額外的本地環境變量命名NEXT_CHUNK_EXTERNAL_LINK包含一個API URL片段獲取下一個JSON數據塊。如果響應數據太大,磚的SQL語句塊執行API提供了反應。您可以使用這個API URL片段獲取下一個塊的數據,在步驟2。如果沒有下一塊,然後此環境變量設置為零。

6. 輸出的值SQL_STATEMENT_ID和NEXT_CHUNK_INTERNAL_LINK環境變量。

curl——請求後\https://$ {DATABRICKS_HOST}. . / / api / 2.0 / sql語句\——頭“授權:持票人$ {DATABRICKS_TOKEN}”\——頭“application / json內容類型:\——數據”{“warehouse_id”:“”DATABRICKS_SQL_WAREHOUSE_ID美元”’”,“目錄”:“樣品”,“模式”:“tpch”,“聲明”:“選擇l_orderkey、l_extendedprice l_shipdate lineitem限製2”}'\——輸出“sql-execution-response.json”\& &金橋。“sql-execution-response.json”\& &出口SQL_STATEMENT_ID=$ (金橋- r .statement_id“sql-execution-response.json”)\& &出口NEXT_CHUNK_INTERNAL_LINK=$ (金橋- r .result.next_chunk_internal_link“sql-execution-response.json”)\& &回聲SQL_STATEMENT_ID=SQL_STATEMENT_ID美元\& &回聲NEXT_CHUNK_INTERNAL_LINK=NEXT_CHUNK_INTERNAL_LINK美元

在前麵的要求:

• 默認情況下,任何以JSON數組格式返回數據,默認位置的任何SQL語句的數據結果是在響應負載。這種行為明確,添加“格式”:“JSON_ARRAY”、“性格”:“內聯”請求負載。如果你試圖返回數據結果大於16 MiB響應負載的故障狀態返回SQL語句是取消了。大於16 MiB數據結果,您可以使用外部鏈接而不是試圖返回響應負載,這是在步驟3中演示。

• 旋度響應負載的內容存儲到一個本地文件。不支持本地數據存儲API直接由磚SQL語句的執行。

• 默認情況下,10秒後,如果SQL語句通過倉庫尚未執行完,磚的SQL語句執行API隻返回SQL語句ID和它的當前狀態,而不是語句的結果。要改變這種行為,添加:“wait_timeout < x > s”請求負載,< x >之間可以5和50例如,秒包容性“wait_timeout”:“50年代”。返回SQL語句ID及其當前狀態立即集合wait_timeout來0。

• 默認情況下,SQL語句繼續運行,如果超時周期。取消一個SQL語句,如果超時周期達到相反,添加“on_wait_timeout”:“取消”到請求paylod。

如果語句的結果在等待超時結束之前,響應如下:

{“statement_id”:“01 ed92c5 - 3583 - 1 - f38 b21b c6773e7c56b3”,“狀態”:{“狀態”:“成功”},“清單”:{“格式”:“JSON_ARRAY”,“模式”:{“column_count”:3,“列”:({“名稱”:“l_orderkey”,“type_name”:“長”,“位置”:0},{“名稱”:“l_extendedprice”,“type_name”:“小數”,“位置”:1,“type_precision”:18,“type_scale”:2},{“名稱”:“l_shipdate”,“type_name”:“日期”,“位置”:2}]}},“結果”:{“chunk_index”:0,“row_offset”:0,“row_count”:2,“data_array”:((“15997987”,“66516.00”,“1992-02-12”),(“15997988”,“53460.96”,“1994-05-31”]]}}

如果等待超時之前結束語句的結果是可用的,反應是這樣的:

{“statement_id”:“01 ed92c5 - 3583 - 1 - f38 b21b c6773e7c56b3”,“狀態”:{“狀態”:“等待”}}

如果語句的結果數據太大(例如在這種情況下,通過運行選擇l_orderkey,l_extendedprice,l_shipdate從lineitem限製3000000),結果數據分塊,看起來是這樣的。請注意,“……”:“…”在這裏表示省略結果簡潔:

{“statement_id”:“01 ed92c5 - 3583 - 1 - f38 b21b c6773e7c56b3”,“狀態”:{“狀態”:“成功”},“清單”:{“格式”:“JSON_ARRAY”,“模式”:{“column_count”:3,“列”:({“…”:“…”}]}},“結果”:{“chunk_index”:0,“row_offset”:0,“row_count”:432500年,“next_chunk_index”:1,“next_chunk_internal_link”:“. . / api / 2.0 / sql /報表/ 01 ed92c5 - 3583 - 1 - f38 b21b c6773e7c56b3 /結果/塊/ 1 ? row_offset = 432500”,“data_array”:((“15997987”,“66516.00”,“1992-02-12”),(“…”]]}}

步驟2:獲得一個語句的執行現狀和數據結果為JSON

您可以使用一個SQL語句的ID,語句的執行現狀,如果執行成功,語句的結果。如果你忘記了聲明的ID,您可以把它從查詢曆史磚的SQL控製台,或者通過調用查詢曆史API。例如,您可以繼續輪詢該命令,每次檢查是否執行成功。

得到一個SQL語句的執行現狀,如果執行成功了,這句話的結果和一個API URL片段得到任何一塊的JSON數據,運行以下命令。這個命令假設您有一個環境變量在本地開發機器命名SQL_STATEMENT_ID的值,設置為SQL語句從上一步的ID或另有規定。當然,你可以替代$ {SQL_STATEMENT_ID}下麵的命令的SQL語句的硬編碼的ID。

旋度,請求得到\https://$ {DATABRICKS_HOST}. . / / api / 2.0 / sql語句$ {SQL_STATEMENT_ID}\——頭“授權:持票人$ {DATABRICKS_TOKEN}”\——輸出“sql-execution-response.json”\& &金橋。“sql-execution-response.json”\& &出口NEXT_CHUNK_INTERNAL_LINK=$ (金橋- r .result.next_chunk_internal_link“sql-execution-response.json”)\& &回聲NEXT_CHUNK_INTERNAL_LINK=NEXT_CHUNK_INTERNAL_LINK美元

如果NEXT_CHUNK_INTERNAL_LINK將一個非-零值,您可以使用它來得到下一塊數據,等等,例如使用下麵的命令:

旋度,請求得到\https://$ {DATABRICKS_HOST}$ {NEXT_CHUNK_INTERNAL_LINK}\——頭“授權:持票人$ {DATABRICKS_TOKEN}”\——輸出“sql-execution-response.json”\& &金橋。“sql-execution-response.json”\& &出口NEXT_CHUNK_INTERNAL_LINK=$ (金橋- r .next_chunk_internal_link“sql-execution-response.json”)\& &回聲NEXT_CHUNK_INTERNAL_LINK=NEXT_CHUNK_INTERNAL_LINK美元

你可以繼續運行前麵的命令,一遍又一遍,得到下一個塊等等。注意,一旦獲取最後一個塊,SQL語句是關閉的。這個閉包後,您不能使用語句ID的現狀或獲取任何更多的塊。

步驟3:使用外部鏈接獲取大的結果

本節演示了使用一個可選的配置為EXTERNAL_LINKS處理檢索大型數據集。默認位置(性格)響應負載中的SQL語句的結果數據,但是這些結果僅限於16 MiB。通過設置性格來為EXTERNAL_LINKS響應包含url,您可以使用它來獲取大量數據與標準HTTP的結果。url指向您的工作區內部DBFS,結果塊在哪裏暫時存儲。

使用下麵的命令了為EXTERNAL_LINKS。使用這種模式,而不是類似的查詢步驟1中演示:

curl——請求後\https://$ {DATABRICKS_HOST}. . / / api / 2.0 / sql語句\——頭“授權:持票人$ {DATABRICKS_TOKEN}”\——頭“application / json內容類型:\——數據”{“warehouse_id”:“”DATABRICKS_SQL_WAREHOUSE_ID美元”’”,“目錄”:“樣品”,“模式”:“tpch”,“格式”:“ARROW_STREAM”,“性格”:“為EXTERNAL_LINKS”,“聲明”:“選擇l_orderkey、l_extendedprice l_shipdate lineitem限製100000”}'\——輸出“sql-execution-response.json”\& &金橋。“sql-execution-response.json”\& &出口SQL_STATEMENT_ID=$ (金橋- r .statement_id“sql-execution-response.json”)\& &回聲SQL_STATEMENT_ID=SQL_STATEMENT_ID美元

響應如下:

{“statement_id”:“01 ed92c5 - 3583 - 1 - f38 b21b c6773e7c56b3”,“狀態”:{“狀態”:“成功”},“清單”:{“格式”:“ARROW_STREAM”,“模式”:{“column_count”:3,“列”:({“名稱”:“l_orderkey”,“type_name”:“長”,“位置”:0},{“名稱”:“l_extendedprice”,“type_name”:“小數”,“位置”:1,“type_precision”:18,“type_scale”:2},{“名稱”:“l_shipdate”,“type_name”:“日期”,“位置”:2}]},“total_chunk_count”:1,“塊”:({“chunk_index”:0,“row_offset”:0,“row_count”:100000年}),“total_row_count”:100000年,“total_byte_count”:2848312},“結果”:{“為external_links”:({“chunk_index”:0,“row_offset”:0,“row_count”:100000年,“external_link”:“< url-to-data-stored-externally >”,“過期”:“< url-expiration-timestamp >”}]}}

如果請求超時,反應是這樣的:

{“statement_id”:“01 ed92c5 - 3583 - 1 - f38 b21b c6773e7c56b3”,“狀態”:{“狀態”:“等待”}}

語句的執行現狀和,如果執行成功了,語句的結果,運行以下命令:

旋度,請求得到\https://$ {DATABRICKS_HOST}. . / / api / 2.0 / sql語句$ {SQL_STATEMENT_ID}\——頭“授權:持票人$ {DATABRICKS_TOKEN}”\——輸出“sql-execution-response.json”\& &金橋。“sql-execution-response.json”

如果響應足夠大(例如在這種情況下,通過運行選擇l_orderkey,l_extendedprice,l_shipdate從lineitem沒有行限製),響應將有多個塊,如以下示例所示。請注意,“……”:“…”在這裏表示省略結果簡潔:

{“statement_id”:“01 ed92c5 - 3583 - 1 - f38 b21b c6773e7c56b3”,“狀態”:{“狀態”:“成功”},“清單”:{“格式”:“ARROW_STREAM”,“模式”:{“column_count”:3,“列”:({“…”:“…”}]},“total_chunk_count”:43,“塊”:({“chunk_index”:0,“row_offset”:0,“row_count”:737500年},{“chunk_index”:1,“row_offset”:737500年,“row_count”:737500年},{“…”:“…”},{“chunk_index”:41,“row_offset”:28755596,“row_count”:737500年},{“chunk_index”:42,“row_offset”:29493096,“row_count”:506699年}),“total_row_count”:29999795,“total_byte_count”:854409376},“結果”:{“為external_links”:({“chunk_index”:0,“row_offset”:0,“row_count”:737500年,“next_chunk_index”:1,“next_chunk_internal_link”:“. . / api / 2.0 / sql /報表/ 01 ed92c5 - 3583 - 1 - f38 b21b c6773e7c56b3 /結果/塊/ 1 ? row_offset = 737500”,“external_link”:“< url-to-result-stored-externally >”,“過期”:“< expiration-timestamp-for-url >”}]}}

下載存儲內容的結果,您可以運行下麵的旋度命令,使用的URLexternal_link對象,指定您想要下載的文件。不包括你的磚牌在這個命令:

旋度“< url-to-result-stored-externally >”\——輸出“<路徑/ /下載/ /文件/本地>”

下載一個特定的塊流內容的結果,第一次使用chunk_index和row_offset從響應負載值。例如,要獲取一塊chunk_index的41和一個row_offset的28755596從以前的響應,運行以下命令:

旋度,請求得到\https://$ {DATABRICKS_HOST}. . / / api / 2.0 / sql語句$ {SQL_STATEMENT_ID}/結果/塊/ 41 ? row_offset=28755596\——頭“授權:持票人$ {DATABRICKS_TOKEN}”\——輸出“sql-execution-response.json”\& &金橋。“sql-execution-response.json”

下載存儲塊,使用的URLexternal_link對象。

Apache箭頭格式的更多信息,請參閱:

• IPC流媒體格式

• 寫作和閱讀的流媒體格式

• 使用流

步驟4:取消一個SQL語句的執行

如果你需要取消一個SQL語句,尚未成功,運行以下命令:

curl——請求後\https://$ {DATABRICKS_HOST}. . / / api / 2.0 / sql語句$ {SQL_STATEMENT_ID}/取消\——頭“授權:持票人$ {DATABRICKS_TOKEN}”

安全最佳實踐

磚的SQL語句執行API增加了數據傳輸的安全利用端到端傳輸層安全性(transport layer security, TLS)加密和短暫的憑證,如presigned url。

有幾層在這個安全模型。在傳輸層,隻有可能與磚的SQL語句執行通信API使用TLS 1.2或以上。同時,磚的SQL語句執行API的調用者必須經過身份驗證的一個有效的磚個人訪問令牌映射到一個用戶有權利使用磚SQL。該用戶必須有可以使用訪問特定使用SQL倉庫,就可以限製和訪問IP訪問列表。這適用於所有請求數據磚SQL語句執行API。此外,對於執行語句,經過身份驗證的用戶必須有權限的數據對象(例如表、視圖和函數)在每個語句中使用。這是通過現有的訪問控製機製在實施統一目錄或者使用表acl;看到數據治理指南。這也意味著,隻執行一個語句的用戶可以獲取請求語句的結果。

磚推薦以下安全最佳實踐每當你使用API以及磚SQL語句的執行為EXTERNAL_LINKS處理檢索大型數據集:

• 把磚授權對Amazon S3請求頭

• 保護presigned url

• 配置網絡限製存儲賬戶

• 配置登錄存儲賬戶

的為EXTERNAL_LINKS性格可以禁用要求通過創建一個支持情況。這個請求,創建一個支持情況。看到支持。