Menyambungkan ke layanan HTTP eksternal

Penting

Fitur ini ada di Pratinjau Publik.

Koneksi HTTP adalah objek yang dapat diamankan Katalog Unity yang menyimpan titik akhir dan informasi kredensial untuk layanan HTTP eksternal. Gunakan koneksi HTTP untuk mengirim permintaan terautentikasi ke REST API eksternal, server MCP, dan alat agen AI dari Azure Databricks tanpa menyematkan kredensial dalam kode Anda.

Sebelum Anda mulai

Persyaratan ruang kerja:

  • Workspace telah diaktifkan untuk Unity Catalog. Ruang kerja yang dibuat setelah 9 November 2023 aktif untuk Katalog Unity secara otomatis, termasuk penyediaan metastore otomatis. Anda tidak perlu membuat metastore secara manual, kecuali jika ruang kerja Anda dibuat sebelum pengaktifan otomatis dan belum diaktifkan untuk Katalog Unity. Lihat Pengaktifan otomatis untuk Unity Catalog.

Persyaratan komputasi:

  • komputasi Azure Databricks harus menggunakan Databricks Runtime 15.4 LTS atau lebih tinggi dan Standard atau Dedicated mode akses.
  • Gudang SQL harus pro atau tanpa server dan harus menggunakan 2023.40 atau lebih tinggi.

Izin diperlukan:

  • Untuk membuat koneksi, Anda harus menjadi administrator metastore atau pengguna yang memiliki hak istimewa CREATE CONNECTION pada metastore Unity Catalog yang terhubung dengan ruang kerja. Di ruang kerja yang diaktifkan untuk Katalog Unity secara otomatis, admin ruang kerja memiliki CREATE CONNECTION hak istimewa secara default.

Persyaratan izin tambahan dinyatakan di setiap bagian berbasis tugas berikut.

  • Siapkan autentikasi ke layanan eksternal menggunakan salah satu metode berikut:
    • Token pembawa: Dapatkan token pembawa untuk autentikasi berbasis token sederhana.
    • Pendaftaran Klien Dinamis (DCR): Secara otomatis menemukan dan mendaftarkan kredensial OAuth menggunakan protokol RFC 7591 . Setiap pengguna mengautentikasi satu per satu.
    • OAuth 2.0 Machine-to-Machine: Membuat dan mengonfigurasi aplikasi untuk mengaktifkan autentikasi komputer ke komputer.
    • OAuth 2.0 User-to-Machine Shared: Mengautentikasi dengan interaksi pengguna untuk berbagi akses antara identitas layanan dan komputer.
    • OAuth 2.0 User-to-Machine Per User: Mengautentikasi dengan interaksi per pengguna untuk mengakses antara identitas pengguna dan komputer.

Metode autentikasi untuk layanan eksternal

Token pembawa

Token pembawa adalah mekanisme autentikasi berbasis token sederhana di mana token dikeluarkan untuk klien dan digunakan untuk mengakses sumber daya tanpa memerlukan kredensial tambahan. Token disertakan dalam header permintaan dan memberikan akses selama valid.

Mesin-ke-Mesin OAuth

Autentikasi OAuth Machine-to-Machine (M2M) digunakan ketika dua sistem atau aplikasi berkomunikasi tanpa keterlibatan pengguna langsung. Token dikeluarkan untuk klien mesin terdaftar, yang menggunakan kredensialnya sendiri untuk mengautentikasi. Ini sangat ideal untuk komunikasi server-ke-server, layanan mikro, dan tugas otomatisasi di mana tidak ada konteks pengguna yang diperlukan. Databricks merekomendasikan penggunaan OAuth Machine-to-Machine dibandingkan OAuth User-to-Machine Shared ketika tersedia.

OAuth Berbagi Pengguna-ke-Mesin

Autentikasi Bersama Pengguna-ke-Mesin OAuth memungkinkan satu identitas pengguna untuk mengautentikasi dan berbagi serangkaian kredensial yang sama di beberapa klien atau pengguna. Semua pengguna berbagi token akses yang sama. Pendekatan ini cocok untuk perangkat atau lingkungan bersama di mana identitas pengguna yang konsisten cukup, tetapi mengurangi akuntabilitas dan pelacakan individu. Dalam kasus di mana login identitas diperlukan, pilih Berbagi Pengguna-ke-Mesin. Databricks merekomendasikan penggunaan OAuth Machine-to-Machine dibandingkan OAuth User-to-Machine Shared ketika tersedia.

