外部 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
権限を持っている必要があります。
追加の権限要件は、以下の各タスクベースのセクションに記載しています。
-
次のいずれかの方法を使用して、外部サービスへの認証を設定します。
- Bearerトークン:単純なトークンベースの認証のためにベアラートークンを取得します。
- OAuth 2.0 Machine-to-Machine: マシン間認証を有効にするアプリを作成して構成します。
- OAuth 2.0 User-to-Machine Shared: ユーザー操作で認証し、サービス 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] を選択します。
外部サービスへの接続を作成する
まず、外部サービスへの 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ユーザー
-
認証 ページで、HTTP 接続の次の接続プロパティを入力します。
Bearerトークンの場合:
- ホスト : たとえば、
https://databricks.com
- ポート : たとえば、
443
- Bearerトークン :たとえば、
bearer-token
- ベースパス : たとえば、
/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 トークンの場合:
-
クライアント 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 Shared の場合、OAuth 資格情報を使用して HTTP でサインインするように求められます。
- 接続の作成 をクリックします。
CREATE CONNECTION
SQL コマンドを使用して、接続を作成します。
SQL コマンドを使用して、 OAuth Machine-to-User Shared を使用する接続を作成することはできません。代わりに、カタログ エクスプローラの UI の手順を参照してください。
Bearer トークン を使用して新しい接続を作成するには、ノートブックまたは 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 エージェント ツールを外部サービスに接続する」を参照してください。