Gérez les paramètres via l’API des paramètres

L’API Paramètres vous permet de lire et de mettre à jour les paramètres du compte, de l’espace de travail et des utilisateurs Azure Databricks, y compris les prévisions de fonctionnalités au niveau du compte et de l’espace de travail, de manière programmatique. Cette page explique comment découvrir les paramètres disponibles, comment les lire et les mettre à jour. Pour la liste des paramètres disponibles via l’API publique, consultez la référence des clés de l’API des paramètres.

Pour la référence complète du point de terminaison, consultez l’API REST des Paramètres.

Note

Les aperçus de fonctionnalités au niveau de l’espace de travail et du compte sont également gérés via l’API Paramètres v2, mais ils ne sont pas listés dans la référence des clés API de Paramètres car un aperçu atteint finalement la fin de vie lorsque la fonctionnalité est graduée ou supprimée. Découvrez les préversions actuellement disponibles via le settings-metadata endpoint. Chaque aperçu qu’il renvoie est lisible et peut être mis à jour via les mêmes endpoints get et update (PATCH) que tout autre paramètre.

Modèle d’API des paramètres

L’API Paramètres v2 est dynamique. Une API unique et généralisée sert tous les paramètres, et de nouveaux paramètres deviennent disponibles via elle sans nouvelle version de l’API, version du SDK ou mise à jour de la documentation. Plutôt qu’une liste fixe et maintenue à la main des points de terminaison, vous découvrez ce qui est actuellement configurable à l’exécution via le point de terminaison des métadonnées.

Un univers a un nom, une valeur dont la forme dépend du type de l’univers, 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 d’espace de travail s’appliquent à un seul espace de travail.
  • Les préférences utilisateur s’appliquent à un utilisateur dans un compte.

Certains paramètres sont disponibles à plusieurs niveaux. Les paramètres de compte et d’espace de travail nécessitent généralement des autorisations administrateur pour lire ou mettre à jour.

Points d’extrémité par étendue

Chaque scope possède son propre ensemble de points de terminaison. Utilisez celui qui correspond à la façon dont le cadre est géré :

Étendue Obtenir Mise à jour (PATCH)
Compte /api/2.1/accounts/<account-id>/settings/<key-name> /api/2.1/accounts/<account-id>/settings/<key-name>
Espace de travail /api/2.1/settings/<key-name> /api/2.1/settings/<key-name>
Préférences utilisateur /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name> /api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>

Découvrez les réglages disponibles

Les noms des paramètres et leurs métadonnées actuelles (y compris le type de valeur nécessaire pour les mises à jour) sont disponibles depuis le point de terminaison des métadonnées. Il s’agit de la source de référence toujours à jour concernant ce qui peut actuellement être configuré dans votre espace de travail ou votre compte. Le point de terminaison est paginané, alors feuilleter 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 aussi afficher la liste des paramètres avec le Databricks CLI :

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

Pour les paramètres du compte, utilisez plutôt le point de terminaison des métadonnées associé 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 type (par exemple, boolean_val) et est la valeur qui a été définie. La valeur effective se trouve dans le champ correspondant effective_* (par exemple, effective_boolean_val) et est la valeur que le serveur calcule après avoir appliqué les valeurs par défaut et tout override à portée supérieure. Par exemple, un paramètre booléen donne :

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

Pour lire un paramètre d’espace de travail, appelez le point de terminaison get avec le nom 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 délimité par le 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 limité au compte. La lecture et la mise à jour des préférences utilisateur nécessitent les 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 PATCH requête dont le corps est l’objet de paramètres, avec la valeur contenue dans le champ correspondant au type du paramètre. Utilisez list-workspace-settings-metadata (ou le point de terminaison des métadonnées) pour déterminer le champ de type correct pour un paramètre donné. Par exemple, pour mettre à jour un paramètre d’espace de travail booléen :

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 du compte, envoyez le même corps de requête au chemin propre 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 associé 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>" }
  }'

Ressources additionnelles

  • Dernière mise à jour :