Auftrags-CLI (Legacy)

Artikel
03/01/2024

Wichtig

Diese Dokumentation wurde eingestellt und wird unter Umständen nicht aktualisiert.

Diese Informationen gelten für ältere Versionen der Databricks-Befehlszeilenschnittstelle (0.18 und niedriger). Databricks empfiehlt, stattdessen die neuere Databricks-CLI Version 0.205 oder höher zu verwenden. Weitere Informationen finden Sie unter Was ist die Databricks-CLI?. Führen Sie databricks -v aus, um die Version Ihrer Databricks CLI zu ermitteln.

Informationen zum Migrieren der Databricks CLI-Version 0.18 oder niedriger zur Databricks CLI-Version 0.205 oder höher finden Sie unter Databricks CLI-Migration.

Sie können CLI-Unterbefehle für Databricks-Aufträge ausführen, indem Sie sie an databricks jobs anfügen, und CLI-Unterbefehle für Databricks-Auftragsausführungen ausführen, indem Sie sie an databricks runs anfügen. Informationen zu CLI-Unterbefehlen für Databricks-Auftragsausführungen finden Sie unter Ausführungs-CLI (Legacy). Zusammen rufen diese Unterbefehle die Auftrags-API und die Auftrags-API 2.0 auf.

Wichtig

Die Databricks-Auftrags-CLI unterstützt Aufrufe von zwei Versionen der REST-API für Databricks-Aufträge: Version 2.1 und Version 2.0. In der Version 2.1 wird die Unterstützung für die Orchestrierung von Aufträgen mit mehreren Aufgaben hinzugefügt. Weitere Informationen finden Sie unter Erstellen und Ausführen von Azure Databricks-Aufträgen sowie unter Aktualisieren der Auftrags-API 2.0 auf die Version 2.1. Databricks empfiehlt, Version 2.1 aufzurufen, sofern Sie keine Legacy-Skripts nutzen, die Version 2.0 erfordern und nicht migriert werden können.

Sofern nicht anders angegeben, gelten die in diesem Artikel beschriebenen programmgesteuerten Verhaltensweisen gleichermaßen für die Versionen 2.1 und 2.0.

Anforderungen zum Aufrufen der REST-API Version 2.1 für Aufträge

Gehen Sie wie folgt vor, um die Databricks-Auftrags-CLI (und die CLI für Auftragsausführungen) zum Aufrufen der REST-API Version 2.1 für Aufträge einzurichten und zu verwenden:

Aktualisieren Sie die CLI auf Version 0.16.0 oder höher.
Führen Sie eines der folgenden Verfahren aus:
- Führen Sie den Befehl databricks jobs configure --version=2.1aus. Dadurch wird der Datei ~/.databrickscfg unter Unix, Linux oder macOS oder %USERPROFILE%\.databrickscfg unter Windows die Einstellung jobs-api-version = 2.1 hinzugefügt. Alle Unterbefehle der Auftrags-CLI (und CLI für Auftragsausführungen) rufen standardmäßig die REST-API Version 2.1 für Aufträge auf.
- Fügen Sie unter Unix, Linux oder macOS der Datei ~/.databrickscfg oder auf Windows der Datei %USERPROFILE%\.databrickscfg die Einstellung jobs-api-version = 2.1 hinzu. Alle Unterbefehle der Auftrags-CLI (und CLI für Auftragsausführungen) rufen standardmäßig die REST-API Version 2.1 für Aufträge auf.
- Fügen Sie die Option --version=2.1 (z. B. databricks jobs list --version=2.1) an, um die CLI anzuweisen, nur für diesen Aufruf die REST-API Version 2.1 für Aufträge aufzurufen.
Wenn Sie keine der vorherigen Aktionen ausführen, ruft die Auftrags-CLI (und die CLI für Auftragsausführungen) standardmäßig die REST-API Version 2.0 für Aufträge auf.

Anforderungen zum Aufrufen der REST-API Version 2.0 für Aufträge

Nutzen Sie eine der folgenden Methoden, um die Databricks-Auftrags-CLI (und die CLI für Auftragsausführungen) zum Aufrufen der REST-API Version 2.0 für Aufträge einzurichten und zu verwenden:

