Sdílet prostřednictvím

Rozhraní API pro spouštění příkazů: Spuštění SQL ve skladech

  • Článek

Důležité

Pokud chcete získat přístup k rozhraním REST API služby Databricks, musíte použít ověřování.

V tomto kurzu se dozvíte, jak pomocí rozhraní API pro spouštění příkazů SQL databricks 2.0 spouštět příkazy SQL ze skladů SQL Databricks.

Pokud chcete zobrazit referenční informace k rozhraní API pro spouštění příkazů SQL Databricks 2.0, přečtěte si téma Provádění příkazů.

Než začnete

Než začnete s tímto kurzem, ujistěte se, že máte:

  • Rozhraní příkazového řádku Databricks verze 0.205 nebo novější nebo curlnásledující:

    • Rozhraní příkazového řádku Databricks je nástroj příkazového řádku pro odesílání a přijímání požadavků a odpovědí rozhraní REST API Databricks. Pokud používáte Rozhraní příkazového řádku Databricks verze 0.205 nebo vyšší, musí být nakonfigurované pro ověřování v pracovním prostoru Azure Databricks. Viz Instalace nebo aktualizace rozhraní příkazového řádku Databricks a ověřování pro Rozhraní příkazového řádku Databricks.

      Pokud například chcete provést ověření pomocí osobního přístupového tokenu Databricks, postupujte podle kroků v osobních přístupových tokenech Azure Databricks pro uživatele pracovního prostoru.

      Potom pomocí rozhraní příkazového řádku Databricks vytvořte konfigurační profil Azure Databricks pro váš osobní přístupový token následujícím postupem:

      Poznámka:

      Následující postup používá rozhraní příkazového řádku Databricks k vytvoření konfiguračního profilu Azure Databricks s názvem DEFAULT. Pokud už máte DEFAULT konfigurační profil, tento postup přepíše stávající DEFAULT konfigurační profil.

      Pokud chcete zkontrolovat, jestli už máte DEFAULT konfigurační profil, a pokud chcete zobrazit nastavení tohoto profilu, použijte k spuštění příkazu rozhraní databricks auth env --profile DEFAULTpříkazového řádku Databricks .

      Chcete-li vytvořit konfigurační profil s jiným názvem než DEFAULT, nahraďte DEFAULT část --profile DEFAULT v následujícím databricks configure příkazu jiným názvem konfiguračního profilu.

      1. Pomocí rozhraní příkazového řádku Databricks vytvořte konfigurační profil Azure Databricks s názvemDEFAULT, který používá ověřování tokenů pat Azure Databricks. Provedete to spuštěním následujícího příkazu:

        databricks configure --profile DEFAULT

      2. Pro výzvu Databricks Host

      3. V případě výzvy osobního přístupového tokenu zadejte osobní přístupový token Azure Databricks pro váš pracovní prostor.

      V příkladech Rozhraní příkazového řádku Databricks v tomto kurzu si všimněte následujících věcí:

      • V tomto kurzu se předpokládá, že na místním vývojovém počítači máte proměnnou DATABRICKS_SQL_WAREHOUSE_ID prostředí. Tato proměnná prostředí představuje ID vašeho databricks SQL Warehouse. Toto ID je řetězec písmen a číslic, které následují /sql/1.0/warehouses/ v poli cesta HTTP pro váš sklad. Informace o tom, jak získat hodnotu cesty HTTP vašeho skladu, najdete v tématu Získání podrobností o připojení pro výpočetní prostředek Azure Databricks.
      • Pokud místo příkazového prostředí systému Unix, Linux nebo macOS použijete příkazové prostředí Systému Windows, nahraďte \ ho ^a nahraďte ${...} ho .%...%
      • Pokud místo příkazového prostředí systému Unix, Linux nebo macOS použijete příkazové prostředí Windows, nahraďte v deklaracích dokumentů JSON otevírání a zavírání '"a nahraďte vnitřní " řetězcem \".

    • curl je nástroj příkazového řádku pro odesílání a přijímání požadavků a odpovědí rozhraní REST API. Viz také Instalace curl. Nebo přizpůsobte příklady tohoto kurzu curl pro použití s podobnými nástroji, jako je HTTPie.

      V příkladech curl tohoto kurzu si poznamenejte následující:

      • --header "Authorization: Bearer ${DATABRICKS_TOKEN}"Místo toho můžete použít soubor .netrc. Pokud používáte .netrc soubor, nahraďte --header "Authorization: Bearer ${DATABRICKS_TOKEN}" ho .--netrc
      • Pokud místo příkazového prostředí systému Unix, Linux nebo macOS použijete příkazové prostředí Systému Windows, nahraďte \ ho ^a nahraďte ${...} ho .%...%
      • Pokud místo příkazového prostředí systému Unix, Linux nebo macOS použijete příkazové prostředí Windows, nahraďte v deklaracích dokumentů JSON otevírání a zavírání '"a nahraďte vnitřní " řetězcem \".

      V příkladech tohoto kurzu curl se také předpokládá, že máte na místním vývojovém počítači následující proměnné prostředí:

      • DATABRICKS_HOST představující název instance pracovního prostoru, například adb-1234567890123456.7.azuredatabricks.net, pro váš pracovní prostor Azure Databricks.
      • DATABRICKS_TOKENpředstavuje token patu Azure Databricks pro uživatele pracovního prostoru Azure Databricks.
      • DATABRICKS_SQL_WAREHOUSE_IDpředstavuje ID vašeho databricks SQL Warehouse. Toto ID je řetězec písmen a číslic, které následují /sql/1.0/warehouses/ v poli cesta HTTP pro váš sklad. Informace o tom, jak získat hodnotu cesty HTTP vašeho skladu, najdete v tématu Získání podrobností o připojení pro výpočetní prostředek Azure Databricks.

      Poznámka:

      Osvědčeným postupem při ověřování pomocí automatizovaných nástrojů, systémů, skriptů a aplikací doporučuje Databricks místo uživatelů pracovního prostoru používat tokeny patního přístupu, které patří instančním objektům . Pokud chcete vytvořit tokeny pro instanční objekty, přečtěte si téma Správa tokenů instančního objektu.

      Pokud chcete vytvořit osobní přístupový token Azure Databricks, postupujte podle kroků v osobních přístupových tokenech Azure Databricks pro uživatele pracovního prostoru.

      Upozorňující

      Databricks důrazně nedoporučuje pevně kódovat informace do vašich skriptů, protože tyto citlivé informace mohou být zpřístupněny ve formátu prostého textu prostřednictvím systémů správy verzí. Databricks doporučuje používat přístupy, jako jsou proměnné prostředí nastavené na vývojovém počítači. Odebráním těchto pevně zakódovaných informací ze skriptů můžete tyto skripty usnadnit.

  • V tomto kurzu se předpokládá, že máte také procesor příkazového řádku pro dotazování datových částí odpovědí JSON, které rozhraní API pro spouštění příkazů SQL pro Databricks vrátí za každé volání, které provedete v rozhraní API pro spouštění příkazů SQL databricks. Viz Stáhnout jq.

  • Musíte mít aspoň jednu tabulku, pro kterou můžete spouštět příkazy SQL. Tento kurz je založený na lineitem tabulce ve schématu tpch (označované také jako databáze) v samples katalogu. Pokud nemáte přístup k tomuto katalogu, schématu nebo tabulce z pracovního prostoru, nahraďte je v tomto kurzu vlastním.