Pendaftaran Klien Dinamis (DCR)

Pendaftaran Klien Dinamis (DCR) menggunakan protokol RFC 7591 untuk menemukan titik akhir OAuth secara otomatis dan mendaftarkan klien dengan layanan eksternal. Anda hanya menyediakan URL host, dan Databricks menangani sisanya — menemukan server otorisasi, mendaftarkan kredensial OAuth, dan mengelola alur persetujuan per pengguna. Setiap pengguna diminta untuk mengotorisasi penggunaan pertama, memungkinkan kontrol akses individual dan akuntabilitas. Layanan eksternal harus mendukung DCR OAuth 2.0 dan mengekspos titik akhir metadata OAuth untuk penemuan otomatis. Metode ini sangat ideal untuk terhubung ke server MCP dan layanan lain yang mendukung standar DCR.

OAuth User-to-Machine Per Pengguna

Autentikasi Pengguna-ke-Mesin OAuth Per Pengguna memungkinkan setiap identitas pengguna untuk mengautentikasi dan menggunakan kredensialnya sendiri untuk mengakses sumber daya. Setiap pengguna mengeluarkan token akses unik, memungkinkan kontrol akses individu, audit, dan akuntabilitas. Metode ini cocok ketika akses data khusus pengguna diperlukan dan saat mengakses layanan eksternal atas nama pengguna individual.

Layanan eksternal harus mematuhi spesifikasi OAuth 2.0

Koneksi HTTP yang menggunakan OAuth harus terhubung ke layanan yang mematuhi spesifikasi OAuth 2.0 resmi tentang cara mereka menangani dan mengembalikan data token akses. Ini berarti bahwa respons layanan harus menggunakan nama bidang dan format data yang tepat yang dijelaskan dalam spesifikasi, seperti , access_token, dan sebagainyaexpires_in.

Jika Anda mengalami masalah saat menyambungkan ke layanan eksternal menggunakan OAuth 2.0, periksa apakah respons layanan mengikuti persyaratan ini.

Membuat koneksi ke layanan eksternal

Pertama, buat koneksi Katalog Unity ke layanan eksternal yang menentukan jalur dan kredensial untuk mengakses layanan.

Manfaat menggunakan koneksi Katalog Unity meliputi yang berikut ini:

  • Manajemen kredensial Aman: Rahasia dan token disimpan dan dikelola dengan aman di Katalog Unity, memastikan mereka tidak pernah terekspos ke pengguna.
  • Kontrol akses Granular: Unity Catalog memungkinkan kontrol terperinci atas siapa yang dapat menggunakan atau mengelola koneksi dengan hak istimewa USE CONNECTION dan MANAGE CONNECTION.
  • Penerapan token khusus Host: Token dibatasi untuk host_name yang ditentukan saat pembuatan koneksi, sehingga memastikan token tersebut tidak dapat digunakan dengan host yang tidak sah.

Izin diperlukan: Admin atau pengguna Metastore dengan CREATE CONNECTION hak istimewa.

Buat koneksi menggunakan salah satu metode berikut:

  • Gunakan UI Penjelajah Katalog.
  • Jalankan perintah CREATE CONNECTION SQL di buku catatan Azure Databricks atau editor kueri Databricks SQL.
  • Gunakan Databricks REST API atau Databricks CLI untuk membuat koneksi. Lihat perintah POST /api/2.1/unity-catalog/connections dan perintah Unity Catalog.

Eksplorer Katalog

