Delen via

Uitvoerings-API voor instructies: SQL uitvoeren op magazijnen

  • Artikel

Belangrijk

U moet u verifiëren voor toegang tot Databricks-REST API's.

In deze zelfstudie leert u hoe u de Databricks SQL-instructieuitvoerings-API 2.0 gebruikt om SQL-instructies uit te voeren vanuit Databricks SQL-warehouses.

Zie De instructieuitvoering voor instructies voor de Databricks SQL-instructieuitvoerings-API 2.0 bekijken.

Voordat u begint

Voordat u aan deze zelfstudie begint, moet u ervoor zorgen dat u het volgende hebt:

  • Databricks CLI versie 0.205 of hoger of curl, als volgt:

    • De Databricks CLI is een opdrachtregelprogramma voor het verzenden en ontvangen van Databricks REST API-aanvragen en -antwoorden. Als u Databricks CLI versie 0.205 of hoger gebruikt, moet deze worden geconfigureerd voor verificatie met uw Azure Databricks-werkruimte. Zie De Databricks CLI en verificatie voor de Databricks CLI installeren of bijwerken.

      Als u bijvoorbeeld wilt verifiëren met persoonlijke toegangstokenverificatie van Databricks, volgt u de stappen op persoonlijke toegangstokens van Azure Databricks voor werkruimtegebruikers.

      Ga als volgt te werk om de Databricks CLI te gebruiken om een Azure Databricks-configuratieprofiel te maken voor uw persoonlijke toegangstoken:

      Notitie

      In de volgende procedure wordt de Databricks CLI gebruikt om een Azure Databricks-configuratieprofiel met de naam DEFAULTte maken. Als u al een DEFAULT configuratieprofiel hebt, overschrijft deze procedure uw bestaande DEFAULT configuratieprofiel.

      Als u wilt controleren of u al een DEFAULT configuratieprofiel hebt en de instellingen van dit profiel wilt weergeven als dit bestaat, gebruikt u de Databricks CLI om de opdracht databricks auth env --profile DEFAULTuit te voeren.

      Als u een configuratieprofiel wilt maken met een andere naam dan DEFAULT, vervangt u het DEFAULT deel van --profile DEFAULT de volgende databricks configure opdracht door een andere naam voor het configuratieprofiel.

      1. Gebruik de Databricks CLI om een Azure Databricks-configuratieprofiel te maken met de naam DEFAULT die gebruikmaakt van persoonlijke toegangstokenverificatie van Azure Databricks. Voer hiervoor de volgende opdracht uit:

        databricks configure --profile DEFAULT

      2. Voer voor de prompt databricks-host de URL van uw Azure Databricks per werkruimte in, bijvoorbeeldhttps://adb-1234567890123456.7.azuredatabricks.net.

      3. Voer het persoonlijke toegangstoken van Azure Databricks in voor uw werkruimte voor de prompt persoonlijke toegangstoken.

      In de Databricks CLI-voorbeelden van deze zelfstudie ziet u het volgende:

      • In deze zelfstudie wordt ervan uitgegaan dat u een omgevingsvariabele DATABRICKS_SQL_WAREHOUSE_ID hebt op uw lokale ontwikkelcomputer. Deze omgevingsvariabele vertegenwoordigt de id van uw Databricks SQL-warehouse. Deze id is de tekenreeks met letters en cijfers die volgen /sql/1.0/warehouses/ in het veld HTTP-pad voor uw magazijn. Zie Verbindingsgegevens ophalen voor een Azure Databricks-rekenresource voor meer informatie over het verkrijgen van de HTTP-padwaarde van uw warehouse.
      • Als u de Windows Command-shell gebruikt in plaats van een opdrachtshell voor Unix, Linux of macOS, vervangt u deze door \ ^en vervangt u deze ${...} %...%door .
      • Als u de Windows Command-shell gebruikt in plaats van een opdrachtshell voor Unix, Linux of macOS, vervangt u in JSON-documentdeclaraties het openen en sluiten ' door "en vervangt u de binnenste " \"door .

    • curl is een opdrachtregelprogramma voor het verzenden en ontvangen van REST API-aanvragen en -antwoorden. Zie ook Curl installeren. Of pas de voorbeelden van curl deze zelfstudie aan voor gebruik met vergelijkbare hulpprogramma's zoals HTTPie.

      In de voorbeelden van curl deze zelfstudie ziet u het volgende:

      • In plaats van --header "Authorization: Bearer ${DATABRICKS_TOKEN}"kunt u een .netrc-bestand gebruiken. Als u een .netrc bestand gebruikt, vervangt u door --header "Authorization: Bearer ${DATABRICKS_TOKEN}" --netrc.
      • Als u de Windows Command-shell gebruikt in plaats van een opdrachtshell voor Unix, Linux of macOS, vervangt u deze door \ ^en vervangt u deze ${...} %...%door .
      • Als u de Windows Command-shell gebruikt in plaats van een opdrachtshell voor Unix, Linux of macOS, vervangt u in JSON-documentdeclaraties het openen en sluiten ' door "en vervangt u de binnenste " \"door .

      Voor de voorbeelden van curl deze zelfstudie wordt in deze zelfstudie ook ervan uitgegaan dat u de volgende omgevingsvariabelen hebt op uw lokale ontwikkelcomputer:

      • DATABRICKS_HOST, dat de naam van het werkruimte-exemplaar vertegenwoordigt, bijvoorbeeld adb-1234567890123456.7.azuredatabricks.netvoor uw Azure Databricks-werkruimte.
      • DATABRICKS_TOKEN, dat een persoonlijk toegangstoken van Azure Databricks vertegenwoordigt voor de gebruiker van uw Azure Databricks-werkruimte.
      • DATABRICKS_SQL_WAREHOUSE_ID, die de id van uw Databricks SQL-warehouse vertegenwoordigt. Deze id is de tekenreeks met letters en cijfers die volgen /sql/1.0/warehouses/ in het veld HTTP-pad voor uw magazijn. Zie Verbindingsgegevens ophalen voor een Azure Databricks-rekenresource voor meer informatie over het verkrijgen van de HTTP-padwaarde van uw warehouse.

      Notitie

      Als best practice voor beveiliging, wanneer u zich verifieert met geautomatiseerde hulpprogramma's, systemen, scripts en apps, raadt Databricks u aan om persoonlijke toegangstokens te gebruiken die behoren tot service-principals in plaats van werkruimtegebruikers. Zie Tokens voor een service-principal beheren om tokens voor service-principals te maken.

      Als u een persoonlijk toegangstoken voor Azure Databricks wilt maken, volgt u de staps in persoonlijke toegangstokens van Azure Databricks voor werkruimtegebruikers.

      Waarschuwing

      Databricks ontmoedigt hard-coding-informatie in uw scripts, omdat deze gevoelige informatie in tekst zonder opmaak kan worden weergegeven via versiebeheersystemen. Databricks raadt u aan om in plaats daarvan benaderingen te gebruiken, zoals omgevingsvariabelen die u instelt op uw ontwikkelcomputer. Door dergelijke in code vastgelegde informatie uit uw scripts te verwijderen, kunt u deze scripts ook draagbaarder maken.

  • In deze zelfstudie wordt ervan uitgegaan dat u ook jq hebt, een opdrachtregelprocessor voor het uitvoeren van query's op JSON-antwoordpayloads, die de Databricks SQL-instructieuitvoerings-API naar u retourneert na elke aanroep die u maakt naar de Databricks SQL-instructieuitvoerings-API. Zie Jq downloaden.

  • U moet ten minste één tabel hebben waarop u SQL-instructies kunt uitvoeren. Deze zelfstudie is gebaseerd op de lineitem tabel in het tpch schema (ook wel een database genoemd) in de samples catalogus. Als u geen toegang hebt tot deze catalogus, schema of tabel vanuit uw werkruimte, vervangt u deze in deze zelfstudie door uw eigen zelfstudie.

