Condividi tramite

API di esecuzione dell'istruzione: eseguire SQL nei warehouse

  • Articolo

Importante

Per accedere alle API REST di Databricks, è necessario eseguire l'autenticazione.

Questa esercitazione illustra come usare l'API di esecuzione delle istruzioni SQL di Databricks 2.0 per eseguire istruzioni SQL da Databricks SQL Warehouse.

Per visualizzare le informazioni di riferimento sull'API di esecuzione di istruzioni SQL di Databricks 2.0, consultare Esecuzione di istruzioni.

Operazioni preliminari

Prima di iniziare questa esercitazione, assicurarsi di avere:

  • L'interfaccia della riga di comando di Databricks versione 0.205 o successiva o curl, come indicato di seguito:

    • L'interfaccia della riga di comando di Databricks è uno strumento da riga di comando per l'invio e la ricezione di richieste e risposte dell'API REST di Databricks. Se si usa l'interfaccia della riga di comando di Databricks versione 0.205 o successiva, è necessario configurarla per l'autenticazione con l'area di lavoro di Azure Databricks. Consultare Installare o aggiornare l'interfaccia della riga di comando di Databricks e l'autenticazione per l'interfaccia della riga di comando di Databricks.

      Ad esempio, per eseguire l'autenticazione con l'autenticazione del token di accesso personale di Databricks, seguire la procedura descritta in Token di accesso personale di Azure Databricks per gli utenti dell'area di lavoro.

      E quindi per usare l'interfaccia della riga di comando di Databricks per creare un profilo di configurazione di Azure Databricks per il token di accesso personale, eseguire le operazioni seguenti:

      Nota

      La procedura seguente usa l'interfaccia della riga di comando di Databricks per creare un profilo di configurazione di Azure Databricks con il nome DEFAULT. Se si dispone già di un DEFAULT profilo di configurazione, questa procedura sovrascrive il profilo di configurazione DEFAULT esistente.

      Per verificare se si dispone già di un DEFAULT profilo di configurazione e per visualizzare le impostazioni di questo profilo, usare l'interfaccia della riga di comando di Databricks per eseguire il comando databricks auth env --profile DEFAULT.

      Per creare un profilo di configurazione con un nome diverso da DEFAULT, sostituire la parte DEFAULT di --profile DEFAULT nel comando seguente databricks configure, come illustrato nel passaggio seguente, con un nome diverso per il profilo di configurazione.

      1. Usare l'interfaccia della riga di comando di Databricks per creare un profilo di configurazione di Azure Databricks denominato DEFAULT che usa l'autenticazione del token di accesso personale di Azure Databricks. A tale scopo, usare il comando seguente:

        databricks configure --profile DEFAULT

      2. Per il prompt dell'host Databricks immettere l'URL di Azure Databricks per area di lavoro, ad esempio https://adb-1234567890123456.7.azuredatabricks.net.

      3. Per il prompt del token di accesso personale immettere il token di accesso personale di Azure Databricks per l'area di lavoro.

      Negli esempi dell'interfaccia della riga di comando di Databricks di questa esercitazione tenere presente quanto segue:

      • Questa esercitazione presuppone che nel computer di sviluppo locale sia presente una variabile di ambiente DATABRICKS_SQL_WAREHOUSE_ID. Questa variabile di ambiente rappresenta l'ID del databricks SQL Warehouse. Questo ID è la stringa di lettere e numeri che seguono /sql/1.0/warehouses/ nel campo percorso HTTP per il warehouse. Per informazioni su come ottenere il valore del percorso HTTP del warehouse, consultare Ottenere i dettagli della connessione per una risorsa di calcolo di Azure Databricks.
      • Se si usa la shell dei comandi di Windows anziché una shell dei comandi per Unix, Linux o macOS, sostituire \ con ^ e sostituire ${...} con %...%.
      • Se si usa la shell dei comandi di Windows anziché una shell dei comandi per Unix, Linux o macOS, nelle dichiarazioni di documento JSON sostituire l'apertura e la chiusura ' con " e sostituire inner " con \".

    • curl è uno strumento da riga di comando per l'invio e la ricezione di richieste e risposte dell'API REST. Consultare anche Installare curl. In alternativa, adattare gli esempi di curl questa esercitazione per l'uso con strumenti simili, ad esempio HTTPie.

      Negli esempi di curl questa esercitazione si noti quanto segue:

      • Anziché --header "Authorization: Bearer ${DATABRICKS_TOKEN}", è possibile usare un file .netrc. Se si usa un file .netrc, sostituire --header "Authorization: Bearer ${DATABRICKS_TOKEN}" con --netrc.
      • Se si usa la shell dei comandi di Windows anziché una shell dei comandi per Unix, Linux o macOS, sostituire \ con ^ e sostituire ${...} con %...%.
      • Se si usa la shell dei comandi di Windows anziché una shell dei comandi per Unix, Linux o macOS, nelle dichiarazioni di documento JSON sostituire l'apertura e la chiusura ' con " e sostituire inner " con \".

      Inoltre, per gli esempi di questa esercitazione, questa esercitazione presuppone che nel computer di sviluppo locale siano presenti le variabili di ambiente seguenti curl:

      Nota

      Come procedura consigliata per la sicurezza, quando si esegue l'autenticazione con strumenti automatizzati, sistemi, script e app, Databricks consiglia di usare token di accesso personali appartenenti alle entità servizio, anziché agli utenti dell'area di lavoro. Per creare token per le entità servizio, consultare Gestire i token per un'entità servizio.

      Per creare un token di accesso personale di Azure Databricks, seguire i passaggi nei token di accesso personale di Azure Databricks per gli utenti dell'area di lavoro.

      Avviso

      Databricks sconsiglia vivamente le informazioni hardcoded negli script, perché queste informazioni riservate possono essere esposte in testo normale tramite sistemi di controllo della versione. Databricks consiglia di usare approcci come le variabili di ambiente impostate nel computer di sviluppo. La rimozione di tali informazioni hardcoded dagli script consente di rendere questi script più portabili.

  • Questa esercitazione presuppone che sia disponibile anche jq, un processore da riga di comando per l'esecuzione di query sui payload di risposta JSON, che l'API di esecuzione dell'istruzione SQL di Databricks torna all'utente dopo ogni chiamata eseguita all'API di esecuzione delle istruzioni SQL di Databricks. Consultare Download jq.

  • È necessario disporre di almeno una tabella su cui è possibile eseguire istruzioni SQL. Questa esercitazione si basa sulla tabella lineitem nello schema tpch (noto anche come database) all'interno del catalogo samples. Se non si ha accesso a questo catalogo, schema o tabella dall'area di lavoro, sostituirli in questa esercitazione con i propri.

