Menyambungkan ke aplikasi API Databricks menggunakan autentikasi token

Anda dapat memanggil aplikasi Databricks yang mengekspos API HTTP (misalnya, aplikasi FastAPI atau Gradio) menggunakan autentikasi token Pembawa OAuth 2.0. Metode ini berfungsi dari lingkungan pengembangan lokal, aplikasi eksternal, dan aplikasi Azure Databricks lainnya.

Nota

Metode ini hanya berlaku untuk aplikasi yang mengekspos API atau titik akhir (dapat diakses menggunakan /api/ rute). Untuk aplikasi yang hanya menyediakan antarmuka pengguna atau pemrosesan latar belakang, Anda tidak dapat tersambung menggunakan autentikasi token.

Persyaratan

Untuk menyambungkan ke aplikasi Databricks menggunakan autentikasi token, Anda harus memenuhi persyaratan berikut:

Aplikasi harus mengekspos setidaknya satu titik akhir API yang dapat diakses menggunakan /api/ rute.
Anda harus memiliki CAN USE izin di aplikasi. Lihat Mengonfigurasi izin untuk aplikasi Databricks.
Anda harus dapat menghasilkan token akses Azure Databricks menggunakan salah satu metode autentikasi yang didukung.

Metode autentikasi

Nota

Anda tidak dapat memanggil aplikasi Databricks secara langsung menggunakan token Azure Entra ID. Federasi token memerlukan langkah pertukaran token sisi klien, yang Azure Databricks tidak melakukan sisi server. Untuk menggunakan token Azure Entra ID untuk autentikasi, Anda harus terlebih dahulu menukarnya dengan token OAuth. Lihat Mengautentikasi dengan token penyedia identitas.

Pilih metode autentikasi yang cocok dengan skenario koneksi Anda:

Pengembangan lokal

Untuk menyambungkan dari lingkungan pengembangan lokal Anda, gunakan Databricks CLI atau SDK dengan kredensial pengguna Anda.

Masuk dengan CLI:
```
databricks auth login --host https://<workspace-url> --profile my-env
```
Azure Databricks merekomendasikan penggunaan autentikasi OAuth user-to-machine (U2M).

Hasilkan token akses:

antarmuka baris perintah (CLI)

databricks auth token --profile my-env

Python

from databricks.sdk.core import Config
config = Config(profile="my-env")
token = config.oauth_token().access_token

Aplikasi eksternal

Untuk akses terprogram dari aplikasi eksternal, gunakan autentikasi prinsipal layanan dengan kredensial antar mesin (M2M). Lihat Otorisasi akses prinsipal layanan ke Azure Databricks dengan OAuth.

Buat perwakilan layanan dan dapatkan ID dan rahasia klien. Lihat Service principals.

Hasilkan token akses menggunakan Databricks SDK:

from databricks.sdk import WorkspaceClient
import requests

# Option 1: Explicit credentials
wc = WorkspaceClient(
    host="https://<workspace-url>",
    client_id="<service-principal-client-id>",
    client_secret="<service-principal-client-secret>"
)

# Option 2: Environment variables
# Set DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET
wc = WorkspaceClient()

# Generate Bearer token
headers = wc.config.authenticate()

Dari aplikasi Databricks lainnya

Saat Anda terhubung dari satu aplikasi Databricks ke aplikasi lain, aplikasi menangani autentikasi secara otomatis menggunakan perwakilan layanan yang ditetapkan.

from databricks.sdk import WorkspaceClient
import requests

# No explicit credentials needed, uses app's service principal
wc = WorkspaceClient()
headers = wc.config.authenticate()

Dari buku catatan Azure Databricks

Untuk memanggil API aplikasi dari buku catatan Azure Databricks, Anda harus menukar token internal notebook dengan token OAuth yang terlingkup audiens, lalu menggunakan token tersebut untuk mengkueri aplikasi.

Dapatkan ID klien OAuth aplikasi. Ambil ID menggunakan SDK Azure Databricks:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
app_client_id = w.apps.get("<app-name>").oauth2_app_client_id

Tukar token notebook untuk token akses dengan cakupan audiens.

import requests

url = "https://<workspace-url>/oidc/v1/token"
notebook_token = (
    dbutils.notebook.entry_point.getDbutils()
    .notebook().getContext().apiToken().get()
)

data = {
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": notebook_token,
    "subject_token_type": "urn:databricks:params:oauth:token-type:personal-access-token",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "all-apis",
    "audience": app_client_id,
}

response = requests.post(url=url, data=data)
audience_token = response.json()["access_token"]

audience_token Gunakan sebagai token Pembawa untuk memanggil aplikasi Anda. Misalnya, lihat Mengirim permintaan ke aplikasi.

Nota

