REST-API 1.2

Mit der Databricks-REST-API können Sie programmgesteuert auf Azure Databricks zugreifen, anstatt die Webbenutzeroberfläche zu durchlaufen.

In diesem Artikel wird REST-API 1.2 behandelt. Die neueste Version der REST-API sowie rest-API 2.1 und 2.0sind ebenfalls verfügbar.

Wichtig

Wichtig

Für den Zugriff auf Databricks-REST-APIs müssen Sie sich authentifizieren.

Anwendungsfälle für die REST-API

  • Starten von Apache Spark Aufträgen, die durch Ihre vorhandenen Produktionssysteme oder durch Workflowsysteme ausgelöst werden
  • Programmgesteuertes Bereitstellen eines Clusters mit einer bestimmten Größe zu einer festgelegten Tageszeit und Herunterfahren des Clusters am Abend

API-Kategorien

  • Ausführungskontext: Erstellen eindeutiger Variablennamespaces, über die Spark-Befehle aufgerufen werden können
  • Befehlsausführung: Ausführen von Befehlen in einem bestimmten Ausführungskontext

Details

  • Diese Rest-API wird über HTTPS ausgeführt.
  • Verwenden Sie zum Abrufen von Informationen HTTP GET.
  • Verwenden Sie zum Ändern des Zustands HTTP POST.
  • Verwenden Sie zum Hochladen von Dateien multipart/form-data und andernfalls application/json.
  • Der Inhaltstyp von Antworten lautet JSON.
  • Zum Authentifizieren des Benutzers für jeden API-Aufruf wird die Standardauthentifizierung verwendet.
  • Benutzeranmeldeinformationen sind Base64-codiert und befinden sich im HTTP-Header jedes API-Aufrufs. Beispiel: Authorization: Basic YWRtaW46YWRtaW4=. Wenn Sie curl verwenden, können Sie alternativ Benutzeranmeldeinformationen in einer .netrc Datei speichern.
  • Weitere Informationen zur Verwendung der Databricks-REST-API finden Sie in der Databricks-REST-API-Referenz.

Erste Schritte

  • Um die Beispiele in diesem Artikel auszuprobieren, ersetzen Sie durch <databricks-instance> die <databricks-instance> Ihrer Azure Databricks-Bereitstellung.
  • In den folgenden Beispielen werden curl und eine NETRC-Dateiverwendet. Sie können diese curl Beispiele mit einer HTTP-Bibliothek in Ihrer bevorzugten Programmiersprache anpassen.

API-Referenz

Abrufen der Clusterliste

Methode und Pfad:

GET /api/1.2/clusters/list

Beispiel

Anforderung:

curl --netrc --request GET \
  https://<databricks-instance>/api/1.2/clusters/list

Antwort:

[
  {
    "id": "1234-567890-span123",
    "name": "MyCluster",
    "status": "Terminated",
    "driverIp": "",
    "jdbcPort": 10000,
    "numWorkers":0
  },
  {
    "..."
  }
]

Anforderungsschema

Keine.

Antwortschema

Ein Array von -Objekten, wobei jedes -Objekt Informationen zu einem Cluster wie folgt darstellt:

Feld
id

Typ: string

Die ID des Clusters.
name

Typ: string

Der Name des Clusters.
status

Typ: string

Der Status des Clusters. Enthält einen der folgenden Werte:

* Error
* Pending
* Reconfiguring
* Restarting
* Running
* Terminated
* Terminating
* Unknown
driverIp

Typ: string

Die IP-Adresse des Treibers.
jdbcPort

Typ: number

Die JDBC-Portnummer.
numWorkers

Typ: number

Die Anzahl der Worker für den Cluster.

Abrufen von Informationen zu einem Cluster

Methode und Pfad:

GET /api/1.2/clusters/status

Beispiel

Anforderung:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/clusters/status \
  --data clusterId=1234-567890-span123

Antwort:

{
  "id": "1234-567890-span123",
  "name": "MyCluster",
  "status": "Terminated",
  "driverIp": "",
  "jdbcPort": 10000,
  "numWorkers": 0
}

Anforderungsschema

Feld
clusterId

Typ: string

Die ID des Clusters.

Antwortschema

Ein -Objekt, das Informationen zum Cluster darstellt.