Passaggio 1: eseguire un'istruzione SQL e salvare il risultato dei dati come JSON

Eseguire il comando seguente, che esegue le operazioni seguenti:

  1. Usa il warehouse SQL specificato, insieme al token specificato se si usa curl, per eseguire una query per tre colonne dalle prime due righe della tabella lineitem nello schema tcph all'interno del catalogo samples.
  2. Salva il payload della risposta in formato JSON in un file denominato sql-execution-response.json all'interno della directory di lavoro corrente.
  3. Stampa il contenuto del file sql-execution-response.json.
  4. Imposta una variabile di ambiente locale denominata SQL_STATEMENT_ID. Questa variabile contiene l'ID dell'istruzione SQL corrispondente. È possibile usare questo ID istruzione SQL per ottenere informazioni su tale istruzione in un secondo momento in base alle esigenze, come illustrato nel passaggio 2. È anche possibile visualizzare questa istruzione SQL e ottenere il relativo ID istruzione dalla sezione della cronologia delle query della console SQL di Databricks oppure chiamando l'API Cronologia query.
  5. Imposta una variabile di ambiente locale aggiuntiva denominata NEXT_CHUNK_EXTERNAL_LINK che contiene un frammento di URL API per ottenere il blocco successivo di dati JSON. Se i dati di risposta sono troppo grandi, l'API di esecuzione dell'istruzione SQL di Databricks fornisce la risposta in blocchi. È possibile usare questo frammento di URL dell’API per ottenere il blocco di dati successivo, illustrato nel passaggio 2. Se non è presente alcun blocco successivo, questa variabile di ambiente viene impostata su null.
  6. Stampa i valori delle variabili di ambiente SQL_STATEMENT_ID e 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

Sostituire <profile-name> con il nome del profilo di configurazione di Azure Databricks per l'autenticazione.

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

