コンシューマーに外部エンドポイントをリクエストするためにアプリ仕様を使用する

このトピックでは、プロバイダーがアプリの仕様を使用する Snowflake Native App を構成する方法について説明します。アプリの仕様により、コンシューマーはSnowflakeの外部にあるサービスへのアプリのアクセスを承認または拒否できます。

Snowflake Native App から外部サービスにアクセスする

一部 Snowflake Native Apps は、Snowflake の外部に存在するリソースに接続する必要があります。Snowflakeは、必要な外部接続のタイプに応じて異なるオブジェクトを提供します。

権限の自動付与 を使用する場合、アプリはセットアップスクリプトを実行するときに、これらのオブジェクトを作成するために必要な権限を持っています。ただし、これらのオブジェクトはSnowflakeの外部からの接続を許可するため、コンシューマーはアプリを構成するときにこれらの接続を承認する必要があります。

アプリの仕様では、プロバイダーはアプリがどのような接続情報をリクエストするかを指定できます。コンシューマーがアプリをインストールすると、アプリの仕様を確認し、必要に応じて承認または拒否します。

アプリ仕様定義

アプリ仕様定義は、外部アクセス統合またはセキュリティ統合に必要な構成の詳細のリストです。アプリ仕様定義には、アプリ仕様のメタデータとプロパティのサブセットが含まれます。

外部エンドポイントへのアクセス

Snowflakeの外部にあるサービスにアクセスするために、Snowflakeは次のオブジェクトを提供します。

ネットワークルール:

ホスト名などの外部ネットワーク識別子のリストを指定します。

外部アクセス統合:

ユーザー定義関数またはストアドプロシージャ内で外部ネットワークエンドポイントへのセキュアアクセスを許可します。外部アクセス統合は、ネットワークルールを使用して、特定の外部ネットワークロケーションへのアクセスを制限する。

外部エンドポイントにアクセスするには、アプリは ネットワークルールと外部アクセス統合を作成する必要があります。単一のアプリ仕様は、アプリによって作成されるすべての外部アクセス統合に適用されます。プロバイダーはアプリに対して複数のアプリ仕様を作成できますが、これは必須ではありません。

外部アクセス統合のアプリ仕様定義

外部アクセス統合の場合、アプリ仕様定義には以下の項目があります。

  • HOST_PORTS:アプリが必要とするネットワークルールで定義されているホストポートのリスト。

  • PRIVATE_HOST_PORTS:Snowflake外部のリソースへのプライベート接続を許可するプライベートホストポートのリスト。

注釈

これらの値は、アプリが ネットワークルールの作成 に使用する値と一致する必要があります。

サードパーティの認証プロバイダーへのアクセス

サードパーティの認証サービスを実装するために、Snowflakeは セキュリティ統合を提供します。セキュリティ統合により、アプリは のようなサードパーティの認証サービスに接続できます。 OAuth.セキュリティ統合により、アプリは安全な認証とアクセス制御を使用できます。

注釈

Snowflake Native Apps タイプ API_AUTHENTICATION のセキュリティ統合のみをサポートします。詳細については、 CREATE SECURITY INTEGRATION （外部 API 認証） をご参照ください。

セキュリティ統合のアプリ仕様定義

セキュリティ統合の場合は、 アプリ仕様定義 には、サードパーティプロバイダーへの接続に必要な情報が含まれています。OAuth の場合、仕様定義には次が含まれます。

セキュリティ統合タイプ

アプリ仕様で定義された値

CLIENT_CREDENTIALS

  • OAUTH_TOKEN_ENDPOINT （必須）

  • OAUTH_ALLOWED_SCOPES （必須）

アプリ仕様のシーケンス番号

シーケンス番号は、アプリ仕様のバージョン番号に似ています。シーケンス番号は、プロバイダーがアプリ仕様の定義を変更すると自動的に増加されます。アプリ仕様の定義には、構成の詳細やその他の必要な情報が含まれます。定義の一部ではないフィールド description などは、シーケンス番号の更新をトリガーしません。