Feld
id

Typ: string

Die ID des Clusters.
name

Typ: string

Der Name des Clusters.
status

Typ: string

Der Status des Clusters. Enthält einen der folgenden Werte:

* Error
* Pending
* Reconfiguring
* Restarting
* Running
* Terminated
* Terminating
* Unknown
driverIp

Typ: string

Die IP-Adresse des Treibers.
jdbcPort

Typ: number

Die JDBC-Portnummer.
numWorkers

Typ: number

Die Anzahl der Worker für den Cluster.

Neustarten eines Clusters

Methode und Pfad:

POST /api/1.2/clusters/restart

Beispiel

Anforderung:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/clusters/restart \
  --data clusterId=1234-567890-span123

Antwort:

{
  "id": "1234-567890-span123"
}

Anforderungsschema

Feld
clusterId

Typ: string

Die ID des neu zu startende Clusters.

Antwortschema

Feld
id

Typ: string

Die ID des Clusters.

Erstellen eines Ausführungskontexts

Methode und Pfad:

POST /api/1.2/contexts/create

Beispiel

Anforderung:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/create \
  --data clusterId=1234-567890-span123 \
  --data language=sql

Antwort:

{
  "id": "1234567890123456789"
}

Anforderungsschema

Feld
clusterId

Typ: string

Die ID des Clusters, für den der Kontext erstellt werden soll.
clusterId

Typ: string

Die Sprache für den Kontext. Enthält einen der folgenden Werte:

* python
* scala
* sql

Antwortschema

Feld
id

Typ: string

Die ID des Ausführungskontexts.

Abrufen von Informationen zu einem Ausführungskontext

Methode und Pfad:

POST /api/1.2/contexts/status

Beispiel

Anforderung:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/contexts/status \
  --data clusterId=1234-567890-span123 \
  --data contextId=1234567890123456789

Antwort:

{
  "id": "1234567890123456789",
  "status": "Running"
}

Anforderungsschema

Feld
clusterId

Typ: string

Die ID des Clusters, zu dem Ausführungskontextinformationen abzurufen sind.
Contextid

Typ: string

Die ID des Ausführungskontexts.

Antwortschema

Feld
id

Typ: string

Die ID des Ausführungskontexts.
status

Typ: string

Der Status des Ausführungskontexts. Enthält einen der folgenden Werte:

* Error
* Pending
* Running

Löschen eines Ausführungskontexts

Methode und Pfad:

POST /api/1.2/contexts/destroy

Beispiel

Anforderung:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/destroy \
  --data clusterId=1234-567890-span123 \
  --data contextId=1234567890123456789

Antwort:

{
  "id": "1234567890123456789"
}

Anforderungsschema

Feld
clusterId

Typ: string

Die ID des Clusters, für den der Ausführungskontext zerstört werden soll.
Contextid

Typ: string

Die ID des zu zerstörende Ausführungskontexts.

Antwortschema

Feld
id

Typ: string

Die ID des Ausführungskontexts.

Ausführen eines Befehls

Methode und Pfad:

POST /api/1.2/commands/execute

Beispiel

Anforderung:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/execute \
  --header 'Content-Type: application/json' \
  --data @execute-command.json

execute-command.json:

{
   "clusterId": "1234-567890-span123",
   "contextId": "1234567890123456789",
   "language": "python",
   "command": "print('Hello, World!')"
}

Antwort:

{
  "id": "1234ab56-7890-1cde-234f-5abcdef67890"
}

Anforderungsschema

Feld
clusterId

Typ: string

Die ID des Clusters, auf dem der Befehl ausgeführt werden soll.
Contextid

Typ: string

Die ID des Ausführungskontexts, in dem der Befehl ausgeführt werden soll.
Sprache

Typ: string

Die Sprache des Befehls.
command

Typ: string

Die auszuführende Befehlszeichenfolge.

Geben Sie entweder den Befehl oder an.
commandFile.
commandFile

Typ: string

Der Pfad zu einer Datei, die den auszuführenden Befehl enthält.

Geben Sie entweder commandFile oder an.
Befehl.
options

Typ: string

Eine optionale Zuordnung der nachgeschalteten Werte. Beispielsweise eine displayRowLimit Außerkraftsetzung (wird beim Testen verwendet).

