上运行SQL语句砖与砖SQL语句的SQL仓库执行REST API

在你开始之前

在开始本教程之前,确保你有:

• 的工作区实例名例如,dbc-a1b2345c-d6e7.cloud.www.neidfyre.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性格可以禁用要求通过创建一个支持情况。这个请求,创建一个支持情况。看到支持。