Gerir definições através da API de Definições

A API de Definições permite-lhe ler e atualizar as definições da conta, do espaço de trabalho e do utilizador do Azure Databricks, incluindo pré-visualizações de contas e funcionalidades ao nível do espaço de trabalho, de forma programática. Esta página explica como descobrir as definições disponíveis e como lê-las e atualizá-las. Para a lista de definições disponíveis através da API pública, consulte a referência de chaves da API de Definições.

Para a referência completa do endpoint, consulte a API REST Settings.

Note

As pré-visualizações de funcionalidades ao nível da conta e do espaço de trabalho também são geridas através da API de Definições v2, mas não estão listadas na referência de chaves da API de Definições porque uma pré-visualização acaba por chegar ao fim de vida quando a funcionalidade se gradua ou é removida. Descubra as pré-visualizações atualmente disponíveis através do endpoint de definições-metadados. Todas as pré-visualizações que retorna podem ser lidas e atualizadas através dos mesmos endpoints de get e update (PATCH) que qualquer outra configuração.

Modelo da API de definições

A API de Definições v2 é dinâmica. Uma API única e generalizada serve todas as definições, e novas definições ficam disponíveis através dela sem uma nova versão da API, lançamento do SDK ou atualização da documentação. Em vez de uma lista fixa de endpoints mantida manualmente, descobre-se o que pode ser atualmente configurado em tempo de execução no metadata endpoint.

Um cenário tem um nome, um valor cuja forma depende do tipo do cenário, e um âmbito que determina onde se aplica:

  • As definições da conta aplicam-se em toda a conta.
  • As definições do espaço de trabalho aplicam-se a um único espaço de trabalho.
  • As preferências do utilizador aplicam-se a um utilizador numa conta.

Algumas definições estão disponíveis em mais do que um âmbito. As definições da conta e do espaço de trabalho geralmente exigem permissões de administrador para ler ou atualizar.

Pontos finais por âmbito

Cada âmbito tem o seu próprio conjunto de endpoints. Usa o que corresponde à forma como o cenário é gerido:

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 utilizador /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 os cenários disponíveis

Os nomes das definições e os seus metadados atuais (incluindo o tipo de valor necessário para atualizações) estão disponíveis no endpoint de metadados. Esta é a fonte fidedigna, sempre atualizada, do que pode atualmente ser configurado no seu espaço de trabalho ou conta. O endpoint é paginado, por isso folheie os resultados para obter a lista completa:

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

Também pode listar definições com a linha de comando do Databricks:

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

Para as definições da conta, utilize antes o endpoint de metadados ao nível da conta:

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

Leia um cenário

Uma resposta get devolve dois valores para cada definição. O valor armazenado está no campo de tipo (por exemplo, boolean_val) e é o valor que foi definido. O valor efetivo encontra-se no campo correspondente effective_* (por exemplo, effective_boolean_val) e é o valor que o servidor calcula após aplicar os padrões e quaisquer sobreposições de âmbito superior. Por exemplo, uma configuração booleana devolve:

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

Para ler uma configuração do espaço de trabalho, utilize o endpoint get com o nome da chave da configuração:

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

Para ler uma definiçã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 de utilizador, use o caminho de utilizador no âmbito da conta. Ler e atualizar as preferências do utilizador 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>'

Atualizar uma definição

Para atualizar uma definição, envie um PATCH pedido cujo corpo seja o objeto de definição, com o valor transportado no campo que corresponde ao tipo da definiçã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 definiçã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 definição de conta, envie o mesmo corpo para o caminho com âmbito de 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 utilizador, envie a solicitação para o caminho do utilizador no âmbito da conta. O exemplo abaixo atualiza uma preferência por 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 a