Antwortschema

Feld
id

Typ: string

Die Befehls-ID.

Abrufen von Informationen zu einem Befehl

Methode und Pfad:

GET /api/1.2/commands/status

Beispiel

Anforderung:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/commands/status \
  --data clusterId=1234-567890-span123 \
  --data contextId=1234567890123456789 \
  --data commandId=1234ab56-7890-1cde-234f-5abcdef67890

Antwort:

{
  "id": "1234ab56-7890-1cde-234f-5abcdef67890",
  "status": "Finished",
  "results": {
    "resultType": "text",
    "data": "Hello, World!"
  }
}

Anforderungsschema

Feld
clusterId

Typ: string

Die ID des Clusters, zu dem die Befehlsinformationen abzurufen sind.
Contextid

Typ: string

Die ID des Ausführungskontexts, der dem Befehl zugeordnet ist.
Commandid

Typ: string

Die ID des Befehls, zu dem Informationen abzurufen sind.

Antwortschema

Feld
id

Typ: string

Die Befehls-ID.
status

Typ: string

Der Status des Befehls. Enthält einen der folgenden Werte:

* Cancelled
* Cancelling
* Error
* Finished
* Queued
* Running
Ergebnisse

Typ: object

Die Ergebnisse des Befehls.

* resultType: Der Ergebnistyp. Typ: string Eine der beiden:

* error
* image
* images
* table
* text

Für error:

* cause: Die Ursache des Fehlers. Typ: string

Für image:

* fileName: Der Imagedateiname. Typ: string

Für images:

* fileNames: Die Dateinamen der Bilder. Typ: array von string

Für table:

* data: Die Tabellendaten. Typ: arrayarray von any

* schema: Das Tabellenschema. Typ: arrayarray von (string, any)

* truncated: true , wenn Teilergebnisse zurückgegeben werden. Typ: true/false

* isJsonSchema: true , wenn anstelle einer Zeichenfolgendarstellung des Hive-Typs ein JSON-Schema zurückgegeben wird. Typ: true/false

Für text:

* data: Der Text. Typ: string

Abbrechen eines Befehls

Methode und Pfad:

POST/api/1.2/commands/cancel

Beispiel

Anforderung:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/cancel \
  --data clusterId=1234-567890-span123 \
  --data contextId=1234567890123456789 \
  --data commandId=1234ab56-7890-1cde-234f-5abcdef67890

Antwort:

{
  "id": "1234ab56-7890-1cde-234f-5abcdef67890"
}

Anforderungsschema

Feld
clusterId

Typ: string

Die ID des Clusters, der dem abzubrechende Befehl zugeordnet ist.
Contextid

Typ: string

Die ID des Ausführungskontexts, der dem abzubrechende Befehl zugeordnet ist.
Commandid

Typ: string

Die ID des abzubrechende Befehls.

Antwortschema

Feld
id

Typ: string

Die Befehls-ID.

Abrufen der Liste der Bibliotheken für einen Cluster

Wichtig

Dieser Vorgang ist veraltet. Verwenden Sie stattdessen den Clusterstatusvorgang in der Bibliotheks-API.

Methode und Pfad:

GET /api/1.2/libraries/list

Beispiel

Anforderung:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/libraries/list \
  --data clusterId=1234-567890-span123

Anforderungsschema

Feld
clusterId

Typ: string

Die ID des Clusters.

Antwortschema

Ein Array von -Objekten, wobei jedes -Objekt Informationen über eine Bibliothek wie folgt darstellt:

Feld
name

Typ: string

Der Name der Bibliothek.
status

Typ: string

Der Status der Bibliothek. Enthält einen der folgenden Werte:

* LibraryError
* LibraryLoaded
* LibraryPending

Hochladen einer Bibliothek zu einem Cluster

Wichtig

Dieser Vorgang ist veraltet. Verwenden Sie stattdessen den Installationsvorgang in der Bibliotheks-API.

Methode und Pfad:

POST /api/1.2/libraries/upload

Anforderungsschema

Feld
clusterId

Typ: string

Die ID des Clusters, in den die Bibliothek hochgeladen werden soll.
name

Typ: string

Der Name der Bibliothek.
Sprache

Typ: string

Die Sprache der Bibliothek.
uri

