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

この記事では、Azure Databricks によって管理されていない外部サービス データに対してフェデレーション クエリを実行するように Lakehouse Federation を設定する方法について説明します。 レイクハウス フェデレーションの詳細については、「Lakehouse Federation とは」を参照してください。.

Lakehouse フェデレーションを使用して外部サービス データベースに接続するには、Azure Databricks Unity カタログ メタストアで次のコードを作成する必要があります。

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

開始する前に

ワークスペースの要件:

• Unity Catalog を使用できるワークスペース。

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

• コンピューティング リソースからターゲット データベース システムへのネットワーク接続。 「レイクハウス フェデレーションのためのネットワークに関する推奨事項」を参照してください。
• Azure Databricks コンピューティングでは、Databricks Runtime 15.4 LTS 以降と Standard または Dedicated アクセス モードを使用する必要があります。
• SQL ウェアハウスはプロまたはサーバーレスである必要があり、2023.40 以降を使用する必要があります。

必要なアクセス許可:

• 接続を作成するには、メタストア管理者であるか、ワークスペースにアタッチされている Unity カタログメタストアに対する CREATE CONNECTION 権限を持つユーザーである必要があります。
• 外部カタログを作成するには、メタストアに対する CREATE CATALOG 権限を持ち、接続の所有者であるか、接続に対する CREATE FOREIGN CATALOG 特権を持っている必要があります。

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

• 次のいずれかの方法を使用して、外部サービスへの認証を設定します。

  • ベアラー トークン: 単純なトークン ベースの認証用のベアラー トークンを取得します。
  • OAuth 2.0 Machine-to-Machine: コンピューター間認証を有効にするアプリを作成して構成します。
  • OAuth 2.0 User-to-Machine Shared: サービス ID とマシンの間でアクセスを共有するために、ユーザーの操作で認証します。
  • OAuth 2.0 User-to-Machine Per User: ユーザー ID とマシンの間でアクセスするために、ユーザーごとの操作で認証を行います。

外部サービスの認証方法

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

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

OAuth ユーザーからマシンへの共有: OAuth ユーザー間共有認証を使用すると、1 人のユーザー ID が複数のクライアントまたはユーザー間で同じ資格情報セットを認証および共有できます。 すべてのユーザーが同じアクセス トークンを共有します。 このアプローチは、一貫性のあるユーザー ID で十分な共有デバイスまたは環境に適していますが、個々の説明責任と追跡を減らします。 ID ログインが必要な場合は、[ユーザーからマシンへの共有] を選択します。

OAuth ユーザー対マシン、ユーザーごと: OAuth ユーザー対マシン認証では、各ユーザーは自身の資格情報を認証し、それを用いてリソースにアクセスできます。 各ユーザーには一意のアクセス トークンが発行され、個々のアクセス制御、監査、アカウンタビリティが有効になります。 この方法は、ユーザー固有のデータ アクセスが必要な場合や、個々のユーザーに代わって外部サービスにアクセスする場合に適しています。

外部サービスは 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 ワークスペースで、[ カタログ。

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

   または、[クイック アクセス] ページで、[外部データ >] ボタンをクリックし、[接続] タブに移動し、[接続の作成] をクリックします。

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

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

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

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

   • ベアラートークン
   • OAuth マシン対マシン
   • OAuth ユーザー対マシン共有
   • OAuth ユーザーからマシンへのユーザーごと

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

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

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

   OAuth Machine-to-Machine トークンの場合:

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

   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 ユーザー・ツー・マシン・パーユーザー・トークンの場合:

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

   プロパティ	説明
   クライアント ID	作成したアプリケーションの一意の識別子。 OAuth フロー中にクライアント アプリケーションを識別するために承認サーバーによって使用されます。
   クライアント シークレット	作成したアプリケーション用に生成されたシークレットまたはパスワード。 トークンの承認コードを交換するときにクライアント アプリケーションを認証するために使用され、機密を保持する必要があります。[1][5][6]
   OAuth スコープ	ユーザー承認時に付与するスコープ。 アプリケーションが要求するアクセス許可を定義する、スペース区切りの大文字と小文字を区別する文字列の一覧として表されます。 例: channels:read channels:history chat:write
   承認エンドポイント	ユーザー エージェント リダイレクトを使用してリソース所有者を認証し、承認を取得するために使用されるエンドポイント。 通常は次の形式です。 https://authorization-server.com/oauth/authorize クライアントは、ユーザーをこのエンドポイントに誘導してログインし、アクセス許可に同意します。
   トークン エンドポイント	アクセス トークンの承認付与 (承認コードなど) または更新トークンを交換するためにクライアントによって使用されるエンドポイント。 通常は次の形式です。 https://authorization-server.com/oauth/token

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

外部システムに HTTP 要求を送信する

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

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