シーケンス番号によって、プロバイダーとコンシューマーは、アプリ仕様の現在のステータスと、どの外部エンドポイントが有効になっているかを知ることができます。

アプリ仕様ワークフロー

アプリの仕様を構成して使用するための一般的なワークフローは次のとおりです。

  1. プロバイダーは、アプリの :doc:` 権限の自動付与 <requesting-auto-privs>` 構成します。これにより、コンシューマーはアプリに外部アクセス統合を作成する権限を与えることができます。

    注釈

    アプリの仕様ではマニフェストファイルで manifest_version = 2 に設定します。

  2. プロバイダー :ref:` マニフェストファイルに CREATEEXTERNALACCESSINTEGRATION の権限 <label-native_apps_app_spec_add_eai_priv>` を追加します。

  3. プロバイダーが追加 必要に応じて、次のオブジェクトを作成するためにセットアップスクリプトに SQL のステートメントを実行します。

    • ネットワークルール

    • :doc:` 外部アクセス統合 </sql-reference/sql/create-external-access-integration>`

    • :doc:` セキュリティ統合 </sql-reference/sql/create-security-integration>`

    • ジョブ仕様

    セットアップスクリプトは、アプリのインストール時やアップグレード時、または実行時にアプリの仕様やその他のオブジェクトを作成します。

  4. アプリを構成するとき、コンシューマーはホストポートおよびその他の外部サービスを承認します。詳細については、 アプリの仕様を使用した外部リソースへの接続の承認 をご参照ください。

マニフェストファイルに CREATEEXTERNALACCESSINTEGRATION に対する権限を追加します

アプリが CREATEEXTERNALACCESSINTEGRATION 権限をリクエストするように構成するには、マニフェストファイルの privileges セクションに次のコードを追加します:

manifest_version: 2
...
privileges:
  - CREATE EXTERNAL ACCESS INTEGRATION:
      description: "Allows the app to create an external access integration to connect to an external service."
...
Copy

マニフェストファイルの privileges セクションにあるこのエントリは、アプリが外部アクセス統合を使用することを指定します。アプリが権限の自動付与を使用するには、マニフェストファイルに manifest_version: 2 も設定する必要があります。

セットアップスクリプトにネットワークルールと外部アクセス統合を追加する

外部アクセス統合は、特定の外部ネットワークロケーションへのアクセスを可能にするSnowflakeオブジェクトです。外部アクセス統合には、アプリがアクセスできる外部ロケーションを指定するネットワークルールのリストが含まれています。

アプリのネットワークルールを作成するには、次の例に示すようにセットアップスクリプトに CREATE NETWORK RULE コマンドを追加します。

CREATE OR REPLACE NETWORK RULE setup.my_network_rule
 TYPE = HOST_PORT
 VALUE_LIST = ( 'example.com' )
 MODE = EGRESS;
Copy

HOST_PORT および VALUE_LIST プロパティは、ネットワークルールが有効なドメイン、ポート、またはポートの範囲をポイントする必要があることを示します。アプリがインストールまたはアップグレードされると、コンシューマーはアプリがこれらのドメインやポートを使用する許可を与えることになります。

アプリの外部アクセス統合を作成するには、 次の例に示すように、セットアップスクリプトに CREATE EXTERNAL ACCESS INTEGRATION コマンドを追加します。

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_app_prefix_eai_rule
  ALLOWED_NETWORK_RULES = (setup.my_network_rule)
  ENABLED = TRUE;
Copy

このコマンドは、アプリが外部リソースやエンドポイントにアクセスできるようにする、my_app_prefix_eai_rule という名前の外部アクセス統合を作成します。setup.my_network_rule ネットワークルールを使用します。

セットアップスクリプトにセキュリティ統合を追加する

セキュリティ統合により、アプリは OAuth のようなサードパーティの認証サービスに接続できます。 次の例に示すように、CREATE SECURITY INTEGRATION （外部 API 認証） コマンドを使用してアプリのセキュリティ統合を作成します。