Stap 1: Voer een SQL-instructie uit en sla het gegevensresultaat op als JSON

Voer de volgende opdracht uit. Dit doet u als volgt:

  1. Maakt gebruik van het opgegeven SQL-warehouse, samen met het opgegeven token als u gebruikt curl, om een query uit te voeren op drie kolommen uit de eerste twee rijen van de lineitem tabel in het tcph schema in de samples catalogus.
  2. Slaat de nettolading van het antwoord op in JSON-indeling in een bestand met de naam sql-execution-response.json in de huidige werkmap.
  3. Hiermee wordt de inhoud van het sql-execution-response.json bestand afgedrukt.
  4. Hiermee stelt u een lokale omgevingsvariabele in met de naam SQL_STATEMENT_ID. Deze variabele bevat de id van de bijbehorende SQL-instructie. U kunt deze SQL-instructie-id gebruiken om later informatie over die instructie op te halen. Dit wordt in stap 2 gedemonstreerd. U kunt deze SQL-instructie ook bekijken en de bijbehorende instructie-id ophalen uit de sectie querygeschiedenis van de Databricks SQL-console of door de Querygeschiedenis-API aan te roepen.
  5. Hiermee stelt u een extra lokale omgevingsvariabele NEXT_CHUNK_EXTERNAL_LINK in die een API-URL-fragment bevat voor het ophalen van het volgende segment JSON-gegevens. Als de antwoordgegevens te groot zijn, levert de Databricks SQL-instructieuitvoerings-API het antwoord in segmenten. U kunt dit API-URL-fragment gebruiken voor het ophalen van het volgende segment gegevens, dat wordt gedemonstreerd in stap 2. Als er geen volgende segment is, wordt deze omgevingsvariabele ingesteld op null.
  6. Hiermee worden de waarden van de SQL_STATEMENT_ID en NEXT_CHUNK_INTERNAL_LINK omgevingsvariabelen afgedrukt.

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

Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.

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