Gunakan UI Catalog Explorer untuk membuat koneksi.

  1. Di ruang kerja Azure Databricks Anda, klik Ikon Data.Catalog.

  2. Di bagian atas panel Katalog , klik ikon Tambahkan atau plusTambahkan ikon dan pilih Buat koneksi dari menu.

  3. Klik Buat koneksi.

  4. Masukkan nama Koneksi yang mudah digunakan.

  5. Pilih jenis Koneksi dari HTTP.

  6. Pilih jenis Autentikasi dari opsi berikut:

    • Bearer token
    • Pendaftaran Klien Dinamis
    • OAuth Antarmesin
    • Pengguna OAuth ke Mesin Berbagi
    • Pengguna OAuth ke Mesin Per Pengguna
      • Pilih Konfigurasi Manual untuk memasukkan kredensial OAuth Anda sendiri. Jika Anda menyambungkan ke server MCP eksternal dan ingin Databricks mengelola kredensial OAuth untuk Anda, lihat Alur OAuth Terkelola.
  7. Pada halaman Autentikasi, masukkan properti koneksi berikut untuk koneksi HTTP.

    Properti token pembawa

    Untuk token pembawa:

    Harta benda Deskripsi Contoh nilai
    Tuan rumah URL dasar ruang kerja atau penyebaran Databricks Anda. https://databricks.com
    Pelabuhan Port jaringan yang digunakan untuk koneksi, biasanya 443 untuk HTTPS. 443
    Bearer Token Token autentikasi yang digunakan untuk mengotorisasi permintaan API. bearer-token
    Jalur Dasar Jalur akar untuk titik akhir API. /api/
    Properti Pendaftaran Klien Dinamis

    Untuk Pendaftaran Klien Dinamis:

    Harta benda Deskripsi
    Tuan rumah HTTPS URL dari layanan eksternal. Databricks menggunakan URL ini untuk menemukan server otorisasi OAuth dan mendaftarkan klien secara otomatis.
    Pelabuhan Port jaringan yang digunakan untuk koneksi, biasanya 443 untuk HTTPS.
    Jalur Dasar Jalur akar untuk titik akhir API.
    Cakupan OAuth (Opsional) Cakupan yang akan diberikan selama otorisasi pengguna. Dinyatakan sebagai daftar string yang dibatasi spasi dan peka huruf besar/kecil. Jika dihilangkan, server menentukan cakupan default.
    Properti OAuth Mesin-ke-Mesin

    Untuk OAuth Machine-to-Machine:

    Harta benda Deskripsi
    ID Pelanggan Pengidentifikasi unik untuk aplikasi yang Anda buat.
    Rahasia klien Rahasia atau kata sandi yang dihasilkan untuk aplikasi yang Anda buat.
    Cakupan OAuth Cakupan yang akan diberikan selama otorisasi pengguna. Parameter cakupan dinyatakan sebagai daftar string yang dibatasi spasi dan peka huruf besar/kecil.
    Misalnya: channels:read channels:history chat:write
    Titik akhir token Digunakan oleh klien untuk mendapatkan token akses dengan menggunakan izin otorisasi atau token pembaruan.
    Biasanya dalam format: https://authorization-server.com/oauth/token
    Properti Bersama Pengguna-ke-Komputer OAuth

    Untuk OAuth Pengguna-ke-Mesin yang Dibagikan:

    • Anda akan diminta untuk masuk menggunakan kredensial OAuth Anda. Kredensial yang Anda gunakan akan dibagikan oleh siapa pun yang menggunakan koneksi ini. Beberapa penyedia memerlukan daftar izin untuk URL pengalihan, harap sertakan <databricks_workspace_url>/login/oauth/http.html sebagai daftar izin URL pengalihan. Contoh: https://databricks.com/login/oauth/http.html
    Harta benda Deskripsi
    ID Pelanggan Pengidentifikasi unik untuk aplikasi yang Anda buat.
    Rahasia klien Rahasia atau kata sandi yang dihasilkan untuk aplikasi yang Anda buat.
    Cakupan OAuth Cakupan yang akan diberikan selama otorisasi pengguna. Parameter cakupan dinyatakan sebagai daftar string yang dibatasi spasi dan peka huruf besar/kecil.
    Misalnya: channels:read channels:history chat:write
    Titik akhir otorisasi Digunakan untuk mengautentikasi dengan pemilik sumber daya melalui pengalihan agen pengguna.
    Biasanya dalam format: https://authorization-server.com/oauth/authorize
    Titik akhir token Digunakan oleh klien untuk mendapatkan token akses dengan menggunakan izin otorisasi atau token pembaruan.
    Biasanya dalam format: https://authorization-server.com/oauth/token
    Properti OAuth Pengguna ke Mesin untuk Setiap Pengguna

    Untuk OAuth User-to-Machine Per Pengguna:

    • Setiap pengguna akan diminta untuk masuk menggunakan info masuk OAuth individual mereka saat pertama kali mereka menggunakan koneksi HTTP. Beberapa penyedia memerlukan daftar izin untuk URL pengalihan, harap sertakan <databricks_workspace_url>/login/oauth/http.html sebagai daftar izin URL pengalihan. Contoh: https://databricks.com/login/oauth/http.html
    Harta benda Deskripsi
    ID Pelanggan Pengidentifikasi unik untuk aplikasi yang Anda buat. Digunakan oleh server otorisasi untuk mengidentifikasi aplikasi klien selama alur OAuth.
    Rahasia klien Rahasia atau kata sandi yang dihasilkan untuk aplikasi yang Anda buat. Ini digunakan untuk mengautentikasi aplikasi klien saat bertukar kode otorisasi untuk token dan harus dirahasiakan.
    Cakupan OAuth Cakupan yang akan diberikan selama otorisasi pengguna. Dinyatakan sebagai daftar string yang berbatas spasi dan peka huruf besar/kecil yang menentukan izin yang diminta aplikasi.
    Misalnya: channels:read channels:history chat:write
    Titik akhir otorisasi Endpoint digunakan untuk mengautentikasi pemilik sumber daya melalui pengalihan user-agent dan memperoleh otorisasi.
    Biasanya dalam format: https://authorization-server.com/oauth/authorize
    Klien mengarahkan pengguna ke titik akhir ini untuk masuk dan menyetujui izin.
    Titik akhir token Titik akhir yang digunakan oleh klien untuk bertukar pemberian otorisasi (seperti kode otorisasi) atau token refresh untuk token akses.
    Biasanya dalam format: https://authorization-server.com/oauth/token
    Metode pertukaran kredensial Oauth Penyedia memerlukan metode yang berbeda untuk meneruskan kredensial klien OAuth selama pertukaran token. Pilih salah satu opsi berikut:
    • header_and_body: Menempatkan kredensial di header otorisasi dan isi permintaan (default).
    • body_only: Menempatkan kredensial hanya di dalam tubuh permintaan tanpa header otorisasi.
    • header_only: Menempatkan info masuk hanya di header otorisasi (untuk penyedia seperti OKTA).
  8. Klik Buat koneksi.

