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 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 se rozhodnete použít Databricks CLI verze 0.205 nebo novější, musíte ho nakonfigurovat 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 chcete například provést ověření pomocí osobního přístupového tokenu Databricks, vytvořte osobní přístupový token následujícím způsobem:
- V pracovním prostoru Azure Databricks klikněte na své uživatelské jméno Azure Databricks v horním panelu a pak v rozevíracím seznamu vyberte Nastavení .
- Klikněte na Vývojář.
- Vedle přístupových tokenů klikněte na Spravovat.
- Klikněte na Vygenerovat nový token.
- (Volitelné) Zadejte komentář, který vám pomůže identifikovat tento token v budoucnu a změnit výchozí životnost tokenu na 90 dnů. Pokud chcete vytvořit token bez životnosti (nedoporučuje se), nechte pole Životnost (dny) prázdné (prázdné).
- Klikněte na Vygenerovat.
- Zkopírujte zobrazený token do zabezpečeného umístění a klikněte na tlačítko Hotovo.
Poznámka:
Nezapomeňte zkopírovaný token uložit do zabezpečeného umístění. Nesdílejte svůj zkopírovaný token s ostatními. Pokud ztratíte zkopírovaný token, nemůžete tento úplně stejný token znovu vygenerovat. Místo toho musíte tento postup zopakovat, abyste vytvořili nový token. Pokud ztratíte zkopírovaný token nebo se domníváte, že došlo k ohrožení zabezpečení tokenu, databricks důrazně doporučuje tento token okamžitě odstranit z pracovního prostoru kliknutím na ikonu koše (Odvolat) vedle tokenu na stránce Přístupové tokeny .
Pokud v pracovním prostoru nemůžete vytvářet nebo používat tokeny, může to být proto, že správce pracovního prostoru zakázal tokeny nebo vám neudělil oprávnění k vytváření nebo používání tokenů. Obraťte se na správce pracovního prostoru nebo následující:
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áteDEFAULTkonfigurační profil, tento postup přepíše stávajícíDEFAULTkonfigurační profil.Pokud chcete zkontrolovat, jestli už máte
DEFAULTkonfigurač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ďteDEFAULTčást--profile DEFAULTv následujícímdatabricks configurepříkazu jiným názvem konfiguračního profilu.Pomocí rozhraní příkazového řádku Databricks vytvořte konfigurační profil Azure Databricks s názvem
DEFAULT, 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 DEFAULTPro výzvu Databricks Host zadejte adresu URL azure Databricks pro jednotlivé pracovní prostory, například
https://adb-1234567890123456.7.azuredatabricks.net.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_IDprostř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. Můžete také přizpůsobit příklady tohoto kurzu
curlpro použití s podobnými nástroji, jako je Postman nebo HTTPie.V příkladech
curltohoto kurzu si poznamenejte následující:--header "Authorization: Bearer ${DATABRICKS_TOKEN}"Místo toho můžete použít soubor .netrc. Pokud používáte.netrcsoubor, 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
curlse 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_HOSTpředstavující název instance pracovního prostoru, napříkladadb-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 takto:
- V pracovním prostoru Azure Databricks klikněte na své uživatelské jméno Azure Databricks v horním panelu a pak v rozevíracím seznamu vyberte Nastavení .
- Klikněte na Vývojář.
- Vedle přístupových tokenů klikněte na Spravovat.
- Klikněte na Vygenerovat nový token.
- (Volitelné) Zadejte komentář, který vám pomůže identifikovat tento token v budoucnu a změnit výchozí životnost tokenu na 90 dnů. Pokud chcete vytvořit token bez životnosti (nedoporučuje se), nechte pole Životnost (dny) prázdné (prázdné).
- Klikněte na Vygenerovat.
- Zkopírujte zobrazený token do zabezpečeného umístění a klikněte na tlačítko Hotovo.
Poznámka:
Nezapomeňte zkopírovaný token uložit do zabezpečeného umístění. Nesdílejte svůj zkopírovaný token s ostatními. Pokud ztratíte zkopírovaný token, nemůžete tento úplně stejný token znovu vygenerovat. Místo toho musíte tento postup zopakovat, abyste vytvořili nový token. Pokud ztratíte zkopírovaný token nebo se domníváte, že došlo k ohrožení zabezpečení tokenu, databricks důrazně doporučuje tento token okamžitě odstranit z pracovního prostoru kliknutím na ikonu koše (Odvolat) vedle tokenu na stránce Přístupové tokeny .
Pokud v pracovním prostoru nemůžete vytvářet nebo používat tokeny, může to být proto, že správce pracovního prostoru zakázal tokeny nebo vám neudělil oprávnění k vytváření nebo používání tokenů. Obraťte se na správce pracovního prostoru nebo následující:
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
lineitemtabulce ve schématutpch(označované také jako databáze) vsampleskatalogu. 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í:
- 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ůlineitemtabulky ve schématusamplesvtcphkatalogu. - Uloží datovou část odpovědi ve formátu JSON do souboru pojmenovaného
sql-execution-response.jsonv aktuálním pracovním adresáři. - Vytiskne obsah
sql-execution-response.jsonsouboru. - 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ů. - 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 nanullhodnotu . - Vytiskne hodnoty proměnných
SQL_STATEMENT_IDprostředí aNEXT_CHUNK_INTERNAL_LINKpromě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íminameavalueobjekty vparameterspoli.typeVolitelně 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 mezi5a50sekundy včetně, například"50s". Chcete-li vrátit ID příkazu SQL a jeho aktuální stav okamžitě, nastavtewait_timeoutna0shodnotu .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říklad1000.Pokud chcete omezit počet vrácených řádků, můžete místo přidání
LIMITklauzule dostatementpož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, neborow_limitjetruncatedpole nastavené natruedatovou čá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.
Krok 3: Načtení velkých výsledků pomocí externích odkazů
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 .
Dispozii EXTERNAL_LINKS je možné na vyžádání zakázat. Pokud chcete tuto žádost provést, vytvořte případ 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_indexz 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 Databricks musí být také ověřeni pomocí platného tokenu pat Azure Databricks nebo tokenu Microsoft Entra ID (dříve Azure Active Directory), který se mapuje na uživatele, který má nárok na použití 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 a vytvořte případ podpory.
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.
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro