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

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

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

  7. 認証 ページで、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 フロー中にクライアントアプリケーションを識別するために、認証サーバーによって使用されます。

クライアントのシークレット

作成したアプリケーションに対して生成されたシークレットまたはパスワード。これは、認証コードをトークンと交換するときにクライアント アプリケーションを認証するために使用され、機密を保持する必要があります。

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 などのプロバイダーの場合)。
  1. 接続の作成 をクリックします。

Unity Catalog接続を共有する​

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

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

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 エージェント ツールを外部サービスに接続する」を参照してください。