Pagination des opérations de l’API REST Unity Catalog
La pagination limite les tailles de réponse, ce qui rend les requêtes plus prévisibles et réduit les échecs causés par des réponses de plus en plus volumineuses à mesure que votre metastore augmente. Par conséquent, les requêtes non paginées vers les opérations de l’API REST Unity Catalog listées sur cette page ne seront bientôt plus prises en charge. Ces opérations resteront disponibles sous forme paginée. Pour plus d’informations, consultez Les requêtes non paginées vers certaines opérations de l’API REST Unity Catalog seront bientôt rejetées.
Cette page décrit comment trouver et mettre à jour vos clients qui appellent ces opérations.
Opérations qui nécessitent une pagination
Les opérations suivantes utilisent leur forme paginée lorsque max_results est spécifié. Définissez max_results=0 pour laisser le serveur choisir la taille de la page, ou définissez une valeur positive pour demander une taille de page :
Opérations | Référence de l’API |
|---|---|
Liste les métastores | |
Liste les emplacements externes | |
Lister les connexions | |
Lister les catalogues | |
Obtenir les liaisons de workspace | |
Liste des schémas | |
Liste des tables | |
Lister les fonctions | |
Obtenir des autorisations | |
Obtenir les autorisations effectives | |
Répertorier les schémas système | |
Liste les identifiants de stockage |
Pour trouver les clients qui appellent ces opérations sans pagination, consultez Rechercher les appelants non paginés dans le journal d'audit.
Les autres opérations de la liste Unity Catalog, telles que Volumes de liste et Résumés de table de liste, renvoient déjà des pages lorsque vous omettez max_results. Les Opérations qui utilisent un parameter page_size, telles que Lister les autorisations, renvoient également des pages par défaut. Votre client doit toujours suivre avec des jetons de page pour ces opérations afin de récupérer chaque résultat.
Utiliser des opérations plus récentes si disponibles
Pour les nouvelles intégrations, Databricks recommande d'utiliser les opérations plus récentes suivantes. Les clients existants peuvent continuer à utiliser les opérations non obsolètes sous forme paginée. Obtenir les liaisons de workspace de catalogue est obsolète et nécessite une migration. Lors du basculement des opérations, mettez à jour votre client pour prendre en compte les différences dans les URL, les paramètres de requête ou les champs de réponse.
Opération plus ancienne | Opération plus récente | À faire |
|---|---|---|
Liste les identifiants de stockage | Utilisez les informations d'identification de la liste pour les nouvelles intégrations. Les clients existants peuvent continuer à appeler les informations d'identification de stockage de liste avec | |
Obtenir les liaisons workspace-catalogue | Migrer. Obtenir les liaisons workspace-catalogue est obsolète. Appelez Obtenir les liaisons workspace avec | |
Obtenir des autorisations | Utilisez List permissions pour les nouvelles intégrations. Les clients existants peuvent continuer à appeler Get permissions avec | |
Obtenir les autorisations effectives | Utilisez Lister les autorisations effectives pour les nouvelles intégrations. Les clients existants peuvent continuer à appeler Obtenir les autorisations effectives avec |
Utiliser une version actuelle du SDK ou de la CLI
Les commandes de liste des SDK Databricks et du CLI Databricks paginent pour vous. Utilisez la dernière version prise en charge des SDK Python, Java ou Go, ainsi que la dernière version généralement disponible du CLI Databricks.
Les versions SDK et CLI plus anciennes peuvent ne pas paginer pour chaque opération de liste Unity Catalog. Si votre intégration pin une version, vérifiez que sa commande de liste ou son itérateur SDK récupère toutes les pages, et mettez-la à niveau si elle ne renvoie que la première page.
Les appels REST directs, y compris les appels effectués avec databricks api get, ne paginent pas automatiquement. Votre client doit continuer avec next_page_token comme décrit dans la section suivante.
Récupérer toutes les pages avec un client REST direct
Pour récupérer un ensemble complet de résultats à partir d’une opération affectée :
- Lors de la première demande, définissez
max_results=0et omettezpage_token. La définition demax_results=0permet au serveur de choisir la taille de page. - Lire
next_page_tokendepuis la réponse. Dans la requête suivante, transmettez sa valeur sous la formepage_tokenet gardez tous les autres paramètres de requête identiques. - Répétez jusqu'à ce qu'une réponse omette
next_page_tokenou le retourne comme une valeur vide. Continuez à demander des pages même si une page ne contient aucun résultat.
Le champ de réponse qui contient les résultats varie en fonction de l'opération. Consultez la référence de l'API pour chaque opération.
L’exemple suivant liste toutes les tables d’un schéma. Il lit l’URL du workspace et un jeton d’accès personnel à partir des variables d’environnement DATABRICKS_HOST et DATABRICKS_TOKEN :
import os
import requests
def list_tables(catalog_name, schema_name):
url = f"{os.environ['DATABRICKS_HOST'].rstrip('/')}/api/2.1/unity-catalog/tables"
headers = {"Authorization": f"Bearer {os.environ['DATABRICKS_TOKEN']}"}
params = {
"catalog_name": catalog_name,
"schema_name": schema_name,
"max_results": 0, # Let the server choose the page size.
}
tables = []
while True:
response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
body = response.json()
tables.extend(body.get("tables", []))
# Stop when the response no longer includes a page token.
page_token = body.get("next_page_token")
if not page_token:
return tables
params["page_token"] = page_token
Pour plus d’instructions sur l’API REST, notamment sur la façon de gérer les réponses HTTP 429 et d’omettre les champs de réponse dont vous n’avez pas besoin, consultez les meilleures pratiques.
Rechercher des appelants sans pagination dans le journal d’audit
Pour trouver les clients qui appellent les Opérations affectées sans pagination, query la table système des logs d'audit pour les requêtes qui omettent max_results. La query suivante vérifie les 30 derniers jours et regroupe les requêtes par opération et par appelant. Pour identifier et contacter le propriétaire de chaque client, utilisez le nom de l'application OAuth lorsqu'il est disponible, l'user agent et l'ID de requête d'exemple.
WITH unpaginated_calls AS (
SELECT
action_name,
COALESCE(
NULLIF(request_params['workspace_id'], '0'),
NULLIF(CAST(workspace_id AS STRING), '0'),
'account-level or unknown'
) AS originating_workspace,
COALESCE(
user_identity.email,
user_identity.subject_name,
'unknown'
) AS caller,
identity_metadata.acting_resource_display_name AS oauth_app,
user_agent,
source_ip_address,
event_time,
request_id,
request_params
FROM system.access.audit
WHERE event_date >= date_sub(current_date(), 30)
AND service_name = 'unityCatalog'
AND action_name IN (
'listMetastores',
'listExternalLocations',
'listConnections',
'listCatalogs',
'GetWorkspaceBindings',
'listSchemas',
'listTables',
'listFunctions',
'getPermissions',
'getEffectivePermissions',
'listSystemSchemas',
'listStorageCredentials'
)
AND request_params['max_results'] IS NULL
)
SELECT
action_name,
originating_workspace,
caller,
oauth_app,
user_agent,
COUNT(*) AS unpaginated_requests,
MIN(event_time) AS first_seen,
MAX(event_time) AS last_seen,
MAX_BY(source_ip_address, event_time) AS sample_source_ip,
MAX_BY(request_id, event_time) AS sample_request_id
FROM unpaginated_calls
GROUP BY
action_name,
originating_workspace,
caller,
oauth_app,
user_agent
ORDER BY unpaginated_requests DESC;
Si la query ne renvoie aucune ligne, étendez la plage temporelle pour détecter les jobs qui s’exécutent rarement. La plupart des Logs d’audit ne sont disponibles que dans la région du Workspace ; exécutez donc la query dans chaque région contenant vos Workspace. Un résultat vide ne garantit pas que tous vos clients utilisent la pagination.