外部 HTTP サービスに接続する

HTTP 接続は、外部 HTTP サービスのエンドポイントと資格情報を格納する Unity カタログセキュリティ保護可能なオブジェクトです。 HTTP 接続を使用して、認証された要求をコードに埋め込まずに、Azure Databricksから外部 REST API、MCP サーバー、AI エージェント ツールに送信します。

開始する前に

ワークスペースの要件:

• Unity Catalog を使用できるワークスペース。 2023 年 11 月 9 日以降に作成されたワークスペースは、自動メタストア プロビジョニングを含め、Unity カタログに対して自動的に有効になります。 ワークスペースが自動有効化の前にあり、Unity カタログに対して有効になっていない場合を除き、メタストアを手動で作成する必要はありません。 「Unity Catalog の自動有効化」を参照してください。

コンピューティング要件:

• Azure Databricksコンピューティングでは、Databricks Runtime 15.4 LTS 以降と Standard または Dedicated アクセス モードを使用する必要があります。
• SQL ウェアハウスはプロまたはサーバーレスである必要があり、2023.40 以降を使用する必要があります。

必要なアクセス許可:

• 接続を作成するには、メタストア管理者であるか、ワークスペースにアタッチされている Unity カタログメタストアに対する CREATE CONNECTION 権限を持つユーザーである必要があります。 Unity カタログが自動的に有効になっているワークスペースでは、ワークスペース管理者は既定で CREATE CONNECTION 特権を持っています。

追加の権限要件は、以下の各タスク ベースのセクションで規定されています。

• 次のいずれかの方法を使用して、外部サービスへの認証を設定します。
  • ベアラー トークン: 単純なトークン ベースの認証用のベアラー トークンを取得します。
  • 動的クライアント登録 (DCR):RFC 7591 プロトコルを使用して OAuth 資格情報を自動的に検出して登録します。 各ユーザーは個別に認証します。
  • OAuth 2.0 Machine-to-Machine: コンピューター間認証を有効にするアプリを作成して構成します。
  • OAuth 2.0 User-to-Machine Shared: サービス ID とマシンの間でアクセスを共有するために、ユーザーの操作で認証します。
  • OAuth 2.0 User-to-Machine Per User: ユーザー ID とマシンの間でアクセスするために、ユーザーごとの操作で認証を行います。

外部サービスの認証方法

外部サービスは OAuth 2.0 仕様に準拠している必要があります

OAuth を使用する HTTP 接続では、 OAuth 2.0 の公式仕様に準拠したサービスに接続して、アクセス トークン データの処理方法と返し方法を確認する必要があります。 つまり、サービスの応答では、 access_token、 expires_inなど、仕様で説明されている正確なフィールド名とデータ形式を使用する必要があります。

OAuth 2.0 を使用した外部サービスへの接続で問題が発生した場合は、サービスの応答が次の要件に従っていることを確認してください。

外部サービスへの接続を作成する

まず、サービスにアクセスするためのパスと資格情報を指定する外部サービスへの Unity カタログ接続を作成します。

Unity カタログ接続を使用する利点は次のとおりです。

• セキュリティで保護された資格情報の管理: シークレットとトークンは Unity カタログに安全に格納および管理され、ユーザーに公開されないようにします。
• 詳細なアクセス制御: Unity カタログを使用すると、USE CONNECTION と MANAGE CONNECTION の特権で接続を使用または管理できるユーザーをきめ細かく制御できます。
• ホスト固有のトークンの適用: トークンは、接続の作成時に指定された host_name に制限され、承認されていないホストで使用できないようにします。

必要な権限: メタストア管理者、または CREATE CONNECTION 特権を持つユーザー。

次のいずれかの方法を使用して接続を作成します。

• カタログ エクスプローラー UI を使用します。
• Azure Databricks ノートブックまたは Databricks SQL クエリ エディターで、CREATE CONNECTION SQL コマンドを実行します。
• 接続を作成するには、Databricks REST API または Databricks CLI を使用します。 POST /api/2.1/unity-catalog/connections および Unity Catalog コマンドを参照してください。

カタログ エクスプローラー

カタログ エクスプローラー UI を使用して接続を作成します。

1. Azure Databricks ワークスペースで、Catalog をクリックします。

2. [カタログ] ウィンドウの上部にある の [追加] アイコンをクリックし、メニューから [接続の作成] を選択します。

3. [接続の作成] をクリックします。

4. わかりやすい接続名を入力します。

5. HTTPの 接続の種類 を選択します。

6. 次のオプションから 認証の種類 を選択します。

   • ベアラートークン
   • 動的クライアント登録
   • OAuth マシン対マシン
   • OAuth ユーザーからマシン共有へ
   • OAuth ユーザーからマシンへ (ユーザーごと)
     • 独自の OAuth 資格情報を入力するには、[ 手動構成] を選択します。 外部 MCP サーバーに接続していて、Databricks で OAuth 資格情報を管理する場合は、「 マネージド OAuth フロー」を参照してください。

7. [認証] ページで、HTTP 接続の次の接続プロパティを入力します。

   ベアラー トークンのプロパティ

   ベアラー トークンの場合:

   プロパティ	説明	値の例
   ホスト	Databricks ワークスペースまたはデプロイのベース URL。	https://databricks.com
   ポート	接続に使用されるネットワーク ポート (通常は HTTPS 用に 443 )。	443
   ベアラー トークン	API 要求の承認に使用される認証トークン。	bearer-token
   ベース パス	API エンドポイントのルート パス。	/api/

   動的クライアント登録プロパティ

   動的クライアント登録の場合:

   プロパティ	説明
   ホスト	外部サービスの HTTPS URL。 Databricks では、この URL を使用して OAuth 承認サーバーを検出し、クライアントを自動的に登録します。
   ポート	接続に使用されるネットワーク ポート (通常は HTTPS 用に 443 )。
   ベース パス	API エンドポイントのルート パス。
   OAuth の範囲	(省略可能)ユーザー承認時に付与するスコープ。 スペースで区切られた、大文字と小文字を区別する必要がある文字列の一覧として表されます。 省略すると、サーバーによって既定のスコープが決定されます。

   OAuth Machine-to-Machine プロパティ

   マシン対マシンのOAuthについて:

   プロパティ	説明
   クライアント ID	作成したアプリケーションの一意の識別子。
   クライアント シークレット	作成したアプリケーション用に生成されたシークレットまたはパスワード。
   OAuth の範囲	ユーザー承認時に付与するスコープ。 スコープ パラメーターは、スペースで区切られた大文字と小文字を区別する文字列の一覧として表されます。 例: channels:read channels:history chat:write
   トークン エンドポイント	承認許可または更新トークンを提示してアクセス トークンを取得するためにクライアントによって使用されます。 通常は次の形式です。 https://authorization-server.com/oauth/token

   OAuth ユーザーからマシンへの共有プロパティ

   OAuth ユーザーからマシンへの共有の場合:

   • OAuth 資格情報を使用してサインインするように求められます。 使用する資格情報は、この接続を使用するすべてのユーザーによって共有されます。 一部のプロバイダーでは、リダイレクト URL の許可リストが必要です。リダイレクト URL の許可リストとして <databricks_workspace_url>/login/oauth/http.html を含めてください。 例: https://databricks.com/login/oauth/http.html

   プロパティ	説明
   クライアント ID	作成したアプリケーションの一意の識別子。
   クライアント シークレット	作成したアプリケーション用に生成されたシークレットまたはパスワード。
   OAuth の範囲	ユーザー承認時に付与するスコープ。 スコープ パラメーターは、スペースで区切られた大文字と小文字を区別する文字列の一覧として表されます。 例: channels:read channels:history chat:write
   承認エンドポイント	ユーザーエージェントのリダイレクトを通じてリソース所有者を認証するために使用されます。 通常は次の形式です。 https://authorization-server.com/oauth/authorize
   トークン エンドポイント	承認許可または更新トークンを提示してアクセス トークンを取得するためにクライアントによって使用されます。 通常は次の形式です。 https://authorization-server.com/oauth/token

   OAuth ユーザーとマシンのユーザーごとのプロパティ

   ユーザーあたりの OAuth ユーザー対マシンの場合:

   • 各ユーザーは、HTTP 接続を初めて使用する際に、個々の OAuth 資格情報を使用してサインインするように求められます。 一部のプロバイダーでは、リダイレクト URL の許可リストが必要です。リダイレクト URL の許可リストとして <databricks_workspace_url>/login/oauth/http.html を含めてください。 例: https://databricks.com/login/oauth/http.html

   プロパティ	説明
   クライアント ID	作成したアプリケーションの一意の識別子。 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 などのプロバイダーの場合)。

8. [接続の作成] をクリックします。

SQL

CREATE CONNECTION SQL コマンドを使用して接続を作成します。

ベアラー トークンを使用して新しい接続を作成するには、ノートブックまたは Databricks SQL クエリ エディターで次のコマンドを実行します。

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 を使用して新しい接続を作成するには、ノートブックまたは 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>'
)

Unity カタログ接続を共有する

接続 USE CONNECTION 使用する必要がある ID プリンシパルに特権を付与します。

1. ワークスペースで、[ Catalog>Connections> Your connection >Permissions] に移動します。
2. Unity カタログ接続への適切なアクセス権を ID に付与します。

HTTP 接続プロキシ経由で要求を転送する

外部サービスに要求を送信するために、Databricks では HTTP 接続プロキシを使用することをお勧めします。

Unity カタログ HTTP 接続プロキシは、Databricks でホストされる HTTP エンドポイントであり、ユーザーに代わって外部サービスに要求を転送します。 アプリケーションで認証トークンを管理する代わりに、Databricks で認証し、Databricks が Unity カタログ接続から外部サービス資格情報を自動的に挿入できるようにします。

これは、次の場合に最も役立ちます。

• 資格情報をアプリに直接格納せずに、Databricks の外部で実行されているアプリケーションから外部 REST API または MCP サーバーを呼び出す必要があります。
• Databricks で、外部サービスの資格情報ストレージ、OAuth トークン更新、およびユーザーごとの認証フローを処理する必要があります。
• Databricks で管理されるプロキシを使用して、MCP クライアント (Claude Desktop や Cursor など) を外部 MCP サーバーに接続しています。 外部 MCP サーバーの使用を参照してください。

接続オブジェクトにUSE CONNECTION のアクセス許可が必要です。

プロキシ エンドポイント URL

プロキシ エンドポイント URL は、次の形式に従います。

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

プロキシが送信要求を構築する方法

プロキシは、接続のホストと 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

ヘッダー転送

プロキシは、次の規則を使用して、要求ヘッダーを外部サービスに転送します。

• Blocked ヘッダー: Azure Databricksの内部ヘッダー (Authorization、Cookie、X-Databricks-*、および同様のセッションヘッダーなど) は、Azure Databricksの資格情報を外部サービスに漏洩しないように転送前に削除されます。
• 指定した他のすべてのヘッダー は、変更されずに外部サービスに転送されます。 これを使用して、外部サービスに必要な Content-Type やカスタム API キーなどのサービス固有のヘッダーを渡します。

リクエスト本文

要求本文は、変更せずに外部サービスに as-is 転送されます。

サポートされている HTTP メソッド

GET、POST、PUT、PATCH、DELETE

認証

プロキシ エンドポイントで認証するには、標準のAzure Databricks認証 (個人用アクセス トークンまたは OAuth) を使用します。 Azure Databricks Unity カタログ接続に格納されている外部サービス資格情報を取得し、送信要求に挿入します。 すべての接続認証の種類 (ベアラー トークン、OAuth M2M、OAuth U2M Shared、OAuth U2M Per User) がサポートされています。 外部サービスの認証方法を参照してください。

例

次の例では、プロキシを介して Slack API エンドポイントに POST 要求を送信します。 Slack ベアラー トークンは、 slack_connection 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 で構成されている場合、この要求は、Azure Databricksによって自動的に挿入された Slack 資格情報を使用して https://slack.com/api/chat.postMessage に転送されます。

を使用して HTTP 要求を送信する http_request

http_request組み込み SQL 関数を使用して、サービスに HTTP 要求を送信します。

接続オブジェクトにUSE CONNECTION のアクセス許可が必要です。

ノートブックまたは Databricks SQL エディターで次の SQL コマンドを実行します。 プレースホルダー値を次のように置き換えます。

• connection-name: ホスト、ポート、base_path、およびアクセス資格情報を指定する 接続オブジェクト。
• http-method: 呼び出しを行うために使用される HTTP 要求メソッド。 例: GET、POST、PUT、DELETE
• 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"
  )
);

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 接続を使用する

AI エージェントは、HTTP 接続を使用して、Slack、Google カレンダー、または HTTP 要求を使用する API を使用して任意のサービスなどの外部アプリケーションにアクセスできます。 エージェントは、外部に接続されたツールを使用して、タスクの自動化、メッセージの送信、サードパーティプラットフォームからのデータの取得を行うことができます。

「エージェントを外部サービスに接続する」を参照してください。

外部サービスへのネットワーク接続をセキュリティで保護する

Azure Databricksは、ワークスペースのサーバーレス コンピューティング プレーンを介して HTTP 接続のトラフィックを外部サービスにルーティングします。 このトラフィックは、Private Linkまたは IP 許可リストを使用してセキュリティで保護できます。

Private Link (推奨)

Private Linkは、完全なテナント分離を提供します。 接続を介してサービスに到達できるのは、Azure Databricks ワークスペースだけです。 トラフィックは、パブリック インターネットではなくプライベート接続経由で移動します。 クラウド ネットワーク (VPC または VNet) 内でホストされている外部サービスに対してPrivate Linkを使用します。

Private Linkを構成するには、「 VNet 内のリソースへのプライベート接続を構成するを参照してください。 プロキシのセットアップ パターンについては、プライベートおよび専用の接続パターンを解説した Azure Databricks サーバーレスのブログ シリーズを参照してください。

IP 許可リスト

Private Linkが利用できない場合は、外部サービスのファイアウォールルールを構成して、Azure Databricksのサーバーレスの送信元IPアドレスを許可リストに追加します。 IP 許可リストでは、送信 IP はAzure Databricksの顧客間で共有されるため、このアプローチではテナントの分離は提供されません。

サーバーレス送信 IP の一覧については、 サーバーレス コンピューティング ファイアウォールプレビューの送信 IP を参照してください。