アプリケーション構成¶

アプリケーション構成：概要¶

アプリケーション構成は、|native-app|とコンシューマーの間の調整メカニズムを提供するキーと値のペアです。|native-app|がコンシューマーからの入力を必要とする場合、構成キーと、構成の目的を説明する説明を定義します。コンシューマーはそのキーの値を提供します。

アプリケーション構成は、次の型をサポートします。

APPLICATION_NAME

コンシューマーは、コンシューマーアカウントにインストールされているアプリの名前を提供します。この型は:doc:`アプリ間通信<inter-app-communication>`に使用されます。

STRING

コンシューマーは、任意の文字列値を提供します。この型は、外部URLs、アカウント識別子、またはその他のアプリ固有の設定の提供など、さまざまなユースケースに使用できます。

アプリケーション構成ワークフローには、以下のステップが含まれます。

1. アプリは、:code:`ALTER APPLICATION SET CONFIGURATION DEFINITION`を使用して構成定義を作成し、必要な情報の種類と、構成にアクセスできるアプリロールを指定します。

2. コンシューマーは、:code:`SHOW CONFIGURATIONS`または|sf-web-interface|を使用して受信構成リクエストを表示します。

3. コンシューマーは、:code:`ALTER APPLICATION SET CONFIGURATION VALUE`または|sf-web-interface|を使用してリクエストされた値を提供します。

4. アプリは値を取得し、それを使用して、接続のアプリケーション仕様を作成するなどの追加操作を実行します。

|naf|は、構成値が設定または変更されたときにアプリに通知するコールバックを提供します。詳細については、 構成コールバック をご参照ください。

用語¶

アプリケーション構成では、次の用語を使用します。

構成定義

アプリがコンシューマーに特定の情報を要求するために作成するオブジェクト。構成定義は、リクエストされた情報の種類、ラベル、説明、および構成にアクセスできるアプリロールを指定します。

構成値

構成定義のリクエストに応答してコンシューマーが提供する値。

構成の使用¶

このセクションでは、構成を作成、表示、および管理する方法について説明します。

• 構成リクエストの作成

• 構成リクエストの表示

• 構成値の指定

• 構成の値の更新

• 構成値の設定解除

• 構成の値の取得

ALTER APPLICATION SET CONFIGURATION DEFINITION company_url
  TYPE = STRING
  LABEL = 'Company URL'
  DESCRIPTION = 'Provide the company website URL'
  APPLICATION_ROLES = (app_user)
  SENSITIVE = FALSE;

SHOW CONFIGURATIONS IN APPLICATION example_app;

DESCRIBE CONFIGURATION company_url IN APPLICATION example_app;

ALTER APPLICATION <app> SET CONFIGURATION <config> VALUE = '<value>';

ALTER APPLICATION <app> SET CONFIGURATION <config> VALUE = '<value>';

ALTER APPLICATION <app> UNSET CONFIGURATION <config>;

SELECT SYS_CONTEXT('SNOWFLAKE$APPLICATION', 'GET_CONFIGURATION_VALUE' , '<config_name>')

機密性の高い構成¶

アプリが構成を作成するときに、:code:`SENSITIVE = TRUE`を設定することで、構成を機密としてマークできます。これは、アプリが個人アクセストークンやAPIキーなどの機密情報を消費者に要求する必要がある場合に便利です。

構成が機密である場合、コンシューマーが提供した値は他のコンシューマーのユーザーやロールから保護されます。|naf|は、Snowflakeの:doc:`SECRETオブジェクト</sql-reference/sql/create-secret>`に使用されるものと同様の保護を適用します。

• コンシューマーが値を設定すると、:code:`ALTER APPLICATION SET CONFIGURATION VALUE`コマンドのクエリ履歴によってその値がマスキングされ、他のコンシューマーロールまたはユーザーに公開されなくなります。

• 値は、SHOW CONFIGURATIONS、DESCRIBE CONFIGURATION、INFORMATION_SCHEMAビュー、またはACCOUNT_USAGEビューの出力に表示されません。

構成を作成したアプリは、構成が機密であっても、常にコンシューマーが提供した値を取得できます。これは仕様によるものです。アプリケーション構成の目的は、コンシューマーがアプリに値を提供することだからです。

SQL リファレンス¶

次のSQLコマンド、関数、ビューはアプリケーションの構成を管理するために使用されます。

コールバック¶

構成値が変更されると、|naf|は、アプリの:doc:マニフェスト</developer-guide/native-apps/manifest-reference>`ファイルに登録されているライフサイクルコールバックを呼び出すことができます。。これらのコールバックによって、アプリは構成の変更を検証したり、準備したり、対応したりすることができます。たとえば、アプリ間通信を構成する際に、コンシューマーがサーバーアプリ名を設定する際に、:ref:`before_configuration_change<label-native_apps_configuration_callbacks_before_configuration_change>`コールバックを使用して接続仕様を自動的に作成または更新することが一般的なユースケースです。これにより、構成値を設定した後にコンシューマーが追加の手動手順を実行する必要がなくなります。アプリ間通信の詳細については、:doc:/developer-guide/native-apps/inter-app-communication`をご参照ください。

次の構成コールバックが使用可能です。

validate_configuration_change

:code:`ALTER APPLICATION SET CONFIGURATION VALUE`コマンドの一部として呼び出される同期コールバック。アプリが指定された値に対してカスタム検証を実行できるようにします。コールバックがエラーを返す場合、コマンドは失敗し、新しい値は設定されません。

before_configuration_change

:code:`ALTER APPLICATION SET CONFIGURATION VALUE`および:code:`ALTER APPLICATION UNSET CONFIGURATION`コマンドの一部として呼び出される同期コールバック。構成値が保存される前に、アプリが構成値に基づいて操作を実行できるようにします。

after_configuration_change

:code:`ALTER APPLICATION SET CONFIGURATION VALUE`または:code:`ALTER APPLICATION UNSET CONFIGURATION`コマンドの完了後に呼び出される非同期コールバック。通知や追跡などの目的で、アプリが変更に対応できるようにします。

完全なコールバックの署名と戻り値については、:doc:`/developer-guide/native-apps/callbacks`をご参照ください。