In de voorgaande aanvraag:

  • Geparameteriseerde query's bestaan uit de naam van elke queryparameter die wordt voorafgegaan door een dubbele punt (bijvoorbeeld :extended_price) met een overeenkomend name object in value de parameters matrix. Een optioneel type kan ook worden opgegeven, met de standaardwaarde van STRING indien niet opgegeven.

    Waarschuwing

    Databricks raadt u ten zeerste aan parameters te gebruiken als best practice voor uw SQL-instructies.

    Als u de Databricks SQL-instructieuitvoerings-API gebruikt met een toepassing die SQL dynamisch genereert, kan dit leiden tot SQL-injectieaanvallen. Als u bijvoorbeeld SQL-code genereert op basis van de selecties van een gebruiker in een gebruikersinterface en geen passende maatregelen neemt, kan een aanvaller schadelijke SQL-code injecteren om de logica van uw eerste query te wijzigen, waardoor gevoelige gegevens worden gelezen, gewijzigd of verwijdert.

    Geparameteriseerde query's beschermen tegen aanvallen met SQL-injecties door invoerargumenten afzonderlijk van de rest van uw SQL-code te verwerken en deze argumenten als letterlijke waarden te interpreteren. Parameters helpen ook bij het hergebruik van code.

  • Geretourneerde gegevens hebben standaard de JSON-matrixindeling en de standaardlocatie voor de gegevensresultaten van de SQL-instructie valt binnen de nettolading van het antwoord. Als u dit gedrag expliciet wilt maken, voegt u deze toe "format":"JSON_ARRAY","disposition":"INLINE" aan de nettolading van de aanvraag. Als u gegevensresultaten probeert te retourneren die groter zijn dan 25 MiB in de nettolading van het antwoord, wordt er een foutstatus geretourneerd en wordt de SQL-instructie geannuleerd. Voor gegevensresultaten die groter zijn dan 25 MiB, kunt u externe koppelingen gebruiken in plaats van deze te retourneren in de nettolading van het antwoord. Dit wordt gedemonstreerd in stap 3.

  • Met de opdracht wordt de inhoud van de nettolading van het antwoord opgeslagen in een lokaal bestand. Lokale gegevensopslag wordt niet rechtstreeks ondersteund door de Databricks SQL-instructieuitvoerings-API.

  • Als de SQL-instructie na 10 seconden nog niet is uitgevoerd via het warehouse, retourneert de Databricks SQL-instructieuitvoerings-API standaard alleen de SQL-instructie-id en de huidige status, in plaats van het resultaat van de instructie. Als u dit gedrag wilt wijzigen, voegt u deze toe "wait_timeout" aan de aanvraag en stelt u "<x>s"deze in op , waar <x> kan zich tussen 5 en 50 seconden bevinden, bijvoorbeeld "50s". Als u de SQL-instructie-id en de huidige status onmiddellijk wilt retourneren, stelt u deze in wait_timeout op 0s.

  • De SQL-instructie wordt standaard uitgevoerd als de time-outperiode is bereikt. Als u een SQL-instructie wilt annuleren als de time-outperiode is bereikt, voegt u deze toe "on_wait_timeout":"CANCEL" aan de nettolading van de aanvraag.

  • Als u het aantal geretourneerde bytes wilt beperken, voegt u deze toe "byte_limit" aan de aanvraag en stelt u deze in op het aantal bytes, bijvoorbeeld 1000.

  • Als u het aantal geretourneerde rijen wilt beperken in plaats van een LIMIT component toe te statementvoegen, kunt u deze toevoegen "row_limit" aan de aanvraag en instellen op het aantal rijen, bijvoorbeeld "statement":"SELECT * FROM lineitem","row_limit":2.

  • Als het resultaat groter is dan het opgegeven byte_limit of row_limit, wordt het truncated veld ingesteld op true in de nettolading van het antwoord.

