Uitvoerings-API voor instructies: SQL uitvoeren op magazijnen
Belangrijk
U moet u verifiëren voor toegang tot Databricks-REST API's.
In deze zelfstudie leert u hoe u de Databricks SQL-instructieuitvoerings-API 2.0 gebruikt om SQL-instructies uit te voeren vanuit Databricks SQL-warehouses.
Zie De instructieuitvoering voor instructies voor de Databricks SQL-instructieuitvoerings-API 2.0 bekijken.
Voordat u begint
Voordat u aan deze zelfstudie begint, moet u ervoor zorgen dat u het volgende hebt:
Databricks CLI versie 0.205 of hoger of
curl, als volgt:De Databricks CLI is een opdrachtregelprogramma voor het verzenden en ontvangen van Databricks REST API-aanvragen en -antwoorden. Als u ervoor kiest om Databricks CLI versie 0.205 of hoger te gebruiken, moet deze worden geconfigureerd voor verificatie met uw Azure Databricks-werkruimte. Zie De Databricks CLI en verificatie voor de Databricks CLI installeren of bijwerken.
Als u bijvoorbeeld wilt verifiëren met persoonlijke toegangstokenverificatie van Databricks, maakt u als volgt een persoonlijk toegangstoken:
- Klik in uw Azure Databricks-werkruimte op uw Azure Databricks-gebruikersnaam in de bovenste balk en selecteer vervolgens Instellingen in de vervolgkeuzelijst.
- Klik op Ontwikkelaars.
- Klik naast Access-tokens op Beheren.
- Klik op Nieuw token genereren.
- (Optioneel) Voer een opmerking in waarmee u dit token in de toekomst kunt identificeren en de standaardlevensduur van het token van 90 dagen kunt wijzigen. Als u een token zonder levensduur wilt maken (niet aanbevolen), laat u het vak Levensduur (dagen) leeg (leeg).
- Klik op Genereren.
- Kopieer het weergegeven token naar een veilige locatie en klik vervolgens op Gereed.
Notitie
Zorg ervoor dat u het gekopieerde token op een veilige locatie opslaat. Deel uw gekopieerde token niet met anderen. Als u het gekopieerde token kwijtraakt, kunt u dat token niet opnieuw genereren. In plaats daarvan moet u deze procedure herhalen om een nieuw token te maken. Als u het gekopieerde token kwijtraakt of als u denkt dat het token is aangetast, raadt Databricks u ten zeerste aan dat u dat token onmiddellijk uit uw werkruimte verwijdert door te klikken op het prullenbakpictogram (Intrekken) naast het token op de pagina Toegangstokens .
Als u geen tokens in uw werkruimte kunt maken of gebruiken, kan dit komen doordat uw werkruimtebeheerder tokens heeft uitgeschakeld of u geen toestemming hebt gegeven om tokens te maken of te gebruiken. Neem de werkruimtebeheerder of het volgende weer:
Ga als volgt te werk om de Databricks CLI te gebruiken om een Azure Databricks-configuratieprofiel te maken voor uw persoonlijke toegangstoken:
Notitie
In de volgende procedure wordt de Databricks CLI gebruikt om een Azure Databricks-configuratieprofielmet de naam
DEFAULTte maken. Als u al eenDEFAULTconfiguratieprofiel hebt, overschrijft deze procedure uw bestaandeDEFAULTconfiguratieprofiel.Als u wilt controleren of u al een
DEFAULTconfiguratieprofiel hebt en de instellingen van dit profiel wilt weergeven als dit bestaat, gebruikt u de Databricks CLI om de opdrachtdatabricks auth env --profile DEFAULTuit te voeren.Als u een configuratieprofiel wilt maken met een andere naam dan
DEFAULT, vervangt u hetDEFAULTdeel van--profile DEFAULTde volgendedatabricks configureopdracht door een andere naam voor het configuratieprofiel.Gebruik de Databricks CLI om een Azure Databricks-configuratieprofielte maken met de naam
DEFAULTdie gebruikmaakt van persoonlijke toegangstokenverificatie van Azure Databricks. Voer hiervoor de volgende opdracht uit:databricks configure --profile DEFAULTVoer voor de prompt databricks-host de URL van uw Azure Databricks per werkruimte in, bijvoorbeeld
https://adb-1234567890123456.7.azuredatabricks.net.Voer het persoonlijke toegangstoken van Azure Databricks in voor uw werkruimte voor de prompt persoonlijke toegangstoken.
In de Databricks CLI-voorbeelden van deze zelfstudie ziet u het volgende:
- In deze zelfstudie wordt ervan uitgegaan dat u een omgevingsvariabele
DATABRICKS_SQL_WAREHOUSE_IDhebt op uw lokale ontwikkelcomputer. Deze omgevingsvariabele vertegenwoordigt de id van uw Databricks SQL-warehouse. Deze id is de tekenreeks met letters en cijfers die volgen/sql/1.0/warehouses/in het veld HTTP-pad voor uw magazijn. Zie Verbindingsgegevens ophalen voor een Azure Databricks-rekenresource voor meer informatie over het verkrijgen van de HTTP-padwaarde van uw warehouse. - Als u de Windows Command-shell gebruikt in plaats van een opdrachtshell voor Unix, Linux of macOS, vervangt u deze door
\^en vervangt u deze${...}%...%door . - Als u de Windows Command-shell gebruikt in plaats van een opdrachtshell voor Unix, Linux of macOS, vervangt u in JSON-documentdeclaraties het openen en sluiten
'door"en vervangt u de binnenste"\"door .
curl is een opdrachtregelprogramma voor het verzenden en ontvangen van REST API-aanvragen en -antwoorden. Zie ook Curl installeren. U kunt ook de voorbeelden van
curldeze zelfstudie aanpassen voor gebruik met vergelijkbare hulpprogramma's zoals Postman of HTTPie.In de voorbeelden van
curldeze zelfstudie ziet u het volgende:- In plaats van
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"kunt u een .netrc-bestand gebruiken. Als u een.netrcbestand gebruikt, vervangt u door--header "Authorization: Bearer ${DATABRICKS_TOKEN}"--netrc. - Als u de Windows Command-shell gebruikt in plaats van een opdrachtshell voor Unix, Linux of macOS, vervangt u deze door
\^en vervangt u deze${...}%...%door . - Als u de Windows Command-shell gebruikt in plaats van een opdrachtshell voor Unix, Linux of macOS, vervangt u in JSON-documentdeclaraties het openen en sluiten
'door"en vervangt u de binnenste"\"door .
Voor de voorbeelden van
curldeze zelfstudie wordt in deze zelfstudie ook ervan uitgegaan dat u de volgende omgevingsvariabelen hebt op uw lokale ontwikkelcomputer:DATABRICKS_HOST, dat de naam van het werkruimte-exemplaar vertegenwoordigt, bijvoorbeeldadb-1234567890123456.7.azuredatabricks.netvoor uw Azure Databricks-werkruimte.DATABRICKS_TOKEN, dat een persoonlijk toegangstoken van Azure Databricks vertegenwoordigt voor de gebruiker van uw Azure Databricks-werkruimte.DATABRICKS_SQL_WAREHOUSE_ID, die de id van uw Databricks SQL-warehouse vertegenwoordigt. Deze id is de tekenreeks met letters en cijfers die volgen/sql/1.0/warehouses/in het veld HTTP-pad voor uw magazijn. Zie Verbindingsgegevens ophalen voor een Azure Databricks-rekenresource voor meer informatie over het verkrijgen van de HTTP-padwaarde van uw warehouse.
Notitie
Als best practice voor beveiliging, wanneer u zich verifieert met geautomatiseerde hulpprogramma's, systemen, scripts en apps, raadt Databricks u aan om persoonlijke toegangstokens te gebruiken die behoren tot service-principals in plaats van werkruimtegebruikers. Zie Tokens voor een service-principal beheren om tokens voor service-principals te maken.
Ga als volgt te werk om een persoonlijk toegangstoken voor Azure Databricks te maken:
- Klik in uw Azure Databricks-werkruimte op uw Azure Databricks-gebruikersnaam in de bovenste balk en selecteer vervolgens Instellingen in de vervolgkeuzelijst.
- Klik op Ontwikkelaars.
- Klik naast Access-tokens op Beheren.
- Klik op Nieuw token genereren.
- (Optioneel) Voer een opmerking in waarmee u dit token in de toekomst kunt identificeren en de standaardlevensduur van het token van 90 dagen kunt wijzigen. Als u een token zonder levensduur wilt maken (niet aanbevolen), laat u het vak Levensduur (dagen) leeg (leeg).
- Klik op Genereren.
- Kopieer het weergegeven token naar een veilige locatie en klik vervolgens op Gereed.
Notitie
Zorg ervoor dat u het gekopieerde token op een veilige locatie opslaat. Deel uw gekopieerde token niet met anderen. Als u het gekopieerde token kwijtraakt, kunt u dat token niet opnieuw genereren. In plaats daarvan moet u deze procedure herhalen om een nieuw token te maken. Als u het gekopieerde token kwijtraakt of als u denkt dat het token is aangetast, raadt Databricks u ten zeerste aan dat u dat token onmiddellijk uit uw werkruimte verwijdert door te klikken op het prullenbakpictogram (Intrekken) naast het token op de pagina Toegangstokens .
Als u geen tokens in uw werkruimte kunt maken of gebruiken, kan dit komen doordat uw werkruimtebeheerder tokens heeft uitgeschakeld of u geen toestemming hebt gegeven om tokens te maken of te gebruiken. Neem de werkruimtebeheerder of het volgende weer:
Waarschuwing
Databricks ontmoedigt hard-coding-informatie in uw scripts, omdat deze gevoelige informatie in tekst zonder opmaak kan worden weergegeven via versiebeheersystemen. Databricks raadt u aan om in plaats daarvan benaderingen te gebruiken, zoals omgevingsvariabelen die u instelt op uw ontwikkelcomputer. Door dergelijke in code vastgelegde informatie uit uw scripts te verwijderen, kunt u deze scripts ook draagbaarder maken.
- In plaats van
In deze zelfstudie wordt ervan uitgegaan dat u ook jq hebt, een opdrachtregelprocessor voor het uitvoeren van query's op JSON-antwoordpayloads, die de Databricks SQL-instructieuitvoerings-API naar u retourneert na elke aanroep die u maakt naar de Databricks SQL-instructieuitvoerings-API. Zie Jq downloaden.
U moet ten minste één tabel hebben waarop u SQL-instructies kunt uitvoeren. Deze zelfstudie is gebaseerd op de
lineitemtabel in hettpchschema (ook wel een database genoemd) in desamplescatalogus. Als u geen toegang hebt tot deze catalogus, schema of tabel vanuit uw werkruimte, vervangt u deze in deze zelfstudie door uw eigen zelfstudie.
Stap 1: Voer een SQL-instructie uit en sla het gegevensresultaat op als JSON
Voer de volgende opdracht uit. Dit doet u als volgt:
- Maakt gebruik van het opgegeven SQL-warehouse, samen met het opgegeven token als u gebruikt
curl, om een query uit te voeren op drie kolommen uit de eerste twee rijen van delineitemtabel in hettcphschema in desamplescatalogus. - Slaat de nettolading van het antwoord op in JSON-indeling in een bestand met de naam
sql-execution-response.jsonin de huidige werkmap. - Hiermee wordt de inhoud van het
sql-execution-response.jsonbestand afgedrukt. - Hiermee stelt u een lokale omgevingsvariabele in met de naam
SQL_STATEMENT_ID. Deze variabele bevat de id van de bijbehorende SQL-instructie. U kunt deze SQL-instructie-id gebruiken om later informatie over die instructie op te halen. Dit wordt in stap 2 gedemonstreerd. U kunt deze SQL-instructie ook bekijken en de bijbehorende instructie-id ophalen uit de sectie querygeschiedenis van de Databricks SQL-console of door de Querygeschiedenis-API aan te roepen. - Hiermee stelt u een extra lokale omgevingsvariabele
NEXT_CHUNK_EXTERNAL_LINKin die een API-URL-fragment bevat voor het ophalen van het volgende segment JSON-gegevens. Als de antwoordgegevens te groot zijn, levert de Databricks SQL-instructieuitvoerings-API het antwoord in segmenten. U kunt dit API-URL-fragment gebruiken voor het ophalen van het volgende segment gegevens, dat wordt gedemonstreerd in stap 2. Als er geen volgende segment is, wordt deze omgevingsvariabele ingesteld opnull. - Hiermee worden de waarden van de
SQL_STATEMENT_IDenNEXT_CHUNK_INTERNAL_LINKomgevingsvariabelen afgedrukt.
Databricks-CLI
databricks api post /api/2.0/sql/statements \
--profile <profile-name> \
--json '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "2", "type": "INT" }
]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.
curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "2", "type": "INT" }
]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
In de voorgaande aanvraag:
Geparameteriseerde query's bestaan uit de naam van elke queryparameter die wordt voorafgegaan door een dubbele punt (bijvoorbeeld
:extended_price) met een overeenkomendnameobject invaluedeparametersmatrix. Een optioneeltypekan ook worden opgegeven, met de standaardwaarde vanSTRINGindien niet opgegeven.Waarschuwing
Databricks raadt u ten zeerste aan parameters te gebruiken als best practice voor uw SQL-instructies.
Als u de Databricks SQL-instructieuitvoerings-API gebruikt met een toepassing die SQL dynamisch genereert, kan dit leiden tot SQL-injectieaanvallen. Als u bijvoorbeeld SQL-code genereert op basis van de selecties van een gebruiker in een gebruikersinterface en geen passende maatregelen neemt, kan een aanvaller schadelijke SQL-code injecteren om de logica van uw eerste query te wijzigen, waardoor gevoelige gegevens worden gelezen, gewijzigd of verwijdert.
Geparameteriseerde query's beschermen tegen aanvallen met SQL-injecties door invoerargumenten afzonderlijk van de rest van uw SQL-code te verwerken en deze argumenten als letterlijke waarden te interpreteren. Parameters helpen ook bij het hergebruik van code.
Geretourneerde gegevens hebben standaard de JSON-matrixindeling en de standaardlocatie voor de gegevensresultaten van de SQL-instructie valt binnen de nettolading van het antwoord. Als u dit gedrag expliciet wilt maken, voegt u deze toe
"format":"JSON_ARRAY","disposition":"INLINE"aan de nettolading van de aanvraag. Als u gegevensresultaten probeert te retourneren die groter zijn dan 25 MiB in de nettolading van het antwoord, wordt er een foutstatus geretourneerd en wordt de SQL-instructie geannuleerd. Voor gegevensresultaten die groter zijn dan 25 MiB, kunt u externe koppelingen gebruiken in plaats van deze te retourneren in de nettolading van het antwoord. Dit wordt gedemonstreerd in stap 3.Met de opdracht wordt de inhoud van de nettolading van het antwoord opgeslagen in een lokaal bestand. Lokale gegevensopslag wordt niet rechtstreeks ondersteund door de Databricks SQL-instructieuitvoerings-API.
Als de SQL-instructie na 10 seconden nog niet is uitgevoerd via het warehouse, retourneert de Databricks SQL-instructieuitvoerings-API standaard alleen de SQL-instructie-id en de huidige status, in plaats van het resultaat van de instructie. Als u dit gedrag wilt wijzigen, voegt u deze toe
"wait_timeout"aan de aanvraag en stelt u"<x>s"deze in op , waar<x>kan zich tussen5en50seconden bevinden, bijvoorbeeld"50s". Als u de SQL-instructie-id en de huidige status onmiddellijk wilt retourneren, stelt u deze inwait_timeoutop0s.De SQL-instructie wordt standaard uitgevoerd als de time-outperiode is bereikt. Als u een SQL-instructie wilt annuleren als de time-outperiode is bereikt, voegt u deze toe
"on_wait_timeout":"CANCEL"aan de nettolading van de aanvraag.Als u het aantal geretourneerde bytes wilt beperken, voegt u deze toe
"byte_limit"aan de aanvraag en stelt u deze in op het aantal bytes, bijvoorbeeld1000.Als u het aantal geretourneerde rijen wilt beperken in plaats van een
LIMITcomponent toe testatementvoegen, kunt u deze toevoegen"row_limit"aan de aanvraag en instellen op het aantal rijen, bijvoorbeeld"statement":"SELECT * FROM lineitem","row_limit":2.Als het resultaat groter is dan het opgegeven
byte_limitofrow_limit, wordt hettruncatedveld ingesteld optruein de nettolading van het antwoord.
Als het resultaat van de instructie beschikbaar is voordat de time-out van de wachttijd eindigt, is het antwoord als volgt:
{
"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"
}
}
Als de time-out voor de wachttijd eindigt voordat het resultaat van de instructie beschikbaar is, ziet het antwoord er als volgt uit:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Als de resultaatgegevens van de instructie te groot zijn (bijvoorbeeld in dit geval door uit te voeren SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), worden de resultaatgegevens gesegmenteerd en ziet dit er als volgt uit. Houd er rekening mee dat "...": "..." hier de weggelaten resultaten worden aangegeven voor beknoptheid:
{
"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"
}
}
Stap 2: de huidige uitvoeringsstatus en het gegevensresultaat van een instructie ophalen als JSON
U kunt de id van een SQL-instructie gebruiken om de huidige uitvoeringsstatus van die instructie op te halen en, als de uitvoering is geslaagd, is het resultaat van die instructie. Als u de id van de instructie vergeet, kunt u deze ophalen uit de sectie querygeschiedenis van de Databricks SQL-console of door de Querygeschiedenis-API aan te roepen. U kunt deze opdracht bijvoorbeeld blijven peilen en elke keer controleren of de uitvoering is geslaagd.
Voer de volgende opdracht uit om de huidige uitvoeringsstatus van een SQL-instructie op te halen en, als de uitvoering is geslaagd, het resultaat van die instructie en een API-URL-fragment voor het ophalen van een volgend segment van JSON-gegevens. Met deze opdracht wordt ervan uitgegaan dat u een omgevingsvariabele hebt op uw lokale ontwikkelcomputer met de naam SQL_STATEMENT_ID, die is ingesteld op de waarde van de id van de SQL-instructie uit de vorige stap. Natuurlijk kunt u in de volgende opdracht vervangen ${SQL_STATEMENT_ID} door de in code vastgelegde id van de SQL-instructie.
Databricks-CLI
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.
curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
Als de NEXT_CHUNK_INTERNAL_LINK waarde is ingesteld op een niet-waardenull , kunt u deze gebruiken om het volgende gegevenssegment op te halen, enzovoort, bijvoorbeeld met de volgende opdracht:
Databricks-CLI
databricks api get /${NEXT_CHUNK_INTERNAL_LINK} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.
curl
curl --request GET \
https://${DATABRICKS_HOST}${NEXT_CHUNK_INTERNAL_LINK} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK
U kunt de voorgaande opdracht steeds opnieuw uitvoeren om het volgende segment op te halen, enzovoort. Houd er rekening mee dat zodra het laatste segment is opgehaald, de SQL-instructie is gesloten. Na deze sluiting kunt u de id van die instructie niet gebruiken om de huidige status op te halen of om meer segmenten op te halen.
Stap 3: Grote resultaten ophalen met behulp van externe koppelingen
In deze sectie ziet u een optionele configuratie die gebruikmaakt van de EXTERNAL_LINKS verwijdering om grote gegevenssets op te halen. De standaardlocatie (verwijdering) voor de resultaatgegevens van de SQL-instructie bevindt zich binnen de nettolading van het antwoord, maar deze resultaten zijn beperkt tot 25 MiB. Door het disposition in te EXTERNAL_LINKSstellen, bevat het antwoord URL's die u kunt gebruiken om de segmenten van de resultatengegevens op te halen met standaard HTTP. De URL's verwijzen naar de interne DBFS van uw werkruimte, waarbij de resultaatsegmenten tijdelijk worden opgeslagen.
Waarschuwing
Databricks raadt u ten zeerste aan de URL's en tokens te beveiligen die door de EXTERNAL_LINKS verwijdering worden geretourneerd.
Wanneer u de EXTERNAL_LINKS verwijdering gebruikt, wordt er een SAS-URL (Shared Access Signature) gegenereerd, die kan worden gebruikt om de resultaten rechtstreeks vanuit Azure Storage te downloaden. Aangezien een kortdurende SAS-token is ingesloten in deze SAS-URL, moet u zowel de SAS-URL als het SAS-token beveiligen.
Omdat SAS-URL's al worden gegenereerd met ingesloten tijdelijke SAS-tokens, moet u geen header instellen Authorization in de downloadaanvragen.
De EXTERNAL_LINKS verwijdering kan op verzoek worden uitgeschakeld. Als u deze aanvraag wilt indienen, maakt u een ondersteuningsaanvraag.
Zie ook aanbevolen procedures voor beveiliging.
Notitie
De uitvoerindeling en het gedrag van de nettolading van het antwoord, zodra deze zijn ingesteld voor een bepaalde SQL-instructie-id, kunnen niet worden gewijzigd.
In deze modus kunt u met de API resultaatgegevens opslaan in JSON-indeling (JSON), CSV-indeling (CSV) of Apache Arrow-indeling (ARROW_STREAM), die afzonderlijk moeten worden opgevraagd met HTTP. Wanneer u deze modus gebruikt, is het ook niet mogelijk om de resultaatgegevens binnen de nettolading van het antwoord inline te plaatsen.
De volgende opdracht demonstreert het gebruik en EXTERNAL_LINKS de Apache Arrow-indeling. Gebruik dit patroon in plaats van de vergelijkbare query die wordt gedemonstreerd in stap 1:
Databricks-CLI
databricks api post /api/2.0/sql/statements/ \
--profile <profile-name> \
--json '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"format": "ARROW_STREAM",
"disposition": "EXTERNAL_LINKS",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "100000", "type": "INT" }
]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID
Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.
curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
"warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
"catalog": "samples",
"schema": "tpch",
"format": "ARROW_STREAM",
"disposition": "EXTERNAL_LINKS",
"statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
"parameters": [
{ "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
{ "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
{ "name": "row_limit", "value": "100000", "type": "INT" }
]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID
Het antwoord is als volgt:
{
"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"
}
}
Als er een time-out optreedt voor de aanvraag, ziet het antwoord er als volgt uit:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Voer de volgende opdracht uit om de huidige uitvoeringsstatus van die instructie op te halen en voer de volgende opdracht uit als de uitvoering is geslaagd:
Databricks-CLI
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.
curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Als het antwoord groot genoeg is (bijvoorbeeld in dit geval door uit te voeren SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem zonder rijlimiet), heeft het antwoord meerdere segmenten, zoals in het volgende voorbeeld hieronder. Houd er rekening mee dat "...": "..." hier de weggelaten resultaten worden aangegeven voor beknoptheid:
{
"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"
}
}
Als u de resultaten van de opgeslagen inhoud wilt downloaden, kunt u de volgende curl opdracht uitvoeren met behulp van de URL in het external_link object en opgeven waar u het bestand wilt downloaden. Neem uw Azure Databricks-token niet op in deze opdracht:
curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"
Als u een specifiek segment van de resultaten van een gestreamde inhoud wilt downloaden, kunt u een van de volgende opties gebruiken:
- De
next_chunk_indexwaarde van de nettolading van het antwoord voor het volgende segment (als er een volgende segment is). - Een van de segmentindexen uit het manifest van de nettolading van het antwoord voor elk beschikbaar segment als er meerdere segmenten zijn.
Als u bijvoorbeeld het segment met een chunk_index van 10 het vorige antwoord wilt ophalen, voert u de volgende opdracht uit:
Databricks-CLI
databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.
curl
curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'
Notitie
Als u de voorgaande opdracht uitvoert, wordt een nieuwe SAS-URL geretourneerd.
Als u het opgeslagen segment wilt downloaden, gebruikt u de URL in het external_link object.
Zie voor meer informatie over de Apache Arrow-indeling:
Stap 4: de uitvoering van een SQL-instructie annuleren
Als u een SQL-instructie wilt annuleren die nog niet is geslaagd, voert u de volgende opdracht uit:
Databricks-CLI
databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'
Vervang <profile-name> door de naam van uw Azure Databricks-configuratieprofiel voor verificatie.
curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"
Aanbevolen procedures voor beveiliging
De Databricks SQL-instructieuitvoerings-API verhoogt de beveiliging van gegevensoverdracht met behulp van end-to-end TLS-versleuteling (Transport Layer Security) en kortstondige referenties zoals SAS-tokens.
Er zijn verschillende lagen in dit beveiligingsmodel. Op de transportlaag is het alleen mogelijk om de Databricks SQL-instructieuitvoerings-API aan te roepen met behulp van TLS 1.2 of hoger. Aanroepers van de Databricks SQL-instructieuitvoerings-API moeten ook worden geverifieerd met een geldig persoonlijk toegangstoken van Azure Databricks of Microsoft Entra ID (voorheen Azure Active Directory) dat is toegewezen aan een gebruiker die het recht heeft om Databricks SQL te gebruiken. Deze gebruiker moet CAN USE-toegang hebben voor het specifieke SQL Warehouse dat wordt gebruikt en toegang kan worden beperkt met IP-toegangslijsten. Dit geldt voor alle aanvragen voor de Databricks SQL-instructieuitvoerings-API. Bovendien moet de geverifieerde gebruiker voor het uitvoeren van instructies gemachtigd zijn voor de gegevensobjecten (zoals tabellen, weergaven en functies) die in elke instructie worden gebruikt. Dit wordt afgedwongen door bestaande mechanismen voor toegangsbeheer in Unity Catalog of met behulp van tabel-ACL's. (Zie Gegevensbeheer met Unity Catalog voor meer informatie.) Dit betekent ook dat alleen de gebruiker die een instructie uitvoert, aanvragen voor de resultaten van de instructie kan ophalen.
Databricks raadt de volgende aanbevolen beveiligingsprocedures aan wanneer u de Databricks SQL-instructieuitvoerings-API gebruikt, samen met de EXTERNAL_LINKS verwijdering om grote gegevenssets op te halen:
- De Databricks-autorisatieheader voor Azure-opslagaanvragen verwijderen
- SAS-URL's en SAS-tokens beveiligen
De EXTERNAL_LINKS verwijdering kan op aanvraag worden uitgeschakeld door een ondersteuningsaanvraag te maken. Neem contact op met uw Azure Databricks-accountteam om een ondersteuningsaanvraag te maken.
De Databricks-autorisatieheader voor Azure-opslagaanvragen verwijderen
Alle aanroepen naar de Databricks SQL-instructieuitvoerings-API die wordt gebruikt curl , moeten een Authorization header bevatten die Azure Databricks-toegangsreferenties bevat. Neem deze Authorization header niet op wanneer u gegevens downloadt uit Azure Storage. Deze header is niet vereist en kan onbedoeld uw Azure Databricks-toegangsreferenties beschikbaar maken.
SAS-URL's en SAS-tokens beveiligen
Wanneer u de EXTERNAL_LINKS verwijdering gebruikt, wordt er een KORTdurende SAS-URL gegenereerd, die de aanroeper kan gebruiken om de resultaten rechtstreeks vanuit Azure Storage te downloaden met behulp van TLS. Aangezien een kortdurende SAS-token is ingesloten in deze SAS-URL, moet u zowel de SAS-URL als het SAS-token beveiligen.
Feedback
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor