メインコンテンツまでスキップ
に最終更新

外部 HTTP サービスへの接続

備考

プレビュー

この機能は パブリック プレビュー段階です。

このページでは、 Databricks管理されていない外部サービスデータに対して横串検索を実行するためのレイクハウスフェデレーションの設定方法について説明します。 レイクハウスフェデレーションの詳細については、「 レイクハウスフェデレーションとは」を参照してください。

レイクハウスフェデレーションを使用して外部サービス データベースに接続するには、 Databricks Unity Catalogメタストアに次のものを作成する必要があります (2024 年 3 月 6 日以降に作成されたワークスペースには、すでにUnity Catalogメタストア プロビジョニングが自動的に作成されています)。

  • 外部サービス データベースへの接続。
  • 外部サービス・データベースを にミラーリングする フォーリンカタログ Unity Catalog Unity CatalogDatabricks。これにより、 クエリ構文とデータガバナンス・ツールを使用して、データベースへの ・ユーザー・アクセスを管理できます。

始める前に​

ワークスペースの要件：

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

コンピュートの要件：

  • コンピュート・リソースからターゲット・データベース・システムへのネットワーク接続。 レイクハウスフェデレーションのネットワーキングに関する推奨事項を参照してください。
  • Databricks コンピュートは、 Databricks Runtime 15.4 の 15.4 LTS 以上、 および標準 または 専用 アクセスモードを使用する必要があります。
  • SQLウェアハウスはProまたはServerlessで、2023.40以上を使用している必要があります。

必要な権限：

  • 接続を作成するには、メタストア管理者であるか、ワークスペースにアタッチされた Unity Catalog メタストアに対するCREATE CONNECTION権限を持つユーザーである必要があります。Unity Catalogが自動的に有効になったワークスペースでは、ワークスペース管理者は無事にCREATE CONNECTION権限を持ちます。
  • フォーリンカタログを作成するには、メタストアに対するCREATE CATALOG権限があり、接続の所有者であるか、接続に対するCREATE FOREIGN CATALOG権限を持っている必要があります。 Unity Catalogに対して自動的に有効になったワークスペースでは、ワークスペース管理者は無事にCREATE CATALOG権限を持っています。

追加の権限要件は、以下の各タスクベースのセクションに記載しています。

  • 次のいずれかの方法を使用して、外部サービスへの認証を設定します。
    • ベアラートークン :単純なトークンベースの認証のためにベアラートークンを取得します。
    • OAuth 2.0 Machine-to-Machine : マシン間認証を有効にするアプリを作成して構成します。
    • OAuth 2.0 User-to-Machine Shared : ユーザー操作で認証し、サービス ID とマシン間でアクセスを共有します。
    • OAuth 2.0 User-to-Machine Per User : ユーザーIDとマシン間のアクセスに、ユーザーごとのインタラクションで認証します。

外部サービスの認証方法​

Bearerトークン

ベアラー トークンは、トークンがクライアントに発行され、追加の資格情報を必要とせずにリソースにアクセスするために使用される、シンプルなトークン ベースの認証メカニズムです。トークンはリクエスト ヘッダーに含まれており、有効である限りアクセスを許可します。

OAuth マシンツーマシン

OAuth マシンツーマシン (M2M) 認証は、2 つのシステムまたはアプリケーションがユーザーの直接の関与なしに通信する場合に使用されます。トークンは登録済みのマシン クライアントに発行され、独自の資格情報を使用して認証されます。これは、ユーザー コンテキストが不要なサーバー間通信、マイクロサービス、自動化タスクに最適です。Databricks では、OAuth User-to-Machine Shared よりも OAuth Machine-to-Machine が利用可能な場合は、OAuth Machine-to-Machine を使用することをお勧めします。

OAuth ユーザーとマシンの共有

