Dış HTTP hizmetlerine bağlanma

HTTP bağlantısı, dış HTTP hizmeti için uç nokta ve kimlik bilgisi bilgilerini depolayan bir Unity Kataloğu güvenliği sağlanabilir nesnesidir. Kodunuza kimlik bilgileri eklemeden dış REST API'lerine, MCP sunucularına ve AI aracısı araçlarına Azure Databricks kimliği doğrulanmış istekler göndermek için HTTP bağlantısı kullanın.

Bölgesel kullanılabilirlik

Unity Kataloğu HTTP bağlantıları yalnızca Model Sunma'nın desteklendiği bölgelerde kullanılabilir. Bkz. Model dağıtım özellikleri kullanılabilirliği.

Başlamadan önce

Çalışma alanı gereksinimleri:

• Unity Kataloğu için etkinleştirilen çalışma alanı. Otomatik meta veri deposu sağlama dahil olmak üzere, 9 Kasım 2023'den sonra oluşturulan çalışma alanları Unity Kataloğu için otomatik olarak etkinleştirilir. Çalışma alanınız otomatik etkinleştirmeden önce gelmediği ve Unity Kataloğu için etkinleştirilmediği sürece el ile meta veri deposu oluşturmanız gerekmez. Bkz. Unity Kataloğu'nu kullanmaya başlama.

İşlem gereksinimleri:

• Azure Databricks işlemci, Databricks Runtime 15.4 LTS veya üzerini ve Standard veya Dedicated erişim modunu kullanmalıdır.
• SQL ambarları profesyonel veya sunucusuz olmalı ve 2023.40 veya üzerini kullanmalıdır.

Gerekli izinler:

• Bağlantı oluşturmak için meta veri deposu yöneticisi veya çalışma alanına bağlı Unity Kataloğu meta veri deposunda CREATE CONNECTION ayrıcalığına sahip bir kullanıcı olmanız gerekir. Unity Kataloğu için otomatik olarak etkinleştirilen çalışma alanlarında, çalışma alanı yöneticileri varsayılan olarak ayrıcalıklara CREATE CONNECTION sahiptir.

Aşağıdaki her görev tabanlı bölümde ek izin gereksinimleri belirtilir.

• Aşağıdaki yöntemlerden birini kullanarak dış hizmette kimlik doğrulamasını ayarlayın:
  • Taşıyıcı belirteci: Basit belirteç tabanlı kimlik doğrulaması için taşıyıcı belirteci alın.
  • Dinamik İstemci Kaydı (DCR):RFC 7591 protokolunu kullanarak OAuth kimlik bilgilerini otomatik olarak bulun ve kaydedin. Her kullanıcı tek tek kimlik doğrulaması yapar.
  • OAuth 2.0 Makineden Makineye: Makineden makineye kimlik doğrulamasını etkinleştirmek için bir uygulama oluşturun ve yapılandırın.
  • OAuth 2.0 Makine ile Kullanıcı Arasında Paylaşılan: Hizmet kimliği ile makine arasında erişim paylaşımını sağlamak için kullanıcı etkileşimi ile kimlik doğrulama yapılır.
  • Kullanıcı Başına OAuth 2.0 Kullanıcıdan Makineye: Kullanıcı kimliği ile makine arasında erişim sağlamak için kullanıcı etkileşimi başına kimlik doğrulaması.

Dış hizmetler için kimlik doğrulama yöntemleri

Dış hizmetler OAuth 2.0 belirtimlerine uygun olmalıdır

OAuth kullanan HTTP bağlantıları, erişim belirteci verilerini nasıl işledikleri ve döndürdikleri için resmi OAuth 2.0 belirtimine uygun hizmetlere bağlanmalıdır. Bu, hizmetin yanıtlarının belirtimde tanımlandığı gibi tam alan adlarını ve veri biçimlerini access_token, expires_in, ve benzeri şekilde kullanması gerektiğini ifade eder.

OAuth 2.0 kullanarak bir dış hizmete bağlanırken sorun yaşıyorsanız hizmetin yanıtlarının bu gereksinimlere uygun olup olmadığını denetleyin.

Yönetilen OAuth sağlayıcıları

Aşağıdaki sağlayıcılar için Azure Databricks arka uçtaki OAuth kimlik bilgilerini yönetir, böylece kendi OAuth uygulamanızı kaydetmezsiniz. Bağlantıyı oluşturduğunuzda, Kullanıcı Başına OAuth Kullanıcıdan Makineye seçeneğini belirleyin ve sağlayıcıyı seçin.

Yönetilen OAuth kullanıyorsanız, gerekirse aşağıdaki yeniden yönlendirme URI'lerini izin verilenler listesine ekleyin:

Dış hizmete bağlantı oluşturma

İlk olarak, hizmete erişmek için bir yol ve kimlik bilgileri belirten dış hizmete bir Unity Kataloğu bağlantısı oluşturun.

Unity Kataloğu bağlantısı kullanmanın avantajları şunlardır:

• Güvenli kimlik yönetimi: Gizli bilgiler ve belirteçler, hiçbir zaman kullanıcılara gösterilmemesi sağlanarak Unity Kataloğu'nda güvenli bir şekilde depolanır ve yönetilir.
• Ayrıntılı erişim denetimi: Unity Kataloğu, USE CONNECTION ve MANAGE ayrıcalıklarıyla bağlantıları kimlerin kullanabileceği veya yönetebileceği üzerinde ayrıntılı denetim sağlar.
• Konağa özgü belirteç zorlaması: Belirteçler, yetkisiz konaklarla kullanılamamaları için bağlantı oluşturma sırasında belirlenen host_name ile kısıtlanır.

Gerekli izinler: Meta veri deposu yöneticisi veya ayrıcalığına CREATE CONNECTION sahip kullanıcı.

Aşağıdaki yöntemlerden birini kullanarak bağlantı oluşturun:

• Katalog Gezgini kullanıcı arabirimini kullanın.
• Azure Databricks not defterinde veya Databricks SQL sorgu düzenleyicisinde CREATE CONNECTION SQL komutunu yürütür.
• Bağlantı oluşturmak için Databricks REST API'sini veya Databricks CLI'yi kullanın. Bkz. POST /api/2.1/unity-catalog/connections ve Unity Catalog komutları.

Katalog Tarayıcısı

Bağlantı oluşturmak için Katalog Gezgini kullanıcı arabirimini kullanın.

1. Azure Databricks çalışma alanınızda Catalog öğesine tıklayın.

2. Katalog bölmesinin üst kısmında tıklayın ve menüden Bağlantı oluştur'u seçin.

3. Bağlantı oluştur'a tıklayın.

4. Kullanıcı dostu birBağlantı adı girin.

5. HTTPBağlantı türü seçin.

6. Aşağıdaki seçeneklerden bir Kimlik Doğrulaması türü seçin:

   • Taşıyıcı belirteci
   • Dinamik İstemci Kaydı
   • OAuth Makineden Makineye
   • OAuth Kullanıcıdan Makineye Paylaşımı
   • Her Kullanıcı İçin Makineye OAuth Kullanıcı İzni
     • Kendi OAuth kimlik bilgilerinizi girmek için El ile Yapılandırma'yı seçin. Bir dış MCP sunucusuna bağlanıyorsanız ve Databricks'in OAuth kimlik bilgilerini sizin yerine yönetmesini istiyorsanız bkz. Yönetilen OAuth sağlayıcıları.