Krok 1: Provedení příkazu SQL a uložení výsledku dat ve formátu JSON

Spusťte následující příkaz, který provede následující:

  1. Použije zadaný SQL Warehouse spolu se zadaným tokenem, pokud používáte curl, k dotazování na tři sloupce z prvních dvou řádků lineitem tabulky ve schématu tcph v samples katalogu.
  2. Uloží datovou část odpovědi ve formátu JSON do souboru pojmenovaného sql-execution-response.json v aktuálním pracovním adresáři.
  3. Vytiskne obsah sql-execution-response.json souboru.
  4. Nastaví místní proměnnou prostředí s názvem SQL_STATEMENT_ID. Tato proměnná obsahuje ID odpovídajícího příkazu SQL. Toto ID příkazu SQL můžete použít k získání informací o tomto příkazu později podle potřeby, což je znázorněno v kroku 2. Tento příkaz SQL můžete také zobrazit a získat JEHO ID příkazu z části historie dotazů konzoly SQL Databricks nebo voláním rozhraní API historie dotazů.
  5. Nastaví další místní proměnnou prostředí s názvem NEXT_CHUNK_EXTERNAL_LINK , která obsahuje fragment adresy URL rozhraní API pro získání dalšího bloku dat JSON. Pokud jsou data odpovědi příliš velká, rozhraní API pro spouštění příkazů SQL databricks poskytuje odpověď v blocích dat. Tento fragment adresy URL rozhraní API můžete použít k získání dalšího bloku dat, který je ukázaný v kroku 2. Pokud neexistuje žádný další blok dat, je tato proměnná prostředí nastavena na nullhodnotu .
  6. Vytiskne hodnoty proměnných SQL_STATEMENT_ID prostředí a NEXT_CHUNK_INTERNAL_LINK proměnné prostředí.

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

