Подключение к внешним службам HTTP

Это важно

Эта функция доступна в общедоступной предварительной версии.

HTTP-подключение — это защищаемый объект каталога Unity, в который хранятся сведения о конечной точке и учетных данных для внешней службы HTTP. Используйте HTTP-подключение для отправки прошедших проверку подлинности запросов внешним ИНТЕРФЕЙСАм REST API, серверам MCP и средствам агента искусственного интеллекта из Azure Databricks без внедрения учетных данных в код.

Доступность по регионам

HTTP-подключения каталога Unity доступны только в регионах, где поддерживается обслуживание моделей. См. сведения о доступности функций обслуживания моделей.

Перед тем как начать

Требования к рабочей области:

Рабочая область активирована для Unity Catalog. Рабочие области, созданные после 9 ноября 2023 г., автоматически включены для каталога Unity, включая автоматическую подготовку хранилища метаданных. Вам не нужно создавать хранилище метаданных вручную, если ваша рабочая область была создана до автоматического включения и не была включена для Unity Catalog. См. статью "Начало работы с каталогом Unity".

Требования к вычислениям:

Azure Databricks вычисления должны использовать Databricks Runtime 15.4 LTS или более поздней версии и Standard или Dedicated режим доступа.
Хранилища SQL должны быть профессиональными или бессерверными и должны использовать 2023.40 или более поздней версии.

Необходимые разрешения:

Чтобы создать подключение, необходимо быть администратором хранилища метаданных или пользователем с правами CREATE CONNECTION в хранилище метаданных каталога Unity, подключенном к рабочей области. В рабочих областях, автоматически включённых в каталог Unity, администраторы рабочих областей по умолчанию имеют CREATE CONNECTION привилегии.

Дополнительные требования к разрешениям указываются в каждом последующем разделе, посвящённом задачам.

Настройте проверку подлинности во внешней службе с помощью одного из следующих методов:
- Токен носителя: получение токена для простой аутентификации на основе токенов.
- Динамическая регистрация клиентов (DCR): автоматически обнаруживайте и регистрируйте учетные данные OAuth с помощью протокола RFC 7591 . Каждый пользователь выполняет проверку подлинности по отдельности.
- OAuth 2.0 Машина-к-машине: создание и настройка приложения для обеспечения аутентификации машина-к-машине.
- OAuth 2.0 — совместный доступ пользователя и машины: Аутентификация с участием пользователя для совместного доступа между служебным идентификатором и машиной.
- OAuth 2.0 "Пользователь—машина" для каждого пользователя: аутентификация с индивидуальным взаимодействием пользователя для обеспечения доступа между идентификацией пользователя и компьютером.

Методы проверки подлинности для внешних служб

Маркер носителя

Маркер доступа — это простой механизм аутентификации, основанный на использовании маркера, который выдается клиенту и служит для доступа к ресурсам без необходимости предоставления дополнительных учетных данных. Маркер включен в заголовок запроса и предоставляет доступ до тех пор, пока он действителен.

OAuth для межмашинного взаимодействия

Проверка подлинности OAuth machine-to-Machine (M2M) используется, когда две системы или приложения взаимодействуют без прямого участия пользователей. Токены выдаются зарегистрированному клиенту машины, который использует собственные учетные данные для аутентификации. Это идеально подходит для обмена данными между серверами, микрослужбами и задачами автоматизации, в которых не требуется контекст пользователя. Databricks рекомендует использовать OAuth Machine-to-Machine,если он доступен по протоколу OAuth User-to-Machine Shared.

Общий доступ пользователей к компьютеру OAuth

Общая проверка подлинности OAuth между компьютерами позволяет одному удостоверению пользователя проходить проверку подлинности и предоставлять общий доступ к одному набору учетных данных для нескольких клиентов или пользователей. Все пользователи используют один и тот же маркер доступа. Этот подход подходит для общих устройств или сред, где достаточно согласованного удостоверения пользователя, но снижает индивидуальную подотчетность и отслеживание. В случаях, когда требуется идентификационный вход, выберите общий доступ пользователь-машина. Databricks рекомендует использовать OAuth Machine-to-Machine,если он доступен по протоколу OAuth User-to-Machine Shared.

Динамическая регистрация клиента (DCR)

