Dela via

Instruktionskörnings-API: Kör SQL på lager

  • Artikel

Viktigt!

För att få åtkomst till Databricks REST API:er måste du autentisera.

Den här självstudien visar hur du använder Körnings-API 2.0 för Databricks SQL-instruktion för att köra SQL-instruktioner från Databricks SQL-lager.

Information om hur du visar REFERENS för Körning av API 2.0 för Databricks SQL-instruktion finns i Körning av instruktion.

Innan du börjar

Innan du påbörjar den här självstudien måste du se till att du har:

  • Antingen Databricks CLI version 0.205 eller senare eller curl, enligt följande:

    • Databricks CLI är ett kommandoradsverktyg för att skicka och ta emot Databricks REST API-begäranden och svar. Om du använder Databricks CLI version 0.205 eller senare måste den konfigureras för autentisering med din Azure Databricks-arbetsyta. Se Installera eller uppdatera Databricks CLI och autentisering för Databricks CLI.

      Om du till exempel vill autentisera med autentisering med personlig åtkomsttoken för Databricks följer du stegen i Personliga åtkomsttoken för Azure Databricks för arbetsyteanvändare.

      Gör sedan följande för att använda Databricks CLI för att skapa en Azure Databricks-konfigurationsprofil för din personliga åtkomsttoken:

      Kommentar

      Följande procedur använder Databricks CLI Om du redan har en DEFAULT konfigurationsprofil skriver den här proceduren över din befintliga DEFAULT konfigurationsprofil.

      Om du vill kontrollera om du redan har en DEFAULT konfigurationsprofil och visa profilens inställningar om den finns använder du Databricks CLI för att köra kommandot databricks auth env --profile DEFAULT.

      Om du vill skapa en konfigurationsprofil med ett annat namn än DEFAULTersätter du DEFAULT delen i --profile DEFAULT i följande databricks configure kommando med ett annat namn för konfigurationsprofilen.

      1. Använd Databricks CLI för att skapa en Azure Databricks-konfigurationsprofil med namnet DEFAULT som använder personlig åtkomsttokenautentisering i Azure Databricks. Gör detta genom att köra följande kommando:

        databricks configure --profile DEFAULT

      2. Ange url:en för Azure Databricks per arbetsyta för fråga Databricks-värden, till exempel https://adb-1234567890123456.7.azuredatabricks.net.

      3. För frågan Personlig åtkomsttoken anger du personlig åtkomsttoken för Azure Databricks för din arbetsyta.

      Observera följande i den här självstudiekursens Databricks CLI-exempel:

      • Den här självstudien förutsätter att du har en miljövariabel DATABRICKS_SQL_WAREHOUSE_ID på din lokala utvecklingsdator. Den här miljövariabeln representerar ID:t för ditt Databricks SQL-lager. Det här ID:t är strängen med bokstäver och siffror som följer /sql/1.0/warehouses/ i fältet HTTP-sökväg för ditt lager. Information om hur du hämtar ditt lagers HTTP-sökvägsvärde finns i Hämta anslutningsinformation för en Azure Databricks-beräkningsresurs.
      • Om du använder Windows-kommandogränssnittet i stället för ett kommandogränssnitt för Unix, Linux eller macOS ersätter \ du med ^och ersätter ${...} med %...%.
      • Om du använder Windows-kommandogränssnittet i stället för ett kommandogränssnitt för Unix, Linux eller macOS i JSON-dokumentdeklarationer ersätter du öppningen och stängningen ' med "och ersätter inre " med \".

    • curl är ett kommandoradsverktyg för att skicka och ta emot REST API-begäranden och svar. Se även Installera curl. Eller så kan du anpassa den här självstudiekursens curl exempel för användning med liknande verktyg som HTTPie.

      Observera följande i den här självstudiekursens curl exempel:

      • I stället --header "Authorization: Bearer ${DATABRICKS_TOKEN}"för kan du använda en .netrc-fil . Om du använder en .netrc fil ersätter du --header "Authorization: Bearer ${DATABRICKS_TOKEN}" med --netrc.
      • Om du använder Windows-kommandogränssnittet i stället för ett kommandogränssnitt för Unix, Linux eller macOS ersätter \ du med ^och ersätter ${...} med %...%.
      • Om du använder Windows-kommandogränssnittet i stället för ett kommandogränssnitt för Unix, Linux eller macOS i JSON-dokumentdeklarationer ersätter du öppningen och stängningen ' med "och ersätter inre " med \".

      För den här självstudiekursens curl exempel förutsätter den här självstudien också att du har följande miljövariabler på din lokala utvecklingsdator:

      • DATABRICKS_HOST, som representerar namnet på arbetsytans instans, till exempel adb-1234567890123456.7.azuredatabricks.net, för din Azure Databricks-arbetsyta.
      • DATABRICKS_TOKEN, som representerar en personlig åtkomsttoken för Azure Databricks för din Azure Databricks-arbetsyteanvändare.
      • DATABRICKS_SQL_WAREHOUSE_ID, som representerar ID:t för ditt Databricks SQL-lager. Det här ID:t är strängen med bokstäver och siffror som följer /sql/1.0/warehouses/ i fältet HTTP-sökväg för ditt lager. Information om hur du hämtar ditt lagers HTTP-sökvägsvärde finns i Hämta anslutningsinformation för en Azure Databricks-beräkningsresurs.

      Kommentar

      När du autentiserar med automatiserade verktyg, system, skript och appar rekommenderar Databricks att du använder personliga åtkomsttoken som tillhör tjänstens huvudnamn i stället för arbetsyteanvändare. Information om hur du skapar token för tjänstens huvudnamn finns i Hantera token för tjänstens huvudnamn.

      Om du vill skapa en personlig åtkomsttoken för Azure Databricks följer du staps i Personliga åtkomsttoken för Azure Databricks för arbetsyteanvändare.

      Varning

      Databricks avråder starkt från hårdkodning av information i dina skript, eftersom den här känsliga informationen kan exponeras i oformaterad text via versionskontrollsystem. Databricks rekommenderar att du använder metoder som miljövariabler som du anger på utvecklingsdatorn i stället. Om du tar bort sådan hårdkodad information från skripten kan du även göra skripten mer portabla.

  • Den här självstudien förutsätter att du också har jq, en kommandoradsprocessor för att köra frågor mot JSON-svarsnyttolaster, som Databricks SQL-instruktionskörnings-API:et returnerar till dig efter varje anrop som du gör till DATAbricks SQL-instruktionens körnings-API. Se Ladda ned jq.

  • Du måste ha minst en tabell som du kan köra SQL-instruktioner mot. Den här självstudien lineitem baseras på tabellen i tpch schemat (kallas även databas) i samples katalogen. Om du inte har åtkomst till den här katalogen, schemat eller tabellen från din arbetsyta ersätter du dem i den här självstudien med dina egna.

Steg 1: Kör en SQL-instruktion och spara dataresultatet som JSON

Kör följande kommando, vilket gör följande:

  1. Använder det angivna SQL-lagret, tillsammans med den angivna token om du använder curl, för att fråga efter tre kolumner från de två första raderna lineitem i tabellen i tcph schemat i samples katalogen.
  2. Sparar svarsnyttolasten i JSON-format i en fil med namnet sql-execution-response.json i den aktuella arbetskatalogen.
  3. Skriver ut innehållet i sql-execution-response.json filen.
  4. Anger en lokal miljövariabel med namnet SQL_STATEMENT_ID. Den här variabeln innehåller ID:t för motsvarande SQL-instruktion. Du kan använda det här SQL-instruktions-ID:t för att få information om den instruktionen senare efter behov, vilket visas i steg 2. Du kan också visa den här SQL-instruktionen och hämta dess instruktions-ID från frågehistorikavsnittet i Databricks SQL-konsolen, eller genom att anropa API:et för frågehistorik.
  5. Anger ytterligare en lokal miljövariabel med namnet NEXT_CHUNK_EXTERNAL_LINK som innehåller ett API URL-fragment för att hämta nästa segment av JSON-data. Om svarsdata är för stora tillhandahåller Databricks SQL-instruktionskörnings-API:et svaret i segment. Du kan använda det här API-URL-fragmentet för att hämta nästa datasegment, vilket visas i steg 2. Om det inte finns något nästa segment är den här miljövariabeln inställd på null.
  6. Skriver ut värdena för SQL_STATEMENT_ID miljövariablerna och 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

