Freigeben über

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

  • Artikel

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 Azure Databricks persönliche Zugriffstokenauthentifizierung für Benutzer des Arbeitsbereichs aus, um sich bei Databricks mit persönlichen Zugriffstoken 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 ein DEFAULT-Konfigurationsprofil haben, und um die Einstellungen dieses Profils anzuzeigen, wenn es existiert, verwenden Sie die Databricks-Befehlszeilenschnittstelle, um den Befehl databricks auth env --profile DEFAULT auszufü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 Tutorials 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. 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). Sie können auch die curl-Beispiele dieses Tutorials für die Verwendung mit ähnlichen Tools wie 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 .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 für die curl-Beispiele dieses Tutorials in diesem Tutorial davon ausgegangen, dass Sie über die folgenden Umgebungsvariablen auf Ihrem lokalen Entwicklungscomputer verfügen:

      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 Staps in Azure Databricks persönliche Zugriffstoken für Arbeitsbereichsbenutzer.

      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:

  1. 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.
  2. Die Nutzdaten der Antwort werden im aktuellen Arbeitsverzeichnis in einer Datei namens sql-execution-response.json im JSON-Format gespeichert.
  3. Der Inhalt der Datei sql-execution-response.json wird ausgegeben.
  4. 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.
  5. 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.
  6. 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.

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 übereinstimmenden 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 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 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 statement eine LIMIT-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 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-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.

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

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.

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.

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

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

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:

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.

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