Nella richiesta precedente:

  • Le query con parametri sono costituite dal nome di ogni parametro di query preceduto da due punti (ad esempio, :extended_price) con un oggetto name e value corrispondente nella matrice parameters. È anche possibile specificare un valore facoltativo type, con il valore predefinito di STRING se non specificato.

    Avviso

    Databricks consiglia vivamente di usare i parametri come procedura consigliata per le istruzioni SQL.

    Se si usa l'API Esecuzione istruzioni SQL di Databricks con un'applicazione che genera SQL in modo dinamico, ciò può comportare attacchi SQL injection. Ad esempio, se si genera codice SQL in base alle selezioni di un utente in un'interfaccia utente e non si prendono misure appropriate, un utente malintenzionato potrebbe inserire codice SQL dannoso per modificare la logica della query iniziale, leggendo, modificando o eliminando dati sensibili.

    Le query con parametri consentono di proteggere gli attacchi SQL injection gestendo gli argomenti di input separatamente dal resto del codice SQL e interpretando questi argomenti come valori letterali. I parametri consentono anche di riutilizzare il codice.

  • Per impostazione predefinita, tutti i dati restituiti sono in formato matrice JSON e il percorso predefinito per uno dei risultati dei dati dell'istruzione SQL si trova all'interno del payload della risposta. Per rendere esplicito questo comportamento, aggiungere "format":"JSON_ARRAY","disposition":"INLINE" al payload della richiesta. Se si tenta di restituire risultati di dati superiori a 25 MiB nel payload della risposta, viene restituito uno stato di errore e l'istruzione SQL viene annullata. Per i risultati dei dati maggiori di 25 MiB, è possibile usare collegamenti esterni anziché tentare di restituirli nel payload della risposta, illustrato nel passaggio 3.

  • Il comando archivia il contenuto del payload della risposta in un file locale. L'archiviazione dati locale non è supportata direttamente dall'API di esecuzione delle istruzioni SQL di Databricks.

  • Per impostazione predefinita, dopo 10 secondi, se l'istruzione SQL non è ancora stata eseguita tramite il warehouse, l'API di esecuzione dell'istruzione SQL di Databricks restituisce solo l'ID istruzione SQL e il relativo stato corrente, anziché il risultato dell'istruzione. Per modificare questo comportamento, aggiungere "wait_timeout" alla richiesta e impostarlo su "<x>s", dove <x> può essere compreso tra 5 e 50 secondi inclusi, ad esempio "50s". Per restituire immediatamente l'ID istruzione SQL e il relativo stato corrente, impostare wait_timeout su 0s.

  • Per impostazione predefinita, l'istruzione SQL continua a essere eseguita se viene raggiunto il periodo di timeout. Per annullare un'istruzione SQL se viene raggiunto il periodo di timeout, aggiungere "on_wait_timeout":"CANCEL" al payload della richiesta.

  • Per limitare il numero di byte restituiti, aggiungere "byte_limit" alla richiesta e impostarlo sul numero di byte, ad esempio 1000.

  • Per limitare il numero di righe restituite, anziché aggiungere una LIMIT clausola a statement, è possibile aggiungerlo "row_limit" alla richiesta e impostarlo sul numero di righe, ad esempio "statement":"SELECT * FROM lineitem","row_limit":2.

  • Se il risultato è maggiore del valore specificato byte_limit o row_limit, il truncated campo viene impostato su true nel payload della risposta.

Se il risultato dell'istruzione è disponibile prima del termine del timeout di attesa, la risposta è la seguente:

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

Se il timeout di attesa termina prima che il risultato dell'istruzione sia disponibile, la risposta sarà simile alla seguente:

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

Se i dati dei risultati dell'istruzione sono troppo grandi, ad esempio in questo caso eseguendo SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000, i dati dei risultati vengono suddivisi in blocchi e hanno un aspetto simile al seguente. Si noti che "...": "..." indica i risultati omessi qui per brevità:

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

Passaggio 2: Ottenere lo stato di esecuzione corrente di un'istruzione e il risultato dei dati come JSON

È possibile usare l'ID di un'istruzione SQL per ottenere lo stato di esecuzione corrente dell'istruzione e, se l'esecuzione è riuscita, il risultato dell'istruzione. Se si dimentica l'ID dell'istruzione, è possibile ottenerlo dalla sezione della cronologia delle query della console SQL di Databricks o chiamando l'API Cronologia query. Ad esempio, è possibile continuare a eseguire il polling di questo comando, verificando ogni volta che l'esecuzione è riuscita.