7. Kimlik Doğrulaması sayfasında HTTP bağlantısı için aşağıdaki bağlantı özelliklerini girin.

   Taşıyıcı belirteç özellikleri

   Taşıyıcı belirteci için:

   Mülkiyet	Açıklama	Örnek değer
   Sunucu	Databricks çalışma alanınızın veya dağıtımınızın temel URL'si.	https://databricks.com
   Liman	Bağlantı için kullanılan ağ bağlantı noktası, genellikle 443 HTTPS için.	443
   Taşıyıcı Belirteci	API isteklerini yetkilendirmek için kullanılan kimlik doğrulama belirteci.	bearer-token
   Temel Yol	API uç noktaları için kök yol.	/api/

   Dinamik İstemci Kaydı özellikleri

   Dinamik İstemci Kaydı için:

   Mülkiyet	Açıklama
   Sunucu	Dış hizmetin HTTPS URL'si. Databricks, OAuth yetkilendirme sunucusunu bulmak ve bir istemciyi otomatik olarak kaydetmek için bu URL'yi kullanır.
   Liman	Bağlantı için kullanılan ağ bağlantı noktası, genellikle 443 HTTPS için.
   Temel Yol	API uç noktaları için kök yol.
   OAuth kapsamı	(İsteğe bağlı) Kullanıcı yetkilendirmesi sırasında verilmesi gereken kapsam. Boşlukla ayrılmış, büyük/küçük harfe duyarlı dizelerin listesi olarak ifade edilir. Atlanırsa, sunucu varsayılan kapsamları belirler.

   Makineden Makineye OAuth özellikleri

   OAuth Makineden Makineye:

   Mülkiyet	Açıklama
   Müşteri Kimliği	Oluşturduğunuz uygulamanın benzersiz tanımlayıcısı.
   İstemci sırrı	Oluşturduğunuz uygulama için oluşturulan gizli dizi veya parola.
   OAuth kapsamı	Kullanıcı yetkilendirmesi sırasında verilmesi gereken kapsam. Kapsam parametresi, boşlukla ayrılmış, büyük/küçük harfe duyarlı dizelerin listesi olarak ifade edilir. Örneğin: channels:read channels:history chat:write
   Belirteç uç noktası	İstemci tarafından yetkilendirme verme veya yenileme belirtecini sunarak erişim belirteci almak için kullanılır. Genellikle şu biçimdedir: https://authorization-server.com/oauth/token

   OAuth Kullanıcıdan Makineye Paylaşılan özellikler

   OAuth Kullanıcıdan Makineye Paylaşılan için:

   • OAuth kimlik bilgilerinizi kullanarak oturum açmanız istenir. Kullandığınız kimlik bilgileri bu bağlantıyı kullanan herkes tarafından paylaşılır. Bazı sağlayıcılar, yeniden yönlendirme URL'si için izin listesi gerektirir, lütfen <databricks_workspace_url>/login/oauth/http.html adresini izin listesi olarak ekleyin. Örnek: https://databricks.com/login/oauth/http.html

   Mülkiyet	Açıklama
   Müşteri Kimliği	Oluşturduğunuz uygulamanın benzersiz tanımlayıcısı.
   İstemci sırrı	Oluşturduğunuz uygulama için oluşturulan gizli dizi veya parola.
   OAuth kapsamı	Kullanıcı yetkilendirmesi sırasında verilmesi gereken kapsam. Kapsam parametresi, boşlukla ayrılmış, büyük/küçük harfe duyarlı dizelerin listesi olarak ifade edilir. Örneğin: channels:read channels:history chat:write
   Yetkilendirme uç noktası	Kullanıcı aracısını yeniden yönlendirerek kaynak sahibiyle kimlik doğrulaması yapmak için kullanılır. Genellikle şu biçimdedir: https://authorization-server.com/oauth/authorize
   Belirteç uç noktası	İstemci tarafından yetkilendirme verme veya yenileme belirtecini sunarak erişim belirteci almak için kullanılır. Genellikle şu biçimdedir: https://authorization-server.com/oauth/token

   Kullanıcı Başına Kullanıcıdan Makineye OAuth özellikleri

   Kullanıcı Başına OAuth Kullanıcıdan Makineye:

   • Her kullanıcıdan, HTTP bağlantısını ilk kez kullandığında tek tek OAuth kimlik bilgilerini kullanarak oturum açması istenir. Bazı sağlayıcılar, yeniden yönlendirme URL'si için izin listesi gerektirir, lütfen <databricks_workspace_url>/login/oauth/http.html adresini izin listesi olarak ekleyin. Örnek: https://databricks.com/login/oauth/http.html

   Mülkiyet	Açıklama
   Müşteri Kimliği	Oluşturduğunuz uygulamanın benzersiz tanımlayıcısı. OAuth akışı sırasında istemci uygulamasını tanımlamak için yetkilendirme sunucusu tarafından kullanılır.
   İstemci sırrı	Oluşturduğunuz uygulama için oluşturulan gizli dizi veya parola. Belirteçler için yetkilendirme kodları alışverişi yapılırken istemci uygulamasının kimliğini doğrulamak için kullanılır ve gizli tutulması gerekir.
   OAuth kapsamı	Kullanıcı yetkilendirmesi sırasında verilmesi gereken kapsam. Uygulamanın istediği izinleri tanımlayan, boşlukla ayrılmış, büyük/küçük harfe duyarlı dizelerin listesi olarak ifade edilir. Örneğin: channels:read channels:history chat:write
   Yetkilendirme uç noktası	Kullanıcı aracısı yeniden yönlendirmesi yoluyla kaynak sahibinin kimliğini doğrulamak ve yetkilendirmeyi almak için kullanılan uç nokta. Genellikle şu biçimdedir: https://authorization-server.com/oauth/authorize İstemci, oturum açmak ve izinlere onay vermek için kullanıcıyı bu uç noktaya yönlendirir.
   Belirteç uç noktası	İstemci tarafından bir yetkilendirme izni belgesini (örneğin, yetkilendirme kodu) veya yenileme belirtecini bir erişim belirteciyle değiştirmek için kullanılan uç nokta. Genellikle şu biçimdedir: https://authorization-server.com/oauth/token
   Oauth kimlik bilgisi değişim yöntemi	Sağlayıcılar, belirteç değişimi sırasında OAuth istemci kimlik bilgilerini geçirmek için farklı yöntemler gerektirir. Aşağıdaki seçeneklerden birini belirleyin: header_and_body: Kimlik bilgilerini hem yetkilendirme üst bilgisine hem de istek gövdesine (varsayılan) yerleştirir. body_only: Kimlik bilgilerini yalnızca yetkilendirme üst bilgisi olmayan istek gövdesine yerleştirir. header_only: Kimlik bilgilerini yalnızca yetkilendirme üst bilgisine (OKTA gibi sağlayıcılar için) yerleştirir.