Als het resultaat van de instructie beschikbaar is voordat de time-out van de wachttijd eindigt, is het antwoord als volgt:

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

Als de time-out voor de wachttijd eindigt voordat het resultaat van de instructie beschikbaar is, ziet het antwoord er als volgt uit:

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

Als de resultaatgegevens van de instructie te groot zijn (bijvoorbeeld in dit geval door uit te voeren SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), worden de resultaatgegevens gesegmenteerd en ziet dit er als volgt uit. Houd er rekening mee dat "...": "..." hier de weggelaten resultaten worden aangegeven voor beknoptheid:

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

Stap 2: de huidige uitvoeringsstatus en het gegevensresultaat van een instructie ophalen als JSON

U kunt de id van een SQL-instructie gebruiken om de huidige uitvoeringsstatus van die instructie op te halen en, als de uitvoering is geslaagd, is het resultaat van die instructie. Als u de id van de instructie vergeet, kunt u deze ophalen uit de sectie querygeschiedenis van de Databricks SQL-console of door de Querygeschiedenis-API aan te roepen. U kunt deze opdracht bijvoorbeeld blijven peilen en elke keer controleren of de uitvoering is geslaagd.

Voer de volgende opdracht uit om de huidige uitvoeringsstatus van een SQL-instructie op te halen en, als de uitvoering is geslaagd, het resultaat van die instructie en een API-URL-fragment voor het ophalen van een volgend segment van JSON-gegevens. Met deze opdracht wordt ervan uitgegaan dat u een omgevingsvariabele hebt op uw lokale ontwikkelcomputer met de naam SQL_STATEMENT_ID, die is ingesteld op de waarde van de id van de SQL-instructie uit de vorige stap. Natuurlijk kunt u in de volgende opdracht vervangen ${SQL_STATEMENT_ID} door de in code vastgelegde id van de SQL-instructie.

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

Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.

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

Als de NEXT_CHUNK_INTERNAL_LINK waarde is ingesteld op een niet-waardenull , kunt u deze gebruiken om het volgende gegevenssegment op te halen, enzovoort, bijvoorbeeld met de volgende opdracht:

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

Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.

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