Verwenden Sie eine Version der Databricks-CLI unter 0.16.0 oder
Aktualisieren Sie die CLI auf Version X.Y.Z oder höher und gehen Sie dann wie folgt vor:
- Führen Sie den Befehl databricks jobs configure --version=2.0aus. Dadurch wird der Datei ~/.databrickscfg unter Unix, Linux oder macOS oder %USERPROFILE%\.databrickscfg unter Windows die Einstellung jobs-api-version = 2.0 hinzugefügt. Alle Unterbefehle der Auftrags-CLI (und CLI für Auftragsausführungen) rufen standardmäßig die REST-API Version 2.0 für Aufträge auf.
- Fügen Sie unter Unix, Linux oder macOS der Datei ~/.databrickscfg oder auf Windows der Datei %USERPROFILE%\.databrickscfg die Einstellung jobs-api-version = 2.0 hinzu. Alle Unterbefehle der Auftrags-CLI (und CLI für Auftragsausführungen) rufen standardmäßig die REST-API Version 2.0 für Aufträge auf.
- Fügen Sie die Option --version=2.1 (z. B. databricks jobs list --version=2.0) an, um die CLI anzuweisen, nur für diesen Aufruf die REST-API Version 2.0 für Aufträge aufzurufen.

Wenn Sie keine der vorherigen Aktionen ausführen, ruft die Auftrags-CLI (und die CLI für Auftragsausführungen) standardmäßig die REST-API Version 2.0 für Aufträge auf.

Unterbefehle und allgemeine Verwendung

databricks jobs -h

Usage: databricks jobs [OPTIONS] COMMAND [ARGS]...

  Utility to interact with jobs.

  Job runs are handled by ``databricks runs``.

Options:
  -v, --version  [VERSION]
  -h, --help     Show this message and exit.

Commands:
  create   Creates a job.
    Options:
      --json-file PATH            File containing JSON request to POST to /api/2.0/jobs/create.
      --json JSON                 JSON string to POST to /api/2.0/jobs/create.
  delete   Deletes a job.
    Options:
      --job-id JOB_ID             Can be found in the URL at https://<databricks-instance>/?o=<16-digit-number>#job/$JOB_ID. [required]
  get      Describes the metadata for a job.
    Options:
    --job-id JOB_ID               Can be found in the URL at https://<databricks-instance>/?o=<16-digit-number>#job/$JOB_ID. [required]
  list     Lists the jobs in the Databricks Job Service.
  reset    Resets (edits) the definition of a job.
    Options:
      --job-id JOB_ID             Can be found in the URL at https://<databricks-instance>/?o=<16-digit-number>#job/$JOB_ID. [required]
      --json-file PATH            File containing JSON request to POST to /api/2.0/jobs/create.
      --json JSON                 JSON string to POST to /api/2.0/jobs/create.
  run-now  Runs a job with optional per-run parameters.
    Options:
      --job-id JOB_ID             Can be found in the URL at https://<databricks-instance>/#job/$JOB_ID. [required]
      --jar-params JSON           JSON string specifying an array of parameters. i.e. '["param1", "param2"]'
      --notebook-params JSON      JSON string specifying a map of key-value pairs. i.e. '{"name": "john doe", "age": 35}'
      --python-params JSON        JSON string specifying an array of parameters. i.e. '["param1", "param2"]'
      --spark-submit-params JSON  JSON string specifying an array of parameters. i.e. '["--class", "org.apache.spark.examples.SparkPi"]'

Erstellen eines Auftrags

Führen Sie databricks jobs create --help aus, um die Syntaxdokumentation anzuzeigen.

Allgemeine Verwendung

databricks jobs create --json-file create-job.json

Nutzungshinweise und Anforderungsbeispiel für Auftrags-CLI 2.1

Weitere Informationen finden Sie im Abschnitt Erstellen des Artikels Aktualisieren der Auftrags-API 2.0 auf die Version 2.1.

Anforderungspayload und Antwortbeispiel für Auftrags-CLI 2.0