Per ottenere lo stato di esecuzione corrente di un'istruzione SQL e, se l'esecuzione è riuscita, il risultato dell'istruzione e un frammento di URL dell'API per ottenere qualsiasi blocco successivo di dati JSON, eseguire il comando seguente. Questo comando presuppone che nel computer di sviluppo locale sia presente una variabile di ambiente denominata SQL_STATEMENT_ID, che è impostata sul valore dell'ID dell'istruzione SQL del passaggio precedente. Naturalmente, è possibile sostituire ${SQL_STATEMENT_ID} nel comando seguente con l'ID hardcoded dell'istruzione SQL.

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

Sostituire <profile-name> con il nome del profilo di configurazione di Azure Databricks per l'autenticazione.

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

Se NEXT_CHUNK_INTERNAL_LINK è impostato su un valore diverso da null, è possibile usarlo per ottenere il blocco successivo di dati e così via, ad esempio con il comando seguente:

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

Sostituire <profile-name> con il nome del profilo di configurazione di Azure Databricks per l'autenticazione.

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

È possibile continuare a eseguire nuovamente il comando precedente per ottenere il blocco successivo e così via. Si noti che non appena viene recuperato l'ultimo blocco, l'istruzione SQL viene chiusa. Dopo questa chiusura, non è possibile usare l'ID dell'istruzione per ottenere lo stato corrente o recuperare altri blocchi.

Questa sezione illustra una configurazione facoltativa che usa l'eliminazione EXTERNAL_LINKS per recuperare set di dati di grandi dimensioni. Il percorso predefinito (eliminazione) per i dati dei risultati dell'istruzione SQL è compreso nel payload della risposta, ma questi risultati sono limitati a 25 MiB. Impostando disposition su EXTERNAL_LINKS, la risposta contiene gli URL che è possibile usare per recuperare i blocchi dei dati dei risultati con HTTP standard. Gli URL puntano al file DBFS interno dell'area di lavoro, in cui i blocchi dei risultati vengono archiviati temporaneamente.

Avviso

Databricks consiglia vivamente di proteggere gli URL e i token restituiti dall'eliminazione EXTERNAL_LINKS.

Quando si usa l'eliminazione EXTERNAL_LINKS, viene generato un URL di firma di accesso condiviso (SAS), che può essere usato per scaricare i risultati direttamente dall'archiviazione di Azure. Poiché un token di firma di accesso condiviso di breve durata è incorporato in questo URL di firma di accesso condiviso, è necessario proteggere sia l'URL di firma di accesso condiviso che il token di firma di accesso condiviso.

Poiché gli URL di firma di accesso condiviso sono già generati con token di firma di accesso condiviso temporanei incorporati, non è necessario impostare un'intestazione Authorization nelle richieste di download.

L'eliminazione EXTERNAL_LINKS può essere disabilitata su richiesta creando un caso di supporto.

Consultare anche Procedure consigliate per la sicurezza.

Nota

Il formato e il comportamento dell'output del payload della risposta, una volta impostati per un ID istruzione SQL specifico, non possono essere modificati.

In questa modalità, l'API consente di archiviare i dati dei risultati in formato JSON (JSON), in formato CSV (CSV) o in formato Apache Arrow (ARROW_STREAM), che devono essere sottoposti a query separatamente con HTTP. Inoltre, quando si usa questa modalità, non è possibile integrare i dati dei risultati all'interno del payload della risposta.

Il comando seguente illustra l'uso di EXTERNAL_LINKS e del formato Apache Arrow. Usare questo modello anziché la query simile illustrata nel passaggio 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

Sostituire <profile-name> con il nome del profilo di configurazione di Azure Databricks per l'autenticazione.

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

Il formato della risposta è il seguente:

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

Se la richiesta raggiunge il timeout, la risposta sarà simile alla seguente:

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

Per ottenere lo stato di esecuzione corrente dell'istruzione e, se l'esecuzione ha avuto esito positivo, eseguire il comando seguente:

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'

Sostituire <profile-name> con il nome del profilo di configurazione di Azure Databricks per l'autenticazione.

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'

Se la risposta è sufficientemente grande ,ad esempio in questo caso, eseguendo SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem senza limiti di riga, la risposta avrà più blocchi, come nell'esempio seguente. Si noti che "...": "..." indica i risultati omessi qui per brevità:

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

Per scaricare i risultati del contenuto archiviato, è possibile eseguire il comando seguente curl, usando l'URL nell'oggetto external_link e specificando dove scaricare il file. Non includere il token di Azure Databricks in questo comando:

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