8. Bağlantı oluştur'a tıklayın.

SQL

Bağlantı oluşturmak için CREATE CONNECTION SQL komutunu kullanın.

Taşıyıcı belirtecikullanarak yeni bir bağlantı oluşturmak için bir not defterinde veya Databricks SQL sorgu düzenleyicisinde aşağıdaki komutu çalıştırın:

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

Databricks, kimlik bilgileri gibi hassas değerler için düz metin dizeleri yerine gizli dizi kullanılmasını önerir. Örneğin:

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

OAuth Machine-to-Machine kullanarak yeni bir bağlantı oluşturmak için bir not defterinde veya Databricks SQL sorgu düzenleyicisinde aşağıdaki komutu çalıştırın:

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>'
)

Unity Kataloğu bağlantısını paylaşma

Bağlantıyı kullanması gereken kimlik sorumlularına ayrıcalıklar verin USE CONNECTION :

1. Çalışma alanınızda Katalog>Bağlantılar>>İzinler'e gidin.
2. Kimliklere Unity Kataloğu bağlantısına uygun erişim verin.

İstekleri HTTP bağlantı vekil sunucusu aracılığıyla iletme

Databricks, bir dış hizmete istek göndermek için HTTP bağlantı ara sunucusunun kullanılmasını önerir.

