Udostępnij za pomocą

Interfejs API wykonywania instrukcji: uruchamianie bazy danych SQL w magazynach

Ważne

Aby uzyskać dostęp do interfejsów Databricks 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 2.0 wykonania instrukcji SQL usługi Databricks, zapoznaj się z Statement Execution.

Zanim rozpoczniesz

Przed rozpoczęciem tego samouczka upewnij się, że masz następujące elementy:

  • Interfejs wiersza polecenia Databricks w wersji 0.205 lub nowszej lub curl, w następujący sposób:

    • Interfejs wiersza polecenia Databricks to narzędzie do wysyłania i odbierania żądań i odpowiedzi interfejsu API REST Databricks. Jeśli używasz 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, wykonaj kroki opisane w temacie Tworzenie osobistych tokenów dostępu dla użytkowników obszaru roboczego.

      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 Databricks CLI do stworzenia profilu konfiguracji Azure Databricks o nazwie . Jeśli masz DEFAULT już profil konfiguracji, ta procedura zastępuje istniejący DEFAULT profil konfiguracji.

      Aby sprawdzić, czy masz już profil konfiguracyjny DEFAULT i wyświetlić ustawienia tego profilu, jeśli istnieje, rozpocznij Databricks CLI, aby uruchomić polecenie databricks auth env --profile DEFAULT.

      Aby utworzyć profil konfiguracji o nazwie innej niż DEFAULT, zastąp część DEFAULT w poleceniu --profile DEFAULT poniżej inną nazwą profilu konfiguracji.

      1. Użyj Databricks CLI, aby utworzyć profil konfiguracji usługi Azure Databricks o nazwie , używający uwierzytelniania za pomocą osobistego tokenu dostępu Azure Databricks. Aby to zrobić, uruchom następujące polecenie:

        databricks configure --profile DEFAULT

      2. W polu monitu Host Databricks wprowadź swój URL przestrzeni roboczej Azure Databricks, na przykład https://adb-1234567890123456.7.azuredatabricks.net.

      3. W przypadku monitu Osobisty token dostępu wprowadź osobisty token dostępu usługi Azure Databricks dla swojego obszaru roboczego.

      W przykładach interfejsu wiersza polecenia usługi Databricks w tym samouczku zwróć uwagę na następujące kwestie:

      • Ten samouczek zakłada, że masz zmienną środowiskową DATABRICKS_SQL_WAREHOUSE_ID na lokalnej maszynie deweloperskiej. 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 dla swojego magazynu, zapoznaj się z Pobieraniem szczegółów połączenia dla zasobu obliczeniowego platformy Azure Databricks.
      • Jeśli używasz powłoki poleceń systemu Windows zamiast powłoki dla systemów Unix, Linux lub macOS, zamień \ na ^, a ${...} na %...%.
      • Jeśli używasz powłoki poleceń systemu Windows zamiast powłoki poleceń dla systemów Unix, Linux lub macOS, to w deklaracjach dokumentów JSON zastąp elementy otwierające i zamykające ' na ", a elementy wewnętrzne " na \".

    • 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). Możesz też dostosować przykłady tego samouczka curl do użycia z podobnymi narzędziami, takimi jak HTTPie.

      W przykładach tego samouczka curl zwróć uwagę na następujące kwestie:

      • Zamiast --header "Authorization: Bearer ${DATABRICKS_TOKEN}" można użyć pliku .netrc. Jeśli używasz pliku .netrc, zastąp --header "Authorization: Bearer ${DATABRICKS_TOKEN}"--netrc.
      • Jeśli używasz powłoki poleceń systemu Windows zamiast powłoki dla systemów Unix, Linux lub macOS, zamień \ na ^, a ${...} na %...%.
      • Jeśli używasz powłoki poleceń systemu Windows zamiast powłoki poleceń dla systemów Unix, Linux lub macOS, to w deklaracjach dokumentów JSON zastąp elementy otwierające i zamykające ' na ", a elementy wewnętrzne " na \".

      Ponadto w przypadku przykładów tego samouczka curl w 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ład adb-1234567890123456.7.azuredatabricks.net, dla obszaru roboczego usługi Azure Databricks.
      • DATABRICKS_TOKEN, reprezentujący osobisty token dostępu do 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 dla swojego magazynu, zapoznaj się z Pobieraniem szczegółów połączenia dla zasobu obliczeniowego platformy Azure Databricks.

      Uwaga

      Najlepsza praktyka w zakresie zabezpieczeń zalecana przez Databricks w przypadku uwierzytelniania za pomocą zautomatyzowanych narzędzi, systemów, skryptów i aplikacji to 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, postępuj zgodnie z instrukcjami w artykule Tworzenie osobistych tokenów dostępu dla użytkowników obszaru roboczego.

      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. Databricks zaleca zamiast tego korzystanie z metod takich jak zmienne środowiskowe, które ustawiasz na swoim komputerze deweloperskim. Usunięcie takich twardo zakodowanych informacji ze skryptów pomaga zwiększyć przenośność tych skryptów.

  • W tym samouczku przyjęto założenie, że masz jq, procesor wiersza poleceń do wykonywania zapytań o ładunki odpowiedzi JSON, które interfejs API wykonywania instrukcji SQL usługi Databricks zwraca po każdym wywołaniu. Zobacz Pobieranie pliku jq.

  • Musisz mieć co najmniej jedną tabelę, dla której można wykonywać instrukcje SQL. Ten samouczek jest oparty na tabeli lineitem w schemacie tpch (znanym również jako baza danych) w katalogu samples. 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:

  1. Używa określonego magazynu SQL wraz z określonym tokenem, jeśli używasz curl, aby wyszukać trzy kolumny z pierwszych dwóch wierszy tabeli lineitem w schemacie tcph w katalogu samples.
  2. Zapisuje ładunek odpowiedzi w formacie JSON w pliku o nazwie sql-execution-response.json w bieżącym katalogu roboczym.
  3. Drukuje zawartość sql-execution-response.json pliku.
  4. 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 z sekcji Historia zapytań konsoli SQL usługi Databricks lub wywołując Historię zapytań API .
  5. Ustawia dodatkową lokalną zmienną środowiskową o nazwie NEXT_CHUNK_EXTERNAL_LINK zawierają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 na null.
  6. Drukuje wartości zmiennych środowiskowych SQL_STATEMENT_ID i NEXT_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> nazwą profilu konfiguracji usługi Azure Databricks dla uwierzytelniania.

