Hantera inställningar via Settings API

Settings API låter dig läsa och uppdatera Azure Databricks-konton, arbetsytor och användarinställningar, inklusive förhandsvisningar på konto- och arbetsytsnivå, programmatiskt. Den här sidan förklarar hur du hittar de tillgängliga inställningarna och hur du läser och uppdaterar dem. För listan över inställningar som finns tillgängliga via det publika API:et, se referensen Inställningar API-nycklar.

För hela endpoint-referensen, se Settings REST API.

Note

Förhandsversioner på arbetsyte- och kontonivå hanteras också via Settings v2 API:t, men de finns inte med i referensen för Settings API-nycklar eftersom en förhandsversion så småningom avvecklas när funktionen blir allmänt tillgänglig eller tas bort. Upptäck de förhandsvisningar som för närvarande finns tillgängliga för dig via inställnings-metadata-endpointen. Varje förhandsvisning den returnerar är läsbar och uppdaterabar via samma ändpunkter för att hämta och uppdatera (PATCH) som alla andra inställningar.

API-modell för inställningar

Settings v2 API är dynamiskt. Ett enda, generaliserat API betjänar varje inställning, och nya inställningar blir tillgängliga genom det utan en ny API-version, SDK-release eller dokumentationsuppdatering. Istället för en fast, handunderhållen lista av endpoints upptäcker du vad som för närvarande kan ställas in vid körning via metadata-endpointen.

En inställning har ett namn, ett värde vars form beror på miljöns typ, och ett omfång som avgör var det gäller:

  • Kontoinställningar gäller över hela kontot.
  • Arbetsytinställningar gäller för en enda arbetsplats.
  • Användarinställningar gäller för en användare i ett konto.

Vissa inställningar finns tillgängliga på mer än ett teleskop. Konto- och arbetsytinställningar kräver generellt administratörsbehörigheter för att läsa eller uppdatera.

Slutpunkter efter omfattning

Varje område har sin egen uppsättning ändpunkter. Använd den som stämmer överens med hur inställningen hanteras:

Scope Hämta Uppdatera (PATCH)
Konto /api/2.1/accounts/<account-id>/settings/<key-name> /api/2.1/accounts/<account-id>/settings/<key-name>
Arbetsyta /api/2.1/settings/<key-name> /api/2.1/settings/<key-name>
Användarpreferenser /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name> /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>

Upptäck tillgängliga inställningar

Inställningsnamnen och deras aktuella metadata (inklusive värdetypen du behöver för uppdateringar) finns tillgängliga från metadata-endpointen. Detta är den ständigt uppdaterade och tillförlitliga källan för vad som för närvarande går att ställa in i din arbetsyta eller på ditt konto. Slutpunkten är paginerad, så bläddra igenom resultaten för att hämta hela listan:

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

Du kan också lista inställningar med Databricks CLI:

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

För kontoinställningar, använd istället account-scoped metadata-endpoint:

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

Läs en inställning

Ett get-svar returnerar två värden för varje inställning. Det lagrade värdet finns i typfältet (till exempel boolean_val) och är det värde som har satts. Det effektiva värdet finns i motsvarande effective_* fält (till exempel effective_boolean_val) och är det värde som servern beräknar efter att ha tillämpat standardinställningar och eventuella överskrivningar med högre omfattning. Till exempel returnerar en boolesk inställning:

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

För att läsa en arbetsyta-inställning, anropa get-endpointen med inställningens nyckelnamn:

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

För att läsa en inställning för ett konto använder du den kontospecifika sökvägen:

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

För att läsa en användarpreferens använder du den kontoomfattande sökvägen till användaren. Att läsa och uppdatera användarinställningar kräver behörigheter från kontoadministratör:

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

Uppdatera en inställning

För att uppdatera en inställning, skicka en PATCH förfrågan vars kropp är inställningsobjektet, med värdet i fältet som matchar inställningens typ. Använd list-workspace-settings-metadata (eller metadata-endpointen) för att bestämma rätt typfält för en given inställning. Till exempel, för att uppdatera en boolesk arbetsyteinställning:

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 }
  }'

För att uppdatera en kontoinställning skickar du samma brödtext till den kontospecifika sökvägen:

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 }
  }'

För att uppdatera en användarinställning skickar du begäran till den kontospecifika sökvägen för användare. Exemplet nedan uppdaterar en strängtypad preferens:

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>" }
  }'

Ytterligare resurser

  • Uppdaterades senast