OAuth ユーザー対マシン共有認証により、単一のユーザー ID で複数のクライアントまたはユーザー間で同じ資格情報セットを認証および共有できます。すべてのユーザーは同じアクセス権を共有します。 このアプローチは、一貫したユーザー ID で十分な共有デバイスや環境に適していますが、個々の説明責任と追跡は減少します。ID ログインが必要な場合は、「ユーザーとマシンの共有」を選択します。Databricks では、OAuth User-to-Machine Shared よりも OAuth Machine-to-Machine が利用可能な場合は、OAuth Machine-to-Machine を使用することをお勧めします。

OAuth ユーザー対マシン（ユーザーごと）

OAuth ユーザー対マシンのユーザーごとの認証により、各ユーザー ID が認証され、独自の資格情報を使用してリソースにアクセスできます。各ユーザーには固有のアクセス許可が発行され、個別のアクセス制御、監査、説明責任が可能になります。 この方法は、ユーザー固有のデータ アクセスが必要な場合や、個々のユーザーに代わって外部サービスにアクセスする場合に適しています。

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

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

OAuth 2.0 を使用して外部サービスに接続する際に問題が発生した場合は、サービスのレスポンスがこれらの要件に従っていることを確認してください。

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

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

Unity Catalog接続を使用する利点は次のとおりです。

  • 安全な認証情報管理: シークレットとトークンは Unity Catalog に安全に保管され、管理されるため、ユーザーに公開されることはありません。
  • きめ細かなアクセス制御: Unity Catalog では、 USE CONNECTION と MANAGE CONNECTION の特権を使用して、接続を使用または管理できるユーザーをきめ細かく制御できます。
  • ホスト固有のトークンの強制: トークンは、接続の作成時に指定された host_name に制限されるため、承認されていないホストでは使用できません。

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

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

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

  1. Databricks ワークスペースで、データアイコン。 カタログ をクリックします。

  2. カタログ パネルの上部にある追加またはプラスアイコンアイコン を追加し 、メニューから 接続の作成を 選択します。

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

  4. ユーザーフレンドリーな 接続名 を入力します。

  5. 接続タイプ で HTTP を選択します。

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

    • Bearerトークン
    • OAuthによるマシン間通信
    • マシンに共有されたOAuthユーザー
    • OAuthユーザーからマシンへの接続（ユーザーごと）
      • 独自の OAuth 資格情報を入力するには、 「手動構成」 を選択します。外部の MCP サーバーに接続し、Databricks で OAuth 資格情報を管理したい場合は、 「マネージド OAuth フロー」を参照してください。

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

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

Bearerトークンの場合:

Property

Description

Example value

Host

The base URL of your Databricks workspace or deployment.

https://databricks.com

Port

The network port used for the connection, typically 443 for HTTPS.

443

Bearer Token

The authentication token used to authorize API requests.

bearer-token

Base Path

The root path for API endpoints.

/api/

OAuth マシンツーマシンのプロパティ

OAuth マシンツーマシンの場合:

Property

Description

Client ID

Unique identifier for the application you created.

Client secret

Secret or password generated for the application that you created.

OAuth scope

Scope to grant during user authorization. The scope parameter is expressed as a list of space-delimited, case-sensitive strings. For example: channels:read channels:history chat:write

Token endpoint

Used by the client to obtain an access token by presenting its authorization grant or refresh token. Usually in the format: 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

Property

Description

Client ID

Unique identifier for the application you created.

Client secret

Secret or password generated for the application that you created.

OAuth scope

Scope to grant during user authorization. The scope parameter is expressed as a list of space-delimited, case-sensitive strings. For example: channels:read channels:history chat:write

Authorization endpoint

Used to authenticate with the resource owner via user-agent redirection. Usually in the format: https://authorization-server.com/oauth/authorize

Token endpoint

Used by the client to obtain an access token by presenting its authorization grant or refresh token. Usually in the format: 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

Property

Description

Client ID

Unique identifier for the application you created. Used by the authorization server to identify the client application during the OAuth flow.

Client secret

Secret or password generated for the application that you created. It is used to authenticate the client application when exchanging authorization codes for tokens and must be kept confidential.

OAuth scope