SQL

Gunakan perintah CREATE CONNECTION SQL untuk membuat koneksi.

Nota

Anda tidak dapat menggunakan perintah SQL untuk membuat koneksi yang menggunakan OAuth Machine-to-User Shared. Sebagai gantinya, lihat instruksi UI Catalog Explorer.

Untuk membuat koneksi baru menggunakan token pembawa , jalankan perintah berikut di notebook atau editor kueri Databricks SQL:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token '<bearer-token>'
);

Databricks merekomendasikan penggunaan rahasia alih-alih string teks biasa untuk nilai sensitif seperti kredensial. Contohnya:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token secret ('<secret-scope>','<secret-key-password>')
)

Untuk membuat koneksi baru menggunakan OAuth Machine-to-Machine, jalankan perintah berikut ini di notebook atau editor kueri Databricks SQL:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  client_id '<client-id>'
  client_secret '<client-secret>'
  oauth_scope '<oauth-scope1> <oauth-scope-2>'
  token_endpoint '<token-endpoint>'
)

Bagikan koneksi Unity Catalog

Berikan USE CONNECTION hak istimewa kepada prinsip identitas yang perlu menggunakan koneksi:

  1. Di ruang kerja Anda, buka Katalog>Koneksi> Izin > Koneksi Anda.
  2. Berikan identitas akses yang sesuai ke koneksi Unity Catalog.

Meneruskan permintaan melalui proksi koneksi HTTP

Untuk mengirim permintaan ke layanan eksternal, Databricks merekomendasikan penggunaan proksi koneksi HTTP.

