Azure Databricks REST API

이 페이지에서는 Azure Databricks REST API와 호출 방법, 그리고 몇 가지 모범 사례를 설명합니다.

Databricks REST API에 대한 완전한 참고 자료는 Databricks REST API 참고 자료를 참조하세요.

메모

고급 시나리오를 제외하고, Databricks는 Databricks 객체를 프로그래밍적으로 관리할 때 Databricks REST API 대신 Databricks SDK 또는 Databricks CLI 를 사용할 것을 권장합니다.

워크스페이스 REST API와 계정 REST API 비교

Azure Databricks는 두 세트의 REST API를 제공합니다. 워크스페이스 API는 클러스터, 작업, 노트북, Unity 카탈로그 객체 등 단일 워크스페이스 내에서 자원을 관리하며, 워크스페이스 URL 을 호스트로 호출합니다. 계정 API는 사용자 및 그룹 프로비저닝, 작업 공간 생성, 네트워크 및 청구 설정, 계정 단위 Unity 카탈로그 설정 등 계정 전체 자원을 관리하며, 계정 콘솔 로그인 URL과 계정 ID를 사용해 호출합니다.

각 세트에서 사용 가능한 연산에 대해서는 작업 공간 API 참조 와 계정 API 참조를 참조하세요.

REST API 호출

Databricks REST API 호출에는 다음 구성 요소가 포함됩니다:

  • 워크스페이스인지 계정 엔드포인트인지에 따라 다음과 같습니다:
  • REST API 연산 유형, 예를 들어 GET, POST, PATCH, 또는 DELETE.
  • REST API 연산 경로, 예를 들어 /api/2.0/clusters/get.
  • Databricks 인증 정보, 예를 들어 Databricks OAuth 토큰.
  • REST API 연산에서 지원되는 요청 페이로드 또는 클러스터 ID와 같은 요청 쿼리 매개변수.

REST API 요청을 구조화하는 방법과 선호하는 개발자 도구에 맞는 응답 페이로드 파싱 방법에 대한 정보는 제공자의 문서를 참조하세요.

예시 1: 클러스터 생성

다음 예시는 Cluster, List 엔드포인트 를 호출하여 사용 가능한 클러스터 목록을 반환합니다. 환경 변수가 DATABRICKS_HOST Databricks 작업 공간 URL로 설정되어 있고 DATABRICKS_TOKEN Databricks 토큰으로 설정되어 있다고 가정합니다.

curl -X GET "$DATABRICKS_HOST/api/2.0/clusters/list" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN"

import requests
import os

headers = {"Authorization": f"Bearer {os.getenv('DATABRICKS_TOKEN')}"}
response = requests.get(f"{os.getenv('DATABRICKS_HOST')}/api/2.0/clusters/list", headers=headers)

print(response.json())

예시 2: 작업을 진행합니다

다음 예시는 기존 작업의 드라이 런을 실행하기 위해 Job, Run Now 엔드포인트를 호출합니다. 환경 변수가 DATABRICKS_HOST Databricks 작업 공간 URL로 설정되어 있고 DATABRICKS_TOKEN Databricks 토큰으로 설정되어 있다고 가정합니다.

curl -X POST "$DATABRICKS_HOST/api/2.1/jobs/run-now" \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": 45678,
    "notebook_params": {
      "dry_run": "true",
      "start_date": "2026-08-27"
    }
  }'

import requests
import os

url = f"{os.getenv('DATABRICKS_HOST')}/api/2.1/jobs/run-now"
headers = {
    "Authorization": f"Bearer {os.getenv('DATABRICKS_TOKEN')}",
    "Content-Type": "application/json"
}
payload = {
    "job_id": 45678,
    "notebook_params": {"dry_run": "true", "start_date": "2026-08-27"}
}

response = requests.post(url, headers=headers, json=payload)
print(f"Run ID: {response.json().get('run_id')}")

예시 3: 계정 반환 사용자

다음 예제에서는 <account_id>를 호출하여 로 식별되는 Databricks 계정의 사용자를 반환합니다:

curl -X GET '<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users' \
  --header "Authorization: Bearer $OAUTH_TOKEN"

import requests
import os

url = "<databricks-account-login-url>/api/2.0/identity/accounts/<account_id>/users"
headers = {"Authorization": f"Bearer {os.getenv('OAUTH_TOKEN')}"}