Динамическая регистрация клиентов (DCR) использует протокол RFC 7591 для автоматического обнаружения конечных точек OAuth и регистрации клиента во внешней службе. Вы предоставляете только URL-адрес узла, а Databricks обрабатывает остальные данные— обнаружение сервера авторизации, регистрация учетных данных OAuth и управление потоками согласия для каждого пользователя. Каждому пользователю предлагается идентифицироваться при первом использовании, что позволяет управлять индивидуальным доступом и обеспечивать подотчетность. Внешняя служба должна поддерживать DCR OAuth 2.0 и предоставлять конечные точки метаданных OAuth для автоматического обнаружения. Этот метод идеально подходит для подключения к серверам MCP и другим службам, поддерживающим стандарт DCR.

OAuth "Пользователь — компьютер" на пользователя

Проверка подлинности OAuth на компьютер для каждого пользователя позволяет каждому удостоверению пользователя проходить проверку подлинности и использовать собственные учетные данные для доступа к ресурсам. Каждому пользователю выдается уникальный токен доступа, что обеспечивает индивидуальное управление доступом, аудитом и подотчетностью. Этот метод подходит, если требуется доступ к данным конкретного пользователя, а также при доступе к внешним службам от имени отдельного пользователя.

Внешние службы должны соответствовать спецификациям OAuth 2.0

HTTP-подключения, использующие OAuth, должны подключаться к службам, которые соответствуют официальной спецификации OAuth 2.0 о том, как они обрабатывают и возвращают данные маркера доступа. Это означает, что ответы службы должны использовать точные имена полей и форматы данных, описанные в спецификации, например access_token, expires_inи т. д.

Если у вас возникли проблемы с подключением к внешней службе с помощью OAuth 2.0, убедитесь, что ответы службы соответствуют этим требованиям.

Создание подключения к внешней службе

Сначала создайте подключение каталога Unity к внешней службе, указывающее путь и учетные данные для доступа к службе.

Преимущества использования подключения каталога Unity:

Безопасное управление учетными данными: Секреты и маркеры безопасно хранятся и управляются в каталоге Unity, гарантируя, что они никогда не предоставляются пользователям.
Детальный контроль доступа: Каталог Unity позволяет точно контролировать, кто может использовать или управлять подключениями с USE CONNECTION правами и MANAGE CONNECTION привилегиями.
Принудительное применение маркеров для конкретного узла: Маркеры ограничиваются host_name указанным узлом при создании подключения, гарантируя, что они не могут использоваться с несанкционированными хостами.

Необходимые разрешения: администратор хранилища метаданных или пользователь с привилегиями CREATE CONNECTION .

Создайте подключение с помощью одного из следующих методов:

Используйте пользовательский интерфейс обозревателя каталогов.
Выполните команду CREATE CONNECTION SQL в записной книжке Azure Databricks или редакторе запросов Databricks SQL.
Используйте REST API Databricks или интерфейс командной строки Databricks для создания подключения. См. POST /api/2.1/unity-catalog/connections и команды каталога Unity .

Обозреватель каталогов

Используйте пользовательский интерфейс обозревателя каталогов для создания подключения.

В рабочей области Azure Databricks щелкните Catalog.
В верхней части области каталога щелкните " и выберите "Создать подключение" в меню.
Нажмите Create connection (Создать подключение).
Введите понятное имя подключения.
Выберите тип подключенияHTTP.
Выберите тип проверки подлинности из следующих параметров:
- Маркер носителя
- Динамическая регистрация клиента
- Компьютер OAuth на компьютер
- Общий доступ пользователя OAuth к компьютеру
- OAuth: доступ пользователя к машине для каждого пользователя
  - Выберите ручную конфигурацию , чтобы ввести собственные учетные данные OAuth. Если вы подключаетесь к внешнему серверу MCP и хотите, чтобы Databricks управляли учетными данными OAuth для вас, см. раздел "Управляемые потоки OAuth".

На странице проверки подлинности введите следующие свойства подключения для HTTP-подключения.

Свойства маркера носителя

Для маркера носителя:

Недвижимость	Описание	Пример значения
Хост	Базовый URL-адрес рабочего пространства или развертывания Databricks.	`https://databricks.com`
Порт	Сетевой порт, используемый для подключения, обычно `443` для HTTPS.	`443`
Маркер носителя	Маркер проверки подлинности, используемый для авторизации запросов API.	`bearer-token`
Базовый путь	Корневой путь для конечных точек API.	`/api/`

Свойства динамической регистрации клиентов

Для динамической регистрации клиентов:

