Gerencie as configurações pela API de Configurações

A API de Configurações permite que você leia e atualize as configurações de conta, espaço de trabalho e usuários do Azure Databricks, incluindo pré-visualizações de contas e recursos em nível de ambiente, de forma programática. Esta página explica como descobrir as configurações disponíveis e como lê-las e atualizá-las. Para a lista de configurações disponíveis pela API pública, veja referência às chaves da API de Configurações.

Para a referência completa do endpoint, veja a API REST de Configurações.

Note

As visualizações prévias de recursos no nível do espaço de trabalho e da conta também são gerenciadas pela API de Configurações v2, mas não são listadas na referência de chaves da API Settings porque uma visualização prévia acaba sendo descontinuada quando o recurso deixa de ser prévia ou é removido. Descubra as prévias atualmente disponíveis para você através do endpoint de configurações e metadados. Toda visualização prévia retornada pode ser lida e atualizada pelos mesmos endpoints de get e update (PATCH), assim como qualquer outra configuração.

Modelo da API de configurações

A API de Configurações v2 é dinâmica. Uma API única e generalizada atende todas as configurações, e novas configurações ficam disponíveis por meio dela sem uma nova versão da API, lançamento do SDK ou atualização de documentação. Em vez de uma lista fixa e mantida manualmente de endpoints, você descobre o que atualmente pode ser configurado em tempo de execução 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:

  • As configurações da conta se aplicam em toda a conta.
  • As configurações de espaço de trabalho se aplicam a um único espaço de trabalho.
  • Preferências de usuário se aplicam a um usuário em uma conta.

Algumas configurações estão disponíveis em mais de um telescópio. As configurações de conta e espaço de trabalho geralmente exigem permissões de administrador para ler ou atualizar.

Pontos finais por escopo

Cada escopo tem seu próprio conjunto de pontos finais. Use a que corresponde à forma como o cenário é gerenciado:

Scope Obter Atualização (PATCH)
Conta /api/2.1/accounts/<account-id>/settings/<key-name> /api/2.1/accounts/<account-id>/settings/<key-name>
Espaço de Trabalho /api/2.1/settings/<key-name> /api/2.1/settings/<key-name>
Preferência do usuário /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name> /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>

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 informações sempre atualizada sobre o que pode ser configurado no seu workspace ou conta. O endpoint é paginado, então folheie os resultados para recuperar a lista completa:

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

Você também pode listar configurações com a interface de comando do Databricks:

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

Para as configurações da conta, use o endpoint de metadados no escopo da conta:

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

Leia uma configuração

Uma resposta get retorna dois valores para cada configuração. O valor armazenado está no campo tipo (por exemplo, boolean_val) e é o valor que foi definido. O valor efetivo está no campo correspondente effective_* (por exemplo, effective_boolean_val) e é o valor que o servidor calcula após aplicar os padrões e quaisquer sobrescrições de escopo maior. 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 espaço de trabalho, chame o endpoint `get` usando o nome da chave da configuração:

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

Para ler uma configuração de conta, use o caminho com escopo de conta:

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 no escopo da conta. Ler e atualizar as preferências do usuário requer permissões de administrador de conta:

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

Atualize uma configuração

Para atualizar uma configuração, envie uma PATCH solicitação cujo corpo seja o objeto de configuração, com o valor carregado no campo que corresponda 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 de espaço de trabalho 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 }
  }'

Para atualizar uma configuração da conta, envie o mesmo corpo da solicitação para o caminho no escopo da conta:

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 requisição para o caminho do usuário no escopo da conta. O exemplo abaixo atualiza uma preferência de tipo de string:

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

Recursos adicionais

  • Última atualização em