Ersätt <profile-name> med namnet på din Azure Databricks-konfigurationsprofil för autentisering.

hårlock

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

I föregående begäran:

  • Parametriserade frågor består av varje frågeparameters namn föregås av ett kolon (till exempel :extended_price) med matchning name och value objekt i matrisen parameters . Du kan också ange ett valfritt type värde med standardvärdet STRING om det inte har angetts.

    Varning

    Databricks rekommenderar starkt att du använder parametrar som bästa praxis för dina SQL-instruktioner.

    Om du använder KÖRNINGs-API:et för Databricks SQL-instruktion med ett program som genererar SQL dynamiskt kan detta resultera i SQL-inmatningsattacker. Om du till exempel genererar SQL-kod baserat på en användares val i ett användargränssnitt och inte vidtar lämpliga åtgärder, kan en angripare mata in skadlig SQL-kod för att ändra logiken i din första fråga och därmed läsa, ändra eller ta bort känsliga data.

    Parametriserade frågor hjälper till att skydda mot SQL-inmatningsattacker genom att hantera indataargument separat från resten av SQL-koden och tolka dessa argument som literalvärden. Parametrar hjälper också till med återanvändning av kod.

  • Som standard är alla returnerade data i JSON-matrisformat och standardplatsen för någon av SQL-instruktionens dataresultat ligger inom svarsnyttolasten. Om du vill göra det här beteendet explicit lägger du till "format":"JSON_ARRAY","disposition":"INLINE" i nyttolasten för begäran. Om du försöker returnera dataresultat som är större än 25 MiB i svarsnyttolasten returneras en felstatus och SQL-instruktionen avbryts. För dataresultat som är större än 25 MiB kan du använda externa länkar i stället för att försöka returnera dem i svarsnyttolasten, vilket visas i steg 3.

  • Kommandot lagrar svarsnyttolastens innehåll i en lokal fil. Lokal datalagring stöds inte direkt av Databricks SQL-instruktionskörnings-API:et.

  • Om SQL-instruktionen ännu inte har körts via informationslagret efter 10 sekunder returnerar Databricks SQL-instruktionskörnings-API:et endast SQL-instruktions-ID:t och dess aktuella status i stället för -instruktionens resultat. Om du vill ändra det här beteendet lägger du "wait_timeout" till i begäran och ställer in den på "<x>s", där <x> kan vara mellan 5 och 50 sekunder inklusive, till exempel "50s". Om du vill returnera SQL-instruktions-ID:t och dess aktuella status omedelbart anger du wait_timeout till 0s.

  • Som standard fortsätter SQL-instruktionen att köras om tidsgränsen nås. Om du vill avbryta en SQL-instruktion om tidsgränsen nås i stället lägger du till "on_wait_timeout":"CANCEL" i nyttolasten för begäran.

  • Om du vill begränsa antalet returnerade byte lägger du till "byte_limit" i begäran och anger det till antalet byte, till exempel 1000.

  • Om du vill begränsa antalet rader som returneras i stället för att lägga till en LIMIT sats i statementkan du lägga "row_limit" till i begäran och ange den till antalet rader, till exempel "statement":"SELECT * FROM lineitem","row_limit":2.

  • Om resultatet är större än angivet byte_limit eller row_limitanges truncated fältet till true i svarsnyttolasten.

Om -instruktionens resultat är tillgängligt innan tidsgränsen för väntetiden slutar är svaret följande:

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

Om tidsgränsen för väntetiden slutar innan instruktionens resultat är tillgängligt ser svaret ut så här i stället:

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

Om -instruktionens resultatdata är för stora (till exempel i det här fallet genom att köra SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), segmenteras resultatdata och ser ut så här i stället. Observera att "...": "..." anger utelämnade resultat här för korthet:

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

Steg 2: Hämta en instruktions aktuella körningsstatus och dataresultat som JSON

Du kan använda sql-instruktionens ID för att hämta instruktionens aktuella körningsstatus och, om körningen lyckades, instruktionens resultat. Om du glömmer instruktionens ID kan du hämta det från frågehistorikavsnittet i Databricks SQL-konsolen eller genom att anropa API:et för frågehistorik. Du kan till exempel fortsätta att avsöka det här kommandot och kontrollera varje gång för att se om körningen har lyckats.

