Einstellungen über die Settings API verwalten

Die Settings API ermöglicht es Ihnen, Azure Databricks-Konto, Arbeitsflächen und Benutzereinstellungen, einschließlich Vorschauen auf Konto- und Arbeitsbereichsebene, programmatisch zu lesen und zu aktualisieren. Diese Seite erklärt, wie man die verfügbaren Einstellungen entdeckt und wie man sie liest und aktualisiert. Für die Liste der Einstellungen, die über die öffentliche API verfügbar sind, siehe Einstellungen API-Schlüssel-Referenz.

Für die vollständige Endpunktreferenz siehe die Settings REST API.

Note

Vorschauversionen für Funktionen auf Arbeitsbereichs- und Kontoebene werden ebenfalls über die Einstellungen-v2-API verwaltet, aber sie sind nicht in der API-Schlüsselreferenz für Einstellungen aufgeführt, da eine Vorschauversion letztlich das Ende ihrer Lebensdauer erreicht, wenn die Funktion erweitert oder entfernt wird. Entdecken Sie die derzeit für Sie verfügbaren Vorschauen über den settings-metadata-Endpunkt. Jede zurückgegebene Vorschau ist lesbar und kann über dieselben Get- und Update-(PATCH)-Endpunkte wie jede andere Einstellung aktualisiert werden.

API-Modell für Einstellungen

Die Settings v2 API ist dynamisch. Eine einzelne, verallgemeinerte API bedient jede Einstellung, und über sie werden neue Einstellungen verfügbar ohne eine neue API-Version, SDK-Veröffentlichung oder Dokumentationsaktualisierung. Anstelle einer festen, handverwalteten Liste von Endpunkten entdeckt man über den Metadaten-Endpunkt, was aktuell zur Laufzeit eingestellt werden kann.

Eine Einstellung hat einen Namen, einen Wert, dessen Form vom Typ des Settings abhängt, und einen Bereich, der bestimmt, wo sie angewendet wird:

  • Kontoeinstellungen gelten für das gesamte Konto.
  • Arbeitsbereichseinstellungen gelten für einen einzelnen Arbeitsbereich.
  • Benutzerpräferenzen gelten für einen Benutzer in einem Konto.

Einige Einstellungen sind auf mehr als einem Teleskop verfügbar. Konto- und Arbeitsbereichseinstellungen erfordern in der Regel Administratorrechte zum Lesen oder Aktualisieren.

Endpunkte nach Bereich

Jeder Scope hat seinen eigenen Satz von Endpunkten. Verwenden Sie diejenige, die dazu passt, wie die Einstellung verwaltet wird:

Umfang Abrufen Aktualisierung (PATCH)
Konto /api/2.1/accounts/<account-id>/settings/<key-name> /api/2.1/accounts/<account-id>/settings/<key-name>
Arbeitsbereich /api/2.1/settings/<key-name> /api/2.1/settings/<key-name>
Nutzerpräferenz /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name> /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>

Entdecken Sie verfügbare Einstellungen

Die Einstellungsnamen und ihre aktuellen Metadaten (einschließlich des Werttyps, den Sie für Updates benötigen) sind vom Metadaten-Endpunkt verfügbar. Dies ist die stets aktuelle maßgebliche Informationsquelle dafür, was derzeit in Ihrem Arbeitsbereich oder Konto konfiguriert werden kann. Der Endpunkt ist paginiert, also blättern Sie durch die Ergebnisse, um die vollständige Liste abzurufen:

curl -n --request GET \
  'https://<databricks-instance>/api/2.1/settings-metadata'

Du kannst auch Einstellungen mit der Databricks-CLI auflisten:

databricks workspace-settings-v2 list-workspace-settings-metadata

Für Kontoeinstellungen verwenden Sie stattdessen den account-scoped Metadaten-Endpunkt:

curl -n --request GET \
  'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings-metadata'

Eine Einstellung lesen

Eine Get-Antwort gibt für jede Einstellung zwei Werte zurück. Der gespeicherte Wert befindet sich im Typfeld (zum Beispiel boolean_val) und ist der gesetzte Wert. Der effektive Wert befindet sich im entsprechenden effective_* Feld (zum Beispiel effective_boolean_val) und ist der Wert, den der Server nach Anwendung der Standardwerte und aller übergeordneten Überschreibungen berechnet. Zum Beispiel gibt eine boolesche Einstellung zurück:

{
  "name": "<key-name>",
  "boolean_val": { "value": true },
  "effective_boolean_val": { "value": true }
}

Um eine Workspace-Einstellung zu lesen, rufen Sie den get-Endpunkt mit dem Schlüsselnamen der Einstellung auf:

curl -n --request GET \
  'https://<databricks-instance>/api/2.1/settings/<key-name>'

Um eine Kontoeinstellung zu lesen, verwenden Sie den kontobezogenen Pfad:

curl -n --request GET \
  'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings/<key-name>'

Um eine Benutzerpräferenz abzurufen, verwenden Sie den kontobezogenen Benutzerpfad. Das Lesen und Aktualisieren der Benutzerpräferenzen erfordert Berechtigungen des Kontoadministrators:

curl -n --request GET \
  'https://<databricks-instance>/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>'

Aktualisierung einer Einstellung

Um eine Einstellung zu aktualisieren, senden Sie eine PATCH Anfrage, deren Körper das Setting-Objekt ist, wobei der Wert im Feld übernommen wird, der zum Typ der Einstellung passt. Verwenden Sie list-workspace-settings-metadata (oder den Metadaten-Endpunkt), um das richtige Feld „type“ für eine bestimmte Einstellung zu bestimmen. Zum Beispiel, um eine boolesche Arbeitsbereichseinstellung zu aktualisieren:

curl -n --request PATCH \
  'https://<databricks-instance>/api/2.1/settings/<key-name>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<key-name>",
    "boolean_val": { "value": true }
  }'

Um eine Kontoeinstellung zu aktualisieren, senden Sie denselben Anfragetext an den kontobezogenen Pfad:

curl -n --request PATCH \
  'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings/<key-name>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<key-name>",
    "boolean_val": { "value": true }
  }'

Um eine Benutzerpräferenz zu aktualisieren, senden Sie die Anfrage an den kontobezogenen Benutzerpfad. Das untenstehende Beispiel aktualisiert eine stringtypisierte Präferenz:

curl -n --request PATCH \
  'https://<databricks-instance>/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "<key-name>",
    "string_val": { "value": "<value>" }
  }'

Weitere Ressourcen

  • Zuletzt aktualisiert um