설정 API는 Azure Databricks 계정, 작업 공간, 사용자 설정, 계정 및 작업 공간 수준의 기능 미리보기를 프로그래밍적으로 읽고 업데이트할 수 있게 해줍니다. 이 페이지에서는 사용 가능한 설정을 어떻게 발견하고 이를 읽고 업데이트하는지 설명합니다. 공개 API를 통해 이용 가능한 설정 목록은 Settings API 키 참고 자료를 참조하세요.
전체 엔드포인트 참조는 설정 REST API를 참조하세요.
메모
Workspace 및 계정 수준의 기능 미리보기도 설정 v2 API를 통해 관리되지만, 기능이 종료되거나 제거되면 미리보기가 결국 종료되기 때문에 설정 API 키 참조 에는 포함되지 않습니다.
settings-metadata 엔드포인트를 통해 현재 이용 가능한 미리보기를 확인하세요. 반환되는 모든 미리보기는 다른 설정과 마찬가지로 동일한 get and update(PATCH) 엔드포인트를 통해 읽고 업데이트할 수 있습니다.
설정 API 모델
설정 v2 API는 동적입니다. 모든 설정을 하나의 일반화된 API가 제공하며, 새로운 API 버전, SDK 릴리스, 문서 업데이트 없이도 새로운 설정을 통해 제공됩니다. 고정되고 수작업으로 관리하는 엔드포인트 목록 대신, 메타데이터 엔드포인트를 통해 런타임에 현재 설정 가능한 항목을 발견합니다.
설정은 이름, 설정의 유형에 따라 형태가 달라지는 값, 그리고 적용 범위를 결정하는 범위를 가집니다:
- 계정 설정 은 계정 전체에 적용됩니다.
- 작업 공간 설정 은 하나의 작업공간에 적용됩니다.
- 사용자 선호도 는 계정 내 사용자에게 적용됩니다.
일부 설정은 여러 스코프에서 사용할 수 있습니다. 계정 및 작업 공간 설정은 일반적으로 읽거나 업데이트하려면 관리자 권한이 필요합니다.
범위별 엔드포인트
각 범위는 고유한 종점 집합을 가지고 있습니다. 설정이 어떻게 관리되는지 맞는 것을 사용하세요:
사용 가능한 설정 발견
설정 이름과 현재 메타데이터(업데이트에 필요한 값 유형 포함)는 메타데이터 엔드포인트에서 확인할 수 있습니다. 이 문서는 현재 워크스페이스 또는 계정에서 설정할 수 있는 항목에 대해 항상 최신 정보를 제공하는 기준 정보원입니다. 엔드포인트는 페이지 처리되어 있으므로, 전체 목록을 가져오려면 결과 페이지를 순차적으로 조회하세요:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/settings-metadata'
Databricks CLI로 설정을 나열할 수도 있습니다:
databricks workspace-settings-v2 list-workspace-settings-metadata
계정 설정의 경우 대신 계정 범위 메타데이터 엔드포인트를 사용하세요:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings-metadata'
설정 읽기
get 응답은 각 설정마다 두 개의 값을 반환합니다.
저장된 값은 타입 필드(예: boolean_val)에 있으며, 설정된 값입니다.
유효 값은 해당 effective_* 필드(예: effective_boolean_val)에 있으며, 기본값과 상위 범위 덮개 후 서버가 계산하는 값입니다. 예를 들어, 불리언 설정은 다음과 같이 반환합니다:
{
"name": "<key-name>",
"boolean_val": { "value": true },
"effective_boolean_val": { "value": true }
}
작업 공간 설정을 읽으려면, get 엔드포인트에 해당 설정의 키명을 호출하세요:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/settings/<key-name>'
계정 설정을 읽으려면 계정 범위 경로를 사용하세요:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings/<key-name>'
사용자 선호도를 읽으려면 계정 범위 사용자 경로를 사용하세요. 사용자 환경설정을 읽고 업데이트하려면 계정 관리자 권한이 필요합니다:
curl -n --request GET \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>'
설정 업데이트
설정을 업데이트하려면 본문이 설정 객체인 PATCH 요청을 보내고, 값은 설정 유형에 해당하는 필드에 포함되어야 합니다. (또는 메타데이터 엔드포인트)를 사용하여 list-workspace-settings-metadata 특정 설정에 맞는 올바른 타입 필드를 결정하세요. 예를 들어, 불리언 작업 공간을 업데이트하려면:
curl -n --request PATCH \
'https://<databricks-instance>/api/2.1/settings/<key-name>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "<key-name>",
"boolean_val": { "value": true }
}'
계정 설정을 업데이트하려면 동일한 본문을 계정 범위 경로로 보내세요:
curl -n --request PATCH \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/settings/<key-name>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "<key-name>",
"boolean_val": { "value": true }
}'
사용자 선호도를 업데이트하려면 요청을 계정 범위가 설정된 사용자 경로로 전송하세요. 아래 예시는 문자열 타입 선호도를 업데이트합니다:
curl -n --request PATCH \
'https://<databricks-instance>/api/2.1/accounts/<account-id>/users/<user-id>/settings/<key-name>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "<key-name>",
"string_val": { "value": "<value>" }
}'