Om du vill hämta en SQL-instruktions aktuella körningsstatus och, om körningen lyckades, den instruktionens resultat och ett API-URL-fragment för att hämta nästa segment av JSON-data kör du följande kommando. Det här kommandot förutsätter att du har en miljövariabel på din lokala utvecklingsdator med namnet SQL_STATEMENT_ID, som är inställd på värdet för ID:t för SQL-instruktionen från föregående steg. Du kan naturligtvis ersätta ${SQL_STATEMENT_ID} följande kommando med det hårdkodade ID:t för SQL-instruktionen.

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

Ersätt <profile-name> med namnet på din Azure Databricks-konfigurationsprofil för autentisering.

hårlock

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

NEXT_CHUNK_INTERNAL_LINK Om värdet är inställt på ett icke-värdenull kan du använda det för att hämta nästa datasegment, och så vidare, till exempel med följande kommando:

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

Ersätt <profile-name> med namnet på din Azure Databricks-konfigurationsprofil för autentisering.

hårlock

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

Du kan fortsätta att köra föregående kommando, om och om igen, för att hämta nästa segment och så vidare. Observera att sql-instruktionen stängs så snart det sista segmentet hämtas. Efter den här stängningen kan du inte använda instruktionens ID för att hämta dess aktuella status eller för att hämta fler segment.

Det här avsnittet visar en valfri konfiguration som använder borttagningen EXTERNAL_LINKS för att hämta stora datamängder. Standardplatsen (borttagning) för SQL-instruktionens resultatdata ligger inom svarsnyttolasten, men dessa resultat är begränsade till 25 MiB. Genom att ange disposition till EXTERNAL_LINKSinnehåller svaret URL:er som du kan använda för att hämta segmenten i resultatdata med standard-HTTP. URL:erna pekar på arbetsytans interna DBFS, där resultatsegmenten lagras tillfälligt.

Varning

Databricks rekommenderar starkt att du skyddar url:er och token som returneras av borttagningen EXTERNAL_LINKS .

När du använder borttagningen EXTERNAL_LINKS genereras en SAS-URL (signatur för delad åtkomst) som kan användas för att ladda ned resultatet direkt från Azure Storage. Eftersom en kortlivad SAS-token är inbäddad i den här SAS-URL:en bör du skydda både SAS-URL:en och SAS-token.

Eftersom SAS-URL:er redan har genererats med inbäddade tillfälliga SAS-token får du inte ange ett Authorization huvud i nedladdningsbegäranden.

Borttagningen EXTERNAL_LINKS kan inaktiveras på begäran genom att skapa ett supportärende.

Se även Metodtips för säkerhet.

Kommentar

Det går inte att ändra utdataformatet och beteendet för svarsnyttolasten när de har angetts för ett visst SQL-instruktions-ID.

I det här läget gör API:et att du kan lagra resultatdata i JSON-format (JSON), CSV-format (CSV) eller Apache Arrow-format (ARROW_STREAM), som måste frågas separat med HTTP. När du använder det här läget går det inte heller att infoga resultatdata i svarsnyttolasten.

Följande kommando visar hur du använder EXTERNAL_LINKS och Apache Arrow-format. Använd det här mönstret i stället för den liknande fråga som visas i steg 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

Ersätt <profile-name> med namnet på din Azure Databricks-konfigurationsprofil för autentisering.

hårlock

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

Svaret är följande:

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

Om begäran överskrider tidsgränsen ser svaret ut så här i stället:

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

Om du vill hämta instruktionens aktuella körningsstatus och, om körningen lyckades, instruktionens resultat kör du följande kommando:

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'

Ersätt <profile-name> med namnet på din Azure Databricks-konfigurationsprofil för autentisering.

hårlock

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'

Om svaret är tillräckligt stort (till exempel i det här fallet genom att köras SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem utan radgräns) har svaret flera segment, som i följande exempel nedan. Observera att "...": "..." anger utelämnade resultat här för korthet:

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

