Databricks CLI 설정 & 설명서

Databricks CLI(명령줄 인터페이스)는 Azure Databricks 플랫폼에 사용하기 쉬운 인터페이스를 제공합니다. 오픈 소스 프로젝트는 GitHub에서 호스트됩니다. CLI는 Databricks REST API 위에 빌드되며 기본 엔드포인트를 기반으로 하여 명령 그룹으로 구성됩니다.

Databricks CLI를 사용하여 다음과 같은 작업을 수행할 수 있습니다.

  • Azure Databricks 작업 영역에서 컴퓨팅 리소스를 프로비전합니다.
  • 데이터 처리 및 데이터 분석 작업을 실행합니다.
  • 작업 영역의 Notebooks 및 폴더를 나열하고, 가져오고, 내보냅니다.

중요

이 CLI는 현재 개발 중이며 실험 클라이언트로 릴리스됩니다. 이는 인터페이스가 계속 변경될 수 있음을 의미합니다.

CLI 설정

이 섹션에서는 CLI 요구 사항을 나열하고 CLI를 실행하기 위해 환경을 설치하고 구성하는 방법에 대해 설명합니다.

요구 사항

  • Python 3 - 3.6 이상

  • Python 2 - 2.7.9 이상

    중요

    macOS에서 기본 Python 2 설치는 TLSv1_2 프로토콜을 구현하지 않으며 이 Python 설치로 CLI를 실행하면 오류(AttributeError: 'module' object has no attribute 'PROTOCOL_TLSv1_2')가 발생합니다. Homebrew를 사용하여 ssl.PROTOCOL_TLSv1_2가 있는 Python 버전을 설치합니다.

제한 사항

방화벽이 활성화된 스토리지 컨테이너에 Databricks CLI를 사용하는 것은 지원되지 않습니다. Databricks는 Databricks Connect 또는 az storage를 사용하는 것이 좋습니다.

CLI 설치

Python 설치에 적합한 pip 버전을 사용하여 pip install databricks-cli를 실행합니다.

pip install databricks-cli

CLI 업데이트

Python 설치에 적합한 pip 버전을 사용하여 pip install databricks-cli --upgrade를 실행합니다.

pip install databricks-cli --upgrade

현재 설치된 CLI 버전을 나열하려면 databricks --version(또는 databricks -v)을 실행합니다.

databricks --version

# Or...

databricks -v

인증 설정

참고

보안 모범 사례로, 자동화된 도구, 시스템, 스크립트 및 앱을 사용하여 인증할 때 작업 영역 사용자 대신 서비스 주체에 속한 액세스 토큰을 사용하는 것이 좋습니다. 서비스 주체에 대한 액세스 토큰을 만들려면 서비스 주체에 대한 액세스 토큰 관리를 참조하세요.

CLI 명령을 실행하려면 먼저 인증을 설정해야 합니다. CLI에 인증하려면 Databricks 개인용 액세스 토큰 또는 Azure AD(Azure Active Directory) 토큰을 사용할 수 있습니다.

참고

기본적으로 다음 명령은 이 새 파일에 DEFAULT라는 구성 프로필을 사용하여 .databrickscfg라는 구성 프로필 파일을 만듭니다. .databrickscfg 파일이 이미 있는 경우 이 파일의 DEFAULT 구성 프로필을 새 데이터로 덮어씁니다. 다른 이름으로 구성 프로필을 만들려면 연결 프로필을 참조하세요.

Azure AD 토큰을 사용하여 인증 설정

Azure AD 토큰을 사용하여 CLI를 구성하려면 Azure AD 토큰을 생성하고 환경 변수 DATABRICKS_AAD_TOKEN에 저장합니다.

다음 명령을 실행합니다.

databricks configure --aad-token

명령은 다음과 같은 프롬프트를 표시합니다.

