Utasítás-végrehajtási API: SQL futtatása a raktárakban

Cikk
08/29/2024

Fontos

A Databricks REST API-k eléréséhez hitelesítenie kell.

Ez az oktatóanyag bemutatja, hogyan futtathat SQL-utasításokat a Databricks SQL Warehouse-ból a Databricks SQL Statement Execution API 2.0 használatával.

A Databricks SQL Statement Execution API 2.0-ra vonatkozó hivatkozásának megtekintéséhez tekintse meg az Utasítás végrehajtása című témakört.

Mielőtt elkezdené

Mielőtt elkezdené ezt az oktatóanyagot, győződjön meg arról, hogy rendelkezik az alábbiakval:

A Databricks CLI 0.205-ös vagy újabb verziója, vagy curlaz alábbiak szerint:
- A Databricks CLI egy parancssori eszköz a Databricks REST API-kérések és -válaszok küldéséhez és fogadásához. Ha a Databricks CLI 0.205-ös vagy újabb verzióját használja, azt konfigurálni kell az Azure Databricks-munkaterület hitelesítéséhez. Lásd: A Databricks parancssori felület databricks parancssori felületének és hitelesítésének telepítése vagy frissítése.
  
  Ha például a Databricks személyes hozzáférési jogkivonat-hitelesítésével szeretne hitelesíteni, hozzon létre egy személyes hozzáférési jogkivonatot az alábbiak szerint:
  1. Az Azure Databricks-munkaterületen kattintson az Azure Databricks-felhasználónevére a felső sávon, majd válassza a legördülő menü Beállítások elemét .
  2. Kattintson a Fejlesztőeszközök elemre.
  3. Az Access-jogkivonatok mellett kattintson a Kezelés gombra.
  4. Kattintson az Új jogkivonat létrehozása elemre.
  5. (Nem kötelező) Írjon be egy megjegyzést, amely segít azonosítani a jogkivonatot a jövőben, és módosíthatja a jogkivonat alapértelmezett 90 napos élettartamát. Élettartam nélküli (nem ajánlott) jogkivonat létrehozásához hagyja üresen az Élettartam (nap) mezőt (üres).
  6. Kattintson a Létrehozás lehetőségre.
  7. Másolja a megjelenített jogkivonatot egy biztonságos helyre, majd kattintson a Kész gombra.
  Feljegyzés
  
  Ügyeljen arra, hogy a másolt jogkivonatot biztonságos helyre mentse. Ne ossza meg másokkal a másolt jogkivonatot. Ha elveszíti a másolt jogkivonatot, nem tudja pontosan ugyanazt a jogkivonatot újragenerálni. Ehelyett meg kell ismételnie ezt az eljárást egy új jogkivonat létrehozásához. Ha elveszíti a másolt jogkivonatot, vagy úgy véli, hogy a jogkivonat sérült, a Databricks határozottan javasolja, hogy azonnal törölje a jogkivonatot a munkaterületről az Access-jogkivonatok lapon a jogkivonat melletti kuka (Visszavonás) ikonra kattintva.
  
  Ha nem tud jogkivonatokat létrehozni vagy használni a munkaterületen, ennek az lehet az oka, hogy a munkaterület rendszergazdája letiltotta a jogkivonatokat, vagy nem adott engedélyt a jogkivonatok létrehozására vagy használatára. Tekintse meg a munkaterület rendszergazdáját vagy a következő témaköröket:
  - Személyes hozzáférési jogkivonat hitelesítésének engedélyezése vagy letiltása a munkaterületen
  - Személyes hozzáférési jogkivonat engedélyei
  Ezután a Databricks parancssori felületének használatával hozzon létre egy Azure Databricks-konfigurációs profilt a személyes hozzáférési jogkivonathoz, tegye a következőket:
  
  Feljegyzés
  
  Az alábbi eljárás a Databricks CLI használatával hoz létre egy Azure Databricks-konfigurációs profilt a névvel DEFAULT. Ha már rendelkezik konfigurációs profillal DEFAULT , ez az eljárás felülírja a meglévő DEFAULT konfigurációs profilt.
  
  Annak ellenőrzéséhez, hogy rendelkezik-e DEFAULT már konfigurációs profillal, és ha létezik, tekintse meg a profil beállításait, a Databricks parancssori felületével futtassa a parancsot databricks auth env --profile DEFAULT.
  
  Ha nem más DEFAULTnéven szeretne konfigurációs profilt létrehozni, cserélje le a DEFAULT következő databricks configure parancs egy másik --profile DEFAULT nevére a konfigurációs profilt.
  1. A Databricks CLI használatával hozzon létre egy Azure Databricks-konfigurációs profiltDEFAULT, amely azure Databricks személyes hozzáférési jogkivonat-hitelesítést használ. Ehhez futtassa az alábbi parancsot:
```
databricks configure --profile DEFAULT
```
  2. A databricks-gazdagép kéréséhez adja meg például https://adb-1234567890123456.7.azuredatabricks.netaz Azure Databricks munkaterületenkénti URL-címét.
  3. A személyes hozzáférési jogkivonat megadásához adja meg a munkaterület Azure Databricks személyes hozzáférési jogkivonatát.
  Az oktatóanyag Databricks CLI-példáiban jegyezze fel a következőket:
  - Ez az oktatóanyag feltételezi, hogy rendelkezik egy környezeti változóval DATABRICKS_SQL_WAREHOUSE_ID a helyi fejlesztőgépen. Ez a környezeti változó a Databricks SQL Warehouse azonosítóját jelöli. Ez az azonosító a raktár HTTP-elérési útjának mezőjében következő /sql/1.0/warehouses/ betűk és számok sztringje. A raktár HTTP-elérésiút-értékének lekéréséről az Azure Databricks számítási erőforrás kapcsolati adatainak lekérése című témakörben olvashat.
  - Ha a Windows command shellt használja a Unix, Linux vagy macOS parancshéj helyett, cserélje le \ a következőre ^, és cserélje le ${...} a következőre %...%: .
  - Ha a Windows command shellt használja a Unix, Linux vagy macOS parancshéj helyett, JSON-dokumentumdeklarációkban cserélje le a megnyitást és a befejezést ' ", és cserélje le a belsőt " a következőre \": .
