例 - コンテナを使ったアプリのサービスの外部アクセスを設定する¶

このトピックでは、コンテナーを使用するアプリで、Snowflake の外部であるエンドポイントにアクセスを許可する方法について説明します。この例では、外部アクセス統合とシークレットを使ってエンドポイントへのアクセスを許可しています。

コンテナー付きアプリで外部エンドポイントへのアクセスを許可するには、プロバイダーは以下のオブジェクトへの参照を定義しなければなりません。

EXTERNAL ACCESS INTEGRATION

外部エンドポイントのドメイン名を指定するネットワーク・ルールのリストを定義します。外部アクセス統合は、これらのエンドポイントにアクセスするために使用される認証情報を格納するシークレットのリストを指定することもできます。シークレットはオプションで、 NONE または ALL に設定できます。

コンテナーを使ったアプリのコンテキストでは、外部アクセス統合には USAGE 権限が必要です。

注釈

multi_valued プロパティを TRUE に設定することはできません。単一値参照のみがサポートされています。
SECRET

外部アクセス統合を使用して外部エンドポイントに接続するために必要な認証情報が含まれています。

コンテナーを使ったアプリのコンテキストでは、シークレットは USAGE と READ 権限をサポートします。これらの権限のうち、少なくとも1つを指定する必要があります。シークレットがサービスと共に使用される場合、またはストアドプロシージャやユーザー定義関数に添付される場合は、 READ 権限を指定する必要があります。

マニフェストファイルに外部アクセス統合参照を追加する¶

次の例は、プロバイダーがマニフェスト・ファイルで外部アクセス統合を定義する方法を示しています。

references:
  ...
  - my_external_access:
      label: "Default External Access Integration"
      description: "This EAI is required to access xyz.com"
      privileges:
        - USAGE
      object_type: EXTERNAL ACCESS INTEGRATION
      required_at_setup: true
      register_callback: config.REGISTER_EAI_CALLBACK
      configuration_callback: config.get_config_for_ref

この例では、特に以下のプロパティを references で指定しています。

my_external_access: 外部参照の名前を指定します。
- privileges: 外部アクセス統合に必要な権限を一覧表示します。この例では、 USAGE 権限が必要です。
- object_type: EXTERNAL ACCESS INTEGRATION: 外部アクセス統合への参照を示します。
- required_at_setup: true に設定されている場合、アプリがオブジェクトを作成する前に、コンシューマーがオブジェクトへのアクセスを認可する必要があることを示します。
- register_callback: アプリへの参照の登録に使用するコールバックストアドプロシージャを指定します。
- configuration_callback: シークレットの設定コールバック関数を指定します。詳細については、セットアップスクリプトにconfiguration_callback関数を追加するをご参照ください。

マニフェストファイルにシークレットの参照を追加します。¶

次の例は、プロバイダーがマニフェストファイルでどのようにシークレットを定義するかを示しています。

references:
 ...
 - consumer_secret:
     label: "Consumer secret"
     description: "Needed to authenticate with an external endpoint"
     privileges:
       - READ
     object_type: SECRET
     register_callback: config.register_my_secret
     configuration_callback: config.get_config_for_ref

この例では、特に以下のプロパティを references で指定しています。

consumer_secret: 参照の名前を指定します。
- privileges: シークレットに必要な権限を一覧表示します。この例では、 READ 権限が指定されています。
- object_type: SECRET: 参照がシークレットであることを示します。
- register_callback: アプリへの参照の登録に使用するコールバックストアドプロシージャを指定します。
- configuration_callback: シークレットの設定コールバック関数を指定します。詳細については、セットアップスクリプトにconfiguration_callback関数を追加するをご参照ください。

セットアップスクリプトにconfiguration_callback関数を追加する¶