response = requests.get(url, headers=headers)
print(response.json())

모범 사례

다음 섹션에서는 작업 공간 내 데이터가 증가함에 따라 성능이 개선되는 모범 사례를 설명합니다.

Paginate LIST API 응답

LIST API는 단일 큰 응답이 아닌 페이지 단위로 결과를 반환합니다. 완전한 결과 집합을 얻으려면 첫 번째 페이지를 요청한 후, 응답 내 토큰을 사용해 이후 각 페이지를 요청하여 토큰이 반환되지 않을 때까지 반복합니다.

전체 결과 세트를 넘기려면 다음과 같습니다:

  • 각 응답에서 next_page_token 필드를 읽어 보세요. 다음 페이지를 요청하려면 다음 요청의 page_token 쿼리 매개변수에 해당 값을 전달하고, 나머지 요청 매개변수는 동일하게 유지하세요.
  • 응답에서 next_page_token를 생략하거나 이를 빈 값으로 반환할 때까지 반복합니다. 그 답변이 마지막 페이지입니다. 결과가 없더라도 페이지를 계속 요청하세요.
  • page_token을 첫 번째 요청에 포함하지 마세요. 후속 요청에만 추가하세요.

페이지 크기를 제어하는 매개변수는 API마다 다릅니다. 예를 들어, 일부 API는 max_results를 사용하고, 다른 API는 limit를 사용하며, 또 다른 API는 page_size를 사용합니다. 각 엔드포인트가 지원하는 매개변수를 REST API 참조에서 확인하세요.

메모

일부 구형 Unity 카탈로그 LIST API는 max_results를 지정해야만 결과를 페이지 단위로 반환합니다. max_results=0을 설정하여 서버가 페이지 크기를 선택하게 하거나, 양수 값을 설정하여 페이지 크기를 요청하세요. 자세한 내용은 Paginate Unity Catalog REST API Operations를 참조하세요.

429개의 속도 제한 응답 처리

Databricks는 REST API 호출에 속도 제한을 적용하여 무거운 부하 시 작업 공간이 반응하도록 합니다. 공정 사용과 가용성을 지원하기 위해 엔드포인트별 및 작업 공간별 제한이 적용됩니다. 속도 제한을 초과하는 요청은 HTTP 429 Too Many Requests 응답을 반환합니다.

지수 백오프와 지터를 사용해 429 응답을 재시도하며 원활하게 처리하세요:

  • 지수 백오프: 429 후에는 다시 시도하기 전에 기다리고, 이후 각 429 후에는 대기 시간을 두 배로 늘립니다. 최대 대기 시간과 최대 재시도 횟수를 설정하여 요청이 무한히 재시도하지 않도록 하세요.
  • 지터: 각 대기 시간에 무작위로 시간을 조금 추가하세요. 지터는 여러 클라이언트에서 재시도를 분산시켜 모두 동시에 재시도하지 않게 하여 반복적인 트래픽 폭발을 방지합니다.
  • 응답에 헤더가 포함되어 Retry-After 있다면, 최소 그 정도 시간은 기다렸다가 다시 시도하세요.

대부분의 HTTP 클라이언트 라이브러리는 이 재시도 동작을 적용할 수 있습니다. 알고리즘의 배경에 대해서는 지수 백오프와 지터를 참조하세요.

특정 API에 적용되는 속도 제한에 대해서는 API 속도 제한을 참조하세요.

성능 향상을 위한 응답 필드 축소

일부 LIST API는 계산 비용이 많이 들거나 응답이 커지는 필드를 반환하기도 합니다. 이러한 필드가 필요하지 않은 경우, 응답 크기를 줄이고 지연 시간을 낮추기 위해 해당 필드를 제외한 요청 매개변수를 사용하세요.

예를 들어, Unity 카탈로그 테이블 API 는 다음과 같은 매개변수를 지원합니다:

  • omit_properties=true: 응답의 각 테이블에서 properties 필드를 생략합니다.
  • omit_columns=true: 응답의 각 테이블에서 columns 필드를 생략합니다.

만약 테이블 이름을 가져오기만 위해 나열한다면, 두 매개변수를 모두 설정하면 응답이 더 작고 테이블 목록이 더 빨라집니다. 각 엔드포인트가 지원하는 필드 트리밍 매개변수는 REST API 참조 를 확인하세요.

추가 리소스

  • 에 마지막으로 업데이트됨