Nahraďte <profile-name> názvem konfiguračního profilu Azure Databricks pro ověřování.

kudrna

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

V předchozím požadavku:

  • Parametrizované dotazy se skládají z názvu každého parametru dotazu, kterému předchází dvojtečka (například :extended_price) s odpovídajícími name a value objekty v parameters poli. type Volitelně je možné zadat také výchozí hodnotuSTRING, pokud není zadána.

    Upozorňující

    Databricks důrazně doporučuje používat parametry jako osvědčený postup pro příkazy SQL.

    Pokud používáte rozhraní API pro spouštění příkazů SQL Databricks s aplikací, která generuje SQL dynamicky, může to vést k útokům prostřednictvím injektáže SQL. Pokud například vygenerujete kód SQL na základě výběru uživatele v uživatelském rozhraní a nepřijmete příslušná opatření, útočník by mohl vložit škodlivý kód SQL, aby změnil logiku počátečního dotazu, a tím čtení, změnu nebo odstranění citlivých dat.

    Parametrizované dotazy pomáhají chránit před útoky prostřednictvím injektáže SQL tím, že zpracovávají vstupní argumenty odděleně od zbytku kódu SQL a interpretují tyto argumenty jako hodnoty literálů. Parametry také pomáhají s opětovnou použitelností kódu.

  • Ve výchozím nastavení jsou vrácené data ve formátu pole JSON a výchozí umístění pro výsledky dat příkazu SQL je v datové části odpovědi. Pokud chcete toto chování explicitně nastavit, přidejte "format":"JSON_ARRAY","disposition":"INLINE" do datové části požadavku. Pokud se pokusíte vrátit výsledky dat větší než 25 MiB v datové části odpovědi, vrátí se stav selhání a příkaz SQL se zruší. U výsledků dat větších než 25 MiB můžete místo pokusu o vrácení v datové části odpovědi použít externí odkazy, což je znázorněno v kroku 3.

  • Příkaz uloží obsah datové části odpovědi do místního souboru. Rozhraní API pro spouštění příkazů SQL služby Databricks nepodporuje místní úložiště dat.

  • Ve výchozím nastavení po 10 sekundách, pokud příkaz SQL ještě nedokončil provádění prostřednictvím skladu, vrátí rozhraní API pro provádění příkazů SQL Databricks pouze ID příkazu SQL a jeho aktuální stav místo výsledku příkazu. Chcete-li toto chování změnit, přidejte "wait_timeout" do požadavku a nastavte ho na "<x>s", kde <x> může být mezi 5 a 50 sekundy včetně, například "50s". Chcete-li vrátit ID příkazu SQL a jeho aktuální stav okamžitě, nastavte wait_timeout na 0shodnotu .

  • Ve výchozím nastavení se příkaz SQL bude dál spouštět, pokud dojde k dosažení časového limitu. Pokud chcete zrušit příkaz SQL, pokud je místo toho dosaženo časového limitu, přidejte "on_wait_timeout":"CANCEL" do datové části požadavku.

  • Pokud chcete omezit počet vrácených bajtů, přidejte "byte_limit" ho do požadavku a nastavte ho na počet bajtů, například 1000.

  • Pokud chcete omezit počet vrácených řádků, můžete místo přidání LIMIT klauzule do statementpožadavku přidat "row_limit" a nastavit ho na počet řádků, například "statement":"SELECT * FROM lineitem","row_limit":2.

  • Pokud je výsledek větší než zadaný byte_limit , nebo row_limitje truncated pole nastavené na true datovou část odpovědi.

Pokud je výsledek příkazu k dispozici před vypršením časového limitu čekání, odpověď je následující:

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

Pokud časový limit čekání skončí před dostupným výsledkem příkazu, bude odpověď vypadat takto:

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

Pokud jsou výsledná data příkazu příliš velká (například v tomto případě spuštěním SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), výsledná data se blokují a vypadají takto. Všimněte si, že "...": "..." zde jsou vynechány výsledky pro stručnost:

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

Krok 2: Získání aktuálního stavu spuštění příkazu a výsledku dat ve formátu JSON

