Udostępnij za pośrednictwem

Interfejs API wykonywania instrukcji: uruchamianie bazy danych SQL w magazynach

  • Artykuł

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 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 Osobiste tokeny dostępu usługi Azure Databricks 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 usługi Databricks do utworzenia profilu konfiguracji usługi Azure Databricks o nazwie DEFAULT. Jeśli masz DEFAULT już profil konfiguracji, ta procedura zastępuje istniejący DEFAULT profil konfiguracji.

      Aby sprawdzić, czy masz DEFAULT już profil konfiguracji i wyświetlić ustawienia tego profilu, jeśli istnieje, użyj interfejsu wiersza polecenia usługi Databricks, aby uruchomić polecenie databricks auth env --profile DEFAULT.

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

      1. Użyj interfejsu wiersza polecenia usługi Databricks, aby utworzyć profil konfiguracji usługi Azure Databricks o nazwie DEFAULT korzystający z uwierzytelniania osobistego tokenu dostępu usługi Azure Databricks. Aby to zrobić, uruchom następujące polecenie:

        databricks configure --profile DEFAULT

      2. W 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.

      3. 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_ID na 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). 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:

      • --header "Authorization: Bearer ${DATABRICKS_TOKEN}"Zamiast programu można użyć pliku .netrc. Jeśli używasz pliku, zastąp .netrc cią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 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ą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, postępuj zgodnie ze stapsami w osobistych tokenach dostępu usługi Azure Databricks 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. 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 lineitem tabeli w schemacie tpch (znanym również jako baza danych) w wykazie 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 curlmetody , aby wykonać zapytanie o trzy kolumny z pierwszych dwóch wierszy lineitem tabeli w schemacie w tcph wykazie 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 instrukcji z sekcji historia zapytań konsoli SQL usługi Databricks lub wywołując interfejs API historii zapytań.
  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 nullwartość .
  6. Drukuje wartości SQL_STATEMENT_ID zmiennych środowiskowych 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> ciąg nazwą profilu konfiguracji usługi Azure Databricks na potrzeby 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) z pasującym name obiektem i value obiektem w tablicy parameters . Można również określić opcjonalny parametr type z wartością domyślną , jeśli nie zostanie określona STRING .

    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ędzy 5 i 50 sekundami włącznie, na przykład "50s". Aby natychmiast zwrócić identyfikator instrukcji SQL i jego bieżący stan, ustaw wartość wait_timeout 0s.

  • 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ł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ślony byte_limit lub row_limit, truncated pole jest ustawione na true wartość 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.

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

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.

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

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 disposition EXTERNAL_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, tworząc 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.

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 żą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.

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 ładunku odpowiedzi dla dowolnego dostępnego fragmentu, jeśli istnieje wiele fragmentów.

Aby na przykład pobrać fragment z chunk_index 10 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.

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> ciąg nazwą profilu konfiguracji usługi Azure Databricks na potrzeby 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 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ć 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 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.

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.