U kunt de voorgaande opdracht steeds opnieuw uitvoeren om het volgende segment op te halen, enzovoort. Houd er rekening mee dat zodra het laatste segment is opgehaald, de SQL-instructie is gesloten. Na deze sluiting kunt u de id van die instructie niet gebruiken om de huidige status op te halen of om meer segmenten op te halen.

In deze sectie ziet u een optionele configuratie die gebruikmaakt van de EXTERNAL_LINKS verwijdering om grote gegevenssets op te halen. De standaardlocatie (verwijdering) voor de resultaatgegevens van de SQL-instructie bevindt zich binnen de nettolading van het antwoord, maar deze resultaten zijn beperkt tot 25 MiB. Door het disposition in te EXTERNAL_LINKSstellen, bevat het antwoord URL's die u kunt gebruiken om de segmenten van de resultatengegevens op te halen met standaard HTTP. De URL's verwijzen naar de interne DBFS van uw werkruimte, waarbij de resultaatsegmenten tijdelijk worden opgeslagen.

Waarschuwing

Databricks raadt u ten zeerste aan de URL's en tokens te beveiligen die door de EXTERNAL_LINKS verwijdering worden geretourneerd.

Wanneer u de EXTERNAL_LINKS verwijdering gebruikt, wordt er een SAS-URL (Shared Access Signature) gegenereerd, die kan worden gebruikt om de resultaten rechtstreeks vanuit Azure Storage te downloaden. Aangezien een kortdurende SAS-token is ingesloten in deze SAS-URL, moet u zowel de SAS-URL als het SAS-token beveiligen.

Omdat SAS-URL's al worden gegenereerd met ingesloten tijdelijke SAS-tokens, moet u geen header instellen Authorization in de downloadaanvragen.

De EXTERNAL_LINKS verwijdering kan op aanvraag worden uitgeschakeld door een ondersteuningsaanvraag te maken.

Zie ook aanbevolen procedures voor beveiliging.

Notitie

De uitvoerindeling en het gedrag van de nettolading van het antwoord, zodra deze zijn ingesteld voor een bepaalde SQL-instructie-id, kunnen niet worden gewijzigd.

In deze modus kunt u met de API resultaatgegevens opslaan in JSON-indeling (JSON), CSV-indeling (CSV) of Apache Arrow-indeling (ARROW_STREAM), die afzonderlijk moeten worden opgevraagd met HTTP. Wanneer u deze modus gebruikt, is het ook niet mogelijk om de resultaatgegevens binnen de nettolading van het antwoord inline te plaatsen.

De volgende opdracht demonstreert het gebruik en EXTERNAL_LINKS de Apache Arrow-indeling. Gebruik dit patroon in plaats van de vergelijkbare query die wordt gedemonstreerd in stap 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

Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.

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

Het antwoord is als volgt:

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

Als er een time-out optreedt voor de aanvraag, ziet het antwoord er als volgt uit:

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

Voer de volgende opdracht uit om de huidige uitvoeringsstatus van die instructie op te halen en voer de volgende opdracht uit als de uitvoering is geslaagd:

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'

Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.

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'

Als het antwoord groot genoeg is (bijvoorbeeld in dit geval door uit te voeren SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem zonder rijlimiet), heeft het antwoord meerdere segmenten, zoals in het volgende voorbeeld hieronder. Houd er rekening mee dat "...": "..." hier de weggelaten resultaten worden aangegeven voor beknoptheid:

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

Als u de resultaten van de opgeslagen inhoud wilt downloaden, kunt u de volgende curl opdracht uitvoeren met behulp van de URL in het external_link object en opgeven waar u het bestand wilt downloaden. Neem uw Azure Databricks-token niet op in deze opdracht:

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

Als u een specifiek segment van de resultaten van een gestreamde inhoud wilt downloaden, kunt u een van de volgende opties gebruiken:

  • De next_chunk_index waarde van de nettolading van het antwoord voor het volgende segment (als er een volgende segment is).
  • Een van de segmentindexen uit het manifest van de nettolading van het antwoord voor elk beschikbaar segment als er meerdere segmenten zijn.

