Gerenciar configurações por meio da API de configurações
A API de configurações permite ler e atualizar as configurações de conta, workspace e usuário do Databricks, incluindo visualizações de recursos em nível de conta e de workspace, de forma programática. Esta página explica como descobrir as configurações disponíveis e como lê-las e atualizá-las. Para obter a lista de configurações disponíveis por meio da API pública, consulte Referência das chaves de API de configurações.
Para a referência completa do endpoint, consulte a API REST de configurações.
As prévias de recursos no nível do workspace e da conta também são gerenciadas por meio da API de configurações v2, mas não estão listadas na referência de chaves da API de configurações porque uma prévia eventualmente chega ao fim da vida útil quando o recurso é graduado ou removido. Descubra as prévias disponíveis atualmente para você por meio do endpoint settings-metadata. Cada prévia retornada é legível e atualizável por meio dos mesmos get e update (PATCH) Endpoint que qualquer outra configuração.
Modelo da API de configurações
A API Settings v2 é dinâmica. Uma única API generalizada atende a todas as configurações, e novas configurações ficam disponíveis por meio dela sem a necessidade de uma nova versão da API, lançamento de SDK ou atualização da documentação. Em vez de uma lista fixa de endpoints mantida manualmente, você descobre o que pode ser definido atualmente em Runtime por meio do Endpoint de metadados.
Uma configuração tem um nome, um valor cuja forma depende do tipo da configuração e um escopo que determina onde ela se aplica:
- Configurações da account aplicam-se a toda a account.
- Configurações do workspace se aplicam a um único workspace.
- As preferências do usuário se aplicam a um usuário em uma account.
Algumas configurações estão disponíveis em mais de um escopo. As configurações de conta e workspace geralmente exigem permissões de administrador para leitura ou atualização.
Endpoints por escopo
Cada escopo tem seu próprio conjunto de endpoints. Use aquela que corresponde à forma como a configuração é gerenciada:
Escopo | Get | Atualização ( |
|---|---|---|
Conta | ||
Workspace | ||
Preferência do usuário |
|
|
Descubra as configurações disponíveis
Os nomes das configurações e seus metadados atuais (incluindo o tipo de valor necessário para atualizações) estão disponíveis no endpoint de metadados. Esta é a fonte de verdade sempre atualizada para o que pode ser definido atualmente em seu workspace ou account. O endpoint é paginado, portanto, navegue pelas páginas dos resultados para recuperar a lista completa:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/settings-metadata'
Você também pode listar as configurações com a CLI do Databricks:
databricks workspace-settings-v2 list-workspace-settings-metadata
Para configurações de conta, use o endpoint de metadados com escopo de conta:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings-metadata'
Ler uma configuração
Uma resposta get retorna dois valores para cada configuração. O valor armazenado está no campo de tipo (por exemplo, boolean_val) e é o valor que foi definido. O valor efetivo está no campo effective_* correspondente (por exemplo, effective_boolean_val) e é o valor que o servidor calcula após aplicar os default e quaisquer substituições de escopo superior. Por exemplo, uma configuração booleana retorna:
{
"name": "<key-name>",
"boolean_val": { "value": true },
"effective_boolean_val": { "value": true }
}
Para ler uma configuração de workspace, chame o endpoint get com o nome da key da configuração:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/settings/<key-name>'
Para ler uma configuração de account, use o caminho com escopo de account:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings/<key-name>'
Para ler uma preferência do usuário, use o caminho de usuário com escopo de account. A leitura e a atualização das preferências do usuário requerem permissões de administrador da account:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>'
Atualizar uma configuração
Para atualizar uma configuração, envie uma solicitação PATCH cujo corpo seja o objeto de configuração, com o valor contido no campo que corresponde ao tipo da configuração. Use list-workspace-settings-metadata (ou o endpoint de metadados) para determinar o campo de tipo correto para uma determinada configuração. Por exemplo, para atualizar uma configuração booleana do workspace:
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 }
}'
Para atualizar uma configuração de account, envie o mesmo corpo para o caminho com escopo de 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 }
}'
Para atualizar uma preferência de usuário, envie a solicitação para o caminho de usuário com escopo de account. O exemplo abaixo atualiza uma preferência do tipo strings:
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>" }
}'