Unity Catalog REST APIオペレーションのページネーション
ページ分割によって応答サイズが制限されるため、リクエストが予測しやすくなり、メタストアの拡大に伴って応答が巨大化することで発生する障害が低減されます。したがって、このページにリストされている Unity Catalog REST API 操作へのページ分割されていないリクエストは、まもなくサポートされなくなります。これらの操作はページ分割形式で引き続き利用できます。情報については、「一部の Unity Catalog REST API 操作へのページ分割されていない要求は、まもなく拒否されます」を参照してください。
このページでは、これらの操作を呼び出すクライアントを見つけて更新する方法について説明します。
ページ分割が必要な操作
次の操作では、max_results が指定されている場合、ページ分割された形式が使用されます。サーバーにページサイズを選択させるには max_results=0 を設定し、ページサイズを要求するには正の値を設定します。
オペレーション | APIリファレンス |
|---|---|
メタストアのリスト | |
外部ロケーションの一覧 | |
接続のリスト | |
カタログの一覧 | |
ワークスペースバインディングの取得 | |
スキーマのリスト | |
テーブルのリスト | |
関数を一覧表示 | |
権限の取得 | |
有効な権限を取得する | |
システムスキーマの一覧表示 | |
ストレージ資格情報のリスト |
ページネーションなしでこれらの操作を呼び出すクライアントを見つけるには、監査ログでページネーションされていない呼び出し元を見つけるを参照してください。
他のUnity Catalog一覧操作（ や など）は、max_resultsを省略すると、既にページを返すようになっています。「権限の一覧」など、page_sizeパラメーターを使用する操作も、defaultでページを返します。クライアントは、すべての結果を取得するために、これらの操作に対してページトークンで後続の処理を行う必要があります。
利用可能な場合は、新しいオペレーションを使用します
新規統合の場合は、Databricks では以下の新しい操作を使用することをお勧めします。既存のクライアントは、非推奨ではない操作をページ形式で引き続き使用できます。「カタログのワークスペースバインドの取得」は非推奨となり、移行が必要です。操作を切り替える際は、URL、要求パラメーター、または応答フィールドの違いを考慮してクライアントを更新してください。
過去の操作 | 新しい操作 | 実行すべきこと |
|---|---|---|
ストレージ資格情報のリスト | 新しい統合には「資格情報のリスト」を使用してください。既存のクライアントは引き続き | |
カタログとワークスペースのバインドを取得します | 移行します。カタログとワークスペースのバインドを取得は非推奨です。 | |
権限の取得 | 新しい統合には「権限の取得」を使用します。既存のクライアントは、引き続き | |
有効な権限を取得する | 新しい統合には、List effective permissions を使用してください。既存のクライアントは、 |
現在のSDKまたはCLIバージョンを使用する
Databricks SDKとDatabricks CLIの一覧表示コマンドでは、ページネーションが自動的に行われます。Python、Java、またはGo SDKの最新のサポート対象リリースと、Databricks CLIの最新の一般提供リリースを使用してください。
古いSDKおよびCLIバージョンでは、すべての Unity Catalog リスト操作でページネーションが実行されない場合があります。統合でバージョンがピン留めされている場合は、そのリストコマンドまたはSDKイテレーターがすべてのページを取得することを確認し、最初のページのみが返される場合はアップグレードしてください。
databricks api get で行われた呼び出しを含む直接 REST 呼び出しは、自動的にページ分割されません。クライアントは、次のセクションの説明に従って next_page_token を使用する必要があります。
ダイレクト REST クライアントですべてのページを取得します
影響を受ける操作から完全な結果セットを取得するには：
- 最初の要求で、
max_results=0を設定し、page_tokenを省略します。max_results=0を設定すると、サーバーがページサイズを選択できるようになります。 - レスポンスから
next_page_tokenを読み取ります。次の要求で、その値をpage_tokenとして渡し、他のすべての要求パラメーターは同じままにしておきます。 - 応答から
next_page_tokenが省略されるか、空の値として返されるまで繰り返します。ページに結果が含まれていない場合でも、ページの要求を続けます。
結果を含む応答フィールドは、操作によって異なります。各操作の API リファレンスを確認してください。
次の例では、スキーマ内のすべてのテーブルを一覧表示します。DATABRICKS_HOST および DATABRICKS_TOKEN の環境変数からワークスペース URL と個人用アクセストークンを読み取ります：
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
HTTP 429レスポンスの処理方法や不要なレスポンスフィールドの省略方法など、REST APIに関するガイダンスについては、ベストプラクティスを参照してください。
監査ログでページ分割されていない呼び出し元を見つける
ページネーションを使用せずに影響を受ける操作を呼び出すクライアントを見つけるには、監査ログシステムテーブルで max_results を省略したリクエストをクエリーします。次のクエリーは、過去 30 日間を確認し、操作と呼び出し元でリクエストをグループ化します。各クライアントの所有者を特定して連絡するには、可能な場合は OAuth アプリ名、ユーザーエージェント、およびサンプルのリクエスト ID を使用します。
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;
クエリーで行が返されない場合は、実行頻度の低いジョブを検出できるよう、時間範囲を広げてください。監査Logsの大半はワークスペースのリージョンでのみ利用できるため、ワークスペースが存在する各リージョンでクエリーをランしてください。結果が空でも、すべてのクライアントでページネーションが行われるとは限りません。