シークレットおよび外部アクセスの統合の参照を追加した後、セットアップスクリプトに configuration_callback 関数を追加する必要があります。外部アクセス統合またはシークレットを作成するには、アプリケーションがホストポート、シークレットタイプ、 OAuth の承認およびトークンエンドポイントなどの値を決定できる必要があります。 configuration_callback は、コンシューマーアカウントからアプリケーションにこの情報を提供します。

CREATE OR REPLACE PROCEDURE CONFIG.GET_CONFIG_FOR_REFERENCE(ref_name STRING)
RETURNS STRING
LANGUAGE SQL
AS
$$
BEGIN
 CASE (UPPER(ref_name))
   WHEN 'my_external_access' THEN
     RETURN '{
       "type": "CONFIGURATION",
       "payload":{
         "host_ports":["google.com"],
         "allowed_secrets" : "LIST",
         "secret_references":["CONSUMER_SECRET"]}}';
   WHEN 'consumer_secret' THEN
     RETURN '{
       "type": "CONFIGURATION",
       "payload":{
         "type" : "OAUTH2",
         "security_integration": {
           "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
           "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
           "oauth_authorization_endpoint":
               "https://accounts.google.com/o/oauth2/auth"}}}';
  END CASE;
  RETURN '';
END;
$$;

Snowsight はこのコールバックプロシージャを実行して、ユーザーにオブジェクトを構成するよう求める構成ダイアログを表示します。

注釈

configuration_callback 関数は、外部アクセス統合とシークレットオブジェクトに対してのみサポートされます。

実行するには、プロシージャをアプリロールに付与する必要があります。

GRANT USAGE ON PROCEDURE CONFIG.GET_CONFIG_FOR_REFERENCE(STRING)
  TO APPLICATION ROLE app_admin;

コンテナーを使用したアプリで外部アクセス統合を使用する際のベストプラクティス¶

Snowflake では、コンテナーを使用するアプリで外部アクセス統合を使用する場合、以下のベストプラクティスを推奨しています。

CREATE SERVICE または ALTER SERVICE コマンドで指定する外部アクセス統合への参照は、セットアップスクリプトでコマンドを実行する前にバインドする必要があります。参照がバインドされていない場合、これらのコマンドは失敗します。
セットアップスクリプトで CREATE SERVICE または ALTER SERVICE コマンドを実行する前に、サービス仕様で指定されているシークレットへの参照もバインドする必要があります。参照がバインドされていない場合、これらのコマンドは失敗します。
configuration_callback 関数で ERROR 型のペイロードを返す場合、プロバイダーは、消費者がエラーの原因とその解決方法を理解するのに役立つ、有益なエラーメッセージを返すべきです。例:
- アプリでエラーが発生した場合
- 参照がまだ必要でない場合
- 参照が許可される準備ができていない場合。
configuration_callback 関数に required_at_setup プロパティが TRUE に設定された参照が含まれている場合、 configuration_callback 関数は設定時に成功する必要があります。この文脈では、 configuration_callback 関数は、コンシューマーからの情報に依存することはできません。
サービスとの外部アクセス統合への参照を使用する場合、アプリがコンシューマーから提供されるシークレットを必要とする場合は、 ALLOWED_AUTHENTICATION_SECRETS = ALL を使用してサービスを作成することを検討してください。これにより、外部アクセス統合内でのシークレットの取り扱いが簡単になります。
アプリが特定のエンドポイントにのみ到達する必要があり、シークレットを必要としない場合は、 ALLOWED_AUTHENTICATION_SECRETS = NONE を使用します。NONE がデフォルト値です。詳細については、 CREATE EXTERNAL ACCESS INTEGRATION をご参照ください。
アプリが参照を更新する必要がある場合、まず参照をアンバインドし、次にコンシューマーに新しいオブジェクトを作成して参照にバインドするよう促します。コンシューマーは、既存のオブジェクトを編集してバインドすることを選択できます。 CREATE EXTERNAL ACCESS INTEGRATION をご参照ください。