create-job.json:

{
  "name": "my-job",
  "existing_cluster_id": "1234-567890-reef123",
  "notebook_task": {
    "notebook_path": "/Users/someone@example.com/My Notebook"
  },
  "email_notifications": {
    "on_success": [
      "someone@example.com"
    ],
    "on_failure": [
      "someone@example.com"
    ]
  }
}

{ "job_id": 246 }

Tipp

Um einen Auftrag zu kopieren, führen Sie den create-Befehl aus und übergeben Sie ein JSON-Objekt mit den zu kopierenden Einstellungen des Auftrag. In diesem Beispiel werden die Einstellungen des Auftrags mit der ID 246 in einen neuen Auftrag kopiert. Hierfür ist das Hilfsprogramm jq erforderlich.

SETTINGS_JSON=$(databricks jobs get --job-id 246 | jq .settings)

databricks jobs create --json "$SETTINGS_JSON"

{ "job_id": 247 }

Löschen eines Auftrags

Führen Sie databricks jobs delete --help aus, um die Syntaxdokumentation anzuzeigen.

databricks job delete --job-id 246

Bei Erfolg wird keine Ausgabe angezeigt.

Tipp

Um mehrere Aufträge mit derselben Einstellung zu löschen, rufen Sie die Liste der Auftrags-IDs ab, die mit dieser Einstellung übereinstimmen. Führen Sie dann für jede übereinstimmende Auftrags-ID den delete-Befehl aus. In diesem Beispiel werden alle Aufträge mit dem Auftragsnamen Untitled gelöscht. Hierfür ist das Hilfsprogramm jq erforderlich.

databricks jobs list --output json | jq '.jobs[] | select(.settings.name == "Untitled") | .job_id' | xargs -n 1 databricks jobs delete --job-id

Auflistung von Informationen zu einem Auftrag

Führen Sie databricks jobs get --help aus, um die Nutzungsdokumentation anzuzeigen.

Allgemeine Verwendung

databricks jobs get --job-id 246

Nutzungshinweise und Antwortbeispiel für Auftrags-CLI 2.1

Weitere Informationen finden Sie im Abschnitt Abrufen des Artikels Aktualisieren der Auftrags-API 2.0 auf die Version 2.1.

Antwortbeispiel für Auftrags-CLI 2.0

{
  "job_id": 246,
  "settings": {
    "name": "my-job",
    "existing_cluster_id": "1234-567890-reef123",
    "email_notifications": {
      "on_success": [
        "someone@example.com"
      ],
      "on_failure": [
        "someone@example.com"
      ]
    },
    "timeout_seconds": 0,
    "notebook_task": {
      "notebook_path": "/Users/someone@example.com/My Notebook"
    },
    "max_concurrent_runs": 1
  },
  "created_time": 1620163107742,
  "creator_user_name": "someone@example.com"
}

Auflistung von Informationen zu verfügbaren Aufträgen

Führen Sie databricks jobs list --help aus, um die Nutzungsdokumentation anzuzeigen.

Allgemeine Verwendung

databricks jobs list

Nutzungshinweise und Antwortbeispiel für Auftrags-CLI 2.1

Weitere Informationen finden Sie im Abschnitt Auflisten des Artikels Aktualisieren der Auftrags-API 2.0 auf die Version 2.1.

Antwortbeispiel für Auftrags-CLI 2.0

{
  "jobs": [
    {
      "job_id": 246,
      "settings": {
        "name": "my-job",
        "existing_cluster_id": "1234-567890-reef123",
        "email_notifications": {
          "on_success": [
            "someone@example.com"
          ],
          "on_failure": [
            "someone@example.com"
          ]
        },
        "timeout_seconds": 0,
        "notebook_task": {
          "notebook_path": "/Users/someone@example.com/My Notebook"
        },
        "max_concurrent_runs": 1
      },
      "created_time": 1620163107742,
      "creator_user_name": "someone@example.com"
    },
    ...
  ]
}

Auflisten aller Aufträge (nur API 2.1)

