外部 HTTP サービスへの接続

備考

プレビュー

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

レイクハウスフェデレーションを使用して外部サービスデータベースに接続するには、 Databricks Unity Catalog メタストアに次のものを作成する必要があります。

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

始める前に

ワークスペースの要件：

Unity Catalogのワークスペースが有効になっています。

コンピュートの要件：

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

必要な権限：

接続を作成するには、メタストア管理者か、ワークスペースに接続されているUnity Catalogメタストアの 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とマシン間のアクセスに、ユーザーごとのインタラクションで認証します。

外部サービスの認証方法

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

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

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

ユーザーごとの OAuth ユーザー間: OAuth ユーザー間 Per User 認証により、各ユーザー 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 を使用します。
CREATE CONNECTION SQL コマンドは、Databricks ノートブックまたは Databricks SQL クエリエディターで実行します。
Databricks REST API または Databricks CLI を使用して接続を作成します。POST /api/2.1/unity-catalog/connections を参照してください。および Unity Catalog コマンド。

Catalog Explorer
SQL

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

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

または、 クイックアクセス ページから 外部データ > ボタンをクリックし、接続タブに移動して 接続を作成 をクリックします。
接続の作成 をクリックします。
ユーザーフレンドリーな 接続名 を入力します。
接続タイプ で HTTP を選択します。
次のオプションから 認証タイプ を選択します。
- Bearerトークン
- OAuthによるマシン間通信
- マシンに共有されたOAuthユーザー
- OAuthユーザーからマシンへの接続（ユーザーごと）
認証ページで、HTTP 接続の次の接続プロパティを入力します。

Bearerトークンの場合:

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

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

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

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

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

属性	説明
クライアントID	作成したアプリケーションの一意の識別子。
クライアントのシークレット	作成したアプリケーションに対して生成されたシークレットまたはパスワード。
OAuthスコープ	ユーザー認証中に付与するスコープ。scope パラメーターは、スペース区切りで大文字と小文字が区別される文字列のリストとして表されます。例えば： `channels:read channels:history chat:write`
認証エンドポイント	ユーザーエージェントリダイレクトを介してリソース所有者と認証するために使用されます。通常、次の形式になります。 `https://authorization-server.com/oauth/authorize`
トークンのエンドポイント	クライアントが承認グラントまたは更新トークンを提示してアクセストークンを取得するために使用されます。通常、次の形式になります。 `https://authorization-server.com/oauth/token`

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

各ユーザーは、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`

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

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

注記

SQL コマンドを使用して、 OAuth Machine-to-User Shared を使用する接続を作成することはできません。代わりに、カタログエクスプローラの UI の手順を参照してください。

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

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

Databricks では、資格情報などの機密性の高い値には、プレーンテキスト文字列の代わりにシークレットを使用することをお勧めします。例えば：

SQL
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 クエリエディターで次のコマンドを実行します。

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

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

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

始める前に​

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

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

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

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

エージェント ツールに HTTP 接続を使用する​