Per scaricare un blocco specifico dei risultati di un contenuto trasmesso, è possibile usare uno dei seguenti elementi:

  • Valore next_chunk_index del payload della risposta per il blocco successivo (se è presente un blocco successivo).
  • Uno degli indici di blocchi dal manifesto del payload della risposta per qualsiasi blocco disponibile se sono presenti più blocchi.

Ad esempio, per ottenere il blocco con una chunk_index di 10 della risposta precedente, eseguire il comando seguente:

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'

Sostituire <profile-name> con il nome del profilo di configurazione di Azure Databricks per l'autenticazione.

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

L'esecuzione del comando precedente restituisce un nuovo URL di firma di accesso condiviso.

Per scaricare il blocco archiviato, usare l'URL nell'oggetto external_link.

Per altre informazioni sul formato Apache Arrow, consultare:

Passaggio 4: annullare l'esecuzione di un'istruzione SQL

Se è necessario annullare un'istruzione SQL che non è ancora riuscita, eseguire il comando seguente:

Databricks CLI

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

Sostituire <profile-name> con il nome del profilo di configurazione di Azure Databricks per l'autenticazione.

curl

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

Procedure consigliate per la sicurezza

L'API di esecuzione delle istruzioni SQL di Databricks aumenta la sicurezza dei trasferimenti di dati usando la crittografia TLS (Transport Layer Security) end-to-end e le credenziali di breve durata, ad esempio i token di firma di accesso condiviso.

Esistono diversi livelli in questo modello di sicurezza. A livello di trasporto, è possibile chiamare solo l'API di esecuzione delle istruzioni SQL di Databricks usando TLS 1.2 o versione successiva. Inoltre, i chiamanti dell'API di esecuzione delle istruzioni SQL di Databricks devono essere autenticati con un token di accesso personale di Azure Databricks valido, un token di accesso OAuth o un token microsoft Entra ID (in precedenza Azure Active Directory) mappato a un utente che ha il diritto di usare Databricks SQL. L'utente deve disporre dell'accesso CAN USE per lo specifico SQL warehouse in uso e l'accesso può essere limitato con gli elenchi di accesso IP. Questo vale per tutte le richieste all'API di esecuzione di istruzioni SQL di Databricks. Inoltre, per l'esecuzione di istruzioni, l'utente autenticato deve disporre dell'autorizzazione per gli oggetti dati , ad esempio tabelle, viste e funzioni, usati in ogni istruzione. Questa operazione viene applicata dai meccanismi di controllo di accesso esistenti nel catalogo di Unity o tramite elenchi di controllo di accesso di tabella. (Consultare Governance dei dati con Unity Catalog per ulteriori dettagli). Ciò significa anche che solo l'utente che esegue un'istruzione può effettuare richieste di recupero per i risultati dell'istruzione.

Databricks consiglia le procedure consigliate per la sicurezza seguenti ogni volta che si usa l'API di esecuzione delle istruzioni SQL di Databricks insieme all'eliminazione EXTERNAL_LINKS per recuperare set di dati di grandi dimensioni:

  • Rimuovere l'intestazione di autorizzazione di Databricks per le richieste di archiviazione di Azure
  • Proteggere gli URL di firma di accesso condiviso e i token di firma di accesso condiviso

L'eliminazione EXTERNAL_LINKS può essere disabilitata su richiesta creando un caso di supporto. Per effettuare questa richiesta, contattare il team dell'account Azure Databricks.

Rimuovere l'intestazione di autorizzazione di Databricks per le richieste di archiviazione di Azure

Tutte le chiamate all'API di esecuzione di istruzioni SQL di Databricks che usano curl devono includere un'intestazione Authorization che contiene le credenziali di accesso di Azure Databricks. Non includere questa intestazione Authorization ogni volta che si scaricano dati da Archiviazione di Azure. Questa intestazione non è obbligatoria e potrebbe esporre involontariamente le credenziali di accesso di Azure Databricks.

Proteggere gli URL di firma di accesso condiviso e i token di firma di accesso condiviso

Ogni volta che si usa l'eliminazione EXTERNAL_LINKS, viene generato un URL di firma di accesso condiviso di breve durata, che il chiamante può usare per scaricare i risultati direttamente dall'archiviazione di Azure usando TLS. Poiché un token di firma di accesso condiviso di breve durata è incorporato in questo URL di firma di accesso condiviso, è necessario proteggere sia l'URL di firma di accesso condiviso che il token di firma di accesso condiviso.