Gérer les paramètres via l’API Settings
L'API Settings vous permet de lire et de mettre à jour par programmation les paramètres de compte, de Workspace et d'utilisateur Databricks, y compris les aperçus de fonctionnalités au niveau du compte et du Workspace. Cette page explique comment découvrir les paramètres disponibles ainsi que la manière de les lire et de les mettre à jour. Pour obtenir la liste des paramètres disponibles via l'API publique, consultez la référence des clés API des paramètres.
Pour obtenir la référence complète de l’endpoint, consultez l’ API REST Settings.
Les préversions de fonctionnalités au niveau du Workspace et du compte sont également gérées via l'API Settings v2, mais elles ne sont pas répertoriées dans la référence des clés d'API Settings car une préversion finit par atteindre sa fin de vie lorsque la fonctionnalité est validée ou supprimée. Découvrez les préversions actuellement à votre disposition via l'endpoint settings-metadata. Chaque préversion renvoyée est lisible et peut être mise à jour via les mêmes endpoints get et update (PATCH) que n'importe quel autre paramètre.
Modèle d’API de paramètres
L’API Settings v2 est dynamique. Une API unique et généralisée dessert tous les paramètres, et de nouveaux paramètres y deviennent disponibles sans nécessiter de nouvelle version d’API, de version de SDK ou de mise à jour de la documentation. Plutôt qu’une liste fixe d’endpoints gérée manuellement, vous découvrez ce qui est actuellement configurable au moment de l’exécution via l’ endpoint de métadonnées.
Un paramètre possède un nom, une valeur dont la forme dépend du type de paramètre, et une portée qui détermine où il s’applique :
- Les paramètres du compte s’appliquent à l’ensemble du compte.
- Les paramètres de l'espace de travail s’appliquent à un seul workspace.
- Les préférences utilisateur s’appliquent à un utilisateur dans un compte.
Certains paramètres sont disponibles à plusieurs niveaux de portée. Les paramètres de compte et de workspace nécessitent généralement des autorisations d'administrateur pour être lus ou mis à jour.
Endpoints par portée
Chaque étendue possède son propre ensemble d’Endpoint. Utilisez celle qui correspond à la manière dont le paramètre est géré :
Périmètre | Obtenir | Mise à jour ( |
|---|---|---|
Compte | ||
Espace de travail | ||
Préférence utilisateur |
|
|
Découvrir les paramètres disponibles
Les noms des paramètres et leurs métadonnées actuelles (y compris le type de valeur dont vous avez besoin pour les mises à jour) sont disponibles via l’Endpoint de métadonnées. Il s’agit de la source de vérité toujours à jour pour ce qui est actuellement configurable dans votre Workspace ou votre compte. L’Endpoint est paginé ; parcourez donc les résultats pour récupérer la liste complète :
curl -n --request GET \
'https://<databricks-instance>/api/2.1/settings-metadata'
Vous pouvez également lister les paramètres avec la CLI Databricks:
databricks workspace-settings-v2 list-workspace-settings-metadata
Pour les paramètres de compte, utilisez plutôt l'endpoint de métadonnées limité au compte :
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings-metadata'
Lire un paramètre
Une réponse Get renvoie deux valeurs pour chaque paramètre. La valeur stockée se trouve dans le champ de type (par exemple, boolean_val) et correspond à la valeur qui a été définie. La valeur effective se trouve dans le champ effective_* correspondant (par exemple, effective_boolean_val) et correspond à la valeur calculée par le serveur après l'application des paramètres par défaut et de toute substitution de portée supérieure. Par exemple, un paramètre booléen renvoie :
{
"name": "<key-name>",
"boolean_val": { "value": true },
"effective_boolean_val": { "value": true }
}
Pour lire un paramètre de workspace, appelez l’endpoint get avec le nom de clé du paramètre :
curl -n --request GET \
'https://<databricks-instance>/api/2.1/settings/<key-name>'
Pour lire un paramètre de compte, utilisez le chemin à portée de compte :
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings/<key-name>'
Pour lire une préférence utilisateur, utilisez le chemin utilisateur au niveau du compte. La lecture et la mise à jour des préférences utilisateur nécessitent des autorisations d’administrateur de compte :
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>'
Mettre à jour un paramètre
Pour mettre à jour un paramètre, envoyez une requête PATCH dont le corps est l’objet de paramètre, avec la valeur portée dans le champ qui correspond au type du paramètre. Utilisez list-workspace-settings-metadata (ou l’endpoint de métadonnées) pour déterminer le champ de type correct pour un paramètre donné. Par exemple, pour mettre à jour un paramètre booléen du 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 }
}'
Pour mettre à jour un paramètre de compte, envoyez le même corps au chemin d'accès limité au compte :
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 }
}'
Pour mettre à jour une préférence utilisateur, envoyez la requête au chemin utilisateur limité au compte. L'exemple ci-dessous met à jour une préférence de type chaîne :
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>" }
}'