Sdílet prostřednictvím

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

Důležité

Pokud chcete získat přístup k rozhraním REST API služby Databricks, musíte provést ověření.

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 curl: ná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 pokynů v dokumentu Vytvoření osobních přístupových tokenů 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.

      Chcete-li zkontrolovat, zda již máte konfigurační profil DEFAULT a chcete-li zobrazit nastavení tohoto profilu, použijte příkazový řádek Databricks ke spuštění příkazu databricks auth env --profile DEFAULT.

      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í Databricks CLI vytvořte v Azure Databricks konfigurační profil s názvem, který používá ověřování pomocí osobního přístupového tokenu Azure Databricks. Provedete to spuštěním následujícího příkazu:

        databricks configure --profile DEFAULT

      2. Pro výzvu Databricks Host zadejte URL pro jednotlivé pracovní prostory Azure Databricks , například .

      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. Chcete-li zjistit, jak získat hodnotu HTTP cesty vašeho skladu, podívejte se na Podrobnosti o připojení k výpočetnímu prostředku služby 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 \ za ^ a nahraďte ${...} za %...%.
      • 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}" s --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 \ za ^ a nahraďte ${...} za %...%.
      • 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í:

      Poznámka:

      Jako bezpečnostní opatření při ověřování pomocí automatizovaných nástrojů, systémů, skriptů a aplikací doporučuje Databricks používat osobní přístupové tokeny, které patří služebním subjektům, místo uživatelů pracovního prostoru. 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 pokynů v návodu Vytvoření osobních přístupových tokenů pro uživatele pracovního prostoru.

      Varování

      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ů se tyto skripty stanou přenosnějšími.

  • V tomto kurzu se předpokládá, že máte také jq, procesor příkazového řádku pro dotazování JSON datových částí odpovědí, které rozhraní API pro spouštění SQL příkazů Databricks vrací po každém volání, které v tomto rozhraní provedete. 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ý datový sklad SQL spolu se zadaným tokenem, jestliže používáte curl, pro dotazování na tři sloupce z prvních dvou řádků v tabulce lineitem ve schématu tcph v katalogu samples.
  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í lokální 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 ID příkazu z části historie dotazů konzoly Databricks SQL 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 null.
  6. Vytiskne hodnoty proměnných prostředí SQL_STATEMENT_ID a NEXT_CHUNK_INTERNAL_LINK.

Příkazové rozhraní Databricks

databricks api post /api/2.0/sql/statements \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "2", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

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

kudrlina

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. Volitelně lze zadat type, přičemž pokud není zadáno, použije se výchozí hodnota STRING.

    Varování

    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 v Databricks přímo 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_limit, pak je pole truncated ve výstupní datové části odpovědi nastaveno na true.

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 jsou rozdělena na části 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 tento příkaz opakovaně dotazovat a pokaždé zkontrolovat, jestli bylo spuštění ú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 SQL dotazu.

Příkazové rozhraní Databricks

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

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

kudrlina

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:

Příkazové rozhraní Databricks

databricks api get /${NEXT_CHUNK_INTERNAL_LINK} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

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

kudrlina

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á dispozici EXTERNAL_LINKS k načtení velkých datových sad. 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 na EXTERNAL_LINKS, odpověď obsahuje adresy URL, které můžete použít k načtení částí dat výsledků pomocí standardního protokolu HTTP. Adresy URL odkazují na interní dbFS vašeho pracovního prostoru, kde se dočasně ukládají bloky výsledků.

Varování

Databricks důrazně doporučuje chránit adresy URL a tokeny vrácené operací EXTERNAL_LINKS.

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 .

Nastavení EXTERNAL_LINKS může být na vyžádání zakázáno založením požadavku na podporu.

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:

Příkazové rozhraní Databricks

databricks api post /api/2.0/sql/statements/ \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "format": "ARROW_STREAM",
  "disposition": "EXTERNAL_LINKS",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "100000", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID

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

kudrlina

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:

Příkazové rozhraní Databricks

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í.

kudrlina

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 část s chunk_index z předchozí 10 odpovědi, spusťte následující příkaz:

Příkazové rozhraní Databricks

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

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

kudrlina

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:

Příkazové rozhraní Databricks

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í.

kudrlina

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 Databricks SQL Statement Execution musí být také ověřeni pomocí platného osobního přístupového tokenu Azure Databricks, přístupového tokenu OAuth nebo tokenu Microsoft Entra ID (dříve Azure Active Directory), který se mapuje na uživatele, jenž má oprávnění k používání Databricks SQL. Tento uživatel musí mít přístup CAN USE ke konkrétnímu SQL Warehouse, který je používán, a přístup lze omezit pomocí seznamů přístupových IP adres. To platí pro všechny požadavky na rozhraní API Databricks pro spouštění SQL příkazů. 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. (Další podrobnosti najdete v tématu Zásady správného řízení dat v Azure Databricks .) 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í Databricks SQL Statement Execution API ve spojení s EXTERNAL_LINKS pro načtení velkých datových sad:

  • Odstraňte autorizační hlavičku Databricks ze žádostí o úložiště Azure
  • Ochrana adres URL SAS a tokenů SAS

Nastavení EXTERNAL_LINKS může být na vyžádání zakázáno založením požadavku na podporu. Pokud chcete tuto žádost provést, obraťte se na tým účtu Azure Databricks.

Odstraňte autorizační hlavičku Databricks ze žádostí o úložiště Azure

Všechna volání rozhraní API pro spouštění příkazů SQL Databricks, které používají curl, musí obsahovat hlavičku Authorization, která zahrnuje 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.

  • Last updated on