Anweisungsausführungs-API: Ausführen von SQL auf Warehouses
Wichtig
Für den Zugriff auf Databricks-REST-APIs müssen Sie sich authentifizieren.
In diesem Tutorial wird Ihnen gezeigt, wie Sie die „Databricks SQL Statement Execution“-API 2.0 verwenden, um SQL-Anweisungen von Databricks SQL-Warehouses aus auszuführen.
Informationen zum Anzeigen der SQL-Anweisungsausführungs-API 2.0-Referenz für Databricks finden Sie unter Anweisungsausführung.
Voraussetzungen
Stellen Sie vor Beginn dieses Tutorials sicher, dass Sie über Folgendes verfügen:
Entweder Databricks CLI Version 0.205 oder höher oder
curl, wie folgt:Die Databricks-Befehlszeilenschnittstelle ist ein Befehlszeilentool zum Senden und Empfangen von REST-API-Anforderungen und -Antworten in Databricks. Wenn Sie Version 0.205 oder höher der Databricks CLI verwenden möchten, muss sie für die Authentifizierung mit Ihrem Azure Databricks-Arbeitsbereich konfiguriert werden. Siehe Installieren oder Aktualisieren der Databricks CLI und Authentifizierung für Databricks CLI.
Um sich z. B. Databricks-Authentifizierung für persönliche Zugriffstoken zu authentifizieren, erstellen Sie wie folgt ein persönliches Zugriffstoken:
- Wählen Sie in Ihrem Azure Databricks-Arbeitsbereich in der oberen Leiste Ihren Azure Databricks-Benutzernamen und dann im Dropdownmenü die Option Einstellungen aus.
- Klicken Sie auf Entwickler.
- Klicken Sie neben Zugriffstoken auf Verwalten.
- Klicken Sie auf Neues Token generieren.
- (Optional) Geben Sie einen Kommentar ein, durch den Sie dieses Token in Zukunft identifizieren können, und ändern Sie die standardmäßige Lebensdauer des Tokens von 90 Tagen. Wenn Sie ein Token ohne Gültigkeitsdauer erstellen möchten (nicht empfohlen), lassen Sie das Feld Lebensdauer (Tage) leer.
- Klicken Sie auf Generate (Generieren) .
- Kopieren Sie das angezeigte Token an einen sicheren Speicherort, und klicken Sie auf Fertig.
Hinweis
Achten Sie darauf, den kopierten Token an einem sicheren Ort zu speichern. Geben Sie das kopierte Token nicht an andere Personen weiter. Wenn Sie das kopierte Token verlieren, können Sie das gleiche Token nicht erneut generieren. Stattdessen müssen Sie erneut das Verfahren zum Erstellen eines neuen Tokens durchlaufen. Wenn Sie das kopierte Token verlieren oder glauben, dass das Token kompromittiert wurde, empfiehlt Databricks dringend, dass Sie das Token sofort aus Ihrem Arbeitsbereich löschen. Klicken Sie hierzu auf der Seite Zugriffstoken auf das Papierkorbsymbol (Widerrufen) neben dem Token.
Wenn Sie in Ihrem Arbeitsbereich keine Token erstellen oder verwenden können, liegt dies möglicherweise daran, dass Ihr Arbeitsbereichsadministrator Token deaktiviert hat oder Ihnen keine Berechtigung zum Erstellen oder Verwenden von Token erteilt hat. Wenden Sie sich an Ihren Arbeitsbereichsadministrator oder lesen Sie:
Führen Sie die folgenden Schritte aus, um mithilfe der Databricks CLI ein Azure Databricks-Konfigurationsprofil für Ihr persönliches Zugriffstoken zu erstellen:
Hinweis
Im folgenden Verfahren wird mit der Databricks-CLI ein Azure Databricks-Konfigurationsprofil mit dem Namen
DEFAULTerstellt. Wenn Sie bereits einDEFAULT-Konfigurationsprofil besitzen, wird Ihr vorhandenesDEFAULT-Konfigurationsprofil durch dieses Verfahren überschrieben.Um zu überprüfen, ob Sie bereits ein
DEFAULT-Konfigurationsprofil haben, und um die Einstellungen dieses Profils anzuzeigen, wenn es existiert, verwenden Sie die Databricks-Befehlszeilenschnittstelle, um den Befehldatabricks auth env --profile DEFAULTauszuführen.Um ein Konfigurationsprofil mit einem anderen Namen als
DEFAULTzu erstellen, ersetzen Sie denDEFAULT-Teil von--profile DEFAULTin dem folgendendatabricks configure-Befehl durch einen anderen Namen für das Konfigurationsprofil.Erstellen Sie mithilfe der Databricks-CLI ein Azure Databricks-Konfigurationsprofil mit dem Namen
DEFAULT, das die Authentifizierung des persönlichen Zugriffstokens von Azure Databricks verwendet. Führen Sie zu diesem Zweck den folgenden Befehl aus:databricks configure --profile DEFAULTGeben Sie als Databricks-Host Ihre arbeitsbereichsspezifische Azure Databricks-URL ein, z. B.
https://adb-1234567890123456.7.azuredatabricks.net.Geben Sie für Persönliches Zugriffstoken Ihr persönliches Azure Databricks-Zugriffstoken für Ihren Arbeitsbereich ein.
Beachten Sie in den Databricks CLI-Beispielen dieses Tutorials Folgendes:
- In diesem Tutorial wird davon ausgegangen, dass Sie auf Ihrem lokalen Entwicklungscomputer über eine Umgebungsvariable mit dem Namen
DATABRICKS_SQL_WAREHOUSE_IDverfügen. Diese Umgebungsvariable stellt die ID Ihres Databricks SQL-Warehouse dar. Diese ID ist die Zeichenfolge aus Buchstaben und Zahlen nach/sql/1.0/warehouses/im Feld HTTP-Pfad für Ihr Warehouse. Wie Sie den Wert des HTTP-Pfads Ihrer Warehouses abrufen, erfahren Sie unter Abrufen von Verbindungsdetails für eine Azure Databricks-Computeressource. - Wenn Sie anstelle einer Befehlsshell für Unix, Linux oder macOS die Windows-Befehlsshell verwenden, ersetzen
\Sie durch^und${...}durch%...%. - Wenn Sie anstelle einer Befehlsshell für Unix, Linux oder macOS die Windows-Befehlsshell verwenden, ersetzen Sie in JSON-Dokumentdeklarationen die öffnenden und schließenden
'-Zeichen durch"sowie interne"-Zeichen durch\".
cURL ist ein Befehlszeilentool zum Senden und Empfangen von REST-API-Anforderungen und -Antworten. Weitere Informationen finden Sie unter Install curl (Installieren von cURL). Alternativ können Sie die
curl-Beispiele dieses Tutorials für die Verwendung mit ähnlichen Tools wie Postman oder HTTPie anpassen.Beachten Sie in den
curl-Beispielen dieses Tutorials Folgendes:- Anstelle von
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"können Sie eine Datei mit der Erweiterung .netrc verwenden. Bei Verwendung einer Datei mit der Erweiterung.netrcmuss--header "Authorization: Bearer ${DATABRICKS_TOKEN}"durch--netrcersetzt werden. - Wenn Sie anstelle einer Befehlsshell für Unix, Linux oder macOS die Windows-Befehlsshell verwenden, ersetzen
\Sie durch^und${...}durch%...%. - Wenn Sie anstelle einer Befehlsshell für Unix, Linux oder macOS die Windows-Befehlsshell verwenden, ersetzen Sie in JSON-Dokumentdeklarationen die öffnenden und schließenden
'-Zeichen durch"sowie interne"-Zeichen durch\".
Außerdem wird für die
curl-Beispiele dieses Tutorials in diesem Tutorial davon ausgegangen, dass Sie über die folgenden Umgebungsvariablen auf Ihrem lokalen Entwicklungscomputer verfügen:DATABRICKS_HOST, steht für den Namen der Arbeitsbereichsinstanz (beispielsweiseadb-1234567890123456.7.azuredatabricks.net) für Ihren Azure Databricks-ArbeitsbereichDATABRICKS_TOKEN, steht für ein persönliches Zugriffstoken von Azure Databricks für den*die Azure Databricks-Arbeitsbereichsbenutzer*inDATABRICKS_SQL_WAREHOUSE_ID, steht für die ID Ihres Databricks SQL-Warehouse. Diese ID ist die Zeichenfolge aus Buchstaben und Zahlen nach/sql/1.0/warehouses/im Feld HTTP-Pfad für Ihr Warehouse. Wie Sie den Wert des HTTP-Pfads Ihrer Warehouses abrufen, erfahren Sie unter Abrufen von Verbindungsdetails für eine Azure Databricks-Computeressource.
Hinweis
Als bewährte Methode für die Sicherheit empfiehlt Databricks, dass Sie bei der Authentifizierung mit automatisierten Tools, Systemen, Skripten und Anwendungen persönliche Zugriffstoken verwenden, die zu Dienstprinzipalen und nicht zu Benutzern des Arbeitsbereichs gehören. Informationen zum Erstellen von Token für Dienstprinzipale finden Sie unter Verwalten von Token für einen Dienstprinzipal.
Tun Sie Folgendes, um ein persönliches Azure Databricks-Zugriffstoken zu erstellen:
- Wählen Sie in Ihrem Azure Databricks-Arbeitsbereich in der oberen Leiste Ihren Azure Databricks-Benutzernamen und dann im Dropdownmenü die Option Einstellungen aus.
- Klicken Sie auf Entwickler.
- Klicken Sie neben Zugriffstoken auf Verwalten.
- Klicken Sie auf Neues Token generieren.
- (Optional) Geben Sie einen Kommentar ein, durch den Sie dieses Token in Zukunft identifizieren können, und ändern Sie die standardmäßige Lebensdauer des Tokens von 90 Tagen. Wenn Sie ein Token ohne Gültigkeitsdauer erstellen möchten (nicht empfohlen), lassen Sie das Feld Lebensdauer (Tage) leer.
- Klicken Sie auf Generate (Generieren) .
- Kopieren Sie das angezeigte Token an einen sicheren Speicherort, und klicken Sie auf Fertig.
Hinweis
Achten Sie darauf, den kopierten Token an einem sicheren Ort zu speichern. Geben Sie das kopierte Token nicht an andere Personen weiter. Wenn Sie das kopierte Token verlieren, können Sie das gleiche Token nicht erneut generieren. Stattdessen müssen Sie erneut das Verfahren zum Erstellen eines neuen Tokens durchlaufen. Wenn Sie das kopierte Token verlieren oder glauben, dass das Token kompromittiert wurde, empfiehlt Databricks dringend, dass Sie das Token sofort aus Ihrem Arbeitsbereich löschen. Klicken Sie hierzu auf der Seite Zugriffstoken auf das Papierkorbsymbol (Widerrufen) neben dem Token.
Wenn Sie in Ihrem Arbeitsbereich keine Token erstellen oder verwenden können, liegt dies möglicherweise daran, dass Ihr Arbeitsbereichsadministrator Token deaktiviert hat oder Ihnen keine Berechtigung zum Erstellen oder Verwenden von Token erteilt hat. Wenden Sie sich an Ihren Arbeitsbereichsadministrator oder lesen Sie:
Warnung
Databricks rät dringend davon ab, Informationen als hartcodierte Werte in Skripts einzufügen, da diese sensiblen Informationen als Klartext über Versionskontrollsysteme offengelegt werden können. Databricks empfiehlt, stattdessen Ansätze wie Umgebungsvariablen zu verwenden, die Sie auf Ihrem Entwicklungscomputer festlegen. Durch Entfernen solcher hartcodierten Informationen aus Ihren Skripts werden diese Skripts auch besser portierbar.
- Anstelle von
In diesem Tutorial wird davon ausgegangen, dass Sie außerdem über jq, einen Befehlszeilenprozessor zum Abfragen der Nutzdaten von JSON-Antworten verfügen, die die Databricks SQL Statement Execution-API nach jedem Aufruf an Sie zurückgibt. Siehe Download jq.
Sie benötigen mindestens eine Tabelle, für die Sie SQL-Anweisungen ausführen können. Dieses Tutorial basiert auf der Tabelle
lineitemim Schematpch(auch als Datenbank bezeichnet) innerhalb des Katalogssamples. Wenn Sie von Ihrem Arbeitsbereich aus keinen Zugriff auf den Katalog, das Schema oder die Tabelle haben, ersetzen Sie die Elemente, auf die Sie nicht zugreifen können, in diesem Tutorial durch Ihre eigenen.
Schritt 1: Ausführen einer SQL-Anweisung und Speichern des Datenergebnisses im JSON-Format
Führen Sie den folgenden Befehl aus. Dies bewirkt Folgendes:
- Wenn Sie
curlnutzen, wird das angegebene SQL-Warehouse zusammen mit dem angegebenen Token verwendet, um drei Spalten aus den ersten beiden Zeilen der Tabellelineitemim Schematcphaus dem Katalogsamplesabzufragen. - Die Nutzdaten der Antwort werden im aktuellen Arbeitsverzeichnis in einer Datei namens
sql-execution-response.jsonim JSON-Format gespeichert. - Der Inhalt der Datei
sql-execution-response.jsonwird ausgegeben. - Legt eine lokale Umgebungsvariable namens
SQL_STATEMENT_IDfest. Diese Variable enthält die ID der entsprechenden SQL-Anweisung. Diese SQL-Anweisungs-ID kann bei Bedarf später verwendet werden, um Informationen zu dieser Anweisung zu erhalten, wie in Schritt 2 gezeigt. Sie können diese SQL-Anweisung auch über den Abschnitt Abfrageverlauf der Databricks SQL-Konsole anzeigen und die Anweisungs-ID dort ermitteln oder dazu die Abfrageverlaufs-API aufrufen. - Es wird eine zusätzliche lokale Umgebungsvariable namens
NEXT_CHUNK_EXTERNAL_LINKfestgelegt, die ein API-URL-Fragment zum Abrufen des nächsten JSON-Datenblocks enthält. Sind die Antwortdaten zu groß, wird die Antwort von der „Databricks SQL Statement Execution“-API in Blöcken bereitgestellt. Dieses API-URL-Fragment kann zum Abrufen des nächsten Datenblocks verwendet werden, wie in Schritt 2 gezeigt. Ist kein weiterer Block vorhanden, wird diese Umgebungsvariable aufnullfestgelegt. - Die Werte der Umgebungsvariablen
SQL_STATEMENT_IDundNEXT_CHUNK_INTERNAL_LINKwerden ausgegeben.
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
Ersetzen Sie <profile-name> durch den Namen des Azure Databricks-Konfigurationsprofils für die Authentifizierung.
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 der vorherigen Anforderung gilt Folgendes:
Parametrisierte Abfragen bestehen aus dem Namen der einzelnen Abfrageparameter mit einem vorangestellten Doppelpunkt (z. B.
:extended_price) mit einem übereinstimmendenname- undvalue-Objekt im Arrayparameters. Optional kann auchtypeangegeben werden. Dabei wird der StandardwertSTRINGverwendet, wenn keine Angabe gemacht wird.Warnung
Databricks empfiehlt dringend, Parameter als bewährte Methode für Ihre SQL-Anweisungen zu verwenden.
Wenn Sie die SQL-Anweisungsausführungs-API für Databricks mit einer Anwendung verwenden, die SQL dynamisch generiert, kann dies zu SQL-Einfügungsangriffen führen. Wenn Sie z. B. SQL-Code basierend auf der Auswahl eines Benutzers in einer Benutzeroberfläche generieren und keine geeigneten Maßnahmen ergreifen, könnte ein Angreifer schädlichen SQL-Code einfügen, um die Logik Ihrer anfänglichen Abfrage zu ändern, wodurch vertrauliche Daten gelesen, geändert oder gelöscht werden können.
Parametrisierte Abfragen tragen zum Schutz vor SQL-Einfügungsangriffen bei, indem Eingabeargumente separat vom Rest des SQL-Codes verarbeitet und diese Argumente als Literalwerte interpretiert werden. Parameter helfen auch bei der Wiederverwendbarkeit von Code.
Standardmäßig liegen alle zurückgegebenen Daten im JSON-Arrayformat vor, und der Standardspeicherort für die Datenergebnisse der SQL-Anweisung befindet sich innerhalb der Antwortnutzdaten. Wenn Sie dieses Verhalten explizit machen möchten, können Sie den Anforderungsnutzdaten
"format":"JSON_ARRAY","disposition":"INLINE"hinzufügen. Wenn Sie versuchen, in den Antwortnutzdaten Datenergebnisse mit einer Größe von mehr als 25 MiB zurückzugeben, wird ein Fehlerstatus zurückgegeben, und die SQL-Anweisung wird abgebrochen. Bei Datenergebnissen, deren Größe 25 MiB übersteigt, können Sie externe Links verwenden, anstatt zu versuchen, sie in den Antwortnutzdaten zurückzugeben. Dies wird in Schritt 3 gezeigt.Der Befehl speichert den Inhalt der Antwortnutzdaten in einer lokalen Datei. Lokaler Datenspeicher wird von der „Databricks SQL Statement Execution“-API nicht direkt unterstützt.
Standardmäßig gilt: Wenn die Ausführung der SQL-Anweisung im Warehouse nach zehn Sekunden noch nicht abgeschlossen ist, gibt die „Databricks SQL Statement Execution“-API anstelle des Ergebnisses der Anweisung nur die SQL-Anweisungs-ID und den aktuellen Status zurück. Wenn Sie dieses Verhalten ändern möchten, fügen Sie der Anforderung
"wait_timeout"hinzu und stellen Sie es auf"<x>s".<x>kann hierbei zwischen5und50Sekunden (einschließlich) beispielsweise"50s"liegen. Wenn die SQL-Anweisungs-ID und der aktuelle Status sofort zurückgegeben werden sollen, legen Siewait_timeoutauf0sfest.Standardmäßig wird die SQL-Anweisung bei Erreichen des Timeoutzeitraums weiter ausgeführt. Wenn eine SQL-Anweisung bei Erreichen des Timeoutzeitraums abgebrochen werden soll, fügen Sie den Anforderungsnutzdaten
"on_wait_timeout":"CANCEL"hinzu.Um die Anzahl der zurückgegebenen Bytes zu begrenzen, fügen Sie
"byte_limit"der Anforderung hinzu, und legen Sie sie auf die Anzahl der Bytes fest, z. B auf1000.Um die Anzahl der zurückgegebenen Zeilen zu begrenzen, können Sie statt
statementeineLIMIT-Klausel hinzufügen, der Anfrage"row_limit"hinzufügen und sie auf die Anzahl der Zeilen festlegen, wie z. B."statement":"SELECT * FROM lineitem","row_limit":2.Wenn das Ergebnis größer als die festgelegten
byte_limitoderrow_limitist, wird dastruncated-Feld in der Antwortnutzlast auftruefestgelegt.
Wenn das Ergebnis vor dem Ende des Wartezeittimeouts der Anweisung verfügbar ist, sieht die Antwort wie folgt aus:
{
"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"
}
}
Wenn das Wartezeittimeout endet, bevor das Ergebnis der Anweisung verfügbar ist, sieht die Antwort stattdessen wie folgt aus:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Wenn die Ergebnisdaten der Anweisung zu groß sind (in diesem Fall beispielsweise durch Ausführen von SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), werden die Ergebnisdaten in Blöcke aufgeteilt und sehen stattdessen wie folgt aus. "...": "..." gibt an, dass hier zur Verkürzung Ergebnisse weggelassen wurden:
{
"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"
}
}
Schritt 2: Abrufen des aktuellen Ausführungsstatus einer Anweisung und des Datenergebnisses im JSON-Format
Sie können die ID einer SQL-Anweisung verwenden, um den aktuellen Ausführungsstatus dieser Anweisung abzurufen (und im Falle einer erfolgreichen Ausführung auch das Ergebnis der Anweisung). Wenn Sie die ID der Anweisung vergessen, können Sie sie im Abschnitt Abfrageverlauf der Databricks SQL-Konsole oder durch Aufrufen der Abfrageverlaufs-API ermitteln. Beispielsweise können Sie diesen Befehl weiter abfragen und jedes Mal überprüfen, ob die Ausführung erfolgreich war.
Um den aktuellen Ausführungsstatus einer SQL-Anweisung (und bei erfolgreicher Ausführung das Ergebnis dieser Anweisung sowie ein API-URL-Fragment zum Abrufen des ggf. vorhandenen nächsten JSON-Datenblocks) abzurufen, können Sie den folgenden Befehl ausführen. Bei diesem Befehl wird davon ausgegangen, dass Sie auf Ihrem lokalen Entwicklungscomputer über eine Umgebungsvariable mit dem Namen SQL_STATEMENT_ID verfügen, die auf den Wert der ID der SQL-Anweisung aus dem vorherigen Schritt festgelegt ist. ${SQL_STATEMENT_ID} kann im folgenden Befehl auch durch die hartcodierte ID der SQL-Anweisung ersetzt werden.
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
Ersetzen Sie <profile-name> durch den Namen des Azure Databricks-Konfigurationsprofils für die Authentifizierung.
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
Wenn NEXT_CHUNK_INTERNAL_LINK auf einen Wert festgelegt ist, der nicht null ist, können Sie ihn verwenden, um jeweils den nächsten Datenblock abzurufen – beispielsweise mithilfe des folgenden Befehls:
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
Ersetzen Sie <profile-name> durch den Namen des Azure Databricks-Konfigurationsprofils für die Authentifizierung.
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
Sie können den vorherigen Befehl immer wieder ausführen, um jeweils den nächsten Block abzurufen. Beachten Sie, dass die SQL-Anweisung nach Abruf des letzten Blocks geschlossen wird. Danach kann die ID dieser Anweisung nicht mehr zum Abrufen des aktuellen Status oder zum Abrufen weiterer Blöcke verwendet werden.
Schritt 3: Abrufen großer Ergebnisse mithilfe externer Links
In diesem Abschnitt wird eine optionale Konfiguration gezeigt, die die Disposition EXTERNAL_LINKS verwendet, um große Datasets abzurufen. Der Standardspeicherort (Disposition) für die Ergebnisdaten der SQL-Anweisung ist in den Antwortnutzdaten enthalten. Diese Ergebnisse sind aber auf 25 MiB begrenzt. Durch Festlegen von disposition auf EXTERNAL_LINKSenthält die Antwort URLs, die Sie zum Abrufen der Blöcke der Ergebnisdaten mithilfe von Standard-HTTP verwenden können. Die URLs verweisen auf das interne DBFS Ihres Arbeitsbereichs, in dem die Ergebnisblöcke vorübergehend gespeichert werden.
Warnung
Databricks empfiehlt dringend, die URLs und Token zu schützen, die von der Disposition EXTERNAL_LINKS zurückgegeben werden.
Wenn Sie die Disposition EXTERNAL_LINKS verwenden, wird eine SAS-URL (Shared Access Signature) generiert, die verwendet werden kann, um die Ergebnisse direkt aus Azure Storage herunterzuladen. Da ein kurzlebiges SAS-Token in diese SAS-URL eingebettet ist, sollten Sie sowohl die SAS-URL als auch das SAS-Token schützen.
Da SAS-URLs bereits mit eingebetteten temporären SAS-Token generiert werden, dürfen Sie in den Downloadanforderungen keinen Header Authorization festlegen.
Die Disposition EXTERNAL_LINKS kann durch eine Anforderung deaktiviert werden. Erstellen Sie einen Supportfall, um diese Anforderung zu stellen.
Weitere Informationen finden Sie unter Bewährte Sicherheitsmethoden.
Hinweis
Das Ausgabeformat der Antwortnutzdaten und das Verhalten können nicht mehr geändert werden, nachdem sie für eine bestimmte SQL-Anweisungs-ID festgelegt wurden.
In diesem Modus können Sie mit der API Ergebnisdaten nur im JSON-Format (JSON), CSV-Format (CSV) oder Apache Arrow-Format (ARROW_STREAM) speichern, was separat mithilfe von HTTP abgefragt werden muss. Außerdem ist es bei Verwendung dieses Modus nicht möglich, die Ergebnisdaten in die Antwortnutzdaten zu integrieren.
Der folgende Befehl veranschaulicht das Verwenden von EXTERNAL_LINKS und des Apache Arrow-Formats. Verwenden Sie dieses Muster anstelle der ähnlichen Abfrage, die in Schritt 1 gezeigt wird:
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
Ersetzen Sie <profile-name> durch den Namen des Azure Databricks-Konfigurationsprofils für die Authentifizierung.
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
Die Antwort lautet wie folgt:
{
"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"
}
}
Wenn für die Anforderung ein Timeout auftritt, sieht die Antwort stattdessen wie folgt aus:
{
"statement_id": "00000000-0000-0000-0000-000000000000",
"status": {
"state": "PENDING"
}
}
Führen Sie den folgenden Befehl aus, um den aktuellen Ausführungsstatus dieser Anweisung abzurufen (und im Falle einer erfolgreichen Ausführung auch das Ergebnis der Anweisung):
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'
Ersetzen Sie <profile-name> durch den Namen des Azure Databricks-Konfigurationsprofils für die Authentifizierung.
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'
Wenn die Antwort groß genug ist (in diesem Fall etwa, wenn SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem ohne Zeilengrenzwert ausgeführt wird), umfasst die Antwort mehrere Blöcke, wie im folgenden Beispiel zu sehen. "...": "..." gibt an, dass hier zur Verkürzung Ergebnisse weggelassen wurden:
{
"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"
}
}
Um die Ergebnisse des gespeicherten Inhalts herunterzuladen, können Sie den folgenden curl-Befehl ausführen, indem Sie die URL im Objekt external_link verwenden und angeben, wo die Datei heruntergeladen werden soll. Schließen Sie in diesen Befehl nicht Ihr Azure Databricks-Token ein:
curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"
Um einen bestimmten Teil der Ergebnisse eines gestreamten Inhalts herunterzuladen, können Sie eines der folgenden verwenden:
- Den
next_chunk_index-Wert aus der Antwortnutzlast für den nächsten Block (wenn ein nächster Block vorhanden ist). - Einen der Blöcke aus dem Manifest der Antwortnutzlast für alle verfügbaren Blöcke, wenn mehrere Blöcke vorhanden sind.
Führen Sie also beispielsweise den folgenden Befehl aus, um den Block mit chunk_index von 10 aus der vorherigen Abfrage abzurufen:
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'
Ersetzen Sie <profile-name> durch den Namen des Azure Databricks-Konfigurationsprofils für die Authentifizierung.
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'
Hinweis
Wenn Sie den obigen Befehl ausführen, wird eine neue vorab signierte SAS-URL zurückgegeben.
Verwenden Sie zum Herunterladen des gespeicherten Blocks die URL im external_link-Objekt.
Weitere Informationen zum Apache Arrow-Format finden Sie hier:
- IPC Streaming Format (IPC-Streamingformat)
- Writing and Reading Streaming Format (Schreiben und Lesen des Streamingformats)
- Using streams (Verwenden von Streams)
Schritt 4: Abbrechen der Ausführung einer SQL-Anweisung
Wenn Sie eine noch nicht erfolgreich abgeschlossene SQL-Anweisung abbrechen möchten, können Sie den folgenden Befehl ausführen:
Databricks CLI
databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'
Ersetzen Sie <profile-name> durch den Namen des Azure Databricks-Konfigurationsprofils für die Authentifizierung.
Curl
curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"
Bewährte Methoden für die Sicherheit
Die „Databricks SQL Statement Execution“-API erhöht die Sicherheit von Datenübertragungen durch die Verwendung von End-to-End-TLS-Verschlüsselung (Transport Layer Security) und von kurzlebigen Anmeldeinformationen wie SAS-Token.
Dieses Sicherheitsmodell verfügt über mehrere Ebenen. Auf der Transportschicht ist es nur möglich, die „Databricks SQL Statement Execution“-API abzurufen, indem sie TLS 1.2 oder höher verwenden. Außerdem müssen aufrufende Funktionen der Databricks SQL Statement Execution-API mit einem gültigen persönlichen Azure Databricks-Zugriffstoken oder Microsoft Entra ID-Token (früher Azure Active Directory) authentifiziert werden, das Benutzer*innen zugeordnet ist, die die Berechtigung für die Verwendung von Databricks SQL haben. Dieser Benutzer muss über einen KANN VERWENDEN-Zugriff für das jeweilige SQL-Warehouse verfügen, das verwendet wird. Der Zugriff kann mithilfe von IP-Zugriffslisten eingeschränkt werden. Dies gilt für alle Anforderungen an die „Databricks SQL Statement Execution“-API. Darüber hinaus muss der authentifizierte Benutzer zum Ausführen von Anweisungen über die Berechtigung für die Datenobjekte (z. B. Tabellen, Ansichten und Funktionen) verfügen, die in der jeweiligen Anweisung verwendet werden. Dies wird durch vorhandene Zugriffssteuerungsmechanismen im Unity Catalog oder durch die Verwendung von Tabellen-ACLs erzwungen. (Siehe Datengovernance mit Unity-Katalog für weitere Details.) Dies bedeutet auch, dass nur der Benutzer, der eine Anweisung ausführt, Abrufanforderungen für die Ergebnisse der Anweisung stellen kann.
Databricks empfiehlt die folgenden bewährten Sicherheitsmethoden, wenn Sie die „Databricks SQL Statement Execution“-API zusammen mit der Disposition EXTERNAL_LINKS zum Abrufen großer Datasets verwenden:
- Entfernen des Databricks-Autorisierungsheaders für Azure-Speicheranforderungen
- Schützen von SAS-URLs und SAS-Token
Die Disposition EXTERNAL_LINKS kann durch eine Anforderung deaktiviert werden, indem Sie einen Supportfall erstellen. Wenden Sie sich an Ihr Azure Databricks-Kontoteam, um diese Anforderung als Supportfall zu erstellen.
Entfernen des Databricks-Autorisierungsheaders für Azure-Speicheranforderungen
Alle Aufrufe der Databricks SQL Statement Execution-API, die curlverwenden, müssen einen Authorization-Header enthalten, der Azure Databricks-Zugriffsanmeldeinformationen enthält. Verwenden Sie diesen Authorization-Header nicht, wenn Sie Daten aus Azure Storage herunterladen. Der Header ist in diesem Fall nicht erforderlich und macht möglicherweise unbeabsichtigt Ihre Azure Databricks-Zugriffsanmeldeinformationen verfügbar.
Schützen von SAS-URLs und SAS-Token
Immer wenn Sie die Disposition EXTERNAL_LINKS verwenden, wird eine kurzlebige SAS-URL generiert, die der Aufrufer verwenden kann, um die Ergebnisse mithilfe von TLS direkt aus Azure Storage herunterzuladen. Da ein kurzlebiges SAS-Token in diese SAS-URL eingebettet ist, sollten Sie sowohl die SAS-URL als auch das SAS-Token schützen.
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für