Paginar operações da API REST do Unity Catalog
A paginação limita os tamanhos de resposta, tornando as solicitações mais previsíveis e reduzindo falhas causadas por respostas cada vez maiores à medida que seu metastore cresce. Portanto, solicitações não paginadas para as operações da API REST do Unity Catalog listadas nesta página não terão suporte em breve. Essas operações continuarão disponíveis na forma paginada. Para obter mais informações, consulte Solicitações não paginadas para algumas operações da API REST do Unity Catalog serão rejeitadas em breve.
Esta página descreve como encontrar e atualizar seus clientes que chamam essas operações.
Operações que exigem paginação
As operações a seguir usam seu formato paginado quando max_results é especificado. Defina max_results=0 para permitir que o servidor escolha o tamanho da página ou defina um valor positivo para solicitar um tamanho de página:
Operação | Referência de API |
|---|---|
Listar metastores | |
Listar localizações externas | |
Listar conexões | |
Listar catálogos | |
Obter vinculações de workspace | |
Listar esquemas | |
Listar tabelas | |
Listar funções | |
Obter permissões | |
Obter permissões efetivas | |
Listar esquemas do sistema | |
Listar credenciais de armazenamento |
Para encontrar clientes que chamam essas operações sem paginação, consulte Encontrar chamadores não paginados no log de auditoria.
Outras operações de lista do Unity Catalog, como Listar volumes e Listar resumos de tabelas, já retornam páginas quando você omite max_results. Operações que usam um parâmetro page_size, como Listar permissões, também retornam páginas por default. Seu cliente ainda deve seguir com tokens de página para essas operações para recuperar cada resultado.
Use operações mais recentes quando disponíveis
Para novas integrações, o Databricks recomenda usar as seguintes operações mais recentes. Clientes existentes podem continuar usando as operações não obsoletas de forma paginada. Obter bindings de workspace de catálogo foi descontinuado e requer migração. Ao alternar operações, atualize seu cliente para account diferenças em URLs, parâmetros de solicitação ou campos de resposta.
Operação mais antiga | Operação mais recente | O que fazer |
|---|---|---|
Listar credenciais de armazenamento | Use List credentials para novas integrações. Os clientes existentes podem continuar chamando List storage credentials com | |
Obter vinculações de catálogo de workspace | Migrar. Obter vinculações de catálogo de workspace está obsoleto. Chame Get workspace bindings com | |
Obter permissões | Use Listar permissões para novas integrações. Clientes existentes podem continuar a chamar Listar permissões com | |
Obter permissões efetivas | Use Listar permissões efetivas para novas integrações. Os clientes existentes podem continuar a chamar o Get effective permissions com |
Use uma versão atual do SDK ou CLI
Os comandos de lista dos SDKs Databricks e da CLI Databricks fazem a paginação para você. Use a versão compatível mais recente do SDK Python, Java ou Go e a versão disponível mais recente da CLI do Databricks.
Versões mais antigas do SDK e da CLI podem não paginar para cada operação de lista do Unity Catalog. Se sua integração pin uma versão, verifique se seu comando de lista ou iterador de SDK recupera todas as páginas e atualize se ele retornar apenas a primeira página.
Chamadas REST diretas, incluindo chamadas feitas com databricks api get, não são paginadas automaticamente. O cliente deve continuar com next_page_token conforme descrito na próxima seção.
Buscar todas as páginas com um cliente REST direto
Para recuperar um conjunto completo de resultados de uma operação afetada:
- Na primeira solicitação, defina
max_results=0e omitapage_token. A definiçãomax_results=0permite que o servidor escolha o tamanho da página. - Leia
next_page_tokenda resposta. Na próxima solicitação, passe seu valor comopage_tokene mantenha todos os outros parâmetros de solicitação iguais. - Repita até que uma resposta omita
next_page_tokenou retorne como um valor vazio. Continue solicitando páginas mesmo se uma página não contiver resultados.
O campo de resposta que contém os resultados varia conforme a operação. Verifique a referência da API para cada operação.
O exemplo a seguir lista todas as tabelas em um schema. Ele lê a URL do workspace e um access token pessoal das variáveis de ambiente DATABRICKS_HOST e 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
Para obter mais orientações sobre a API REST, incluindo como lidar com respostas HTTP 429 e omitir campos de resposta de que você não precisa, consulte Práticas recomendadas.
Localizar chamadores não paginados no log de auditoria
Para encontrar clientes que chamam as operações afetadas sem paginação, query a tabela do sistema de logs de auditoria para solicitações que omitem max_results. A seguinte query verifica os últimos 30 dias e agrupa as solicitações por operação e chamador. Para identificar e entrar em contato com o proprietário de cada cliente, use o nome do aplicativo OAuth quando disponível, o agente do usuário e o ID da solicitação de exemplo.
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;
Se a query não retornar nenhuma linha, estenda o intervalo de tempo para capturar jobs que são executados com pouca frequência. A maioria dos Logs de auditoria está disponível apenas na região do Workspace, portanto, faça a execução da query em cada região que contém seus Workspace. Um resultado vazio não garante que todos os seus clientes paginam.