Недвижимость	Описание
Хост	URL-адрес HTTPS внешней службы. Databricks использует этот URL-адрес для обнаружения сервера авторизации OAuth и автоматической регистрации клиента.
Порт	Сетевой порт, используемый для подключения, обычно `443` для HTTPS.
Базовый путь	Корневой путь для конечных точек API.
Область действия OAuth	(Необязательно) Область доступа при авторизации пользователя. Представлено в виде списка строк, разделенных пробелами, с учетом регистра. Если опущен, сервер определяет области по умолчанию.

Свойства OAuth Machine-to-Machine

Для OAuth Machine-to-Machine:

Недвижимость	Описание
идентификатор клиента	Уникальный идентификатор созданного приложения.
Секрет клиента	Секрет или пароль, созданные для созданного приложения.
Область действия OAuth	Область разрешений во время авторизации пользователя. Параметр scope выражается в виде списка строк, разделенных пробелами и учитывающих регистр. Например: `channels:read channels:history chat:write`
Конечная точка токена	Используется клиентом для получения токена доступа путем предоставления своего авторизационного гранта или токена обновления. Обычно в формате: `https://authorization-server.com/oauth/token`

Общие свойства OAuth "Пользователь — компьютер"

Для общего доступа пользователей к компьютеру OAuth:

Вам будет предложено войти с помощью учетных данных OAuth. Используемые учетные данные будут предоставляться всем пользователям, использующим это подключение. Некоторые поставщики требуют список разрешённых URL-адресов для перенаправления, пожалуйста, включите <databricks_workspace_url>/login/oauth/http.html в этот список. Пример: https://databricks.com/login/oauth/http.html

Недвижимость	Описание
идентификатор клиента	Уникальный идентификатор созданного приложения.
Секрет клиента	Секрет или пароль, созданные для созданного приложения.
Область действия OAuth	Область разрешений во время авторизации пользователя. Параметр scope выражается в виде списка строк, разделенных пробелами и учитывающих регистр. Например: `channels:read channels:history chat:write`
Конечная точка авторизации	Используется для аутентификации владельца ресурса через перенаправление агента пользователя. Обычно в формате: `https://authorization-server.com/oauth/authorize`
Конечная точка токена	Используется клиентом для получения токена доступа путем предоставления своего авторизационного гранта или токена обновления. Обычно в формате: `https://authorization-server.com/oauth/token`

Свойства OAuth "Пользователь — компьютер" для каждого пользователя

Для OAuth аутентификации пользователь-машина для каждого пользователя:

Каждому пользователю будет предложено войти с помощью отдельных учетных данных OAuth при первом использовании HTTP-подключения. Некоторые поставщики требуют список разрешённых URL-адресов для перенаправления, пожалуйста, включите <databricks_workspace_url>/login/oauth/http.html в этот список. Пример: https://databricks.com/login/oauth/http.html

Недвижимость	Описание
идентификатор клиента	Уникальный идентификатор созданного приложения. Используется сервером авторизации для идентификации клиентского приложения во время потока OAuth.
Секрет клиента	Секрет или пароль, созданные для созданного приложения. Он используется для проверки подлинности клиентского приложения при обмене кодами авторизации на токены и должен быть конфиденциальным.
Область действия OAuth	Область разрешений во время авторизации пользователя. Выражен в виде списка строк, разделённых пробелами, чувствительных к регистру, определяющих разрешения, которые запрашивает приложение. Например: `channels:read channels:history chat:write`
Конечная точка авторизации	Конечная точка, используемая для аутентификации владельца ресурса через перенаправление через пользовательский агент и получения авторизации. Обычно в формате: `https://authorization-server.com/oauth/authorize` Клиент направляет пользователя в эту конечную точку для входа и предоставления согласия на разрешения.
Конечная точка токена	Конечная точка, используемая клиентом для обмена разрешением на авторизацию (например, кодом авторизации) или токеном обновления на токен доступа. Обычно в формате: `https://authorization-server.com/oauth/token`
Метод обмена учетными данными Oauth	Поставщики требуют различных методов передачи учетных данных клиента OAuth во время обмена маркерами. Выберите один из следующих параметров: header_and_body. Помещает учетные данные в заголовок авторизации и текст запроса (по умолчанию). body_only. Помещает учетные данные только в текст запроса без заголовка авторизации. header_only. Помещает учетные данные только в заголовок авторизации (для поставщиков, таких как OKTA).

Нажмите Create connection (Создать подключение).

SQL

CREATE CONNECTION Используйте команду SQL для создания подключения.

Замечание

Вы не можете использовать команду SQL для создания подключения, использующего общий доступ к компьютеру OAuth для пользователей. Вместо этого см. инструкции по пользовательскому интерфейсу обозревателя каталогов.

Чтобы создать новое подключение с помощью маркера носителя, выполните следующую команду в записной книжке или редакторе sql-запросов Databricks:

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

Databricks рекомендует использовать секреты вместо строк открытого текста для конфиденциальных значений, таких как учетные данные. Рассмотрим пример.

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, выполните следующую команду в записной книжке или редакторе SQL-запросов Databricks.

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

Предоставьте USE CONNECTION привилегии субъектам идентификационных данных, которым необходимо использовать подключение.

В рабочей области перейдите к Каталогу>Подключения> Ваши разрешения >подключений.
Предоставьте удостоверениям соответствующий доступ к подключению каталога Unity.

Переадресация запросов через прокси-сервер http-подключения

Чтобы отправить запрос во внешнюю службу, Databricks рекомендует использовать прокси-сервер HTTP-подключения.

Прокси-сервер http-подключения каталога Unity — это конечная точка HTTP, размещенная в Databricks, которая пересылает запросы на внешние службы от вашего имени. Вместо управления токенами аутентификации в приложении вы авторизуетесь в Databricks, а Databricks позволяет автоматически внедрять учетные данные внешней службы из подключения Unity Catalog.

Это наиболее полезно, когда:

Необходимо вызвать внешний REST API или сервер MCP из приложения, работающего вне Databricks, без хранения учетных данных непосредственно в приложении.
Требуется, чтобы Databricks обрабатывал хранение учетных данных, обновление токенов OAuth и шаги аутентификации для каждого пользователя при работе с внешними службами.
Вы подключаете клиент MCP (например, Claude Desktop или Cursor) к внешнему серверу MCP с помощью управляемого прокси-сервера Databricks. См. статью "Использование внешних серверов MCP".

Необходимые разрешения:USE CONNECTION на объект подключения.

URL-адрес конечной точки прокси-сервера

URL-адрес конечной точки прокси-сервера соответствует этому формату:

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

Параметр	Описание
`<connection-name>`	Имя HTTP-подключения каталога Unity.
`<sub-path>`	Необязательно. Сегмент пути, добавленный после `base_path` подключения при создании URL-адреса для исходящего соединения. Не следует вызывать базовый URL-адрес подключения напрямую.

Как прокси-сервер создает исходящий запрос

Прокси-сервер объединяет узел подключения и подпуть запроса base_path, чтобы создать URL-адрес, отправляемый внешней службе.

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

Например, если подключение настроено с помощью узла https://api.example.com и базового пути /v1, запрос на:

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

Пересылается в:

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

Переадресация заголовков

Прокси-сервер перенаправит заголовки запроса во внешнюю службу со следующими правилами:

Блокированные заголовки: внутренние заголовки Azure Databricks (например, Authorization/>, Cookie, X-Databricks-* и аналогичные заголовки сеансов) удаляются перед пересылкой, чтобы предотвратить утечку учетных данных Azure Databricks во внешние службы.
Все остальные предоставленные заголовки перенаправляются без изменений во внешнюю службу. Используйте это для передачи заголовков для конкретной службы, таких как Content-Type или пользовательские ключи API, необходимые внешней службой.

Текст запроса

Текст запроса пересылается as-is внешней службе без изменений.

Поддерживаемые методы HTTP

GET, POST, , PUT, PATCHDELETE

Аутентификация

Вы проходите аутентификацию через прокси-точку, используя стандартные методы аутентификации Azure Databricks (личный токен доступа или OAuth). Azure Databricks затем извлекает учетные данные внешней службы, хранящиеся в подключении каталога Unity, и внедряет их в исходящий запрос. Поддерживаются все типы проверки подлинности подключения (токен Bearer, OAuth M2M, общий OAuth U2M, индивидуальный OAuth U2M на пользователя). См. сведения о методах проверки подлинности для внешних служб.

Пример

В следующем примере запрос POST отправляется через прокси-сервер в конечную точку API Slack. Токен доступа Slack хранится в соединении каталога Unity и никогда не передается в запросе клиента.

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 настроен с помощью узла https://slack.com и базового пути /api, этот запрос пересылается в https://slack.com/api/chat.postMessage с учетными данными Slack, автоматически введенными Azure Databricks.

Отправка HTTP-запроса с помощью `http_request`

Предупреждение

http_request не рекомендуется к использованию. Используйте Unity Catalog connections proxy endpoint с пакетом SDK от поставщика для нового кода.

Отправьте HTTP-запросы в службу с помощью встроенной http_request функции SQL.

Необходимые разрешения:USE CONNECTION на объект подключения.

Выполните следующую SQL-команду в записной книжке или в SQL-редакторе Databricks. Замените значения по умолчанию:

connection-name: объект подключения , указывающий узел, порт, base_path и учетные данные для доступа.
http-method: метод HTTP-запроса, используемый для вызова. Например: GET, , POSTPUTDELETE
path: путь, который нужно сцепить после base_path, чтобы вызвать ресурс службы.
json: текст JSON для отправки с запросом.
headers: карта для указания заголовков запроса.

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

Замечание

Доступ к SQL с помощью http_request заблокирован для типов подключений "Пользователь-компьютер для каждого пользователя" и "Динамическая регистрация клиентов". Вместо этого используйте пакет SDK Python Databricks.

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

Использование HTTP-подключений для средств агента

Агенты ИИ могут использовать HTTP-подключение для доступа к внешним приложениям, таким как Slack, Google Calendar или любой службе с API с помощью HTTP-запросов. Агенты могут использовать внешние средства для автоматизации задач, отправки сообщений и получения данных с сторонних платформ.

См. статью "Подключение агентов к внешним службам".

Защита сетевого подключения к внешним службам

Azure Databricks маршрутизирует трафик для HTTP-подключений через бессерверный вычислительный уровень рабочей области во внешние службы. Этот трафик можно защитить с помощью Приватный канал или списка разрешенных IP-адресов.

Приватный канал (рекомендуется)

Приватный канал обеспечивает полную изоляцию клиента. Только ваша Azure Databricks рабочая область может связаться со службой через подключение. Трафик перемещается через частное подключение, а не через общедоступный Интернет. Используйте Приватный канал для внешних служб, размещенных в облачной сети (VPC или виртуальной сети).

Сведения о настройке Приватный канал см. в статье Настройка частного подключения к ресурсам в виртуальной сети. Шаблоны настройки прокси-сервера см. в серии блогов о беспроводных и выделенных шаблонах подключения для Azure Databricks.

Разрешенный список IP-адресов

Это важно

Если рабочая область была создана до марта 2026 года, правила брандмауэра могут ссылаться на IP-адреса контрольной плоскости вместо бессерверных IP-адресов. Чтобы избежать сбоев подключения, необходимо обновить списки разрешений до 30 мая 2026 г. См. раздел "Миграция на бессерверную маршрутизацию" для HTTP-подключений.

Если Приватный канал не является вариантом, настройте правила брандмауэра внешней службы для включения в список разрешённых бессерверных исходящих IP-адресов Azure Databricks. При использовании списка разрешенных IP-адресов исходящие IP-адреса совместно используются для Azure Databricks клиентов, поэтому этот подход не обеспечивает изоляцию клиента.

Список бессерверных исходящих IP-адресов см. в разделе Исходящие IP-адреса для предварительной версии брандмауэра бессерверных вычислений.

Замечание

Использование HTTP-подключений может повлечь за собой плату за передачу данных в Azure Databricks. Дополнительные сведения см. в разделе о ценах на передачу данных и подключение.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-05-20

Подключение к внешним службам HTTP

Доступность по регионам

Перед тем как начать

Методы проверки подлинности для внешних служб

Внешние службы должны соответствовать спецификациям OAuth 2.0

Создание подключения к внешней службе

Обозреватель каталогов

SQL

Обмен подключением к каталогу Unity

Переадресация запросов через прокси-сервер http-подключения

URL-адрес конечной точки прокси-сервера

Как прокси-сервер создает исходящий запрос

Переадресация заголовков

Текст запроса

Поддерживаемые методы HTTP

Аутентификация

Пример

Отправка HTTP-запроса с помощью http_request

Использование HTTP-подключений для средств агента

Защита сетевого подключения к внешним службам

Приватный канал (рекомендуется)

Разрешенный список IP-адресов

Обратная связь

Дополнительные ресурсы

Отправка HTTP-запроса с помощью `http_request`