Proksi koneksi HTTP Unity Catalog adalah titik akhir HTTP yang dihosting Databricks yang meneruskan permintaan ke layanan eksternal atas nama Anda. Alih-alih mengelola token autentikasi di aplikasi, Anda mengautentikasi dengan Databricks dan membiarkan Databricks menyuntikkan kredensial layanan eksternal dari koneksi Unity Catalog secara otomatis.

Ini paling berguna ketika:

  • Anda perlu memanggil server REST API atau MCP eksternal dari aplikasi yang berjalan di luar Databricks tanpa menyimpan kredensial langsung di aplikasi Anda.
  • Anda ingin Databricks menangani penyimpanan kredensial, refresh token OAuth, dan alur autentikasi per pengguna untuk layanan eksternal.
  • Anda menghubungkan klien MCP (seperti Claude Desktop atau Kursor) ke server MCP eksternal melalui proksi yang dikelola Databricks. Lihat Menggunakan server MCP eksternal.

Izin diperlukan:USE CONNECTION pada objek koneksi.

URL titik akhir proksi

URL titik akhir proksi mengikuti format ini:

https://<workspace-hostname>/api/2.0/unity-catalog/connections/<connection-name>/proxy[/<sub-path>]
Parameter Deskripsi
<connection-name> Nama koneksi HTTP untuk Katalog Unity.
<sub-path> Optional. Segmen jalur ditambahkan setelah koneksi base_path ketika membangun URL yang akan keluar. Hilangkan untuk memanggil URL dasar koneksi secara langsung.

Bagaimana proksi membuat permintaan keluar

Proksi menggabungkan host koneksi dan base_path dengan sub-jalur permintaan untuk membangun URL yang dikirim ke layanan eksternal:

{connection host}{base_path}{sub-path}

Misalnya, jika koneksi Anda dikonfigurasi dengan host https://api.example.com dan jalur dasar /v1, permintaan ke:

POST /api/2.0/unity-catalog/connections/my_connection/proxy/messages

Diteruskan ke:

POST https://api.example.com/v1/messages

Penerusan header

Proksi meneruskan header permintaan Anda ke layanan eksternal dengan aturan berikut:

  • Header yang diblokir: Header Azure Databricks internal (seperti Authorization, Cookie, X-Databricks-*, dan header sesi serupa) dilucuti sebelum diteruskan untuk mencegah kebocoran kredensial Azure Databricks ke layanan eksternal.
  • Semua header lain yang Anda berikan diteruskan tidak berubah ke layanan eksternal. Gunakan ini untuk meneruskan header khusus layanan seperti Content-Type atau kunci API kustom yang diperlukan oleh layanan eksternal.

Badan permintaan

Isi permintaan diteruskan as-is ke layanan eksternal tanpa modifikasi.

Metode HTTP yang didukung

GET, POST, PUT, PATCH, DELETE

Authentication

Anda mengautentikasi dengan titik akhir proksi menggunakan autentikasi Azure Databricks standar (token akses pribadi atau OAuth). Azure Databricks kemudian mengambil kredensial layanan eksternal yang disimpan dalam koneksi Katalog Unity dan memasukkannya ke dalam permintaan keluar. Semua jenis autentikasi koneksi (Token pembawa, OAuth M2M, OAuth U2M Shared, OAuth U2M Per User) didukung. Lihat Metode autentikasi untuk layanan eksternal.

Example

Contoh berikut mengirimkan permintaan POST melalui proksi ke titik akhir API Slack. Token pembawa Slack disimpan dalam slack_connection koneksi Katalog Unity dan tidak pernah disertakan dalam permintaan klien.

curl -X POST \
  "https://<workspace-hostname>/api/2.0/unity-catalog/connections/slack_connection/proxy/chat.postMessage" \
  -H "Authorization: Bearer <databricks-token>" \
  -H "Content-Type: application/json" \
  -d '{"channel": "C123456", "text": "Hello from Databricks!"}'

Jika slack_connection dikonfigurasi dengan host https://slack.com dan jalur dasar /api, permintaan ini diteruskan ke https://slack.com/api/chat.postMessage dengan info masuk Slack yang secara otomatis disuntikkan oleh Azure Databricks.

Mengirim permintaan HTTP menggunakan http_request

Peringatan