Databricks Host (should begin with https://):

https://adb-<workspace-id>.<random-number>.azuredatabricks.net 형식으로 작업 영역별 URL을 입력합니다. 작업 영역별 URL을 얻으려면 작업 영역별 URL을 참조하세요.

프롬프트를 완료하면 액세스 자격 증명이 Unix, Linux 또는 macOS의 ~/.databrickscfg 파일 또는 Windows의 %USERPROFILE%\.databrickscfg 파일에 저장됩니다. 파일에는 기본 프로필 항목이 포함되어 있습니다.

[DEFAULT]
host = <workspace-URL>
token = <Azure-AD-token>

Databricks 개인용 액세스 토큰을 사용하여 인증 설정

개인용 액세스 토큰을 사용하도록 CLI를 구성하려면 다음 명령을 실행합니다.

databricks configure --token

명령은 다음 프롬프트를 실행하여 시작합니다.

Databricks Host (should begin with https://):

https://adb-<workspace-id>.<random-number>.azuredatabricks.net 형식으로 작업 영역별 URL을 입력합니다. 작업 영역별 URL을 얻으려면 작업 영역별 URL을 참조하세요.

명령은 개인용 액세스 토큰을 입력하라는 프롬프트를 실행하여 계속합니다.

Token:

프롬프트를 완료하면 액세스 자격 증명이 Unix, Linux 또는 macOS의 ~/.databrickscfg 파일 또는 Windows의 %USERPROFILE%\.databrickscfg 파일에 저장됩니다. 파일에는 기본 프로필 항목이 포함되어 있습니다.

[DEFAULT]
host = <workspace-URL>
token = <personal-access-token>

CLI 0.8.1 이상의 경우, 환경 변수 DATABRICKS_CONFIG_FILE을 설정하여 이 파일의 경로를 변경할 수 있습니다.

Unix, linux, macos

export DATABRICKS_CONFIG_FILE=<path-to-file>

Windows

setx DATABRICKS_CONFIG_FILE "<path-to-file>" /M

중요

CLI 0.17.2부터 CLI는 .netrc 파일에서 작동하지 않습니다. 다른 용도로 사용자 환경에 .netrc 파일을 가질 수 있지만 CLI는 해당 .netrc 파일을 사용하지 않습니다.

CLI 0.8.0 이상은 다음과 같은 Azure Databricks 환경 변수를 지원합니다.

  • DATABRICKS_HOST
  • DATABRICKS_TOKEN

환경 변수 설정은 구성 파일의 설정보다 우선적으로 적용됩니다.

인증 설정 테스트

인증을 올바르게 설정했는지 확인하려면 다음과 같은 명령을 실행하여 <someone@example.com>을 Azure Databricks 작업 영역 사용자 이름으로 바꾸면 됩니다.

databricks workspace ls /Users/<someone@example.com>

성공하면 이 명령은 지정된 작업 영역 경로의 개체를 나열합니다.

연결 프로필

Databrick CLI 구성은 여러 연결 프로필을 지원합니다. 동일한 Databrick CLI를 설치하면 여러 Azure Databrick 작업 영역에서 API를 호출할 수 있습니다.

연결 프로필을 추가하려면 프로필의 고유한 이름을 지정합니다.

databricks configure [--token | --aad-token] --profile <profile-name>

.databrickscfg 파일에는 해당하는 프로필 항목이 있습니다.

[<profile-name>]
host = <workspace-URL>
token = <token>

연결 프로필을 사용하려면 다음을 수행합니다.

databricks <group> <command> --profile <profile-name>

--profile <profile-name>을 지정하지 않으면 기본 스키마가 사용됩니다. 기본 프로필을 찾을 수 없는 경우 기본 프로필로 CLI를 구성하라는 메시지가 표시됩니다.

연결 프로필 테스트

연결 프로필을 올바르게 설정했는지 확인하려면 다음과 같은 명령을 실행하여 <someone@example.com>을 Azure Databricks 작업 영역 사용자 이름으로 바꾸고 <DEFAULT>를 연결 프로필 이름 중 하나로 바꿉니다.

databricks workspace ls /Users/<someone@example.com> --profile <DEFAULT>

성공하면 이 명령은 지정된 연결 프로필에 대한 작업 영역의 지정된 작업 영역 경로의 개체를 나열합니다. 테스트하려는 각 연결 프로필에 대해 이 명령을 실행합니다.

별칭 명령 그룹

경우에 따라 각 CLI 호출에 명령 그룹 이름(예: databricks workspace ls)을 접두사로 지정하는 것이 불편할 수 있습니다. CLI를 보다 쉽게 사용할 수 있도록 명령 그룹을 더 짧은 명령으로 별칭을 지정할 수 있습니다. 예를 들어 Bourne again 셸에서 databricks workspace lsdw ls로 줄이려면 적절한 bash 프로필에 alias dw="databricks workspace"를 추가할 수 있습니다. 일반적으로 이 파일은 ~/.bash_profile에 있습니다.

Azure Databricks는 이미 databricks fs에서 dbfs로 별칭을 지정했습니다. databricks fs lsdbfs ls는 동일합니다.

CLI 사용

이 섹션에서는 CLI 도움말을 가져오고 CLI 출력을 구문 분석하고 각 명령 그룹에서 명령을 호출하는 방법을 보여 줍니다.

CLI 명령 그룹 도움말 표시

databricks <group> --help(또는 databricks <group> -h)를 실행하여 명령 그룹에 대한 하위 명령을 나열합니다. 예를 들어 databricks fs -h를 실행하여 DBFS CLI 하위 명령을 나열합니다.

databricks fs -h

CLI 하위 명령 도움말 표시

databricks <group> <subcommand> --help(또는 databricks <group> <subcommand> -h)를 실행하여 하위 명령에 대한 도움말을 나열합니다. 예를 들어 databricks fs cp -h를 실행하여 DBFS 파일 복사 하위 명령에 대한 도움말을 나열합니다.

databricks fs cp -h

jq를 사용하여 CLI 출력 구문 분석

일부 Databricks CLI 명령은 API 엔드포인트에서 JSON 응답을 출력합니다. 경우에 따라 이는 JSON의 일부를 구문 분석하여 다른 명령으로 파이프하는 데에 유용할 수 있습니다. 예를 들어 작업 정의를 복사하려면 databricks jobs get 명령의 settings 필드를 가져와서 databricks jobs create 명령의 인수로 사용해야 합니다. 이 경우 jq 유틸리티를 사용하는 것이 좋습니다.

예를 들어 다음 명령은 ID가 233인 작업의 설정을 인쇄합니다.

databricks jobs list --output JSON | jq '.jobs[] | select(.job_id == 233) | .settings'
{
  "name": "Quickstart",
  "new_cluster": {
    "spark_version": "7.5.x-scala2.12",
    "spark_env_vars": {
      "PYSPARK_PYTHON": "/databricks/python3/bin/python3"
    },
    "num_workers": 8,
    ...
  },
  "email_notifications": {},
  "timeout_seconds": 0,
  "notebook_task": {
    "notebook_path": "/Quickstart"
  },
  "max_concurrent_runs": 1
}

또 다른 예로, 다음 명령은 작업 영역에서 사용 가능한 모든 클러스터의 이름과 ID를 인쇄합니다.

databricks clusters list --output JSON | jq '[ .clusters[] | { name: .cluster_name, id: .cluster_id } ]'
[
  {
    "name": "My Cluster 1",
    "id": "1234-567890-grip123"
  },
  {
    "name": "My Cluster 2",
    "id": "2345-678901-patch234"
  }
]

예를 들어 brew install jq와 함께 Homebrew를 사용하는 macOS 또는 choco install jq와 함께 Chocolatey를 사용하는 Windows에 jq를 설치할 수 있습니다. jq에 대한 자세한 내용은 jq 설명서를 참조하세요.

JSON 문자열 매개 변수

문자열 매개 변수는 운영 체제에 따라 다르게 처리됩니다.

Unix, linux, macos

모든 JSON 문자열 매개 변수는 다음과 같이 작은따옴표로 묶어야 합니다. 다음은 그 예입니다.

databricks jobs run-now --job-id 9 --jar-params '["20180505", "alantest"]'

Windows

JSON 문자열 매개 변수를 큰따옴표로 묶어야 하며, 문자열 내의 따옴표 문자 앞에는 \가 와야 합니다. 예를 들면 다음과 같습니다.

databricks jobs run-now --job-id 9 --jar-params "[\"20180505\", \"alantest\"]"

문제 해결

다음 섹션에서는 Databricks CLI의 일반적인 문제를 해결하기 위한 팁을 제공합니다.

EOF를 databricks configure와 함께 사용할 수 없습니다.

Databricks CLI 0.12.0 이상의 경우 스크립트에서 파일 끝(EOF) 시퀀스를 사용하여 매개변수를 databricks configure 명령에 전달하면 작동하지 않습니다. 예를 들어 다음 스크립트로 인해 Databricks CLI에서 매개 변수를 무시하며 오류 메시지가 표시되지 않습니다.

# Do not do this.
databricksUrl=<per-workspace-url>
databricksToken=<personal-access-token-or-Azure-AD-token>

databricks configure --token << EOF
$databricksUrl
$databricksToken
EOF

이 문제를 수정하려면 다음 중 하나를 수행합니다.

  • 인증 설정에 설명된 대로 다른 프로그래매틱 구성 옵션 중 하나를 사용합니다.
  • 인증 설정에 설명된 대로 hosttoken 값을 .databrickscfg 파일에 수동으로 추가합니다.
  • Databricks CLI 설치를 0.11.0 이하로 다운그레이드하고 스크립트를 다시 실행합니다.

CLI 명령