- A curl egy parancssori eszköz REST API-kérések és válaszok küldéséhez és fogadásához. Lásd még : Install curl. Vagy adaptálhatja az oktatóanyag példáit curl hasonló eszközökkel, például a HTTPie-vel való használatra.
  
  Az oktatóanyag példáiban curl jegyezze fel a következőket:
  - --header "Authorization: Bearer ${DATABRICKS_TOKEN}"Ehelyett .netrc-fájlt használhat. Ha fájlt használ .netrc , cserélje le a következőre --header "Authorization: Bearer ${DATABRICKS_TOKEN}" --netrc: .
  - Ha a Windows command shellt használja a Unix, Linux vagy macOS parancshéj helyett, cserélje le \ a következőre ^, és cserélje le ${...} a következőre %...%: .
  - Ha a Windows command shellt használja a Unix, Linux vagy macOS parancshéj helyett, JSON-dokumentumdeklarációkban cserélje le a megnyitást és a befejezést ' ", és cserélje le a belsőt " a következőre \": .
  Az oktatóanyag példáihoz curl az alábbi környezeti változókat feltételezi a helyi fejlesztőgépen:
  - DATABRICKS_HOST, amely például az Azure Databricks-munkaterület munkaterületének nevétadb-1234567890123456.7.azuredatabricks.net jelöli.
  - DATABRICKS_TOKEN, amely egy Azure Databricks személyes hozzáférési jogkivonatot jelöl az Azure Databricks-munkaterület felhasználója számára.
  - DATABRICKS_SQL_WAREHOUSE_ID, amely a Databricks SQL Warehouse azonosítóját jelöli. Ez az azonosító a raktár HTTP-elérési útjának mezőjében következő /sql/1.0/warehouses/ betűk és számok sztringje. A raktár HTTP-elérésiút-értékének lekéréséről az Azure Databricks számítási erőforrás kapcsolati adatainak lekérése című témakörben olvashat.
  Feljegyzés
  
  Ajánlott biztonsági eljárásként, ha automatizált eszközökkel, rendszerekkel, szkriptekkel és alkalmazásokkal hitelesít, a Databricks azt javasolja, hogy munkaterület-felhasználók helyett a szolgáltatásnevekhez tartozó személyes hozzáférési jogkivonatokat használja. A szolgáltatásnevek jogkivonatainak létrehozásáról a szolgáltatásnév jogkivonatainak kezelése című témakörben olvashat.
  
  Azure Databricks személyes hozzáférési jogkivonat létrehozásához tegye a következőket:
  1. Az Azure Databricks-munkaterületen kattintson az Azure Databricks-felhasználónevére a felső sávon, majd válassza a legördülő menü Beállítások elemét .
  2. Kattintson a Fejlesztőeszközök elemre.
  3. Az Access-jogkivonatok mellett kattintson a Kezelés gombra.
  4. Kattintson az Új jogkivonat létrehozása elemre.
  5. (Nem kötelező) Írjon be egy megjegyzést, amely segít azonosítani a jogkivonatot a jövőben, és módosíthatja a jogkivonat alapértelmezett 90 napos élettartamát. Élettartam nélküli (nem ajánlott) jogkivonat létrehozásához hagyja üresen az Élettartam (nap) mezőt (üres).
  6. Kattintson a Létrehozás lehetőségre.
  7. Másolja a megjelenített jogkivonatot egy biztonságos helyre, majd kattintson a Kész gombra.
  Feljegyzés
  
  Ügyeljen arra, hogy a másolt jogkivonatot biztonságos helyre mentse. Ne ossza meg másokkal a másolt jogkivonatot. Ha elveszíti a másolt jogkivonatot, nem tudja pontosan ugyanazt a jogkivonatot újragenerálni. Ehelyett meg kell ismételnie ezt az eljárást egy új jogkivonat létrehozásához. Ha elveszíti a másolt jogkivonatot, vagy úgy véli, hogy a jogkivonat sérült, a Databricks határozottan javasolja, hogy azonnal törölje a jogkivonatot a munkaterületről az Access-jogkivonatok lapon a jogkivonat melletti kuka (Visszavonás) ikonra kattintva.
  
  Ha nem tud jogkivonatokat létrehozni vagy használni a munkaterületen, ennek az lehet az oka, hogy a munkaterület rendszergazdája letiltotta a jogkivonatokat, vagy nem adott engedélyt a jogkivonatok létrehozására vagy használatára. Tekintse meg a munkaterület rendszergazdáját vagy a következő témaköröket:
  - Személyes hozzáférési jogkivonat hitelesítésének engedélyezése vagy letiltása a munkaterületen
  - Személyes hozzáférési jogkivonat engedélyei
  Figyelmeztetés
  
  A Databricks határozottan visszatartja a szkriptekbe való kemény kódolást, mivel ezek a bizalmas információk egyszerű szövegben, verziókövetési rendszereken keresztül is közzétehetők. A Databricks azt javasolja, hogy olyan megközelítéseket használjon, mint például a fejlesztői gépen beállított környezeti változók. Ha eltávolítja az ilyen szigorúan kódolt adatokat a szkriptekből, az segít, hogy ezek a szkriptek hordozhatóbbak legyenek.
Ez az oktatóanyag feltételezi, hogy a JQ parancssori processzorral is rendelkezik a JSON-válasz hasznos adatainak lekérdezéséhez, amelyet a Databricks SQL Statement Execution API a Databricks SQL-utasítás végrehajtási API-jának minden egyes hívása után visszaad. Lásd: Letöltés jq.
Rendelkeznie kell legalább egy táblával, amellyel SQL-utasításokat hajthat végre. Ez az oktatóanyag a lineitem katalógus sématábláján tpch (más néven adatbázison) samples alapul. Ha nem fér hozzá ehhez a katalógushoz, sémához vagy táblához a munkaterületről, cserélje le őket az oktatóanyag során a sajátjával.

1. lépés: SQL-utasítás végrehajtása és az adateredmény mentése JSON-ként

Futtassa a következő parancsot, amely a következőket hajtja végre:

