Gestisci le impostazioni tramite l'API delle impostazioni

L'API Impostazioni ti permette di leggere e aggiornare le impostazioni di account, workspace e utente di Azure Databricks, incluse anteprime di funzionalità a livello di account e di workspace, in modo programmativo. Questa pagina spiega come scoprire le impostazioni disponibili e come leggerle e aggiornarle. Per l'elenco delle impostazioni disponibili tramite l'API pubblica, consulta il riferimento delle chiavi API delle impostazioni.

Per il riferimento completo all'endpoint, consulta l'API REST delle Impostazioni.

Note

Le anteprime delle funzionalità a livello di spazio di lavoro e di account sono gestite anche tramite l'API Settings v2, ma non sono elencate nel riferimento delle chiavi dell'API Settings perché un'anteprima viene infine ritirata quando la funzionalità esce dall'anteprima o viene rimossa. Scopri le anteprime attualmente disponibili tramite l'endpoint delle impostazioni e dei metadati. Ogni anteprima che restituisce è leggibile e aggiornabile tramite gli stessi endpoint get e update (PATCH) di qualsiasi altra impostazione.

Modello API delle impostazioni

L'API delle Impostazioni v2 è dinamica. Un'unica API generalizzata serve ogni impostazione, e nuove impostazioni diventano disponibili tramite essa senza una nuova versione dell'API, una nuova versione dell'SDK o un aggiornamento della documentazione. Invece di una lista fissa e gestita manualmente degli endpoint, si scopre cosa è attualmente impostabile in runtime tramite l'endpoint metadata.

Un'impostazione ha un nome, un valore la cui forma dipende dal tipo di impostazione e un ambito che determina dove si applica:

  • Le impostazioni dell'account si applicano a tutto l'account.
  • Le impostazioni dello spazio di lavoro si applicano a un singolo spazio di lavoro.
  • Le preferenze dell'utente si applicano a un utente all'interno di un account.

Alcune impostazioni sono disponibili su più di un telescopio. Le impostazioni di account e spazio di lavoro generalmente richiedono i permessi degli amministratori per leggere o aggiornare.

Endpoint per ambito

Ogni ambito ha il proprio insieme di endpoint. Usa quello che corrisponde a come viene gestita l'ambientazione:

Scope GET Aggiornamento (PATCH)
Conto /api/2.1/accounts/<account-id>/settings/<key-name> /api/2.1/accounts/<account-id>/settings/<key-name>
Workspace /api/2.1/settings/<key-name> /api/2.1/settings/<key-name>
Preferenze dell'utente /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name> /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>

Scopri le impostazioni disponibili

I nomi delle impostazioni e i loro metadati attuali (incluso il tipo di valore necessario per gli aggiornamenti) sono disponibili dall'endpoint dei metadati. Questa è la fonte di riferimento sempre aggiornata di ciò che è attualmente configurabile nel tuo spazio di lavoro o nel tuo account. L'endpoint è paginato, quindi sfoglia i risultati per recuperare l'elenco completo:

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

Puoi anche elencare le impostazioni con la CLI Databricks:

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

Per le impostazioni dell'account, usa invece l'endpoint dei metadati a livello di account:

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

Leggere un'impostazione

Una risposta get restituisce due valori per ogni impostazione. Il valore memorizzato si trova nel campo tipo (ad esempio, boolean_val) ed è il valore che è stato impostato. Il valore effettivo si trova nel campo corrispondente effective_* (ad esempio, effective_boolean_val) ed è il valore che il server calcola dopo aver applicato i valori predefiniti e qualsiasi override di ambito superiore. Ad esempio, un'impostazione booleana restituisce:

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

Per leggere un'impostazione di spazio di lavoro, chiama l'endpoint get con il nome chiave dell'impostazione:

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

Per leggere un'impostazione di account, usa il percorso con ambito dell'account:

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

Per leggere una preferenza utente, utilizza il percorso utente relativo all'account. La lettura e l'aggiornamento delle preferenze utente richiedono i permessi dell'amministratore dell'account:

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

Aggiorna un'impostazione

Per aggiornare un'impostazione, invia una richiesta PATCH nel cui corpo è presente l'oggetto impostazione, con il valore riportato nel campo che corrisponde al tipo dell'impostazione. Usa list-workspace-settings-metadata (o l'endpoint dei metadati) per determinare il campo `type` corretto per una determinata impostazione. Ad esempio, per aggiornare un'impostazione di workspace booleana:

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

Per aggiornare un'impostazione dell'account, invia lo stesso payload al percorso relativo all'account:

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

Per aggiornare una preferenza utente, invia la richiesta al percorso utente a livello di account. L'esempio qui sotto aggiorna una preferenza per stringa:

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

Risorse aggiuntive

  • Last updated on