Unity Kataloğu HTTP bağlantı proxy'si, istekleri sizin adınıza dış hizmetlere ileten Databricks tarafından barındırılan bir HTTP uç noktasıdır. Uygulamanızda kimlik doğrulama belirteçlerini yönetmek yerine Databricks ile kimlik doğrulaması yaparsınız ve Databricks'in Unity Kataloğu bağlantısından dış hizmet kimlik bilgilerini otomatik olarak eklemesine izin verirsiniz.

Bu en çok aşağıdaki durumlarda kullanışlıdır:

• Kimlik bilgilerini doğrudan uygulamanızda depolamadan Databricks dışında çalışan bir uygulamadan dış REST API'yi veya MCP sunucusunu çağırmanız gerekir.
• Databricks'in dış hizmetler için kimlik bilgisi depolama, OAuth belirteci yenileme ve kullanıcı başına kimlik doğrulama akışlarını işlemesini istiyorsunuz.
• Bir MCP istemcisini (Claude Desktop veya İmleç gibi) Databricks tarafından yönetilen bir ara sunucu aracılığıyla bir dış MCP sunucusuna bağlıyorsunuz. Bkz . Dış MCP sunucularını kullanma.

İzinler gereklidir: Bağlantı nesnesindeUSE CONNECTION.

Proxy uç noktası URL'si

Ara sunucu uç noktası URL'si şu biçimi izler:

https://<workspace-hostname>/api/2.0/unity-catalog/connections/<connection-name>/proxy[/<sub-path>]

Ara sunucu giden isteği nasıl oluşturur?

Ara sunucu, dış hizmete gönderilen URL'yi oluşturmak için bağlantının ana bilgisayarını ve base_path istek alt yolunu birleştirir:

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

Örneğin, bağlantınız konak https://api.example.com ve temel yol /v1ile yapılandırılmışsa, şu istek:

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

İletilen yer:

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

Başlık yönlendirme

Proxy, istek üst bilgilerinizi aşağıdaki kurallarla dış hizmete iletir:

• Blocked headers: İç Azure Databricks üst bilgileri (Authorization, Cookie, X-Databricks-* ve benzer oturum üst bilgileri gibi) dış hizmetlere Azure Databricks kimlik bilgilerinin sızmasını önlemek için iletilemeden önce kaldırılır.
• Sağladığınız diğer tüm üst bilgiler, dış hizmete değiştirilmeden iletilir. Örneğin Content-Type veya dış hizmet tarafından gereken özel API anahtarları gibi hizmete özgü üst bilgileri geçirmek için bunu kullanın.

İstek içeriği

Talep gövdesi, değişiklik yapılmadan olduğu gibi dış hizmete iletilir.

Desteklenen HTTP yöntemleri

GET, POST, PUT, PATCH, , DELETE

Kimlik Doğrulaması

Standart Azure Databricks kimlik doğrulamasını (kişisel erişim belirteci veya OAuth) kullanarak proxy uç noktasıyla kimlik doğrulaması yaparsınız. Azure Databricks unity kataloğu bağlantısında depolanan dış hizmet kimlik bilgilerini alır ve bunları giden isteğe ekler. Tüm bağlantı kimlik doğrulama türleri (Taşıyıcı belirteci, OAuth M2M, OAuth U2M Paylaşılan, Kullanıcı Başına OAuth U2M) desteklenir. Bkz. Dış hizmetler için kimlik doğrulama yöntemleri.

Example

Aşağıdaki örnek, ara sunucu aracılığıyla slack API uç noktasına bir POST isteği gönderir. Slack taşıyıcı belirteci Unity Kataloğu bağlantısında slack_connection depolanır ve hiçbir zaman istemci isteğine dahil değildir.

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!"}'

slack_connection konak https://slack.com ve temel yol /api ile yapılandırılmışsa, bu istek Azure Databricks tarafından otomatik olarak eklenen Slack kimlik bilgileriyle https://slack.com/api/chat.postMessage iletilir.

http_request kullanarak bir HTTP isteği gönderin

Yerleşik SQL işlevini kullanarak http_request hizmete HTTP istekleri gönderin.

İzinler gereklidir: Bağlantı nesnesindeUSE CONNECTION.

Aşağıdaki SQL komutunu bir not defterinde veya Databricks SQL düzenleyicisinde çalıştırın. Yer tutucu değerlerini değiştirin:

• connection-name: Ana makineyi, bağlantı noktasını, temel yolu ve erişim kimlik bilgilerini belirten bağlantı nesnesi.
• http-method: Çağrıyı yapmak için kullanılan HTTP istek yöntemi. Örneğin: GET, POST, PUT, DELETE
• path: Hizmet kaynağını çağırmak için base_path sonrası birleştirme yolu.
• json: İstekle birlikte gönderilecek JSON gövdesi.
• headers: İstek üst bilgilerini belirtmek için bir harita.

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"
  )
);

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"},
)

Aracı araçları için HTTP bağlantılarını kullanma

Yapay zeka aracıları HTTP bağlantısını kullanarak Slack, Google Takvim gibi dış uygulamalara veya HTTP isteklerini kullanarak API'ye sahip herhangi bir hizmete erişebilir. Aracılar görevleri otomatikleştirmek, ileti göndermek ve üçüncü taraf platformlardan veri almak için dışarıdan bağlı araçları kullanabilir.

Bkz. MCP Hizmetleri ile aracıları üçüncü taraf araçlara bağlama.

Dış hizmetlere ağ bağlantınızın güvenliğini sağlama

Azure Databricks, çalışma alanınızın sunucusuz işlem düzlemi aracılığıyla HTTP bağlantıları için trafiği dış hizmetlere yönlendirir. Özel Bağlantı veya IP izin verilenler listesini kullanarak bu trafiğin güvenliğini sağlayabilirsiniz.

Özel Bağlantı (önerilir)

Özel Bağlantı tam kiracı yalıtımı sağlar. Bağlantı üzerinden hizmetinize yalnızca Azure Databricks çalışma alanınız erişebilir. Trafik, genel İnternet yerine özel bir bağlantı üzerinden hareket eder. Bulut ağınızda (VPC veya VNet) barındırılan dış hizmetler için Özel Bağlantı kullanın.

Özel Bağlantı yapılandırmak için bkz. Sanal ağınızdaki kaynaklara özel bağlantı yapılandırma. Proxy kurulum desenleri için Azure Databricks Sunucusuz blog serisi için Private ve Ayrılmış Bağlantı Desenleri konusuna bakın.

IP izin listesi

Özel Bağlantı bir seçenek değilse, dış hizmetinizin güvenlik duvarı kurallarını sunucusuz Azure Databricks giden IP'lerini izin verilenler listesine ekleyecek şekilde yapılandırın. IP izin listesi oluşturma ile giden IP'ler Azure Databricks müşterileri arasında paylaşılmaktadır, bu nedenle bu yaklaşım kiracı izolasyonu sağlamaz.

Sunucusuz çıkış IP'leri ve bunların izin listesine nasıl alınacağına ilişkin yönergeler için bkz. Azure kaynakları için Azure ağ güvenlik çevresini (NSP) yapılandırın.

Sınırlamalar

• İşlev http_request hız sınırına sahiptir. Yüksek hacimli toplu iş sorguları için değil, etkileşimli ve aracı tabanlı kullanım örnekleri için tasarlanmıştır. http_request öğesini tek bir sorguda çok sayıda satırda çalıştırırsanız, istekler kısıtlanabilir ve hatalara neden olabilir. Bu sorunu geçici olarak çözmek için Python için Databricks SDK'sını kullanarak istekleri aralarında gecikmeler olan daha küçük toplu işlemler halinde gönderin. Databricks, yeni kod için yerine sağlayıcının SDK'sıyla http_request kullanılmasını önerir.