CREATE SECURITY INTEGRATION external_oauth_provider
  TYPE = API_AUTHENTICATION
  AUTH_TYPE = OAUTH2
  OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
  OAUTH_CLIENT_ID = 'YOUR_CLIENT_ID'
  OAUTH_CLIENT_SECRET = 'YOUR_CLIENT_SECRET'
  OAUTH_GRANT = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default')
  ENABLED = TRUE;
Copy

この例は、OAuth クライアント認証情報を使用してMicrosoft Sharepointに接続するセキュリティ統合を作成する方法を示しています。他の OAuth プロバイダーへサポートされている接続方法については CREATE SECURITY INTEGRATION （外部 API 認証） を参照してください。

セットアップスクリプトでのアプリ仕様の作成

アプリ仕様を作成するには、プロバイダーはセットアップスクリプトに ALTER APPLICATION SET SPECIFICATIONS コマンドを追加します。

外部アクセス統合のアプリ仕様の作成

次の例は、外部アクセス統合を作成する方法を示しています。

ALTER APPLICATION SET SPECIFICATION eai_app_spec
        TYPE = EXTERNAL_ACCESS
        LABEL = 'Connection to an external API'
        DESCRIPTION = 'Access an API that exists outside Snowflake'
Copy

このコマンドは、eai_app_spec という名前のアプリ仕様を作成します。

セキュリティ統合のアプリ仕様を作成する

次の例は、CLIENT_CREDENTIALSOAuth タイプを使用して、セキュリティ統合のアプリ仕様を作成する方法を示しています：

ALTER APPLICATION SET SPECIFICATION oauth_app_spec
  TYPE = SECURITY_INTEGRATION
  LABEL = 'Connection to an external OAuth provider'
  DESCRIPTION = 'Integrates an external identity provider in the app'
  OAUTH_TYPE = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default');
Copy

注釈

アプリ仕様を作成するときに提供する値は、セキュリティ統合の作成 セットアップスクリプトの場合に使用する値と同じである必要があります。

他の OAuth タイプの使用については、ALTER APPLICATION SET SPECIFICATIONS をご参照ください。

アプリ仕様を使用するためのベストプラクティス

権限の自動付与 は、アプリが外部アクセス統合を作成するために必要な権限を持っていることを確認します。ただしコンシューマーは、外部エンドポイントへの接続を可能にするアプリ仕様を拒否することを選択できます。アプリを開発するとき、プロバイダーはアプリの仕様が承認されない可能性を考慮する必要があります

たとえば、アプリは外部アクセス統合 のために複数のネットワークポートの使用を要求するかもしれませんが、コンシューマーは1つしか許可しません。アプリには、ネットワークポートが利用できない場合に発生するエラーを処理するロジックが含まれている必要があります。また、発生する可能性のある HTTP 例外をキャッチするためのベストプラクティスです。

アプリ仕様でのコールバック関数の使用

状況によっては、コンシューマーがアプリの仕様を承認または却下したかをアプリが知る必要がある場合があります。たとえば、アプリはオブジェクトを作成する前に、アプリの仕様が承認されるまで待つ必要がある場合があります。

この状況に対処するため、 Snowflake Native App Framework は、コンシューマーがアプリ仕様を承認または却下したときに実行されるコールバックストアドプロシージャをプロバイダーが定義できるメカニズムを提供します。

プロバイダーは、次の例に示すように、マニフェストファイルにストアドプロシージャを追加できます。

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update
Copy

この例は、マニフェストファイルに callbacks.on_spec_update という名前のストアドプロシージャを作成する方法を示しています。セットアップスクリプトでは、プロバイダーは次の例に示すようにストアドプロシージャを追加できます。

CREATE OR REPLACE PROCEDURE callbacks.on_spec_update (
  name STRING,
  status STRING,
  payload STRING)
  ...
Copy

この例は、callbacks.on_spec_update というストアドプロシージャの署名を示しています。このプロシージャの本文には、プロバイダーはアプリ仕様のステータスを確認し、オブジェクトを作成し、必要に応じてアクションを実行するために必要なコードを含みます。

言語: 日本語