Scope to grant during user authorization. Expressed as a list of space-delimited, case-sensitive strings defining the permissions the application requests. For example: channels:read channels:history chat:write

Authorization endpoint

Endpoint used to authenticate the resource owner via user-agent redirection and obtain authorization. Usually in the format: https://authorization-server.com/oauth/authorize The client directs the user to this endpoint to log in and consent to permissions.

Token endpoint

Endpoint used by the client to exchange an authorization grant (such as an authorization code) or refresh token for an access token. Usually in the format: https://authorization-server.com/oauth/token

Oauth credential exchange method

Providers require different methods for passing OAuth client credentials during token exchange. Select one of the following options:

  • header_and_body: Places credentials in both the authorization header and request body (default).
  • body_only: Places credentials only in the request body without an authorization header.
  • header_only: Places credentials only in the authorization header (for providers like OKTA).
  1. 接続の作成 をクリックします。

Unity Catalog接続を共有する​

接続を使用する必要があるアイデンティティ プリンシパルにUSE CONNECTION権限を付与します。

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

HTTP接続プロキシ経由でリクエストを転送する​

外部サービスにリクエストを送信する場合、DatabricksはHTTP接続プロキシの使用を推奨しています。

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

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

  • 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>]

パラメーター

説明

<connection-name>

Unity CatalogのHTTP接続名。

<sub-path>

任意。送信URLを構築する際に、接続のbase_pathの後に追加されるパスセグメント。接続のベース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

ヘッダー転送​

プロキシは、以下のルールに従ってリクエストヘッダーを外部サービスに転送します。

  • ブロックされたヘッダー : Databricks の内部ヘッダー ( Authorization 、 Cookie 、 X-Databricks-*などのセッションヘッダー) は、Databricks の認証情報が外部サービスに漏洩するのを防ぐため、転送前に削除されます。
  • お客様が指定した その他のヘッダーはすべて 、変更されずに外部サービスに転送されます。これを使用して、 Content-Typeなどのサービス固有のヘッダーや、外部サービスが必要とするカスタム API キーを渡します。

リクエストボディ​

リクエスト本文は、変更されることなくそのまま外部サービスに転送されます。

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

GET、POST、PUT、PATCH、 DELETE

認証​

プロキシエンドポイントへの認証には、標準のDatabricks認証（パーソナルアクセストークンまたはOAuth）を使用します。Databricks 、 Unity Catalog接続に保存されている外部サービス認証情報を取得し、送信リクエストに挿入します。 すべての接続認証タイプ（ベアラートークン、OAuth M2M、OAuth U2M共有、OAuth U2Mユーザーごと）がサポートされています。外部サービスの認証方法を参照してください。

例​

以下の例では、プロキシ経由でSlack APIエンドポイントにPOSTリクエストを送信します。Slackベアラー はslack_connection Unity Catalog接続に保存され、クライアントリクエストには含まれません。

Bash
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で構成されている場合、このリクエストは Databricks によって自動的に挿入された Slack 認証情報とともにhttps://slack.com/api/chat.postMessageに転送されます。

HTTPリクエストを送信するには、 http_request​

警告

http_request 非推奨です。新しいコードを作成する場合は、プロバイダーのSDKとUnity Catalog接続プロキシエンドポイントを組み合わせて使用してください。

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: リクエストヘッダーを指定するマップ。
SQL
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"
  )
);
注記

http_request による SQL アクセスは、ユーザー間接続タイプが [ユーザーごとマシンごと] でブロックされます。代わりに、Python Databricks SDK を使用してください。

Python
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を使用する任意のサービスなどの外部アプリケーションにアクセスできます。エージェントは、外部に接続されたツールを使用して、タスクの自動化、メッセージの送信、およびサードパーティプラットフォームからのデータの取得を行うことができます。

エージェントを外部サービスに接続する方法については、こちらをご覧ください。

制限​

  • Private Service Connect を使用したVPC内のリソースへのプライベート接続は、HTTP 接続ではサポートされていません。 この機能が必要な場合は、サポート チームにお問い合わせください。