API de ejecución de instrucciones: ejecución de SQL en almacenes
Importante
Para acceder a las API REST de Databricks, es preciso autenticarse.
Este tutorial le muestra cómo usar la API de ejecución de instrucciones SQL 2.0 de Databricks para ejecutar instrucciones SQL desde almacenes de Databricks SQL.
Para ver la referencia de Databricks SQL Statement Execution API 2.0, consulte Ejecución de instrucciones.
Antes de empezar
Antes de comenzar este tutorial, asegúrese de que dispone de lo siguiente:
La CLI de Databricks, versión 0.205 o posterior, o
curl, como se indica a continuación:La CLI de Databricks es una herramienta de línea de comandos para enviar y recibir solicitudes y respuestas de la API REST de Databricks. Si decide usar la versión 0.205 o superior de la CLI de Databricks, debe configurarse para autenticarse con el área de trabajo de Azure Databricks. Consulte Instalación o actualización de la CLI de Databricks y Autenticación para la CLI de Databricks.
Por ejemplo, para autenticarse con la autenticación de token de acceso personal de Databricks, cree un token de acceso personal como se indica a continuación:
- En el área de trabajo de Azure Databricks, haga clic en el nombre de usuario de Azure Databricks en la barra superior y, a continuación, seleccione Configuración en la lista desplegable.
- Haga clic en Desarrollador.
- Junto a Tokens de acceso, haga clic en Administrar.
- Haga clic en Generate new token (Generar nuevo token).
- (Opcional) Escriba un comentario que le ayude a identificar este token en el futuro y cambie la duración predeterminada del token de 90 días. Para crear un token sin duración (no recomendado), deje el cuadro Duración (días) vacío (en blanco).
- Haga clic en Generar.
- Copie el token mostrado en una ubicación segura y, a continuación, haga clic en Listo.
Nota:
Asegúrese de guardar el token copiado en una ubicación segura. No comparta el token copiado con otros usuarios. Si pierde el token copiado, no podrá volver a generar ese mismo token. Debe repetir el procedimiento para crear un nuevo token. Si pierde el token copiado o cree que el token se ha visto comprometido, Databricks recomienda eliminar inmediatamente ese token del área de trabajo haciendo clic en el icono de papelera (Revocar) situado junto al token en la página Tokens de acceso.
Si no puede crear o usar tokens en el área de trabajo, puede deberse a que el administrador del área de trabajo tiene tokens deshabilitados o no le ha concedido permiso para crear o usar tokens. Consulte el administrador del área de trabajo o lo siguiente:
Y, a continuación, para usar la CLI de Databricks para crear un perfil de configuración de Azure Databricks para el token de acceso personal, haga lo siguiente:
Nota:
En el siguiente procedimiento se usa la CLI de Databricks para crear un perfil de configuración de Azure Databricks con el nombre
DEFAULT. Si ya tiene un perfil de configuraciónDEFAULT, este procedimiento sobrescribe el perfil de configuraciónDEFAULTexistente.Para comprobar si ya tiene un perfil de configuración
DEFAULTy para ver esta configuración de perfil si existe, use la CLI de Databricks para ejecutar el comandodatabricks auth env --profile DEFAULT.Para crear un perfil de configuración con un nombre distinto de
DEFAULT, reemplace la parteDEFAULTde--profile DEFAULTen el siguiente comandodatabricks configurepor un nombre diferente para el perfil de configuración.Use la CLI de Databricks para crear un perfil de configuración de Azure Databricks denominado
DEFAULTque use la autenticación de token de acceso personal de Azure Databricks. Para ello, ejecute el siguiente comando:databricks configure --profile DEFAULTEn el símbolo del sistema Host de Databricks, escriba la dirección URL por área de trabajo de Azure Databricks, por ejemplo,
https://adb-1234567890123456.7.azuredatabricks.net.En el símbolo del sistema Token de acceso personal, escriba el token de acceso personal de Azure Databricks para el área de trabajo.
En los ejemplos de la CLI de Databricks de este tutorial, tenga en cuenta lo siguiente:
- En este tutorial se supone que tiene una variable de entorno
DATABRICKS_SQL_WAREHOUSE_IDen la máquina de desarrollo local. Esta variable de entorno representa el identificador del almacén de Databricks SQL. Este Id. es la cadena de letras y números siguientes/sql/1.0/warehouses/en el campo ruta de acceso HTTP del almacén. Para obtener información sobre cómo obtener el valor de la ruta HTTP de su almacén, consulte Obtener detalles de conexión para un recurso informático de Azure Databricks. - Si usa el shell de comandos de Windows en lugar de un shell de comandos para Unix, Linux o macOS, reemplace
\por^y reemplace${...}por%...%. - Si usa el shell de comandos de Windows en lugar de un shell de comandos para Unix, Linux o macOS, en declaraciones de documento JSON, reemplace el
'de apertura y cierre por"y reemplace el"interior por\".
curl es una herramienta de línea de comandos para enviar y recibir solicitudes y respuestas de la API REST. Consulte también Instalación de curl. Como alternativa, puede adaptar los ejemplos
curlde este tutorial para su uso con herramientas similares, como Postman o HTTPie.En los ejemplos
curlde este tutorial, tenga en cuenta lo siguiente:- En lugar de
--header "Authorization: Bearer ${DATABRICKS_TOKEN}", puede usar un archivo .netrc. Si usa un archivo.netrc, reemplace--header "Authorization: Bearer ${DATABRICKS_TOKEN}"por--netrc. - Si usa el shell de comandos de Windows en lugar de un shell de comandos para Unix, Linux o macOS, reemplace
\por^y reemplace${...}por%...%. - Si usa el shell de comandos de Windows en lugar de un shell de comandos para Unix, Linux o macOS, en declaraciones de documento JSON, reemplace el
'de apertura y cierre por"y reemplace el"interior por\".
Además, en los ejemplos
curlde este tutorial, en este tutorial se asume que tiene las siguientes variables de entorno en la máquina de desarrollo local:DATABRICKS_HOST, que representa el nombre de la instancia del área de trabajo, por ejemploadb-1234567890123456.7.azuredatabricks.net, para el área de trabajo de Azure Databricks.DATABRICKS_TOKEN, que representa un token de acceso personal de Azure Databricks para el usuario del área de trabajo de Azure Databricks.DATABRICKS_SQL_WAREHOUSE_ID, que representa el identificador de almacén de Databricks SQL. Este Id. es la cadena de letras y números siguientes/sql/1.0/warehouses/en el campo ruta de acceso HTTP del almacén. Para obtener información sobre cómo obtener el valor de la ruta HTTP de su almacén, consulte Obtener detalles de conexión para un recurso informático de Azure Databricks.
Nota:
Como procedimiento recomendado de seguridad, cuando se autentique con herramientas, sistemas, scripts y aplicaciones automatizados, Databricks recomienda usar los tokens de acceso personal pertenecientes a las entidades de servicio en lugar de a los usuarios del área de trabajo. Para crear tókenes para entidades de servicio, consulte Administración de tokens de acceso para una entidad de servicio.
Para crear un token de acceso personal de Azure Databricks, haga lo siguiente:
- En el área de trabajo de Azure Databricks, haga clic en el nombre de usuario de Azure Databricks en la barra superior y, a continuación, seleccione Configuración en la lista desplegable.
- Haga clic en Desarrollador.
- Junto a Tokens de acceso, haga clic en Administrar.
- Haga clic en Generate new token (Generar nuevo token).
- (Opcional) Escriba un comentario que le ayude a identificar este token en el futuro y cambie la duración predeterminada del token de 90 días. Para crear un token sin duración (no recomendado), deje el cuadro Duración (días) vacío (en blanco).
- Haga clic en Generar.
- Copie el token mostrado en una ubicación segura y, a continuación, haga clic en Listo.
Nota:
Asegúrese de guardar el token copiado en una ubicación segura. No comparta el token copiado con otros usuarios. Si pierde el token copiado, no podrá volver a generar ese mismo token. Debe repetir el procedimiento para crear un nuevo token. Si pierde el token copiado o cree que el token se ha visto comprometido, Databricks recomienda eliminar inmediatamente ese token del área de trabajo haciendo clic en el icono de papelera (Revocar) situado junto al token en la página Tokens de acceso.
Si no puede crear o usar tokens en el área de trabajo, puede deberse a que el administrador del área de trabajo tiene tokens deshabilitados o no le ha concedido permiso para crear o usar tokens. Consulte el administrador del área de trabajo o lo siguiente:
Advertencia
Databricks no recomienda codificar de forma rígida información en los scripts, ya que esta información confidencial se puede ver expuesta en texto sin formato a través de sistemas de control de versiones. En su lugar, Databricks recomienda usar enfoques como las variables de entorno que establezca en la máquina de desarrollo. Quitar esta información codificada de forma rígida de los scripts ayuda a hacer que esos scripts también sean más portátiles.
- En lugar de
Este tutorial asume que también tiene jq, un procesador de línea de comandos para consultar cargas útiles de respuesta JSON, que la API de ejecución de sentencias SQL de Databricks devuelve después de cada llamada realizada a la API de ejecución de sentencias SQL de Databricks. Consulte Descargar jq.
Debe tener al menos una tabla en la que puede ejecutar instrucciones SQL. Este tutorial se basa en la tabla
lineitemdel esquematpch(también conocida como base de datos) en el catálogosamples. Si no tiene acceso a este catálogo, esquema o tabla desde el área de trabajo, sustituya por el suyo propio en este tutorial.
Paso 1: Ejecutar una instrucción SQL y guardar el resultado de los datos como JSON
Ejecute el siguiente comando, que hace lo siguiente:
- Utilice el almacén SQL especificado, junto con el token especificado si está utilizando
curl, para consultar tres columnas de las dos primeras filas de la tablalineitemen el esquematcphdentro del catálogosamples. - Guarda la carga de respuesta en formato JSON en un archivo denominado
sql-execution-response.jsondentro del directorio de trabajo actual. - Imprima el contenido del archivo
sql-execution-response.json. - Establece una variable de entorno local denominada
SQL_STATEMENT_ID. Esta variable contiene el identificador de la instrucción SQL correspondiente. Puede usar este identificador de instrucción SQL para obtener información sobre esa instrucción más adelante según sea necesario, que se muestra en el paso 2. También puede ver esta instrucción SQL y obtener su identificador de instrucción desde la sección Historial de consultas de la consola de Databricks SQL o llamando a Query History API. - Establece una variable de entorno local adicional denominada
NEXT_CHUNK_EXTERNAL_LINKque contiene un fragmento de dirección URL de API para obtener el siguiente fragmento de datos JSON. Si los datos de respuesta son demasiado grandes, la API de ejecución de sentencias SQL de Databricks proporciona la respuesta en fragmentos. Puede usar este fragmento de dirección URL de API para obtener el siguiente fragmento de datos, que se muestra en el paso 2. Si no hay ningún fragmento siguiente, esta variable de entorno se establece ennull. - Imprime los valores de las variables de entorno
SQL_STATEMENT_IDyNEXT_CHUNK_INTERNAL_LINK.
CLI de Databricks
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
Reemplazar <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.
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
En la solicitud anterior:
Las consultas con parámetros constan del nombre de cada parámetro de consulta precedido de dos puntos (por ejemplo,
:extended_price) con un objetonameyvaluecorrespondiente en la matrizparameters. También se puede especificar un valor opcionaltype, con el valor predeterminado deSTRINGsi no se especifica.Advertencia
Databricks recomienda encarecidamente usar parámetros como procedimiento recomendado para las instrucciones SQL.
Si usa Databricks SQL Statement Execution API con una aplicación que genera SQL dinámicamente, esto puede provocar ataques por inyección de código SQL. Por ejemplo, si genera código SQL basado en las selecciones de un usuario en una interfaz de usuario y no toma medidas adecuadas, un atacante podría insertar código SQL malintencionado para cambiar la lógica de la consulta inicial, leyendo, cambiando o eliminando datos confidenciales.
Las consultas con parámetros ayudan a protegerse frente a ataques por inyección de código SQL mediante el control de argumentos de entrada por separado del resto del código SQL e interpretando estos argumentos como valores literales. Los parámetros también ayudan con la reutilización del código.
De forma predeterminada, los datos devueltos están en formato de matriz JSON y la ubicación predeterminada para cualquiera de los resultados de datos de la instrucción SQL se encuentra dentro de la carga de respuesta. Para que este comportamiento sea explícito, agregue
"format":"JSON_ARRAY","disposition":"INLINE"a la carga de la solicitud. Si intenta devolver resultados de datos mayores de 25 MiB en la carga de respuesta, se devuelve un estado de error y se cancela la instrucción SQL. Para resultados de datos superiores a 25 MiB, puede utilizar vínculos externos en lugar de intentar devolverlos en la carga útil de la respuesta, lo que se demuestra en el paso 3.El comando almacena el contenido de la carga de respuesta en un archivo local. La API de ejecución de sentencias SQL de Databricks no admite directamente el almacenamiento local de datos.
De manera predeterminada, después de 10 segundos, si la sentencia SQL aún no ha terminado de ejecutarse a través del almacén, la API de ejecución de sentencias SQL de Databricks solo devuelve el ID de la sentencia SQL y su estado actual, en lugar del resultado de la sentencia. Para cambiar este comportamiento, agregue
"wait_timeout"a la solicitud y configure a"<x>s", donde<x>puede estar entre5y50segundos inclusive, por ejemplo"50s". Para devolver el identificador de instrucción SQL y su estado actual inmediatamente, establezcawait_timeouten0s.De forma predeterminada, la instrucción SQL continúa ejecutándose si se alcanza el período de tiempo de espera. Para cancelar una instrucción SQL si se alcanza el período de tiempo de espera, agregue
"on_wait_timeout":"CANCEL"a la carga de la solicitud.Para limitar el número de bytes devueltos, agregue
"byte_limit"a la solicitud y establézcalo en el número de bytes, por ejemplo1000.Para limitar el número de filas devueltas, en lugar de agregar una cláusula
LIMITastatement, puede agregar"row_limit"a la solicitud y establecerla en el número de filas, por ejemplo"statement":"SELECT * FROM lineitem","row_limit":2.Si el resultado es mayor que el especificado
byte_limitorow_limit, el campotruncatedse establecetrueen la carga de respuesta.
Si el resultado de la instrucción está disponible antes de que finalice el tiempo de espera, la respuesta es la siguiente:
{
"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"
}
}
Si el tiempo de espera finaliza antes de que el resultado de la instrucción esté disponible, la respuesta tendrá este aspecto en su lugar:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Si los datos de resultados de la instrucción son demasiado grandes (por ejemplo, en este caso, mediante la ejecución de SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), los datos de resultado se fragmentan y tienen este aspecto en su lugar. Tenga en cuenta que "...": "..." indica los resultados omitidos para mayor brevedad:
{
"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"
}
}
Paso 2: Obtener el estado de ejecución actual de una instrucción y el resultado de los datos como JSON
Puede usar el identificador de una instrucción SQL para obtener el estado de ejecución actual de esa instrucción y, si la ejecución se realizó correctamente, el resultado de esa instrucción. Si olvida el identificador de la instrucción, puede obtenerlo desde la sección Historial de consultas de la consola de Databricks SQL o mediante la llamada a Query History API. Por ejemplo, podría seguir sondeando este comando, comprobando cada vez para ver si la ejecución se ha realizado correctamente.
Para obtener el estado de ejecución actual de una instrucción SQL y, si la ejecución se realizó correctamente, el resultado de esa instrucción y un fragmento de dirección URL de API para obtener cualquier fragmento siguiente de datos JSON, ejecute el siguiente comando. Este comando asume que tiene una variable de entorno en su máquina de desarrollo local llamada SQL_STATEMENT_ID, que se establece en el valor del identificador de la instrucción SQL del paso anterior. Por supuesto, puede sustituir ${SQL_STATEMENT_ID} en el siguiente comando por el identificador codificado de forma rígida de la instrucción SQL.
CLI de Databricks
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
Reemplazar <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.
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
Si NEXT_CHUNK_INTERNAL_LINK se establece en un valor distinto de null, puede usarlo para obtener el siguiente fragmento de datos, etc., por ejemplo, con el siguiente comando:
CLI de Databricks
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
Reemplazar <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.
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
Puede seguir ejecutando el comando anterior, una y otra vez, para obtener el siguiente fragmento, etc. Tenga en cuenta que en cuanto se captura el último fragmento, se cierra la instrucción SQL. Después de este cierre, no puede usar el identificador de esa instrucción para obtener su estado actual o para capturar más fragmentos.
Paso 3: Obtención de resultados de gran tamaño mediante enlaces externos
Esta sección muestra una configuración opcional que utiliza la disposición EXTERNAL_LINKS para recuperar grandes conjuntos de datos. La ubicación predeterminada (disposición) para los datos de resultado de la instrucción SQL es dentro de la carga útil de la respuesta, pero estos resultados están limitados a 25 MiB. Al establecer el disposition a EXTERNAL_LINKS, la respuesta contiene URLs que puede utilizar para recuperar los trozos de los datos de resultados con HTTP estándar. Las URL apuntan al DBFS interno del área de trabajo, donde se almacenan temporalmente los fragmentos de resultados.
Advertencia
Databricks recomienda encarecidamente que proteja las URL y los tokens devueltos por la disposición EXTERNAL_LINKS.
Cuando se utiliza la disposición EXTERNAL_LINKS, se genera una URL de firma de acceso compartido (SAS), que puede utilizarse para descargar los resultados directamente del almacenamiento Azure. Como en esta URL SAS se incluye un token SAS de corta duración, debe proteger tanto la URL SAS como el token SAS.
Dado que las URL SAS ya se generan con tokens SAS temporales incrustados, no debe establecer un encabezado Authorization en las solicitudes de descarga.
La disposición EXTERNAL_LINKS puede deshabilitarse previa solicitud. Para realizar esta solicitud, cree un caso de soporte.técnico
Consulte también Procedimientos recomendados de seguridad.
Nota
El comportamiento y el formato de salida de la carga de respuesta, una vez establecidos para un identificador de instrucción SQL determinado, no se puede cambiar.
En este modo, la API permite almacenar datos de resultados en formato JSON (JSON), formato CSV (CSV) o formato de flecha de Apache (ARROW_STREAM), que se deben consultar por separado con HTTP. Además, al usar este modo, no es posible insertar los datos de resultado dentro de la carga de respuesta.
El siguiente comando muestra el uso EXTERNAL_LINKS y el formato de flecha de Apache. Utilice este patrón en lugar de la consulta similar demostrada en el paso 1:
CLI de Databricks
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
Reemplazar <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.
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
La respuesta es la siguiente:
{
"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"
}
}
Si la solicitud agota el tiempo de espera, la respuesta tiene este aspecto en su lugar:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Para obtener el estado de ejecución actual de esa instrucción y, si la ejecución se realizó correctamente, el resultado de esa instrucción, ejecute el comando siguiente.
CLI de Databricks
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Reemplazar <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.
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'
Si la respuesta es lo suficientemente grande (por ejemplo, en este caso, al ejecutar SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem sin límite de filas), la respuesta tendrá varios fragmentos, como en el ejemplo siguiente. Tenga en cuenta que "...": "..." indica los resultados omitidos para mayor brevedad:
{
"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"
}
}
Para descargar los resultados del contenido almacenado, puede ejecutar el siguiente comando curl, mediante la URL del objeto external_link y especificando dónde desea descargar el archivo. No incluya el token de Azure Databricks en este comando:
curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"
Para descargar un fragmento específico de los resultados de un contenido transmitido, puede usar uno de los siguientes:
- Valor
next_chunk_indexde la carga de respuesta del siguiente fragmento (si hay un fragmento siguiente). - Uno de los índices de fragmento del manifiesto de la carga de respuesta para cualquier fragmento disponible si hay varios fragmentos.
Por ejemplo, para obtener el fragmento con chunk_index de 10 para la respuesta anterior, ejecute el siguiente comando:
CLI de Databricks
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'
Reemplazar <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.
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'
Nota:
La ejecución del comando anterior devuelve una nueva URL SAS.
Para descargar el fragmento almacenado, utilice la URL del objeto external_link.
Para obtener más información sobre el formato de Apache Arrow, consulte:
Paso 4: Cancelar la ejecución de una instrucción SQL
Si necesita cancelar una instrucción SQL que aún no se ha realizado correctamente, ejecute el siguiente comando:
CLI de Databricks
databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'
Reemplazar <profile-name> por el nombre del perfil de configuración de Azure Databricks para la autenticación.
curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"
Recomendaciones de seguridad
La API de ejecución de sentencias SQL de Databricks aumenta la seguridad de las transferencias de datos mediante el uso de cifrado de capa de transporte (TLS) de extremo a otro y credenciales de corta duración, como los tokens SAS.
Hay varias capas en este modelo de seguridad. En la capa de transporte, solo es posible llamar a la API de ejecución de instrucciones de Databricks SQL usando TLS 1.2 o superior. Además, los llamadores de la API de ejecución de instrucciones SQL de Databricks deben autenticarse con un token de acceso personal de Azure Databricks válido o un token de Microsoft Entra ID (anteriormente Azure Active Directory) que se asigna a un usuario que tiene derecho a usar Databricks SQL. El usuario debe tener acceso CAN USE para el almacén SQL específico que se utiliza, y el acceso puede restringirse con listas de acceso IP. Esto se aplica a todas las solicitudes a la API de ejecución de sentencias SQL de Databricks. Además, para ejecutar sentencias, el usuario autenticado debe tener permiso para los objetos de datos (como tablas, vistas y funciones) que se utilizan en cada sentencia. Esto se aplica mediante los mecanismos de control de acceso existentes en Unity Catalog o mediante el uso de ACL de tablas. (Consulte Gobernanza de datos con Unity Catalog para obtener más detalles). Esto también significa que solo el usuario que ejecuta una sentencia puede realizar solicitudes de obtención de los resultados de la sentencia.
Databricks recomienda aplicar los siguientes procedimientos recomendados de seguridad siempre que se utilice la API de ejecución de sentencias SQL de Databricks junto con la disposición EXTERNAL_LINKS para recuperar grandes conjuntos de datos:
- Elimine el encabezado de autorización de Databricks para las solicitudes de almacenamiento de Azure.
- Protección de direcciones URL de SAS y tokens de SAS
La disposición EXTERNAL_LINKS puede desactivarse a petición mediante la creación de un caso de soporte. Para realizar esta solicitud, póngase en contacto con el equipo de la cuenta de Azure Databricks para crear un caso de soporte técnico.
Elimine el encabezado de autorización de Databricks para las solicitudes de almacenamiento de Azure.
Todas las llamadas a Databricks SQL Statement Execution API que se utilicen curldeben incluirAuthorization un encabezado que contenga las credenciales de acceso a Azure Databricks. No incluya este encabezado Authorization siempre que descargue datos del almacenamiento de Azure. Este encabezado no es necesario y podría exponer involuntariamente sus credenciales de acceso a Azure Databricks.
Protección de direcciones URL de SAS y tokens de SAS
Siempre que use la disposición EXTERNAL_LINKS, se genera una URL SAS de corta duración, que la persona que llama puede utilizar para descargar los resultados directamente desde el almacenamiento Azure mediante TLS. Como un token SAS de corta duración está incrustado dentro de esta URL SAS, debe proteger tanto la URL SAS como el token SAS.
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de