lok

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) oraz odpowiadających im obiektów name i value w tablicy parameters. Można również określić opcjonalny type, z domyślną wartością STRING w przypadku, gdy nie zostanie on określony.

    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, obsługując argumenty wejściowe niezależnie od pozostałej części kodu SQL i interpretując te argumenty jako wartości literalne. 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 wyraźnie zaznaczyć to zachowanie, dodaj "format":"JSON_ARRAY","disposition":"INLINE" do ładunku żądania. Jeśli spróbujesz zwrócić wyniki danych większe niż 25 MiB w treści odpowiedzi, zostanie zwrócony status niepowodzenia, a 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. Lokalne przechowywanie danych nie jest bezpośrednio obsługiwane przez interfejs API wykonywania zapytań 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 wartość "<x>s", gdzie <x> może znajdować się między 5 a 50 sekundami włącznie, na przykład "50s". Aby natychmiast zwrócić identyfikator instrukcji SQL i jego bieżący stan, ustaw wait_timeout na 0s.

  • Domyślnie instrukcja SQL nadal działa, jeśli osiągnięto limit czasu. Aby anulować instrukcję SQL, jeśli został osiągnięty limit czasu, dodaj "on_wait_timeout":"CANCEL" do treści żądania.

  • Aby ograniczyć liczbę zwróconych bajtów, dodaj "byte_limit" do żądania i ustaw ją na liczbę bajtów, na przykład 1000.

  • Aby ograniczyć liczbę zwracanych wierszy, zamiast dodawać klauzulę LIMIT do statement, 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ślono w byte_limit lub row_limit, pole truncated w treści odpowiedzi jest ustawione na true.

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ć monitorowanie 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 deweloperów 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> nazwą profilu konfiguracji usługi Azure Databricks dla uwierzytelniania.