Id příkazu SQL můžete použít k získání aktuálního stavu spuštění tohoto příkazu a výsledek tohoto příkazu, pokud bylo spuštění úspěšné. Pokud zapomenete ID příkazu, můžete ho získat v části historie dotazů konzoly SQL Databricks nebo voláním rozhraní API historie dotazů. Můžete například pokračovat v dotazování tohoto příkazu a pokaždé zkontrolovat, jestli spuštění proběhlo úspěšně.

Pokud chcete získat aktuální stav spuštění příkazu SQL a pokud bylo spuštění úspěšné, použijte výsledek tohoto příkazu a fragment adresy URL rozhraní API pro získání dalšího bloku dat JSON, spusťte následující příkaz. Tento příkaz předpokládá, že na místním vývojovém počítači máte proměnnou prostředí s názvem SQL_STATEMENT_ID, která je nastavená na hodnotu ID příkazu SQL z předchozího kroku. Samozřejmě můžete v následujícím příkazu nahradit ${SQL_STATEMENT_ID} pevně zakódované ID příkazu 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

Nahraďte <profile-name> názvem konfiguračního profilu Azure Databricks pro ověřování.

kudrna

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 Pokud je nastavená na jinounull hodnotu, můžete ji použít k získání dalšího bloku dat atd., například pomocí následujícího příkazu:

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

Nahraďte <profile-name> názvem konfiguračního profilu Azure Databricks pro ověřování.

kudrna

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

Předchozí příkaz můžete spustit znovu a znovu, abyste získali další blok dat atd. Všimněte si, že jakmile se načte poslední blok dat, příkaz SQL se zavře. Po tomto uzavření nemůžete id tohoto příkazu použít k získání aktuálního stavu nebo načtení dalších bloků dat.

Tato část ukazuje volitelnou konfiguraci, která používá EXTERNAL_LINKS k načtení velkých datových sad dispozici. Výchozí umístění (dispozice) pro data výsledku příkazu SQL je v datové části odpovědi, ale tyto výsledky jsou omezené na 25 MiB. Když nastavíte disposition hodnotu , EXTERNAL_LINKSodpověď obsahuje adresy URL, které můžete použít k načtení bloků dat výsledků se standardním protokolem HTTP. Adresy URL odkazují na interní dbFS vašeho pracovního prostoru, kde se dočasně ukládají bloky výsledků.

Upozorňující

Databricks důrazně doporučuje chránit adresy URL a tokeny, které jsou vráceny EXTERNAL_LINKS dispozicí.

Při použití EXTERNAL_LINKS dispozice se vygeneruje adresa URL sdíleného přístupového podpisu (SAS), která se dá použít ke stažení výsledků přímo z úložiště Azure. Vzhledem k tomu, že do této adresy URL SAS je vložen krátkodobý token SAS, měli byste chránit jak adresu URL SAS, tak token SAS.

Vzhledem k tomu, že adresy URL SAS se už generují s vloženými dočasnými tokeny SAS, nesmíte v žádostech o stažení nastavit hlavičku Authorization .

Dispozice EXTERNAL_LINKS může být na vyžádání zakázána vytvořením případu podpory.

Projděte si také osvědčené postupy zabezpečení.

Poznámka:

Výstupní formát a chování datové části odpovědi, jakmile jsou nastaveny pro konkrétní ID příkazu SQL, nelze změnit.

V tomto režimu rozhraní API umožňuje ukládat výsledná data ve formátu JSON (JSON), ve formátu CSV (CSV) nebo ve formátu Apache Arrow (ARROW_STREAM), které se musí dotazovat samostatně pomocí protokolu HTTP. Při použití tohoto režimu také není možné vložit výsledná data do datové části odpovědi.

Následující příkaz ukazuje použití EXTERNAL_LINKS a formát Apache Arrow. Místo podobného dotazu předvázaného v kroku 1 použijte tento vzor:

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

Nahraďte <profile-name> názvem konfiguračního profilu Azure Databricks pro ověřování.

kudrna

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

Odpověď je následující:

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

Pokud vyprší časový limit požadavku, odpověď vypadá takto:

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

Pokud chcete získat aktuální stav spuštění tohoto příkazu a pokud bylo spuštění úspěšné, spusťte následující příkaz:

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'

Nahraďte <profile-name> názvem konfiguračního profilu Azure Databricks pro ověřování.

kudrna

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'

Pokud je odpověď dostatečně velká (například spuštěním SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem bez limitu řádku), bude mít odpověď několik bloků dat, jak je znázorněno v následujícím příkladu níže. Všimněte si, že "...": "..." zde jsou vynechány výsledky pro stručnost:

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

Pokud chcete stáhnout výsledky uloženého obsahu, můžete spustit následující curl příkaz, použít adresu URL v objektu external_link a určit, kam chcete soubor stáhnout. Do tohoto příkazu nezahrnujte token Azure Databricks:

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

Pokud chcete stáhnout konkrétní blok výsledků streamovaného obsahu, můžete použít jednu z následujících možností:

  • Hodnota next_chunk_index z datové části odpovědi pro další blok dat (pokud existuje další blok dat).
  • Jeden z indexů bloků dat z manifestu datové části odpovědi pro všechny dostupné bloky dat, pokud existuje více bloků dat.

Pokud chcete například získat blok dat s chunk_index předchozí 10 odpovědí, spusťte následující příkaz:

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'

Nahraďte <profile-name> názvem konfiguračního profilu Azure Databricks pro ověřování.

kudrna

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'

Poznámka:

Spuštění předchozího příkazu vrátí novou adresu URL SAS.

Pokud chcete stáhnout uložený blok dat, použijte adresu URL v objektu external_link .

Další informace o formátu Apache Arrow najdete tady:

Krok 4: Zrušení spuštění příkazu SQL

Pokud potřebujete zrušit příkaz SQL, který ještě nebyl úspěšný, spusťte následující příkaz:

Databricks CLI

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

Nahraďte <profile-name> názvem konfiguračního profilu Azure Databricks pro ověřování.

kudrna

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

Osvědčené postupy zabezpečení

Rozhraní API pro spouštění příkazů SQL Databricks zvyšuje zabezpečení přenosů dat pomocí kompletního šifrování TLS (Transport Layer Security) a krátkodobých přihlašovacích údajů, jako jsou tokeny SAS.

V tomto modelu zabezpečení je několik vrstev. V přenosové vrstvě je možné volat pouze rozhraní API pro spouštění příkazů SQL databricks pomocí protokolu TLS 1.2 nebo vyšší. Volající rozhraní API pro spouštění příkazů SQL služby Databricks musí být také ověřeni pomocí platného tokenu pat azure Databricks, přístupového tokenu OAuth nebo tokenu Microsoft Entra ID (dříve Azure Active Directory), který se mapuje na uživatele, který má nárok na používání Databricks SQL. Tento uživatel musí mít přístup CAN USE pro konkrétní používaný SQL Warehouse a přístup je možné omezit pomocí přístupových seznamů IP adres. To platí pro všechny požadavky na rozhraní API pro spouštění příkazů SQL databricks. Kromě toho pro provádění příkazů musí ověřený uživatel mít oprávnění k datovým objektům (například tabulkám, zobrazením a funkcím), které se používají v každém příkazu. To se vynucuje existujícími mechanismy řízení přístupu v katalogu Unity nebo pomocí seznamů ACL tabulky. (Viz Další podrobnosti najdete v zásadách správného řízení dat pomocí katalogu Unity. ) To také znamená, že pouze uživatel, který provádí příkaz, může načíst požadavky na výsledky tohoto příkazu.

Databricks doporučuje následující osvědčené postupy zabezpečení při každém použití rozhraní API pro spouštění příkazů SQL databricks spolu s EXTERNAL_LINKS dispozici k načtení velkých datových sad:

  • Odebrání autorizační hlavičky Databricks pro žádosti o úložiště Azure
  • Ochrana adres URL SAS a tokenů SAS

Dispozice EXTERNAL_LINKS může být na vyžádání zakázána vytvořením případu podpory. Pokud chcete tuto žádost provést, obraťte se na tým účtu Azure Databricks.

Odebrání autorizační hlavičky Databricks pro žádosti o úložiště Azure

Všechna volání rozhraní API pro spouštění příkazů SQL Databricks, která se používají curl , musí obsahovat hlavičku Authorization , která obsahuje přihlašovací údaje pro přístup k Azure Databricks. Tuto Authorization hlavičku nezahrnujte při každém stahování dat z úložiště Azure. Tato hlavička není povinná a může neúmyslně zveřejnit přihlašovací údaje pro přístup k Azure Databricks.

Ochrana adres URL SAS a tokenů SAS

Při každém použití dispozice EXTERNAL_LINKS se vygeneruje krátkodobá adresa URL SAS, kterou může volající použít ke stažení výsledků přímo z úložiště Azure pomocí protokolu TLS. Vzhledem k tomu, že do této adresy URL SAS je vložen krátkodobý token SAS, měli byste chránit jak adresu URL SAS, tak token SAS.