Informations de référence sur l’API REST Databricks

Article
02/01/2023
11 minutes de lecture

Azure Databricks propose trois API REST qui effectuent des tâches différentes :

Les versions 2.0 et 2.1 pour l’administration générale
La version 1.2 pour l’exécution de commandes directement sur Azure Databricks

Pour obtenir la version la plus récente de toutes les API REST, consultez API REST (dernière en date). Vous pouvez également accéder directement aux pages d’accueil de l’API REST pour chaque version : 2.1, 2.0 ou 1.2.

Important

Pour accéder aux API REST Databricks, vous devez vous authentifier.

API Account 2.0
API Clusters 2.0
API Stratégies de cluster 2.0
API de traçabilité des données 2.0
Requêtes, tableaux de bord et alertes API 2.0.
API d’historique des requêtes Databricks SQL 2.0
API Entrepôts Databricks SQL 2.0
API DBFS 2.0
API Delta Live Tables 2.0
API Git Credentials 2.0
API Scripts d’initialisation globaux 2.0
API Groupes 2.0
API Pools d’instances 2.0
API Liste d’accès IP 2.0
API Travaux 2.1, 2.0
API Bibliothèques 2.0
API MLflow 2.0
API Autorisations 2.0
API Dépôts 2.0
API SCIM 2.0
API Secrets 2.0
API Jeton 2.0
API Gestion des jetons 2.0
API Catalogue Unity 2.1, 2.0
API Espace de travail 2.0
API 1.2

Authentification

Pour plus d’informations sur l’authentification auprès de l’API REST à l’aide de jetons d’accès personnels, consultez Authentification à l’aide de jetons d’accès personnels Azure Databricks.

Pour plus d’informations sur l’authentification auprès de l’API REST à l’aide de jetons Azure Active Directory, consultez Authentification à l’aide de jetons Azure Active Directory. Pour obtenir des exemples, consultez Utiliser un jeton d’accès Azure AD pour un utilisateur et Utiliser un jeton d’accès Azure AD pour un principal de service.

Pour obtenir des exemples d’API, consultez Exemples d’API.

Limites du taux de transfert

Pour garantir une haute qualité de service sous une lourde charge, Databricks applique des limites de taux pour tous les appels d’API REST. Les limites sont définies par point de terminaison et par espace de travail pour garantir une utilisation équitable et une haute disponibilité.

Les demandes qui dépassent la limite de taux retournent un code d’état de réponse 429.

Pour plus d’informations sur les limites de taux pour les demandes d’API, consultez Limites de taux pour les API.

Analyser la sortie

Il peut être utile d’analyser des parties de la sortie JSON. Databricks recommande l’utilitaire jq pour l’analyse de données JSON. Vous pouvez installer jq sur Linux à l’aide des versions de jq, sur macOS à l’aide de Homebrew avec brew install jq ou sur Windows à l’aide de Chocolatey avec choco install jq. Pour plus d’informations sur jq, consultez le Manuel jq.

Cet exemple liste les noms et les ID des clusters disponibles dans l’espace de travail spécifié. Cet exemple utilise un fichier .netrc.

curl --netrc -X GET https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/list \
| jq '[ .clusters[] | { id: .cluster_id, name: .cluster_name } ]'

[
  {
    "id": "1234-567890-batch123",
    "name": "My Cluster 1"
  },
  {
    "id": "2345-678901-rigs234",
    "name": "My Cluster 2"
  }
]

Compatibilité

Les réponses pour la même version d’API ne suppriment aucun champ de la sortie JSON. Toutefois, l’API peut ajouter de nouveaux champs à la sortie JSON sans incrémenter la version d’API. Vos workflows programmatiques doivent tenir compte de ces ajouts et ignorer les champs inconnus.

Certains champs STRING (qui contiennent une erreur et un message descriptif destinés à être consommés par l’interface utilisateur) ne sont pas structurés, et vous ne devez pas dépendre du format de ces champs dans les workflows programmatiques.

Utiliser curl pour appeler l’API REST Databricks

curl est un outil connu pour transférer des données vers et à partir de serveurs. Cette section fournit des informations spécifiques sur l’utilisation de curl pour appeler l’API REST Databricks.

Appeler une méthode GET à l’aide d’une chaîne de requête

Même si la plupart des appels d’API exigent que vous spécifiiez un corps JSON, pour les appels GET, vous pouvez spécifier une chaîne de requête en l’ajoutant après ? et en plaçant l’URL entre guillemets. Si vous utilisez curl, vous pouvez spécifier --get (ou -G) et --data (ou -d) avec la chaîne de requête. Vous n’avez pas besoin de placer l’URL ou la chaîne de requête entre guillemets.

Dans les exemples suivants, remplacez adb-1234567890123456.7.azuredatabricks.net par l’URL d’espace de travail de votre déploiement Azure Databricks. Elle doit commencer par adb-. N’utilisez pas l’URL régionale dépréciée qui commence par <azure-region-name>. Elle peut ne pas fonctionner pour les nouveaux espaces de travail, sera moins fiable et montrera des performances inférieures à celles des URL par espace de travail.

Cet exemple affiche des informations relatives au cluster spécifié. Cet exemple utilise un fichier .netrc.

Utilisation de ?:

curl --netrc 'https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get?cluster_id=1234-567890-patch123'

Utilisation de --get et de --data :

curl --netrc --get \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get \
--data cluster_id=1234-567890-batch123

{
  "cluster_id": "1234-567890-batch123",
  "driver": {
    "node_id": "123ab456789012345cd67e8e90123f45",
    "instance_id": "234ab456789012345cd67e8e90123f45",
    "start_timestamp": 1618448261567,
    "host_private_ip": "10.0.0.0",
    "private_ip": "10.0.0.0"
  },
  ...
}

Cet exemple liste le contenu de la racine DBFS. Cet exemple utilise un fichier .netrc.

curl --netrc --get \
https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/dbfs/list \
--data path=/

"files": [
  {
    "path": "/tmp",
    "is_dir": true,
    "file_size": 0,
    "modification_time": 1547078156000
  },
  {
    "path": "/my_file.txt",
    "is_dir": false,
    "file_size": 40,
    "modification_time": 1541374426000
  },
  ...
]

Utiliser Python pour appeler l’API REST Databricks

Pour appeler l’API REST Databricks avec Python, vous pouvez utiliser le package Databricks CLI en tant que bibliothèque. Ce package est écrit en Python et vous permet d’appeler l’API REST Databricks via des classes Python qui modélisent étroitement les charges utiles des requêtes et des réponses de l’API REST Databricks. Pour plus d’informations, consultez Appeler l’API REST Databricks avec Python.

L’utilisation directe de la bibliothèque requests Python est une autre approche. Cependant, vous devez travailler à un niveau inférieur, en fournissant manuellement les en-têtes nécessaires, en gérant les erreurs et en effectuant d’autres tâches de codage associées de bas niveau.

requests est une bibliothèque connue pour effectuer des requêtes HTTP en Python. Cet exemple utilise la bibliothèque requests pour lister les informations relatives au cluster Azure Databricks spécifié. Cet exemple utilise un fichier .netrc.

import requests
import json

instance_id = 'adb-1234567890123456.7.azuredatabricks.net'

api_version = '/api/2.0'
api_command = '/clusters/get'
url = f"https://{instance_id}{api_version}{api_command}"

params = {
  'cluster_id': '1234-567890-batch123'
}

response = requests.get(
  url = url,
  params = params
)

print(json.dumps(json.loads(response.text), indent = 2))

{
  "cluster_id": "1234-567890-batch123",
  "driver": {
    ...
  },
  "spark_context_id": 1234567890123456789,
  ...
}

Utiliser Postman pour appeler l’API REST Databricks

Dans l’application Postman, créez une requête HTTP (Fichier>Nouveau>Requête HTTP).
Dans la liste déroulante des verbes HTTP, sélectionnez le verbe qui correspond à l’opération d’API REST que vous souhaitez appeler. Par exemple, pour lister les informations relatives à un cluster Azure Databricks, sélectionnez GET.
Pour Entrer l’URL de la demande, commencez par entrer https://<databricks-instance-name>, où <databricks-instance-name> est le nom de votre instance d’espace de travail Azure Databricks, par exemple adb-1234567890123456.7.azuredatabricks.net.
Terminez l’URL de la demande par le chemin qui correspond à l’opération d’API REST que vous souhaitez appeler. Par exemple, pour lister les informations relatives à un cluster, utilisez /api/2.0/clusters/get.
Sous l’onglet Authorization, dans la liste Type, sélectionnez Jeton du porteur.
Pour Jeton, entrez votre jeton d’accès personnel Databricks pour votre utilisateur d’espace de travail.

Conseil

Au lieu d’entrer le nom de votre instance d’espace de travail, par exemple adb-1234567890123456.7.azuredatabricks.net, et votre jeton d’accès personnel Databricks pour votre utilisateur d’espace de travail à chaque appel, vous pouvez définir des variables et utiliser des variables dans Postman.
Si l’opération d’API REST que vous souhaitez appeler nécessite un corps de demande, procédez comme suit :
1. Sous l’onglet En-têtes, ajoutez la paire Clé et Valeur de Content-Type et un type de contenu acceptable pour l’opération d’API REST. Par exemple, pour lister les informations relatives à un cluster, utilisez le type de contenu application/json.
2. Sous l’onglet Corps, sélectionnez un type de corps acceptable pour l’opération d’API REST. Par exemple, pour lister les informations relatives à un cluster, sélectionnez le type de corps brut, puis JSON.
3. Entrez le corps de la demande. Par exemple, pour lister les informations relatives au cluster spécifié, entrez ce qui suit :
```
{
  "cluster_id": "1234-567890-batch123"
}
```
Si l’opération d’API REST que vous souhaitez appeler nécessite des en-têtes supplémentaires, entrez-les en tant que paires clé et valeur supplémentaires sous l’onglet En-têtes. Par exemple, pour lister les informations relatives à un cluster, aucun en-tête supplémentaire n’est nécessaire.
Si l’opération d’API REST que vous souhaitez appeler nécessite des paramètres de requête, entrez-les en tant que paires clé et valeur sous l’onglet Paramètres. Par exemple, pour lister les informations relatives à un cluster, au lieu d’utiliser un corps de demande, vous pouvez utiliser un paramètre de requête avec une clé cluster_id et une valeur de l’ID du cluster spécifié, par exemple 1234-567890-batch123.
Cliquez sur Envoyer. Les détails de la réponse s’affichent sous l’onglet Corps de la section de réponse.

Utiliser HTTPie pour appeler l’API REST Databricks

Utiliser l’application de bureau HTTPie ou l’application web HTTPie pour appeler l’API REST Databricks

Ouvrez l’application de bureau HTTPie ou accédez à l’application web HTTPie.
Dans la liste déroulante des verbes HTTP, sélectionnez le verbe qui correspond à l’opération d’API REST que vous souhaitez appeler. Par exemple, pour lister les informations relatives à un cluster Azure Databricks, sélectionnez GET.
Dans la zone httpie.io/hello, commencez par entrer https://<databricks-instance-name>, où <databricks-instance-name> est le nom de votre instance d’espace de travail Azure Databricks, par exemple adb-1234567890123456.7.azuredatabricks.net.
Terminez l’URL de la demande par le chemin qui correspond à l’opération d’API REST que vous souhaitez appeler. Par exemple, pour lister les informations relatives à un cluster, utilisez /api/2.0/clusters/get.
Sous l’onglet Authentification, cliquez sur Jeton du porteur.
Pour token, entrez le jeton d’accès personnel Databricks de votre utilisateur d’espace de travail.

Conseil

Au lieu d’entrer le nom de votre instance d’espace de travail, par exemple adb-1234567890123456.7.azuredatabricks.net, et votre jeton d’accès personnel Databricks pour votre utilisateur d’espace de travail à chaque appel, vous pouvez définir des variables d’environnement (telles que DATABRICKS_HOST et DATABRICKS_TOKEN) puis utiliser ces variables d’environnement (telles que {{DATABRICKS_HOST}} et {{DATABRICKS_TOKEN}}) dans HTTPie. Consultez Environnements sur le blog HTTPie.
Si l’opération d’API REST que vous souhaitez appeler nécessite un corps de demande, procédez comme suit :
1. Sous l’onglet En-têtes, ajoutez la paire nom et valeur de Content-Type et un type de contenu acceptable pour l’opération d’API REST. Par exemple, pour lister les informations relatives à un cluster, utilisez le type de contenu application/json.
2. Sous l’onglet Corps, sélectionnez un type de corps acceptable pour l’opération d’API REST. Par exemple, pour lister les informations relatives à un cluster, sélectionnez le type de corps Texte, puis JSON.
3. Entrez le corps de la demande. Par exemple, pour lister les informations relatives au cluster spécifié, entrez ce qui suit :
```
{
  "cluster_id": "1234-567890-batch123"
}
```
Si l’opération d’API REST que vous souhaitez appeler nécessite des en-têtes supplémentaires, entrez-les en tant que paires nom et valeur supplémentaires sous l’onglet En-têtes. Par exemple, pour lister les informations relatives à un cluster, aucun en-tête supplémentaire n’est nécessaire.
Si l’opération d’API REST que vous souhaitez appeler nécessite des paramètres de requête, entrez-les en tant que paires nom et valeur sous l’onglet Paramètres. Par exemple, pour lister les informations relatives à un cluster, au lieu d’utiliser un corps de demande, vous pouvez utiliser un paramètre de requête avec un nom cluster_id et une valeur de l’ID du cluster spécifié, par exemple 1234-567890-batch123.
Cliquez sur Envoyer. Les détails de la réponse s’affichent sous l’onglet Réponse.

Utiliser l’interface de ligne de commande HTTPie pour appeler l’API REST Databricks

Cet exemple utilise l’interface de ligne de commande HTTPie pour lister les informations relatives au cluster Azure Databricks spécifié. Cet exemple utilise un fichier .netrc.

https GET adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get cluster_id=1234-567890-batch123

# Or...

https adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get cluster_id==1234-567890-batch123

# Which is equivalent in curl with jq...
# curl --netrc 'https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get' -d '{ "cluster_id": "1234-567890-patch123" }' | jq .\
# Or...
# curl --netrc 'https://adb-1234567890123456.7.azuredatabricks.net/api/2.0/clusters/get?cluster_id=1234-567890-patch123' | jq .

Conseil

Vous pouvez convertir curl en syntaxe HTTPie avec des outils tels que le package CurliPie sur PyPI ou l’application web CurliPie.

Utiliser PowerShell pour appeler l’API REST Databricks

Cet exemple utilise l’applet de commande Invoke-RestMethod dans PowerShell pour lister les informations sur le cluster Azure Databricks spécifié.

$Token = 'dapia1b2345678901c23456defa7bcde8fa9'
$ConvertedToken = $Token | ConvertTo-SecureString -AsPlainText -Force

$InstanceID = 'adb-1234567890123456.7.azuredatabricks.net'
$APIVersion = '/api/2.0'
$APICommand = '/clusters/get'
$Uri = "https://$InstanceID$APIVersion$APICommand"

$Body = @{
  'cluster_id' = '1234-567890-batch123'
}

$Response = Invoke-RestMethod `
  -Authentication Bearer `
  -Token $ConvertedToken `
  -Method Get `
  -Uri  $Uri `
  -Body $Body

Write-Output $Response

cluster_id       : 1234-567890-batch123
driver           : ...
spark_context_id : 1234567890123456789
...

Chaînes de la version de Runtime

De nombreux appels d’API requièrent que vous spécifiiez une chaîne de la version de Databricks Runtime. Cette section décrit la structure d’une chaîne de version dans l’API REST Databricks.

<M>.<F>.x[-cpu][-esr][-gpu][-ml][-photon]-scala<scala-version>

where

M : version majeure de Databricks Runtime
F : mise en production de fonctionnalité de Databricks Runtime
cpu : version du processeur (avec -ml uniquement)
esr : support étendu
gpu : avec processeur graphique (GPU)
ml : Machine Learning
photon : Photon
scala-version : version de Scala utilisée pour compiler Spark : 2.10, 2.11 ou 2.12

Par exemple :

7.6.x-gpu-ml-scala2.12 représente Databricks Runtime 7.6 pour Machine Learning, si compatible avec un processeur graphique, et utilise Scala version 2.12 pour compiler Spark version 3.0.1

Les tableaux Versions d’Azure Databricks Runtime prises en charge et calendrier de prise en charge et Versions non prises en charge mappent les versions de Databricks Runtime à la version de Spark contenue dans le runtime.

Vous pouvez obtenir la liste des chaînes de version du runtime Azure Databricks disponibles en appelant l’API Versions de runtime .

Databricks Light

apache-spark.<M>.<F>.x-scala<scala-version>