Als u bijvoorbeeld het segment met een chunk_index van 10 het vorige antwoord wilt ophalen, voert u de volgende opdracht uit:

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'

Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.

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'

Notitie

Als u de voorgaande opdracht uitvoert, wordt een nieuwe SAS-URL geretourneerd.

Als u het opgeslagen segment wilt downloaden, gebruikt u de URL in het external_link object.

Zie voor meer informatie over de Apache Arrow-indeling:

Stap 4: de uitvoering van een SQL-instructie annuleren

Als u een SQL-instructie wilt annuleren die nog niet is geslaagd, voert u de volgende opdracht uit:

Databricks-CLI

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

Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.

curl

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

Aanbevolen procedures voor beveiliging

De Databricks SQL-instructieuitvoerings-API verhoogt de beveiliging van gegevensoverdracht met behulp van end-to-end TLS-versleuteling (Transport Layer Security) en kortstondige referenties zoals SAS-tokens.

Er zijn verschillende lagen in dit beveiligingsmodel. Op de transportlaag is het alleen mogelijk om de Databricks SQL-instructieuitvoerings-API aan te roepen met behulp van TLS 1.2 of hoger. Aanroepers van de Databricks SQL-instructieuitvoerings-API moeten ook worden geverifieerd met een geldig persoonlijk Azure Databricks-toegangstoken, OAuth-toegangstoken of Microsoft Entra ID-token (voorheen Azure Active Directory) dat is toegewezen aan een gebruiker die het recht heeft om Databricks SQL te gebruiken. Deze gebruiker moet CAN USE-toegang hebben voor het specifieke SQL Warehouse dat wordt gebruikt en toegang kan worden beperkt met IP-toegangslijsten. Dit geldt voor alle aanvragen voor de Databricks SQL-instructieuitvoerings-API. Bovendien moet de geverifieerde gebruiker voor het uitvoeren van instructies gemachtigd zijn voor de gegevensobjecten (zoals tabellen, weergaven en functies) die in elke instructie worden gebruikt. Dit wordt afgedwongen door bestaande mechanismen voor toegangsbeheer in Unity Catalog of met behulp van tabel-ACL's. (Zie Gegevensbeheer met Unity Catalog voor meer informatie.) Dit betekent ook dat alleen de gebruiker die een instructie uitvoert, aanvragen voor de resultaten van de instructie kan ophalen.

Databricks raadt de volgende aanbevolen beveiligingsprocedures aan wanneer u de Databricks SQL-instructieuitvoerings-API gebruikt, samen met de EXTERNAL_LINKS verwijdering om grote gegevenssets op te halen:

  • De Databricks-autorisatieheader voor Azure-opslagaanvragen verwijderen
  • SAS-URL's en SAS-tokens beveiligen

De EXTERNAL_LINKS verwijdering kan op aanvraag worden uitgeschakeld door een ondersteuningsaanvraag te maken. Neem contact op met uw Azure Databricks-accountteam om deze aanvraag te doen.

De Databricks-autorisatieheader voor Azure-opslagaanvragen verwijderen

Alle aanroepen naar de Databricks SQL-instructieuitvoerings-API die wordt gebruikt curl , moeten een Authorization header bevatten die Azure Databricks-toegangsreferenties bevat. Neem deze Authorization header niet op wanneer u gegevens downloadt uit Azure Storage. Deze header is niet vereist en kan onbedoeld uw Azure Databricks-toegangsreferenties beschikbaar maken.

SAS-URL's en SAS-tokens beveiligen

Wanneer u de EXTERNAL_LINKS verwijdering gebruikt, wordt er een KORTdurende SAS-URL gegenereerd, die de aanroeper kan gebruiken om de resultaten rechtstreeks vanuit Azure Storage te downloaden met behulp van TLS. Aangezien een kortdurende SAS-token is ingesloten in deze SAS-URL, moet u zowel de SAS-URL als het SAS-token beveiligen.