http_request tidak digunakan lagi. Gunakan titik akhir proksi koneksi Unity Catalog dengan SDK penyedia untuk kode baru.

Kirim permintaan HTTP ke layanan menggunakan fungsi SQL bawaan http_request .

Izin diperlukan:USE CONNECTION pada objek koneksi.

Jalankan perintah SQL berikut ini di notebook atau editor Databricks SQL. Ganti nilai placeholder ini:

  • connection-name: Objek koneksi yang menentukan kredensial host, port, base_path, dan akses.
  • http-method: Metode permintaan HTTP yang digunakan untuk melakukan panggilan. Misalnya: GET, POST, PUT, DELETE
  • path: Jalur untuk menggabungkan setelah base_path untuk memanggil sumber daya layanan.
  • json: Isi JSON untuk dikirim dengan permintaan.
  • headers: Peta untuk menentukan header permintaan.
SELECT http_request(
  conn => <connection-name>,
  method => <http-method>,
  path => <path>,
  json => to_json(named_struct(
    'text', text
  )),
  headers => map(
    'Accept', "application/vnd.github+json"
  )
);

Nota

Akses SQL dengan http_request diblokir untuk jenis koneksi Pengguna-ke-Mesin Per Pengguna dan Pendaftaran Klien Dinamis. Gunakan Python Databricks SDK sebagai gantinya.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod

WorkspaceClient().serving_endpoints.http_request(
  conn="connection-name",
  method=ExternalFunctionRequestHttpMethod.POST,
  path="/api/v1/resource",
  json={"key": "value"},
  headers={"extra-header-key": "extra-header-value"},
)

Gunakan koneksi HTTP untuk alat agen

Agen AI dapat menggunakan koneksi HTTP untuk mengakses aplikasi eksternal seperti Slack, Google Kalender, atau layanan apa pun dengan API menggunakan permintaan HTTP. Agen dapat menggunakan alat yang terhubung secara eksternal untuk mengotomatiskan tugas, mengirim pesan, dan mengambil data dari platform pihak ketiga.

Lihat Menyambungkan agen ke layanan eksternal.

Mengamankan konektivitas jaringan Anda ke layanan eksternal

Azure Databricks mengalihkan lalu lintas untuk koneksi HTTP melalui lapisan komputasi tanpa server di ruang kerja Anda ke layanan eksternal. Anda dapat mengamankan lalu lintas ini menggunakan Private Link atau daftar IP yang diizinkan.

Private Link menyediakan isolasi penyewa lengkap. Hanya ruang kerja Azure Databricks Anda yang dapat menjangkau layanan Anda melalui koneksi. Lalu lintas melakukan perjalanan melalui koneksi pribadi daripada internet publik. Gunakan Private Link untuk layanan eksternal yang dihosting di dalam jaringan cloud Anda (VPC atau VNet).

Untuk mengonfigurasi Private Link, lihat Konfigurasi konektivitas privat ke sumber daya di VNet. Untuk melihat pola konfigurasi proksi, periksa Pola Konektivitas Private dan Dedicated untuk seri blog Azure Databricks Tanpa Server.

Daftar ip yang diizinkan

Penting

Jika ruang kerja Anda dibuat sebelum Maret 2026, aturan firewall Anda dapat merujuk alamat IP lapisan kontrol alih-alih alamat IP serverless. Anda harus memperbarui daftar yang diizinkan sebelum 30 Mei 2026 untuk menghindari kegagalan konektivitas. Lihat Migrasi ke pengalihan tanpa server untuk koneksi HTTP.

Jika Private Link bukan opsi, konfigurasikan aturan firewall layanan eksternal Anda untuk mengizinkan daftar Azure Databricks IP keluar tanpa server. Dengan daftar IP yang diizinkan, IP keluar dibagikan di seluruh pelanggan Azure Databricks, sehingga pendekatan ini tidak menyediakan isolasi penyewa.

Untuk daftar IP keluar tanpa server, lihat IP Keluar untuk pratinjau firewall komputasi tanpa server.

Nota

Menggunakan koneksi HTTP dapat dikenakan biaya transfer data Azure Databricks. Untuk informasi selengkapnya, lihat Transfer data dan harga konektivitas.