lok

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

Jeśli NEXT_CHUNK_INTERNAL_LINK 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> nazwą profilu konfiguracji usługi Azure Databricks dla uwierzytelniania.

lok

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 wielokrotnie uruchamiać poprzednie polecenie, w kółko, by otrzymać następny fragment, i tak dalej. Pamiętaj, że po pobraniu ostatniego fragmentu instrukcja SQL zostanie zamknięta. Po tym zamknięciu nie można użyć identyfikatora instrukcji, aby uzyskać jej bieżący stan ani pobrać więcej fragmentów.

W tej sekcji przedstawiono opcjonalną konfigurację, która używa mechanizmu EXTERNAL_LINKS do pobierania 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ż token SAS o krótkim czasie działania jest osadzony w tym URL SAS, należy chronić zarówno URL SAS, 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, tworząc zgłoszenie do pomocy technicznej.

Zobacz również Najlepsze rozwiązania dotyczące zabezpieczeń.

Uwaga

Nie można zmienić formatu wyjściowego i zachowania ładunku odpowiedzi, gdy zostaną ustawione dla konkretnego 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 osadzić danych wynikowych w ładunku odpowiedzi.

Poniższe polecenie demonstruje użycie EXTERNAL_LINKS oraz formatu Apache Arrow. 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> nazwą profilu konfiguracji usługi Azure Databricks dla uwierzytelniania.

lok

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 przekroczono limit czasu żądania, 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> nazwą profilu konfiguracji usługi Azure Databricks dla uwierzytelniania.

lok

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_index z ładunku odpowiedzi dla następnego fragmentu (jeśli istnieje następny fragment).
  • Jeden z indeksów fragmentów z manifestu odpowiedzi dla każdego dostępnego fragmentu, jeśli jest wiele fragmentów.

Aby na przykład pobrać fragment oznaczony chunk_index10 z 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> nazwą profilu konfiguracji usługi Azure Databricks dla uwierzytelniania.

lok

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:

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> nazwą profilu konfiguracji usługi Azure Databricks dla uwierzytelniania.

lok

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 do wykonywania instrukcji SQL w usłudze 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ć uwierzytelnione przy użyciu prawidłowego osobistego tokenu dostępu usługi Azure Databricks, tokenu dostępu OAuth 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 "MOŻE UŻYWAĆ" do określonego magazynu SQL, który jest używany, a dostęp można ograniczyć za pomocą listy dostępu IP. Dotyczy to wszystkich żądań do interfejsu API usługi Databricks do wykonywania instrukcji SQL. 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 Unity Catalog lub przy użyciu list kontroli dostępu (ACL) tabel. (Aby uzyskać więcej informacji, zobacz Zarządzanie danymi za pomocą usługi Azure Databricks ). 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
  • Chronienie adresów URL SAS 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.

Usuwanie nagłówka autoryzacji usługi Databricks dla żądań usługi Azure Storage

Wszystkie wywołania interfejsu API wykonywania instrukcji SQL usługi Databricks używające curl muszą zawierać nagłówek Authorization z poświadczeniami dostępu do 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.

Chronienie adresów URL SAS i tokenów SAS

Za każdym razem, gdy używasz dyspozycji EXTERNAL_LINKS, generowany jest krótkotrwały adres URL SAS, którego wywołujący może użyć do pobrania wyników bezpośrednio z konta pamięci masowej Azure przy użyciu protokołu TLS. Ponieważ krótkotrwały token SAS jest osadzony w tym adresie URL SAS, należy chronić zarówno ten adres URL, jak i token SAS.

  • Last updated on