アプリケーション構成

このトピックでは、|native-app|がアプリケーション構成オブジェクトを使用してコンシューマーに入力をリクエストする方法について説明します。

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

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

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

APPLICATION_NAME

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

STRING

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

SECRET_AUTHORIZATION

コンシューマーは、トークンをシークレットに格納するための OAuth フローを完了します。このタイプは、プロバイダーがセキュリティ統合とシークレットを作成し、コンシューマーが直接サードパーティ認証を完了する場合に使用されます。詳細については、 コンシューマーからの OAuth 認証リクエスト をご参照ください。

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

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

用語

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

構成定義

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

構成値

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

構成の使用

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

構成リクエストの作成

コンシューマーに構成値を要求するために、アプリはセットアップスクリプト内または実行時に構成定義を作成します。構成定義は、期待される値の型、コンシューマーに表示されるラベルと説明、および構成を表示して値を編集できるアプリロールを指定します。

次の例は、コンシューマーから会社のURLをリクエストする``STRING``型の構成定義を作成する方法を示しています。

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

次のプロパティは、構成の表示方法と管理方法を制御します。

  • LABEL:|sf-web-interface|でコンシューマーに表示される名前。

  • DESCRIPTION:コンシューマーが構成の目的を理解するのに役立つ説明。

  • APPLICATION_ROLES:この構成の値を表示および設定できるアプリロール。指定されたアプリロールのいずれかが付与されているコンシューマーロールは、構成を表示し、その値を編集することができます。

  • SENSITIVE:構成値を機密として扱うかどうかを指定します。TRUE に設定した場合、値は SHOW CONFIGURATIONS の出力に表示されません。 TYPE = STRING の場合に必要です。詳細については、 機密性の高い構成 をご参照ください。

構成リクエストの表示

アプリが構成リクエストを作成すると、コンシューマーは|sf-web-interface|またはSQLを使用して保留中のリクエストを表示できます。

|sf-web-interface|を使用して構成リクエストと構成定義の詳細を表示するには、次の操作を実行します。

  1. Snowsight にサインインします。

  2. ナビゲーションメニューで Catalog » Apps を選択します。

  3. アプリを選択します。

  4. :ui:`Configurations`タブを開きます。:ui:`Configurations`セクションには、:ui:`Other configurations`セクションの文字列構成が表示されます。各文字列構成には以下が表示されます。

    • 構成のラベル。

    • 何用の構成であるかの説明。

    • :ui:`Review`ボタン。

構成値の指定

アプリが構成リクエストを作成した後、コンシューマーは|sf-web-interface|またはSQLを使用してリクエストされた値を提供します。

|sf-web-interface|を使用して構成の値を提供するには、次の操作を実行します。

  1. |sf-web-interface|の構成の詳細ページで:ui:`Review`ボタンをクリックします。構成の詳細ページには、次が表示されます。

    • 構成のラベル。

    • 何用の構成であるかの説明。

    • 構成が機密である場合は:ui:Sensitive data protection`バナーが表示されます。詳細については、 :ref:`label-native_apps_app_configuration_sensitive をご参照ください。

  2. :ui:`Value`フィールドに構成の値を入力します。

  3. :ui:`Save`ボタンをクリックして構成の値を送信します。:ui:`Configuration updated successfully`が表示されます。構成リストが更新され、新しい値が表示されます。

構成の値の更新

|sf-web-interface|またはSQLを使用して、構成の値を更新できます。

|sf-web-interface|を使用して構成の値を更新するには、次の操作を実行します。

  1. |sf-web-interface|の構成の詳細ページで、構成に値が設定されている場合、次の情報が表示されます。

    • :ui:`Configured`バナー。

    • 構成が機密でない場合は、値が表示されます。

    • 構成が機密である場合、値はマスクされます。

    • :ui:`Update`ボタン。

    • :ui:`Clear value`ボタン。

  2. :ui:`Update`ボタンをクリックして、構成の値を更新します。

  3. :ui:`Value`フィールドに構成の新しい値を入力します。

  4. :ui:`Save`ボタンをクリックして、構成の新しい値を送信します。:ui:`Configuration updated successfully`が表示されます。構成リストが更新され、新しい値が表示されます。

構成値の設定解除

|sf-web-interface|またはSQLを使用して構成値を設定解除することができます。

|sf-web-interface|を使用して構成の値を設定解除するには、次の操作を実行します。

  1. |sf-web-interface|の構成の詳細ページで:ui:`Clear value`ボタンをクリックします。

  2. アクションを確認します。構成リストが更新され、未設定の構成が表示されます。

構成の値の取得

SHOW CONFIGURATIONSまたはDESCRIBE CONFIGURATIONに加えて、アプリは:doc:`get_configuration_value</sql-reference/functions/get_configuration_value>`関数を使用して、コンシューマーが提供した構成の値を取得できます。次の例は、構成の値を取得する方法を示しています。

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

注釈

システムコンテキストから構成値を取得できるのは、アプリのみです。コンシューマーとして構成値を表示するには、SQLまたは|sf-web-interface|を使用して構成の詳細を表示できます。詳細については、 構成リクエストの表示 をご参照ください。

機密性の高い構成

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

注釈

:code:`SENSITIVE`プロパティは、``STRING``型の構成に対してのみサポートされます。

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

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

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

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

SENSITIVEプロパティの変更

構成に値が設定されている間（つまり、構成が``PENDING``状態でないとき）アプリは:code:`SENSITIVE`プロパティを変更できません。この制限により、コンシューマーの値が誤って公開されることを防ぎます。値が設定されているのにアプリが:code:`SENSITIVE`プロパティを変更しようとした場合、コマンドはエラーなしで完了しますが、何も変更しません。

:code:`SENSITIVE`プロパティを変更するには、コンシューマーはまず:code:`ALTER APPLICATION UNSET CONFIGURATION`を使用して構成値を設定解除する必要があります。

SQL リファレンス

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

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`をご参照ください。

アプリケーション構成での権限 SDK の使用

アプリにStreamlitフロントエンドが含まれている場合は、 Python Permission SDK を使用してコンシューマーに構成の値を確認して設定するよう促します。SDK は、アプリケーション構成を操作するために次の機能を提供します。

get_application_configurations()

アプリに定義されているすべての構成を返します。これは、 SHOWCONFIGURATIONS を実行するのと同等です。

/sql-reference/sql/alter-application-set-configuration-value`request_application_configuration_value()

Streamlitアプリで、コンシューマーがアプリケーション構成の値を確認および設定できるダイアログを開きます。

request_application_connection_review()

コンシューマーが アプリ間通信 のアプリケーション接続を承認するためのダイアログを開きます。

詳細については、 権限 SDK 参照 をご参照ください。