Typ: string

Der URI der Bibliothek.

Das Schema kann file , oder sein. http
https.

Antwortschema

Informationen zur hochgeladenen Bibliothek.

Feld
Sprache

Typ: string

Die Sprache der Bibliothek.
uri

Typ: string

Der URI der Bibliothek.

Weitere Beispiele

Die folgenden zusätzlichen Beispiele enthalten Befehle, die Sie mit curl einer HTTP-Bibliothek in Ihrer bevorzugten Programmiersprache verwenden oder mit dieser anpassen können.

Erstellen eines Ausführungskontexts

Erstellen Sie einen Ausführungskontext in einem angegebenen Cluster für eine bestimmte Programmiersprache:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/create \
  --header 'Content-Type: application/json' \
  --data '{ "language": "scala", "clusterId": "1234-567890-span123" }'

Abrufen von Informationen zum Ausführungskontext:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/contexts/status \
  --data 'clusterId=1234-567890-span123&contextId=1234567890123456789'

Löschen Sie den Ausführungskontext:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/contexts/destroy \
  --header 'Content-Type: application/json' \
  --data '{ "contextId": "1234567890123456789", "clusterId": "1234-567890-span123" }'

Ausführen eines Befehls

Bekannte Einschränkungen: %run wird von der Befehlsausführung nicht unterstützt.

Führen Sie eine Befehlszeichenfolge aus:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/execute \
  --header 'Content-Type: application/json' \
  --data '{ "language": "scala", "clusterId": "1234-567890-span123", "contextId": "1234567890123456789", "command": "sc.parallelize(1 to 10).collect" }'

Führen Sie eine Datei aus:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/execute \
  --header 'Content-Type: multipart/form-data' \
  --form language=python \
  --form clusterId=1234-567890-span123 \
  --form contextId=1234567890123456789 \
  --form command=@myfile.py

Zeigen Sie den Status und das Ergebnis des Befehls an:

curl --netrc --get \
  https://<databricks-instance>/api/1.2/commands/status \
  --data 'clusterId=1234-567890-span123&contextId=1234567890123456789&commandId=1234ab56-7890-1cde-234f-5abcdef67890'

Brechen Sie den Befehl ab:

curl --netrc --request POST \
  https://<databricks-instance>/api/1.2/commands/cancel \
  --data 'clusterId=1234-567890-span123&contextId=1234567890123456789&commandId=1234ab56-7890-1cde-234f-5abcdef67890' \

Hochladen und Ausführen einer Spark-JAR

Hochladen einer JAR

Verwenden Sie die REST-API (neueste Version), um eine JAR-Datei hochzuladen und an einen Cluster anzufügen.

Ausführen einer JAR

  1. Erstellen Sie einen Ausführungskontext.

    curl --netrc --request POST \
      https://<databricks-instance>/api/1.2/contexts/create \
      --data "language=scala&clusterId=1234-567890-span123"
    
    {
      "id": "1234567890123456789"
    }
    
  2. Führen Sie einen Befehl aus, der Ihre JAR verwendet.

    curl --netrc --request POST \
      https://<databricks-instance>/api/1.2/commands/execute \
      --data 'language=scala&clusterId=1234-567890-span123&contextId=1234567890123456789&command=println(com.databricks.apps.logs.chapter1.LogAnalyzer.processLogFile(sc,null,"dbfs:/somefile.log"))'
    
    {
      "id": "1234ab56-7890-1cde-234f-5abcdef67890"
    }
    
  3. Überprüfen Sie den Status Ihres Befehls. Wenn Sie einen umfangreicheren Spark-Auftrag ausführen, kann die Rückgabe etwas länger dauern.

    curl --netrc 'https://<databricks-instance>/api/1.2/commands/status?clusterId=1234-567890-span123&contextId=1234567890123456789&commandId=1234ab56-7890-1cde-234f-5abcdef67890'
    
    {
       "id": "1234ab56-7890-1cde-234f-5abcdef67890",
       "results": {
         "data": "Content Size Avg: 1234, Min: 1234, Max: 1234",
         "resultType": "text"
       },
       "status": "Finished"
    }
    

    Zu den zulässigen Werten für resultType zählen folgende:

    • error
    • image
    • images
    • table
    • text