Interfejs API wykonywania instrukcji: uruchamianie bazy danych SQL w magazynach
Ważne
Aby uzyskać dostęp do interfejsów API REST, należy uwierzytelnić się.
W tym samouczku pokazano, jak używać interfejsu API wykonywania instrukcji SQL usługi Databricks 2.0 do uruchamiania instrukcji SQL z usługi Databricks SQL Warehouses.
Aby wyświetlić dokumentację interfejsu API wykonywania instrukcji SQL usługi Databricks 2.0, zobacz Wykonywanie instrukcji.
Zanim rozpoczniesz
Przed rozpoczęciem tego samouczka upewnij się, że masz następujące elementy:
Interfejs wiersza polecenia usługi Databricks w wersji 0.205 lub nowszej lub
curl, w następujący sposób:Interfejs wiersza polecenia usługi Databricks to narzędzie wiersza polecenia do wysyłania i odbierania żądań i odpowiedzi interfejsu API REST usługi Databricks. Jeśli zdecydujesz się używać interfejsu wiersza polecenia usługi Databricks w wersji 0.205 lub nowszej, należy go skonfigurować do uwierzytelniania w obszarze roboczym usługi Azure Databricks. Zobacz Instalowanie lub aktualizowanie interfejsu wiersza polecenia usługi Databricks i uwierzytelnianie dla interfejsu wiersza polecenia usługi Databricks.
Aby na przykład uwierzytelnić się przy użyciu uwierzytelniania osobistego tokenu dostępu usługi Databricks, utwórz osobisty token dostępu w następujący sposób:
- W obszarze roboczym usługi Azure Databricks kliknij nazwę użytkownika usługi Azure Databricks na górnym pasku, a następnie wybierz pozycję Ustawienia z listy rozwijanej.
- Kliknij pozycję Deweloper.
- Obok pozycji Tokeny dostępu kliknij pozycję Zarządzaj.
- Kliknij pozycję Generuj nowy token.
- (Opcjonalnie) Wprowadź komentarz, który pomaga zidentyfikować ten token w przyszłości i zmienić domyślny okres istnienia tokenu na 90 dni. Aby utworzyć token bez okresu istnienia (niezalecane), pozostaw puste pole Okres istnienia (dni) (puste).
- Kliknij pozycję Generate (Generuj).
- Skopiuj wyświetlony token do bezpiecznej lokalizacji, a następnie kliknij przycisk Gotowe.
Uwaga
Pamiętaj, aby zapisać skopiowany token w bezpiecznej lokalizacji. Nie udostępniaj skopiowanego tokenu innym osobom. W przypadku utraty skopiowanego tokenu nie można wygenerować tego samego tokenu. Zamiast tego należy powtórzyć tę procedurę, aby utworzyć nowy token. Jeśli utracisz skopiowany token lub uważasz, że token został naruszony, usługa Databricks zdecydowanie zaleca natychmiastowe usunięcie tego tokenu z obszaru roboczego, klikając ikonę kosza (Odwołaj) obok tokenu na stronie Tokeny dostępu.
Jeśli nie możesz utworzyć lub użyć tokenów w obszarze roboczym, może to być spowodowane tym, że administrator obszaru roboczego wyłączył tokeny lub nie udzielił Ci uprawnień do tworzenia lub używania tokenów. Zobacz administratora obszaru roboczego lub następujące elementy:
Następnie, aby użyć interfejsu wiersza polecenia usługi Databricks do utworzenia profilu konfiguracji usługi Azure Databricks dla osobistego tokenu dostępu, wykonaj następujące czynności:
Uwaga
Poniższa procedura używa interfejsu wiersza polecenia usługi Databricks do utworzenia profilu konfiguracji usługi Azure Databricks o nazwie
DEFAULT. Jeśli maszDEFAULTjuż profil konfiguracji, ta procedura zastępuje istniejącyDEFAULTprofil konfiguracji.Aby sprawdzić, czy masz
DEFAULTjuż profil konfiguracji i wyświetlić ustawienia tego profilu, jeśli istnieje, użyj interfejsu wiersza polecenia usługi Databricks, aby uruchomić poleceniedatabricks auth env --profile DEFAULT.Aby utworzyć profil konfiguracji o nazwie innej niż
DEFAULT, zastąpDEFAULTczęść w--profile DEFAULTponiższymdatabricks configurepoleceniu inną nazwą profilu konfiguracji.Użyj interfejsu wiersza polecenia usługi Databricks, aby utworzyć profil konfiguracji usługi Azure Databricks o nazwie
DEFAULTkorzystający z uwierzytelniania osobistego tokenu dostępu usługi Azure Databricks. Aby to zrobić, uruchom następujące polecenie:databricks configure --profile DEFAULTW przypadku monitu o host usługi Databricks wprowadź adres URL usługi Azure Databricks dla obszaru roboczego, na przykład
https://adb-1234567890123456.7.azuredatabricks.net.W przypadku monitu Osobisty token dostępu wprowadź osobisty token dostępu usługi Azure Databricks dla obszaru roboczego.
W przykładach interfejsu wiersza polecenia usługi Databricks w tym samouczku zwróć uwagę na następujące kwestie:
- W tym samouczku założono, że masz zmienną środowiskową
DATABRICKS_SQL_WAREHOUSE_IDna lokalnej maszynie dewelopera. Ta zmienna środowiskowa reprezentuje identyfikator usługi Databricks SQL Warehouse. Ten identyfikator to ciąg liter i cyfr w/sql/1.0/warehouses/polu Ścieżka HTTP dla magazynu. Aby dowiedzieć się, jak uzyskać wartość ścieżki HTTP magazynu, zobacz Pobieranie szczegółów połączenia dla zasobu obliczeniowego usługi Azure Databricks. - Jeśli używasz powłoki poleceń systemu Windows zamiast powłoki poleceń dla systemów Unix, Linux lub macOS, zastąp ciąg
\, i zastąp^%...%ciąg${...}. - Jeśli używasz powłoki poleceń systemu Windows zamiast powłoki poleceń dla systemów Unix, Linux lub macOS, w deklaracjach dokumentów JSON zastąp otwieranie i zamykanie
'ciągiem , a następnie zastąp"element wewnętrzny"ciągiem\".
curl to narzędzie wiersza polecenia do wysyłania i odbierania żądań i odpowiedzi interfejsu API REST. Zobacz też Artykuł Install curl (Instalowanie programu curl). Alternatywnie możesz dostosować przykłady tego samouczka
curldo użycia z podobnymi narzędziami, takimi jak Postman lub HTTPie.W przykładach tego samouczka
curlzwróć uwagę na następujące kwestie:--header "Authorization: Bearer ${DATABRICKS_TOKEN}"Zamiast programu można użyć pliku .netrc. Jeśli używasz pliku, zastąp.netrcciąg--header "Authorization: Bearer ${DATABRICKS_TOKEN}".--netrc- Jeśli używasz powłoki poleceń systemu Windows zamiast powłoki poleceń dla systemów Unix, Linux lub macOS, zastąp ciąg
\, i zastąp^%...%ciąg${...}. - Jeśli używasz powłoki poleceń systemu Windows zamiast powłoki poleceń dla systemów Unix, Linux lub macOS, w deklaracjach dokumentów JSON zastąp otwieranie i zamykanie
'ciągiem , a następnie zastąp"element wewnętrzny"ciągiem\".
Ponadto w przypadku przykładów tego samouczka
curlw tym samouczku założono, że masz następujące zmienne środowiskowe na lokalnej maszynie deweloperskiej:DATABRICKS_HOST, reprezentując nazwę wystąpienia obszaru roboczego, na przykładadb-1234567890123456.7.azuredatabricks.net, dla obszaru roboczego usługi Azure Databricks.DATABRICKS_TOKEN, reprezentując osobisty token dostępu usługi Azure Databricks dla użytkownika obszaru roboczego usługi Azure Databricks.DATABRICKS_SQL_WAREHOUSE_ID, reprezentując identyfikator usługi Databricks SQL Warehouse. Ten identyfikator to ciąg liter i cyfr w/sql/1.0/warehouses/polu Ścieżka HTTP dla magazynu. Aby dowiedzieć się, jak uzyskać wartość ścieżki HTTP magazynu, zobacz Pobieranie szczegółów połączenia dla zasobu obliczeniowego usługi Azure Databricks.
Uwaga
Najlepszym rozwiązaniem w zakresie zabezpieczeń w przypadku uwierzytelniania za pomocą zautomatyzowanych narzędzi, systemów, skryptów i aplikacji usługa Databricks zaleca używanie osobistych tokenów dostępu należących do jednostek usługi zamiast użytkowników obszaru roboczego. Aby utworzyć tokeny dla jednostek usługi, zobacz Zarządzanie tokenami dla jednostki usługi.
Aby utworzyć osobisty token dostępu usługi Azure Databricks, wykonaj następujące czynności:
- W obszarze roboczym usługi Azure Databricks kliknij nazwę użytkownika usługi Azure Databricks na górnym pasku, a następnie wybierz pozycję Ustawienia z listy rozwijanej.
- Kliknij pozycję Deweloper.
- Obok pozycji Tokeny dostępu kliknij pozycję Zarządzaj.
- Kliknij pozycję Generuj nowy token.
- (Opcjonalnie) Wprowadź komentarz, który pomaga zidentyfikować ten token w przyszłości i zmienić domyślny okres istnienia tokenu na 90 dni. Aby utworzyć token bez okresu istnienia (niezalecane), pozostaw puste pole Okres istnienia (dni) (puste).
- Kliknij pozycję Generate (Generuj).
- Skopiuj wyświetlony token do bezpiecznej lokalizacji, a następnie kliknij przycisk Gotowe.
Uwaga
Pamiętaj, aby zapisać skopiowany token w bezpiecznej lokalizacji. Nie udostępniaj skopiowanego tokenu innym osobom. W przypadku utraty skopiowanego tokenu nie można wygenerować tego samego tokenu. Zamiast tego należy powtórzyć tę procedurę, aby utworzyć nowy token. Jeśli utracisz skopiowany token lub uważasz, że token został naruszony, usługa Databricks zdecydowanie zaleca natychmiastowe usunięcie tego tokenu z obszaru roboczego, klikając ikonę kosza (Odwołaj) obok tokenu na stronie Tokeny dostępu.
Jeśli nie możesz utworzyć lub użyć tokenów w obszarze roboczym, może to być spowodowane tym, że administrator obszaru roboczego wyłączył tokeny lub nie udzielił Ci uprawnień do tworzenia lub używania tokenów. Zobacz administratora obszaru roboczego lub następujące elementy:
Ostrzeżenie
Usługa Databricks zdecydowanie odradza stałe kodowanie informacji do skryptów, ponieważ te poufne informacje mogą być widoczne w postaci zwykłego tekstu za pośrednictwem systemów kontroli wersji. Usługa Databricks zaleca użycie metod, takich jak zmienne środowiskowe ustawione na maszynie dewelopera. Usunięcie takich zakodowanych informacji ze skryptów pomaga zwiększyć przenośnie tych skryptów.
W tym samouczku przyjęto założenie, że masz również procesor wiersza polecenia do wykonywania zapytań o ładunki odpowiedzi JSON, do których interfejs API wykonywania instrukcji SQL usługi Databricks powraca po każdym wywołaniu do interfejsu API wykonywania instrukcji SQL usługi Databricks. Zobacz Pobieranie pliku jq.
Musisz mieć co najmniej jedną tabelę, dla której można wykonywać instrukcje SQL. Ten samouczek jest oparty na
lineitemtabeli w schemacietpch(znanym również jako baza danych) w wykaziesamples. Jeśli nie masz dostępu do tego wykazu, schematu lub tabeli z obszaru roboczego, zastąp je własnymi elementami w tym samouczku.
Krok 1. Wykonanie instrukcji SQL i zapisanie wyniku danych w formacie JSON
Uruchom następujące polecenie, które wykonuje następujące czynności:
- Używa określonego magazynu SQL, wraz z określonym tokenem, jeśli używasz
curlmetody , aby wykonać zapytanie o trzy kolumny z pierwszych dwóch wierszylineitemtabeli w schemacie wtcphwykaziesamples. - Zapisuje ładunek odpowiedzi w formacie JSON w pliku o nazwie
sql-execution-response.jsonw bieżącym katalogu roboczym. - Drukuje zawartość
sql-execution-response.jsonpliku. - Ustawia lokalną zmienną środowiskową o nazwie
SQL_STATEMENT_ID. Ta zmienna zawiera identyfikator odpowiadającej instrukcji SQL. Możesz użyć tego identyfikatora instrukcji SQL, aby uzyskać informacje o tej instrukcji później, zgodnie z potrzebami, co przedstawiono w kroku 2. Możesz również wyświetlić tę instrukcję SQL i uzyskać jej identyfikator instrukcji z sekcji historia zapytań konsoli SQL usługi Databricks lub wywołując interfejs API historii zapytań. - Ustawia dodatkową lokalną zmienną środowiskową o nazwie
NEXT_CHUNK_EXTERNAL_LINKzawierającą fragment adresu URL interfejsu API na potrzeby pobierania następnego fragmentu danych JSON. Jeśli dane odpowiedzi są zbyt duże, interfejs API wykonywania instrukcji SQL usługi Databricks udostępnia odpowiedź we fragmentach. Możesz użyć tego fragmentu adresu URL interfejsu API do pobrania następnego fragmentu danych, który przedstawiono w kroku 2. Jeśli nie ma następnego fragmentu, ta zmienna środowiskowa jest ustawiona nanullwartość . - Drukuje wartości
SQL_STATEMENT_IDzmiennych środowiskowych iNEXT_CHUNK_INTERNAL_LINK.
Interfejs wiersza polecenia usługi 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
Zastąp <profile-name> ciąg nazwą profilu konfiguracji usługi Azure Databricks na potrzeby uwierzytelniania.
Narzędzie Curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "2", "type": "INT" }
]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
W poprzednim żądaniu:
Zapytania parametryzowane składają się z nazwy każdego parametru zapytania poprzedzonego dwukropkiem (na przykład
:extended_price) z pasującymnameobiektem ivalueobiektem w tablicyparameters. Można również określić opcjonalny parametrtypez wartością domyślną , jeśli nie zostanie określonaSTRING.Ostrzeżenie
Usługa Databricks zdecydowanie zaleca używanie parametrów jako najlepszych rozwiązań dla instrukcji SQL.
Jeśli używasz interfejsu API wykonywania instrukcji SQL usługi Databricks z aplikacją, która dynamicznie generuje kod SQL, może to spowodować ataki polegających na wstrzyknięciu kodu SQL. Jeśli na przykład wygenerujesz kod SQL na podstawie wyboru użytkownika w interfejsie użytkownika i nie podejmujesz odpowiednich działań, osoba atakująca może wstrzyknąć złośliwy kod SQL, aby zmienić logikę początkowego zapytania, odczytując, zmieniając lub usuwając poufne dane.
Zapytania sparametryzowane pomagają chronić przed atakami polegającymi na wstrzyknięciu kodu SQL przez obsługę argumentów wejściowych niezależnie od pozostałej części kodu SQL i interpretowania tych argumentów jako wartości literału. Parametry pomagają również w ponownym użyciu kodu.
Domyślnie wszystkie zwrócone dane są w formacie tablicy JSON, a domyślna lokalizacja dowolnego wyniku danych instrukcji SQL znajduje się w ładunku odpowiedzi. Aby jawnie ustawić to zachowanie, dodaj
"format":"JSON_ARRAY","disposition":"INLINE"go do ładunku żądania. Jeśli spróbujesz zwrócić wyniki danych większe niż 25 miB w ładunku odpowiedzi, zostanie zwrócony stan niepowodzenia i instrukcja SQL zostanie anulowana. W przypadku wyników danych większych niż 25 MiB można użyć linków zewnętrznych zamiast próbować zwrócić je w ładunku odpowiedzi, który przedstawiono w kroku 3.Polecenie przechowuje zawartość ładunku odpowiedzi do pliku lokalnego. Magazyn danych lokalnych nie jest obsługiwany bezpośrednio przez interfejs API wykonywania instrukcji SQL usługi Databricks.
Domyślnie po 10 sekundach, jeśli instrukcja SQL nie zakończyła jeszcze wykonywania za pośrednictwem magazynu, interfejs API wykonywania instrukcji SQL usługi Databricks zwraca tylko identyfikator instrukcji SQL i jego bieżący stan, zamiast wyniku instrukcji. Aby zmienić to zachowanie, dodaj
"wait_timeout"do żądania i ustaw go na"<x>s", gdzie<x>może być między5i50sekundami włącznie, na przykład"50s". Aby natychmiast zwrócić identyfikator instrukcji SQL i jego bieżący stan, ustaw wartośćwait_timeout0s.Domyślnie instrukcja SQL nadal działa, jeśli osiągnięto limit czasu. Aby anulować instrukcję SQL, jeśli zamiast tego osiągnięto limit czasu, dodaj
"on_wait_timeout":"CANCEL"go do ładunku żądania.Aby ograniczyć liczbę zwracanych bajtów, dodaj
"byte_limit"do żądania i ustaw ją na liczbę bajtów, na przykład1000.Aby ograniczyć liczbę zwracanych wierszy, zamiast dodawać klauzulę
LIMITdostatement, możesz dodać"row_limit"do żądania i ustawić ją na liczbę wierszy, na przykład"statement":"SELECT * FROM lineitem","row_limit":2.Jeśli wynik jest większy niż określony
byte_limitlubrow_limit,truncatedpole jest ustawione natruewartość w ładunku odpowiedzi.
Jeśli wynik instrukcji jest dostępny przed upływem limitu czasu oczekiwania, odpowiedź jest następująca:
{
"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"
}
}
Jeśli limit czasu oczekiwania kończy się przed udostępnieniem wyniku instrukcji, odpowiedź wygląda następująco:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Jeśli dane wynikowe instrukcji są zbyt duże (na przykład w tym przypadku, uruchamiając polecenie SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), dane wynikowe są fragmentowane i wyglądają następująco. Zwróć uwagę, że "...": "..." w tym miejscu pominięto wyniki dla zwięzłości:
{
"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. Pobieranie bieżącego stanu wykonywania instrukcji i wyniku danych w formacie JSON
Możesz użyć identyfikatora instrukcji SQL, aby uzyskać bieżący stan wykonania tej instrukcji i, jeśli wykonanie zakończyło się pomyślnie, wynik tej instrukcji. Jeśli zapomnisz identyfikator instrukcji, możesz ją pobrać z sekcji historia zapytań konsoli SQL usługi Databricks lub wywołując interfejs API historii zapytań. Można na przykład kontynuować sondowanie tego polecenia, sprawdzając za każdym razem, czy wykonanie zakończyło się pomyślnie.
Aby uzyskać bieżący stan wykonywania instrukcji SQL i, jeśli wykonanie zakończyło się pomyślnie, wynik tej instrukcji i fragment adresu URL interfejsu API w celu pobrania dowolnego następnego fragmentu danych JSON uruchom następujące polecenie. To polecenie zakłada, że masz zmienną środowiskową na lokalnej maszynie programistycznej o nazwie SQL_STATEMENT_ID, która jest ustawiona na wartość identyfikatora instrukcji SQL z poprzedniego kroku. Oczywiście można zastąpić ${SQL_STATEMENT_ID} w poniższym poleceniu identyfikatorem zakodowanym w instrukcji SQL.
Interfejs wiersza polecenia usługi 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
Zastąp <profile-name> ciąg nazwą profilu konfiguracji usługi Azure Databricks na potrzeby uwierzytelniania.
Narzędzie Curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
NEXT_CHUNK_INTERNAL_LINK Jeśli właściwość jest ustawiona na wartość inną niżnull, możesz użyć jej do pobrania następnego fragmentu danych itd., na przykład za pomocą następującego polecenia:
Interfejs wiersza polecenia usługi 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
Zastąp <profile-name> ciąg nazwą profilu konfiguracji usługi Azure Databricks na potrzeby uwierzytelniania.
Narzędzie Curl
curl --request GET \
https://${DATABRICKS_HOST}${NEXT_CHUNK_INTERNAL_LINK} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
Możesz nadal uruchamiać poprzednie polecenie, w kóło, aby uzyskać następny fragment itd. Pamiętaj, że po pobraniu ostatniego fragmentu instrukcja SQL zostanie zamknięta. Po tym zamknięciu nie można użyć identyfikatora tej instrukcji, aby uzyskać jego bieżący stan lub pobrać więcej fragmentów.
Krok 3. Pobieranie dużych wyników przy użyciu linków zewnętrznych
W tej sekcji przedstawiono opcjonalną konfigurację, która używa dyspozycji do pobierania EXTERNAL_LINKS dużych zestawów danych. Domyślna lokalizacja (dyspozycja) danych wynikowych instrukcji SQL znajduje się w ładunku odpowiedzi, ale te wyniki są ograniczone do 25 MiB. Ustawiając wartość na dispositionEXTERNAL_LINKS, odpowiedź zawiera adresy URL, których można użyć do pobierania fragmentów danych wyników za pomocą standardowego protokołu HTTP. Adresy URL wskazują wewnętrzny system plików DBFS obszaru roboczego, w którym fragmenty wyników są tymczasowo przechowywane.
Ostrzeżenie
Usługa Databricks zdecydowanie zaleca ochronę adresów URL i tokenów zwracanych przez dyspozycję EXTERNAL_LINKS .
W przypadku korzystania z EXTERNAL_LINKS dyspozycji jest generowany adres URL sygnatury dostępu współdzielonego (SAS), który może służyć do pobierania wyników bezpośrednio z usługi Azure Storage. Ponieważ krótkotrwały token SAS jest osadzony w tym adresie URL sygnatury dostępu współdzielonego, należy chronić zarówno adres URL sygnatury dostępu współdzielonego, jak i token SAS.
Ponieważ adresy URL sygnatur dostępu współdzielonego są już generowane przy użyciu osadzonych tymczasowych tokenów SAS, nie można ustawić nagłówka Authorization w żądaniach pobierania.
Dyspozycję EXTERNAL_LINKS można wyłączyć na żądanie. Aby wysłać to żądanie, utwórz zgłoszenie do pomocy technicznej.
Zobacz również Najlepsze rozwiązania dotyczące zabezpieczeń.
Uwaga
Nie można zmienić formatu i zachowania ładunku odpowiedzi po ustawieniu dla określonego identyfikatora instrukcji SQL.
W tym trybie interfejs API umożliwia przechowywanie danych wynikowych w formacie JSON (), formacie CSV (JSON) lub formacie Apache Arrow (CSVARROW_STREAM), które muszą być odpytywane oddzielnie przy użyciu protokołu HTTP. Ponadto w przypadku korzystania z tego trybu nie można wyliniować danych wynikowych w ładunku odpowiedzi.
Poniższe polecenie demonstruje użycie formatu EXTERNAL_LINKS Apache Arrow i . Użyj tego wzorca zamiast podobnego zapytania przedstawionego w kroku 1:
Interfejs wiersza polecenia usługi 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
Zastąp <profile-name> ciąg nazwą profilu konfiguracji usługi Azure Databricks na potrzeby uwierzytelniania.
Narzędzie Curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"format": "ARROW_STREAM",
"disposition": "EXTERNAL_LINKS",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "100000", "type": "INT" }
]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID
Odpowiedź jest następująca:
{
"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"
}
}
Jeśli żądanie upłynął limit czasu, odpowiedź wygląda następująco:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Aby uzyskać bieżący stan wykonywania tej instrukcji i, jeśli wykonanie zakończyło się pomyślnie, wynik tej instrukcji uruchom następujące polecenie:
Interfejs wiersza polecenia usługi Databricks
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Zastąp <profile-name> ciąg nazwą profilu konfiguracji usługi Azure Databricks na potrzeby uwierzytelniania.
Narzędzie Curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Jeśli odpowiedź jest wystarczająco duża (na przykład w tym przypadku, uruchamiając SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem bez limitu wierszy), odpowiedź będzie zawierać wiele fragmentów, jak w poniższym przykładzie. Zwróć uwagę, że "...": "..." w tym miejscu pominięto wyniki dla zwięzłości:
{
"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"
}
}
Aby pobrać wyniki przechowywanej zawartości, możesz uruchomić następujące curl polecenie, używając adresu URL w external_link obiekcie i określając, gdzie chcesz pobrać plik. Nie dołączaj tokenu usługi Azure Databricks do tego polecenia:
curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"
Aby pobrać określony fragment wyników przesyłanej strumieniowo zawartości, możesz użyć jednej z następujących opcji:
- Wartość
next_chunk_indexz ładunku odpowiedzi dla następnego fragmentu (jeśli istnieje następny fragment). - Jeden z indeksów fragmentów z manifestu ładunku odpowiedzi dla dowolnego dostępnego fragmentu, jeśli istnieje wiele fragmentów.
Aby na przykład pobrać fragment z chunk_index10 poprzedniej odpowiedzi, uruchom następujące polecenie:
Interfejs wiersza polecenia usługi 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'
Zastąp <profile-name> ciąg nazwą profilu konfiguracji usługi Azure Databricks na potrzeby uwierzytelniania.
Narzędzie Curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Uwaga
Uruchomienie poprzedniego polecenia zwraca nowy adres URL sygnatury dostępu współdzielonego.
Aby pobrać przechowywany fragment, użyj adresu URL w external_link obiekcie .
Aby uzyskać więcej informacji na temat formatu apache Arrow, zobacz:
- Format przesyłania strumieniowego IPC
- Format zapisu i odczytywania przesyłania strumieniowego
- Korzystanie ze strumieni
Krok 4. Anulowanie wykonywania instrukcji SQL
Jeśli musisz anulować instrukcję SQL, która nie zakończyła się jeszcze pomyślnie, uruchom następujące polecenie:
Interfejs wiersza polecenia usługi Databricks
databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'
Zastąp <profile-name> ciąg nazwą profilu konfiguracji usługi Azure Databricks na potrzeby uwierzytelniania.
Narzędzie Curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"
Najlepsze rozwiązania dotyczące zabezpieczeń
Interfejs API wykonywania instrukcji SQL usługi Databricks zwiększa bezpieczeństwo transferów danych przy użyciu kompleksowego szyfrowania protokołu TLS (Transport Layer Security) i krótkotrwałych poświadczeń, takich jak tokeny SAS.
W tym modelu zabezpieczeń istnieje kilka warstw. W warstwie transportu można wywołać interfejs API wykonywania instrukcji SQL usługi Databricks przy użyciu protokołu TLS 1.2 lub nowszego. Ponadto osoby wywołujące interfejs API wykonywania instrukcji SQL usługi Databricks muszą być uwierzytelniane przy użyciu prawidłowego osobistego tokenu dostępu usługi Azure Databricks lub tokenu Microsoft Entra ID (dawniej Azure Active Directory), który jest mapowany na użytkownika, który ma uprawnienia do korzystania z usługi Databricks SQL. Ten użytkownik musi mieć dostęp CAN USE dla określonego używanego magazynu SQL, a dostęp można ograniczyć przy użyciu list dostępu do adresów IP. Dotyczy to wszystkich żądań interfejsu API wykonywania instrukcji SQL usługi Databricks. Ponadto w przypadku wykonywania instrukcji uwierzytelniony użytkownik musi mieć uprawnienia do obiektów danych (takich jak tabele, widoki i funkcje), które są używane w każdej instrukcji. Jest to wymuszane przez istniejące mechanizmy kontroli dostępu w wykazie aparatu Unity lub przy użyciu list ACL tabel. (Zobacz Aby uzyskać więcej informacji, zobacz Zarządzanie danymi za pomocą usługi Unity Catalog . Oznacza to również, że tylko użytkownik, który wykonuje instrukcję, może pobierać żądania dotyczące wyników instrukcji.
Usługa Databricks zaleca następujące najlepsze rozwiązania w zakresie zabezpieczeń za każdym razem, gdy używasz interfejsu API wykonywania instrukcji SQL usługi Databricks wraz z dyspozycją EXTERNAL_LINKS do pobierania dużych zestawów danych:
- Usuwanie nagłówka autoryzacji usługi Databricks dla żądań usługi Azure Storage
- Ochrona adresów URL sygnatur dostępu współdzielonego i tokenów SAS
Dyspozycję EXTERNAL_LINKS można wyłączyć na żądanie, tworząc zgłoszenie do pomocy technicznej. Aby wysłać to żądanie, skontaktuj się z zespołem konta usługi Azure Databricks, aby utworzyć zgłoszenie do pomocy technicznej.
Usuwanie nagłówka autoryzacji usługi Databricks dla żądań usługi Azure Storage
Wszystkie wywołania interfejsu API wykonywania instrukcji SQL usługi Databricks, które używają curl , muszą zawierać Authorization nagłówek zawierający poświadczenia dostępu usługi Azure Databricks. Nie dołączaj tego Authorization nagłówka za każdym razem, gdy pobierasz dane z usługi Azure Storage. Ten nagłówek nie jest wymagany i może przypadkowo uwidocznić poświadczenia dostępu do usługi Azure Databricks.
Ochrona adresów URL sygnatur dostępu współdzielonego i tokenów SAS
Za każdym razem, gdy używasz dyspozycji EXTERNAL_LINKS , jest generowany krótkotrwały adres URL sygnatury dostępu współdzielonego, którego obiekt wywołujący może użyć do pobrania wyników bezpośrednio z usługi Azure Storage przy użyciu protokołu TLS. Ponieważ krótkotrwały token SAS jest osadzony w tym adresie URL sygnatury dostępu współdzielonego, należy chronić zarówno adres URL sygnatury dostępu współdzielonego, jak i token SAS.
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla