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, 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.
  
  Führen Sie beispielsweise die Schritte unter Erstellen von persönlichen Zugriffstokens für Arbeitsbereichsbenutzer aus, um sich mit Databricks zu authentifizieren.
  
  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 DEFAULT erstellt. Wenn Sie bereits ein DEFAULT-Konfigurationsprofil besitzen, wird Ihr vorhandenes DEFAULT-Konfigurationsprofil durch dieses Verfahren überschrieben.
  
  Um zu überprüfen, ob Sie bereits über ein DEFAULT Konfigurationsprofil verfügen und die Einstellungen dieses Profils anzeigen möchten, falls vorhanden, verwenden Sie die Databricks CLI, um den Befehl databricks auth env --profile DEFAULTauszuführen.
  
  Um ein Konfigurationsprofil mit einem anderen Namen als DEFAULT zu erstellen, ersetzen Sie den DEFAULT-Teil von --profile DEFAULT in dem folgenden databricks configure-Befehl durch einen anderen Namen für das Konfigurationsprofil.
  1. 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 DEFAULT
```
  2. Geben Sie als Databricks-Host Ihre arbeitsbereichsspezifische Azure Databricks-URL ein, z. B. https://adb-1234567890123456.7.azuredatabricks.net.
  3. 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 Lernprogramms Folgendes:
  - In diesem Tutorial wird davon ausgegangen, dass Sie auf Ihrem lokalen Entwicklungscomputer über eine Umgebungsvariable mit dem Namen DATABRICKS_SQL_WAREHOUSE_ID verfü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. Informationen zum Abrufen des HTTP-Pfadwerts Ihres Lagers finden 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). Oder passen Sie die Beispiele dieses Lernprogramms curl für die Verwendung mit ähnlichen Tools wie HTTPie an.
  
  Beachten Sie in den Beispielen curl dieses Lernprogramms 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 .netrc muss --header "Authorization: Bearer ${DATABRICKS_TOKEN}" durch --netrc ersetzt 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 bei den Beispielen dieses Lernprogramms curl davon ausgegangen, dass Sie über die folgenden Umgebungsvariablen auf Ihrem lokalen Entwicklungscomputer verfügen:
  - DATABRICKS_HOST, steht für den Namen der Arbeitsbereichsinstanz (beispielsweise adb-1234567890123456.7.azuredatabricks.net) für Ihren Azure Databricks-Arbeitsbereich
  - DATABRICKS_TOKEN, steht für ein persönliches Zugriffstoken von Azure Databricks für den*die Azure Databricks-Arbeitsbereichsbenutzer*in
  - DATABRICKS_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. Informationen zum Abrufen des HTTP-Pfadwerts Ihres Lagers finden 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.
  
  Zum Erstellen eines persönlichen Azure Databricks-Zugriffstokens folgen Sie den Klammern in " Persönliche Zugriffstoken für Arbeitsbereichsbenutzer erstellen".
  
  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.
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 lineitem im Schema tpch (auch als Datenbank bezeichnet) innerhalb des Katalogs samples. 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 curl nutzen, wird das angegebene SQL-Warehouse zusammen mit dem angegebenen Token verwendet, um drei Spalten aus den ersten beiden Zeilen der Tabelle lineitem im Schema tcph aus dem Katalog samples abzufragen.
Die Nutzdaten der Antwort werden im aktuellen Arbeitsverzeichnis in einer Datei namens sql-execution-response.json im JSON-Format gespeichert.
Der Inhalt der Datei sql-execution-response.json wird ausgegeben.
Legt eine lokale Umgebungsvariable namens SQL_STATEMENT_ID fest. 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_LINK festgelegt, 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 auf nullfestgelegt.
Die Werte der Umgebungsvariablen SQL_STATEMENT_ID und NEXT_CHUNK_INTERNAL_LINK werden ausgegeben.

Databricks-Befehlszeilenschnittstelle

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.

Locke

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 jedes Abfrageparameters, dem ein Doppelpunkt vorangestellt ist (z. B. :extended_price), zusammen mit einem entsprechenden name und value Objekt im Array parameters. Optional kann auch type angegeben werden. Dabei wird der Standardwert STRING verwendet, 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.

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 befinden sich alle zurückgegebenen Daten im JSON-Arrayformat, und der Standardspeicherort für die Datenergebnisse der SQL-Anweisung befindet sich innerhalb der Antwortnutzlast. 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 Antwortnutzlast in einer lokalen Datei. Lokaler Datenspeicher wird von der „Databricks SQL Statement Execution“-API nicht direkt unterstützt.
Standardmäßig gibt die Databricks SQL-Anweisung-Ausführungs-API nach 10 Sekunden, wenn die SQL-Anweisung im Warehouse noch nicht fertiggestellt wurde, nur die SQL-Anweisungs-ID und ihren aktuellen Status zurück, anstatt das Ergebnis der Anweisung. 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 zwischen 5 und 50 Sekunden (einschließlich) beispielsweise "50s" liegen. Wenn die SQL-Anweisungs-ID und der aktuelle Status sofort zurückgegeben werden sollen, legen Sie wait_timeout auf 0s fest.
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 auf 1000.
Um die Anzahl der zurückgegebenen Zeilen zu begrenzen, können Sie statt LIMIT eine statement-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_limit oder row_limit ist, wird das truncated-Feld in der Antwortnutzlast auf true festgelegt.

Wenn das Ergebnis der Anweisung verfügbar ist, bevor das Wartezeittimeout endet, lautet die Antwort wie folgt:

{
  "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 Wartezeit-Timeout endet, bevor das Ergebnis der Anweisung verfügbar ist, ist die Antwort stattdessen folgendermaßen aufgebaut:

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

Wenn die Ergebnisdaten der Anweisung zu groß sind (z. B. in diesem Fall durch Ausführen SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000), werden die Ergebnisdaten in Stücke aufgeteilt und sehen dann so 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 und des Datenergebnisses einer Anweisung als JSON

Sie können die ID einer SQL-Anweisung verwenden, um den aktuellen Ausführungsstatus dieser Anweisung abzurufen und wenn die Ausführung erfolgreich war, das Ergebnis dieser Anweisung. Wenn Sie die ID der Anweisung vergessen, können Sie sie aus dem Abfrageverlaufsbereich der Databricks SQL-Konsole abrufen oder die Abfrageverlaufs-API aufrufen. Beispielsweise können Sie diesen Befehl weiter abfragen und jedes Mal überprüfen, ob die Ausführung erfolgreich war.

Führen Sie den folgenden Befehl aus, um den aktuellen Ausführungsstatus einer SQL-Anweisung abzurufen. Wenn die Ausführung erfolgreich war, führen Sie den folgenden Befehl aus, um das Ergebnis dieser Anweisung und ein API-URL-Fragment zum Abrufen eines nächsten Blocks von JSON-Daten abzurufen. 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-Befehlszeilenschnittstelle

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.

Locke

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

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.

Locke

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. Nach diesem Schließen können Sie die ID dieser Anweisung nicht verwenden, um den aktuellen Status abzurufen oder weitere Blöcke abzurufen.

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, indem Sie einen Supportfall erstellen.

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

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.

Locke

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, falls die Ausführung erfolgreich war, das Ergebnis dieser Anweisung zu erhalten.

Databricks-Befehlszeilenschnittstelle

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.

Locke

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 external_link Objekt verwenden und angeben, wo Sie die Datei herunterladen möchten. 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 eine der folgenden Aktionen verwenden:

Den next_chunk_index-Wert aus der Antwortnutzlast für den nächsten Block (wenn ein nächster Block vorhanden ist).
Einer der Chunk-Indizes aus dem Manifest der Antwortnutzlast für einen verfügbaren Chunk, wenn es mehrere gibt.

Führen Sie also beispielsweise den folgenden Befehl aus, um den Block mit chunk_index von 10 aus der vorherigen Abfrage abzurufen:

Databricks-Befehlszeilenschnittstelle

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.

Locke

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

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.

Locke

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, OAuth access token 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. (Weitere Informationen finden Sie unter Data Governance mit Azure Databricks .) Dies bedeutet auch, dass nur der Benutzer, der eine Anweisung ausführt, Abrufanforderungen für die Ergebnisse der Anweisung vornehmen 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 Zugriff anzufordern.

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

War diese Seite hilfreich?

Last updated on 2024-11-16

Freigeben über

Anweisungsausführungs-API: Ausführen von SQL auf Warehouses

Voraussetzungen

Schritt 1: Ausführen einer SQL-Anweisung und Speichern des Datenergebnisses im JSON-Format

Databricks-Befehlszeilenschnittstelle

Locke

Schritt 2: Abrufen des aktuellen Ausführungsstatus und des Datenergebnisses einer Anweisung als JSON

Databricks-Befehlszeilenschnittstelle

Locke

Databricks-Befehlszeilenschnittstelle

Locke

Schritt 3: Abrufen großer Ergebnisse mithilfe externer Links

Databricks-Befehlszeilenschnittstelle

Locke

Databricks-Befehlszeilenschnittstelle

Locke

Databricks-Befehlszeilenschnittstelle

Locke

Schritt 4: Abbrechen der Ausführung einer SQL-Anweisung

Databricks-Befehlszeilenschnittstelle

Locke

Bewährte Methoden für die Sicherheit

Entfernen des Databricks-Autorisierungsheaders für Azure-Speicheranforderungen

Schützen von SAS-URLs und SAS-Token

Feedback

Zusätzliche Ressourcen