Token yang ditukar dilingkupkan ke aplikasi tertentu, sehingga Anda tidak dapat menggunakannya untuk memanggil API Azure Databricks lainnya. Parameter scope dalam permintaan pertukaran token harus cocok atau menjadi superset dari cakupan yang dikonfigurasi untuk aplikasi dalam otorisasi pengguna.

Tentukan cakupan OAuth untuk otorisasi pengguna

Jika aplikasi Anda menggunakan otorisasi pengguna, token akses Anda harus menyertakan cakupan yang merupakan superset dari cakupan yang dikonfigurasi untuk aplikasi. Jika token tidak memiliki cakupan yang diperlukan, permintaan dapat gagal dengan kesalahan 401 atau 403.

Token yang dihasilkan menggunakan Databricks CLI mencakup all-apis cakupan secara default, yang memenuhi persyaratan otorisasi pengguna untuk aplikasi apa pun:

databricks auth token --profile my-env

Untuk meminta cakupan tertentu alih-alih all-apis, Anda dapat meminta token akses secara manual dengan cakupan eksplisit menggunakan alur OAuth kustom. Misalnya, permintaan berikut secara eksplisit meminta token akses dengan cakupan sql, file.files, dan dashboards.genie.

curl --request POST \
https://<databricks-instance>/oidc/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=authorization_code" \
--data "redirect_uri=<redirect-url>" \
--data "code_verifier=<code-verifier>" \
--data "code=<authorization-code>" \
--data "scope=sql+file.files+dashboards.genie"

Untuk petunjuk lengkap, lihat Membuat token akses OAuth U2M secara manual.

Mengirim permintaan ke aplikasi

Saat Anda memanggil titik akhir API aplikasi, sertakan token Pembawa di header Otorisasi dan ganti <your-endpoint> dengan jalur API aktual aplikasi Anda:

CURL

curl "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>" \
     -H "Authorization: Bearer <YOUR_TOKEN>"

Python dengan permintaan

import requests

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers={"Authorization": f"Bearer {token}"}
)

Python dengan SDK

from databricks.sdk import WorkspaceClient
import requests

wc = WorkspaceClient()
headers = wc.config.authenticate()

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers=headers
)

Pertimbangan keamanan

Saat Anda terhubung ke aplikasi dari lingkungan lokal Anda, ikuti praktik terbaik keamanan berikut:

Jangan pernah menyematkan token akses secara langsung dalam kode sumber Anda. Gunakan variabel lingkungan atau penyimpanan kredensial yang aman.
Perbarui token secara teratur untuk meminimalkan risiko keamanan jika dikompromikan.
Hindari pencatatan token akses atau data sensitif di log aplikasi Anda.

Troubleshooting

Jika Anda mengalami masalah saat menyambungkan ke aplikasi dari komputer lokal, coba solusi ini.

Kegagalan autentikasi (kesalahan 401)

Verifikasi hal berikut:

Token Anda berlaku (jalankan databricks auth token --profile my-env)
Profil Anda dikonfigurasi dengan benar dengan databricks auth login
Token belum kedaluwarsa
Token Anda mencakup cakupan OAuth yang diperlukan. Cakupan token Anda harus menjadi superset dari cakupan yang dikonfigurasi untuk aplikasi dalam otorisasi pengguna.

Izin ditolak (kesalahan 403)

Verifikasi hal berikut:

Anda memiliki izin CAN USE pada aplikasi
Token Anda mencakup cakupan OAuth yang diperlukan. Cakupan yang tidak mencukupi dapat menyebabkan 403 kesalahan bahkan dengan izin yang valid.

Aplikasi tidak ditemukan (kesalahan 404)

Verifikasi hal berikut:

ID dan URL ruang kerja sudah benar
Aplikasi ini disebarkan dan berjalan
Jalur titik akhir ada di aplikasi

Masalah konektivitas jaringan

Verifikasi hal berikut:

Jaringan Anda mengizinkan koneksi HTTPS keluar
Domain *.databricksapps.com dapat diakses dari jaringan Anda

Selain itu, periksa apakah organisasi Anda menggunakan proksi yang memerlukan konfigurasi.

Sumber daya tambahan

Untuk informasi selengkapnya, lihat sumber daya berikut ini:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-11

Menyambungkan ke aplikasi API Databricks menggunakan autentikasi token

Persyaratan

Metode autentikasi

Pengembangan lokal

antarmuka baris perintah (CLI)

Python

Aplikasi eksternal

Dari aplikasi Databricks lainnya

Dari buku catatan Azure Databricks

Tentukan cakupan OAuth untuk otorisasi pengguna

Mengirim permintaan ke aplikasi

CURL

Python dengan permintaan

Python dengan SDK

Pertimbangan keamanan

Troubleshooting

Kegagalan autentikasi (kesalahan 401)

Izin ditolak (kesalahan 403)

Aplikasi tidak ditemukan (kesalahan 404)

Masalah konektivitas jaringan

Sumber daya tambahan

Saran dan Komentar

Sumber Daya Tambahan: