Beheer instellingen via de Settings API

Met de Settings API kunt u Azure Databricks-account-, werkruimte- en gebruikersinstellingen programmatisch lezen en bijwerken, inclusief previewfuncties op account- en werkruimteniveau. Deze pagina legt uit hoe je de beschikbare instellingen kunt ontdekken en hoe je ze kunt lezen en bijwerken. Voor de lijst met instellingen die beschikbaar zijn via de publieke API, zie Instellingen API-sleutels referentie.

Voor de volledige endpointreferentie, zie de Settings REST API.

Note

Functiebèta’s op werkruimte- en accountniveau worden ook beheerd via de Settings v2 API, maar ze worden niet vermeld in de referentie voor Settings API-sleutels omdat een preview uiteindelijk wordt uitgefaseerd wanneer de functie definitief wordt uitgebracht of verwijderd. Ontdek de previews die momenteel beschikbaar zijn via het instellingen-metadata-eindpunt. Elke voorbeeldweergave die het oplevert, is leesbaar en bij te werken via dezelfde get- en update-eindpunten (PATCH) als elke andere instelling.

Instellingen-API-model

De Settings v2 API is dynamisch. Een enkele, gegeneraliseerde API bedient elke instelling, en nieuwe instellingen worden via deze instelling beschikbaar zonder een nieuwe API-versie, SDK-release of documentatie-update. In plaats van een vaste, handmatig onderhouden lijst van endpoints, ontdek je wat er op dat moment instelbaar is tijdens runtime via het metadata-endpoint.

Een setting heeft een naam, een waarde waarvan de vorm afhangt van het type van de setting, en een scope die bepaalt waar deze van toepassing is:

  • Accountinstellingen gelden voor het hele account.
  • Werkruimte-instellingen gelden voor één werkruimte.
  • Gebruikersvoorkeuren gelden voor een gebruiker in een account.

Sommige instellingen zijn beschikbaar op meer dan één niveau. Account- en werkruimte-instellingen vereisen over het algemeen beheerdersrechten om te lezen of bij te werken.

Eindpunten per bereik

Elke scope heeft zijn eigen set eindpunten. Gebruik degene die aansluit bij hoe de instelling wordt beheerd:

Scope Downloaden Bijwerken (PATCH)
Account /api/2.1/accounts/<account-id>/settings/<key-name> /api/2.1/accounts/<account-id>/settings/<key-name>
Werkruimte /api/2.1/settings/<key-name> /api/2.1/settings/<key-name>
Gebruikersvoorkeur /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name> /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>

Ontdek beschikbare instellingen

De instellingen en hun huidige metadata (inclusief het waardetype dat je nodig hebt voor updates) zijn beschikbaar vanaf het metadata-eindpunt. Dit is de altijd actuele, gezaghebbende bron van wat momenteel in je werkruimte of account kan worden ingesteld. Het eindpunt is gepagineerd, dus blader door de resultaten om de volledige lijst op te halen:

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

Je kunt ook instellingen vermelden met de Databricks CLI:

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

Voor accountinstellingen gebruik in plaats daarvan het account-scoped metadata-eindpunt:

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

Lees een instelling

Een get-response geeft twee waarden terug voor elke instelling. De opgeslagen waarde bevindt zich in het typeveld (bijvoorbeeld boolean_val) en is de waarde die is ingesteld. De effectieve waarde staat in het overeenkomstige effective_*-veld (bijvoorbeeld effective_boolean_val) en is de waarde die de server berekent na toepassing van standaardwaarden en eventuele overschrijvingen op een hoger niveau. Bijvoorbeeld, een booleaanse instelling geeft het volgende terug:

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

Om een werkruimte-instelling te lezen, roep je het get-eindpunt aan met de sleutelnaam van de instelling:

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

Om een accountinstelling te lezen, gebruik je het account-scoped pad:

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

Om een gebruikersvoorkeur te lezen, gebruik je het account-scoped gebruikerspad. Het lezen en bijwerken van gebruikersvoorkeuren vereist accountbeheerdersrechten:

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

Werk een instelling bij

Om een instelling bij te werken, stuur je een PATCH-verzoek waarvan de hoofdtekst het instellingsobject bevat, waarbij de waarde wordt doorgegeven in het veld dat overeenkomt met het type van de instelling. Gebruik list-workspace-settings-metadata (of het metadata-eindpunt) om het juiste typeveld voor een bepaalde setting te bepalen. Bijvoorbeeld, om een booleaanse werkruimte-instelling bij te werken:

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

Om een accountinstelling bij te werken, stuur je dezelfde hoofdtekst naar het accountspecifieke pad:

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

Om een gebruikersvoorkeur bij te werken, stuur je het verzoek naar het accountspecifieke gebruikerspad. Het onderstaande voorbeeld werkt een string-type voorkeur bij:

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

Aanvullende bronnen

  • Laatst bijgewerkt om