Om du vill ladda ned det lagrade innehållets resultat kan du köra följande curl kommando med hjälp av URL:en i external_link objektet och ange var du vill ladda ned filen. Inkludera inte din Azure Databricks-token i det här kommandot:

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

Om du vill ladda ned ett visst segment av ett strömmat innehålls resultat kan du använda något av följande:

  • Värdet next_chunk_index från svarsnyttolasten för nästa segment (om det finns ett nästa segment).
  • Ett av segmentindexen från svarsnyttolastens manifest för alla tillgängliga segment om det finns flera segment.

Om du till exempel vill hämta segmentet med ett chunk_index av 10 från föregående svar kör du följande kommando:

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'

Ersätt <profile-name> med namnet på din Azure Databricks-konfigurationsprofil för autentisering.

hårlock

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'

Kommentar

Om du kör föregående kommando returneras en ny SAS-URL.

Om du vill ladda ned det lagrade segmentet använder du URL:en i external_link objektet.

Mer information om Apache Arrow-formatet finns i:

Steg 4: Avbryt körningen av en SQL-instruktion

Om du behöver avbryta en SQL-instruktion som ännu inte har slutförts kör du följande kommando:

Databricks CLI

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

Ersätt <profile-name> med namnet på din Azure Databricks-konfigurationsprofil för autentisering.

hårlock

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

Metodtips för säkerhet

Körnings-API:et för Databricks SQL-instruktion ökar säkerheten för dataöverföringar med hjälp av TLS-kryptering (End-to-End Transport Layer Security) och kortlivade autentiseringsuppgifter, till exempel SAS-token.

Det finns flera lager i den här säkerhetsmodellen. På transportlagret är det bara möjligt att anropa DATAbricks SQL-instruktionens körnings-API med hjälp av TLS 1.2 eller senare. Anropare av Databricks SQL Statement Execution API måste också autentiseras med en giltig personlig åtkomsttoken för Azure Databricks, OAuth-åtkomsttoken eller Microsoft Entra-ID-token (tidigare Azure Active Directory) som mappar till en användare som har behörighet att använda Databricks SQL. Den här användaren måste ha CAN USE-åtkomst för det specifika SQL-lager som används och åtkomsten kan begränsas med IP-åtkomstlistor. Detta gäller för alla begäranden till KÖRNINGs-API:et för Databricks SQL-instruktion. För att köra instruktioner måste den autentiserade användaren dessutom ha behörighet till de dataobjekt (till exempel tabeller, vyer och funktioner) som används i varje instruktion. Detta framtvingas av befintliga mekanismer för åtkomstkontroll i Unity Catalog eller med hjälp av tabell-ACL:er. (Se Datastyrning med Unity Catalog för mer information.) Det innebär också att endast den användare som kör en instruktion kan hämta begäranden för -instruktionens resultat.

Databricks rekommenderar följande rekommenderade säkerhetsmetoder när du använder KÖRNINGs-API:et för Databricks SQL-instruktion tillsammans med borttagningen EXTERNAL_LINKS för att hämta stora datamängder:

  • Ta bort Databricks-auktoriseringshuvudet för Azure Storage-begäranden
  • Skydda SAS-URL:er och SAS-token

Borttagningen EXTERNAL_LINKS kan inaktiveras på begäran genom att skapa ett supportärende. Kontakta ditt Azure Databricks-kontoteam om du vill göra den här begäran.

Ta bort Databricks-auktoriseringshuvudet för Azure Storage-begäranden

Alla anrop till Körnings-API:et för Databricks SQL-instruktion som använder curl måste innehålla ett Authorization huvud som innehåller autentiseringsuppgifter för Azure Databricks-åtkomst. Inkludera inte den här Authorization rubriken när du laddar ned data från Azure Storage. Det här huvudet krävs inte och kan oavsiktligt exponera dina autentiseringsuppgifter för Azure Databricks-åtkomst.

Skydda SAS-URL:er och SAS-token

När du använder borttagningen EXTERNAL_LINKS genereras en kortlivad SAS-URL som anroparen kan använda för att ladda ned resultaten direkt från Azure Storage med hjälp av TLS. Eftersom en kortlivad SAS-token är inbäddad i den här SAS-URL:en bör du skydda både SAS-URL:en och SAS-token.