Verwenden Sie die Option --all, um die CLI anzuweisen, durch sequenzielle Aufrufe der API alle Aufträge zurückzugeben. Um die Option --all verwenden zu können, müssen Sie die API-Version auf 2.1 festlegen.

databricks jobs list --all

Paginieren der Auftragsliste (nur API 2.1)

Verwenden Sie die Argumente --limit und --offset, um eine paginierte Auftragsliste zurückzugeben. Die Auftragsliste wird standardmäßig als Tabelle zurückgegeben, die die Auftrags-ID und den Auftragsnamen enthält. Verwenden Sie das Argument --output JSON, um optional ein JSON-Dokument mit Auftragsinformationen zurückzugeben.

Damit Sie die Argumente --limit und --offset verwenden können, müssen Sie die API-Version auf 2.1 festlegen.

Bei Verwendung von --output JSON wird die Liste in absteigender Reihenfolge nach Auftragserstellungsdatum zurückgegeben. Bei Verwendung von --output TABLE wird die Liste in absteigender Reihenfolge nach Auftragserstellungsdatum zurückgegeben und dann alphabetisch nach Auftragsname sortiert.

Das folgende Beispiel blättert seitenweise durch die Auftragsliste (jeweils zehn Aufträge) und gibt die Ergebnisse im JSON-Format zurück:

databricks jobs list --output JSON --limit 10
databricks jobs list --output JSON --limit 10 --offset 10
databricks jobs list --output JSON --limit 10 --offset 20

Ändern der Einstellungen für einen Auftrag

Führen Sie databricks jobs reset --help aus, um die Nutzungsdokumentation anzuzeigen.

Allgemeine Verwendung

databricks jobs reset --job-id 246 --json-file reset-job.json

Nutzungshinweise und Anforderungsbeispiel für Auftrags-CLI 2.1

Weitere Informationen finden Sie in den Abschnitten Aktualisieren und Zurücksetzen des Artikels Aktualisieren der Auftrags-API 2.0 auf die Version 2.1.

Anforderungsbeispiel für Auftrags-CLI 2.0

reset-job.json:

{
  "job_id": 246,
  "existing_cluster_id": "2345-678901-batch234",
  "name": "my-changed-job",
  "notebook_task": {
    "notebook_path": "/Users/someone@example.com/My Other Notebook"
  },
  "email_notifications": {
    "on_success": [
      "someone-else@example.com"
    ],
    "on_failure": [
      "someone-else@example.com"
    ]
  }
}

Bei Erfolg wird keine Ausgabe angezeigt.

Ausführen eines Auftrags

Führen Sie databricks jobs run-now --help aus, um die Nutzungsdokumentation anzuzeigen.

databricks jobs run-now --job-id 246

{
  "run_id": 122,
  "number_in_job": 1
}

Freigeben über

Auftrags-CLI (Legacy)

Anforderungen zum Aufrufen der REST-API Version 2.1 für Aufträge

Anforderungen zum Aufrufen der REST-API Version 2.0 für Aufträge

Unterbefehle und allgemeine Verwendung

Erstellen eines Auftrags

Allgemeine Verwendung

Nutzungshinweise und Anforderungsbeispiel für Auftrags-CLI 2.1

Anforderungspayload und Antwortbeispiel für Auftrags-CLI 2.0

Löschen eines Auftrags

Auflistung von Informationen zu einem Auftrag

Allgemeine Verwendung

Nutzungshinweise und Antwortbeispiel für Auftrags-CLI 2.1

Antwortbeispiel für Auftrags-CLI 2.0

Auflistung von Informationen zu verfügbaren Aufträgen

Allgemeine Verwendung

Nutzungshinweise und Antwortbeispiel für Auftrags-CLI 2.1

Antwortbeispiel für Auftrags-CLI 2.0

Auflisten aller Aufträge (nur API 2.1)

Paginieren der Auftragsliste (nur API 2.1)

Ändern der Einstellungen für einen Auftrag

Allgemeine Verwendung

Nutzungshinweise und Anforderungsbeispiel für Auftrags-CLI 2.1

Anforderungsbeispiel für Auftrags-CLI 2.0

Ausführen eines Auftrags

Zusätzliche Ressourcen