A megadott SQL Warehouse-t és a megadott jogkivonatot használja curla katalógusban lévő séma tcph samples tábla első két sorából lineitem származó három oszlop lekérdezéséhez.
A válasz hasznos adatait JSON formátumban menti az aktuális munkakönyvtárban elnevezett sql-execution-response.json fájlba.
Kinyomtatja a fájl tartalmát sql-execution-response.json .
Beállít egy helyi környezeti változót .SQL_STATEMENT_ID Ez a változó a megfelelő SQL-utasítás azonosítóját tartalmazza. Ezt az SQL-utasításazonosítót használhatja az utasítással kapcsolatos információk igény szerinti lekéréséhez, amelyet a 2. lépés mutat be. Ezt az SQL-utasítást a Databricks SQL-konzol lekérdezéselőzmények szakaszából vagy a Lekérdezéselőzmények API meghívásával is megtekintheti és lekérheti annak utasításazonosítóját.
Beállít egy további helyi környezeti változót, NEXT_CHUNK_EXTERNAL_LINK amely egy API URL-töredékét tartalmazza a JSON-adatok következő adattömbjének lekéréséhez. Ha a válaszadatok túl nagyok, a Databricks SQL Statement Execution API adattömbökben adja meg a választ. Ezt az API URL-töredékét használhatja a következő adattömb lekéréséhez, amelyet a 2. lépés mutat be. Ha nincs következő adattömb, akkor ez a környezeti változó a következőre nullvan állítva.
Kinyomtatja a környezeti és NEXT_CHUNK_INTERNAL_LINK a SQL_STATEMENT_ID környezeti változók értékeit.

A Databricks parancssori felülete

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

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

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

Az előző kérelemben:

A paraméteres lekérdezések minden lekérdezési paraméter nevét kettősponttal (például ) előzik meg, :extended_priceamely egyező name és value egy objektumot tartalmaz a parameters tömbben. Megadható opcionális type is, ha nincs megadva az alapértelmezett érték STRING .

Figyelmeztetés

A Databricks határozottan javasolja, hogy az SQL-utasításokhoz ajánlott eljárásként használja a paramétereket.

Ha a Databricks SQL Statement Execution API-t olyan alkalmazással használja, amely dinamikusan generálja az SQL-t, ez SQL-injektálási támadásokat eredményezhet. Ha például sql-kódot hoz létre a felhasználói felületen a felhasználó kijelölései alapján, és nem tesz megfelelő intézkedéseket, a támadó rosszindulatú SQL-kódot szúrhat be a kezdeti lekérdezés logikájának módosításához, ezáltal bizalmas adatok olvasásához, módosításához vagy törléséhez.

A paraméteres lekérdezések segítenek megvédeni az SQL-injektálási támadásokat azáltal, hogy a bemeneti argumentumokat a többi SQL-kódtól elkülönítve kezelik, és ezeket az argumentumokat literális értékekként értelmezik. A paraméterek a kód újrafelhasználhatóságában is segítenek.
Alapértelmezés szerint a visszaadott adatok JSON-tömbformátumban vannak, és az SQL-utasítás adateredményeinek alapértelmezett helye a válasz hasznos adatai között van. A viselkedés explicitvá tétele érdekében adja hozzá "format":"JSON_ARRAY","disposition":"INLINE" a kérelem hasznos adatait. Ha 25 MiB-nél nagyobb adateredményeket próbál visszaadni a válasz hasznos adataiban, a rendszer hibaállapotot ad vissza, és az SQL-utasítás megszakad. A 25 MiB-nél nagyobb adateredmények esetén külső hivatkozásokat használhat ahelyett, hogy megpróbálná visszaadni a válasz hasznos adataiban, amelyet a 3. lépés mutat be.
A parancs a válasz hasznos adatainak tartalmát egy helyi fájlban tárolja. A Databricks SQL Statement Execution API közvetlenül nem támogatja a helyi adattárolást.
Alapértelmezés szerint 10 másodperc elteltével, ha az SQL-utasítás még nem fejezte be a végrehajtást a raktáron keresztül, a Databricks SQL Statement Execution API az utasítás eredménye helyett csak az SQL-utasítás azonosítóját és aktuális állapotát adja vissza. Ennek a viselkedésnek a módosításához adja hozzá "wait_timeout" a kérést, és állítsa be a következő értékre"<x>s", <x> például "50s"a két másodperc 50 közötti 5 értékre. Az SQL-utasítás azonosítójának és aktuális állapotának azonnali visszaadásához állítsa be a következőt wait_timeout 0s: .
Alapértelmezés szerint az SQL-utasítás továbbra is fut, ha eléri az időtúllépési időszakot. Ha az időtúllépési időszak elérésekor meg szeretné szüntetni az SQL-utasítást, adja hozzá "on_wait_timeout":"CANCEL" a kérelem hasznos adatait.
A visszaadott bájtok számának korlátozásához adja hozzá "byte_limit" a kéréshez, és állítsa be például 1000a bájtok számát.
A visszaadott sorok számának korlátozásához záradék statementhozzáadása LIMIT helyett hozzáadhatja "row_limit" a kéréshez, és beállíthatja például "statement":"SELECT * FROM lineitem","row_limit":2a sorok számát.
Ha az eredmény nagyobb a megadottnál byte_limit , vagy row_limitha a truncated mező a válasz hasznos adatai között van beállítva true .

Ha az utasítás eredménye a várakozási időtúllépés vége előtt érhető el, a válasz a következő:

{
  "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"
  }
}

Ha a várakozási időtúllépés az utasítás eredményének megjelenése előtt véget ér, a válasz a következőképpen néz ki:

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

Ha az utasítás eredményadatai túl nagyok (például ebben az esetben futtatáskor SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), az eredményadatok adattömbbe kerülnek, és így néznek ki. Figyelje meg, hogy itt "...": "..." nem található eredmény a rövidség kedvéért:

{
  "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"
  }
}

2. lépés: Az utasítás aktuális végrehajtási állapotának és adateredményének lekérése JSON-ként

Az SQL-utasítás azonosítójával lekérheti az utasítás aktuális végrehajtási állapotát, és ha a végrehajtás sikeres volt, az utasítás eredménye. Ha elfelejti az utasítás azonosítóját, lekérheti a Databricks SQL-konzol lekérdezéselőzmények szakaszából vagy a Lekérdezéselőzmények API meghívásával. Például továbbra is lekérdezheti ezt a parancsot, és minden alkalommal ellenőrizheti, hogy a végrehajtás sikeres volt-e.

Az SQL-utasítás aktuális végrehajtási állapotának lekéréséhez és ha a végrehajtás sikeres volt, futtassa az alábbi parancsot az utasítás eredményének és egy API URL-töredékének lekéréséhez. Ez a parancs feltételezi, hogy rendelkezik egy környezeti változóval SQL_STATEMENT_IDa helyi fejlesztőgépen, amely az előző lépésben megadott SQL-utasítás azonosítójának értékére van beállítva. Az alábbi parancsot természetesen helyettesítheti ${SQL_STATEMENT_ID} az SQL-utasítás kódolt azonosítójával.

A Databricks parancssori felülete

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

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

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

Ha az NEXT_CHUNK_INTERNAL_LINK érték nemnull értékre van állítva, akkor a következő adattömb lekérésére használható, és így tovább, például a következő paranccsal:

A Databricks parancssori felülete

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

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

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

Az előző parancsot újra és újra futtathatja a következő adattömb lekéréséhez, és így tovább. Vegye figyelembe, hogy az utolsó adattömb lekérése után az SQL-utasítás bezárul. A lezárás után nem használhatja az utasítás azonosítóját az aktuális állapot lekéréséhez vagy további adattömbök lekéréséhez.

3. lépés: Nagy eredmények lekérése külső hivatkozások használatával

Ez a szakasz egy választható konfigurációt mutat be, amely a nagy adatkészletek lekérésére használja a EXTERNAL_LINKS diszpozíciót. Az SQL-utasítás eredményadatainak alapértelmezett helye (eloszlása) a válasz hasznos adatain belül van, de ezek az eredmények legfeljebb 25 MiB-re korlátozódnak. A beállítással a disposition EXTERNAL_LINKSválasz URL-címeket tartalmaz, amellyel lekérheti az eredményadatok adattömbjeit a szabványos HTTP-vel. Az URL-címek a munkaterület belső DBFS-ére mutatnak, ahol az eredménytömbök ideiglenesen tárolódnak.

Figyelmeztetés

A Databricks határozottan javasolja a diszpozíció által EXTERNAL_LINKS visszaadott URL-címek és jogkivonatok védelmét.

A diszpozíció használatakor EXTERNAL_LINKS létrejön egy közös hozzáférésű jogosultságkód (SAS) URL-cím, amellyel közvetlenül az Azure Storage-ból töltheti le az eredményeket. Mivel egy rövid élettartamú SAS-jogkivonat van beágyazva ebbe az SAS URL-címbe, az SAS URL-címet és az SAS-jogkivonatot is védenie kell.

Mivel az SAS-URL-címek már beágyazott ideiglenes SAS-jogkivonatokkal vannak létrehozva, nem szabad fejlécet Authorization beállítania a letöltési kérelmekben.

A EXTERNAL_LINKS letiltás kérelemre letiltható egy támogatási eset létrehozásával.

Lásd még a biztonsági ajánlott eljárásokat.

Feljegyzés

A válasz hasznos adat kimeneti formátuma és viselkedése egy adott SQL-utasításazonosító beállítása után nem módosítható.

Ebben a módban az API lehetővé teszi, hogy az eredményadatokat JSON formátumban (), CSV formátumban (JSONCSV) vagy Apache Arrow formátumban (ARROW_STREAM) tárolja, amelyeket külön kell lekérdezni a HTTP-vel. Ha ezt a módot használja, az eredményadatok nem ágyazhatóak be a válasz hasznos adataiba.

Az alábbi parancs a használatot EXTERNAL_LINKS és az Apache Arrow formátumot mutatja be. Használja ezt a mintát az 1. lépésben bemutatott hasonló lekérdezés helyett:

A Databricks parancssori felülete

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

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

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

A válasz a következő:

{
  "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"
  }
}

Ha a kérés túllépi az időkorlátot, a válasz a következőképpen néz ki:

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

Az utasítás aktuális végrehajtási állapotának lekéréséhez és ha a végrehajtás sikeres volt, futtassa az alábbi parancsot:

A Databricks parancssori felülete

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

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

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'

Ha a válasz elég nagy (például ebben az esetben sorkorlát nélkül fut SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem ), a válasz több adattömbből áll, mint az alábbi példában. Figyelje meg, hogy itt "...": "..." nem található eredmény a rövidség kedvéért:

{
  "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"
  }
}

A tárolt tartalom eredményeinek letöltéséhez futtassa az alábbi curl parancsot az objektum URL-címével external_link , és adja meg, hogy hol szeretné letölteni a fájlt. Ne foglalja bele az Azure Databricks-jogkivonatot ebbe a parancsba:

curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"

A streamelt tartalom eredményeinek egy adott adattömbjének letöltéséhez az alábbiak egyikét használhatja:

A next_chunk_index válasz hasznos adatainak értéke a következő adattömbhöz (ha van egy következő adattömb).
Ha több adattömb van, a válasz hasznos adatjegyzékéből származó adattömbindexek egyike a rendelkezésre álló adattömbökhöz.

Ha például le szeretné kapni az adattömbet az előző válaszból chunk_index 10 , futtassa a következő parancsot:

A Databricks parancssori felülete

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'

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

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'

Feljegyzés

Az előző parancs futtatása egy új SAS URL-címet ad vissza.

A tárolt adattömb letöltéséhez használja az objektum URL-címét external_link .

További információ az Apache Arrow formátumról:

4. lépés: SQL-utasítás végrehajtásának megszakítása

Ha egy még nem sikeres SQL-utasítást kell visszavonnia, futtassa a következő parancsot:

A Databricks parancssori felülete

databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'

Cserélje le <profile-name> az Azure Databricks-konfigurációs profil nevére a hitelesítéshez.

csavarodik

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

Ajánlott biztonsági eljárások

A Databricks SQL Statement Execution API a végpontok közötti átvitel biztonsági (TLS) titkosításával és a rövid élettartamú hitelesítő adatokkal, például SAS-jogkivonatokkal növeli az adatátvitel biztonságát.

Ebben a biztonsági modellben több réteg is található. Az átviteli rétegben a Databricks SQL Statement Execution API meghívása csak TLS 1.2 vagy újabb használatával lehetséges. Emellett a Databricks SQL Statement Execution API hívóit hitelesíteni kell érvényes Azure Databricks személyes hozzáférési jogkivonattal, OAuth hozzáférési jogkivonattal vagy Microsoft Entra-azonosítóval (korábbi nevén Azure Active Directory) olyan felhasználóhoz, aki jogosult a Databricks SQL használatára. Ennek a felhasználónak rendelkeznie kell a használt SQL-tárolóhoz való HOZZÁFÉRÉSsel, és a hozzáférés ip-hozzáférési listákkal korlátozható. Ez a Databricks SQL Statement Execution API-ra irányuló összes kérésre vonatkozik. Ezenkívül az utasítások végrehajtásához a hitelesített felhasználónak engedéllyel kell rendelkeznie az egyes utasításokban használt adatobjektumokhoz (például táblákhoz, nézetekhez és függvényekhez). Ezt a Unity Katalógus meglévő hozzáférés-vezérlési mechanizmusai vagy a tábla ACL-jei kényszerítik ki. (Lásd: Adatszabályozás a Unity Katalógussal további részletekért.) Ez azt is jelenti, hogy csak az utasítást végrehajtó felhasználó kérheti le az utasítás eredményeit.

A Databricks a következő ajánlott biztonsági eljárásokat javasolja a Databricks SQL Statement Execution API használatakor, valamint a EXTERNAL_LINKS nagyméretű adatkészletek lekérésére vonatkozó diszpozícióval együtt:

Az Azure Storage-kérelmek Databricks-engedélyezési fejlécének eltávolítása
SAS-URL-címek és SAS-jogkivonatok védelme

A EXTERNAL_LINKS letiltás kérelemre letiltható egy támogatási eset létrehozásával. A kérés teljesítéséhez forduljon az Azure Databricks-fiók csapatához.

Az Azure Storage-kérelmek Databricks-engedélyezési fejlécének eltávolítása

A Databricks SQL Utasítás végrehajtási API-jának minden olyan curl hívásának tartalmaznia kell egy Authorization fejlécet, amely tartalmazza az Azure Databricks hozzáférési hitelesítő adatait. Ne adja meg ezt a Authorization fejlécet, amikor adatokat tölt le az Azure Storage-ból. Ez a fejléc nem szükséges, és előfordulhat, hogy véletlenül elérhetővé teszi az Azure Databricks hozzáférési hitelesítő adatait.

SAS-URL-címek és SAS-jogkivonatok védelme

A diszpozíció használatakor EXTERNAL_LINKS létrejön egy rövid élettartamú SAS URL-cím, amellyel a hívó közvetlenül az Azure Storage-ból töltheti le az eredményeket a TLS használatával. Mivel egy rövid élettartamú SAS-jogkivonat van beágyazva ebbe az SAS URL-címbe, az SAS URL-címet és az SAS-jogkivonatot is védenie kell.

Megosztás a következőn keresztül:

Utasítás-végrehajtási API: SQL futtatása a raktárakban

Mielőtt elkezdené

1. lépés: SQL-utasítás végrehajtása és az adateredmény mentése JSON-ként

A Databricks parancssori felülete

csavarodik

2. lépés: Az utasítás aktuális végrehajtási állapotának és adateredményének lekérése JSON-ként

A Databricks parancssori felülete

csavarodik

A Databricks parancssori felülete

csavarodik

3. lépés: Nagy eredmények lekérése külső hivatkozások használatával

A Databricks parancssori felülete

csavarodik

A Databricks parancssori felülete

csavarodik

A Databricks parancssori felülete

csavarodik

4. lépés: SQL-utasítás végrehajtásának megszakítása

A Databricks parancssori felülete

csavarodik

Ajánlott biztonsági eljárások

Az Azure Storage-kérelmek Databricks-engedélyezési fejlécének eltávolítása

SAS-URL-címek és SAS-jogkivonatok védelme

Visszajelzés

További források