アプリ間通信¶
このトピックでは、アプリ間通信(IAC)を使って1つの Snowflake Native App が別の Snowflake Native App と通信する方法を説明します。
アプリ間通信:概要¶
Inter-app communication (IAC) allows a Snowflake Native App to provide additional functionality to other Snowflake Native Apps in the same consumer account by providing access to objects that other apps can use.
たとえば、カスタマーIDsを解決する Snowflake Native App は、異なるベンダーのデータセットを結合して、他の Snowflake Native Apps がカスタマーデータを強化することをサポートできます。
IACは、2つ以上の独立したアプリが相互に通信するためのインフラストラクチャを提供し、管理とセキュリティのニーズを尊重します。アプリ開発者は、次を実行することでアプリのIACを有効にします。
インターフェースの作成
アプリロールを使用してインターフェースへのアクセスを制御します。
同期または非同期インタラクションの選択。同期インタラクションは、他のアプリが直接呼び出すことができるストアドプロシージャや関数を使用します。一方、非同期インタラクションは、他のアプリが結果をチェックするためにポーリングできる、テーブルやビューに格納されているリクエスト結果へのアクセスを提供します。
用語¶
IACは次の用語を使用します。
- クライアント
The app that initiates the connection request and uses the server app's objects.
- サーバー
The app that provides access to its objects using app roles.
- コンシューマー
クライアントおよびサーバーアプリをインストールするユーザー。
- アプリケーション構成
またはクライアントアプリがサーバーアプリの名前をリクエストするために使用するSQLオブジェクト。IACは、``APPLICATION_NAME``型のアプリケーション構成を使用して、サーバーアプリ名を保存する。
- アプリケーション仕様
クライアントアプリがサーバーアプリへの接続をリクエストするために作成するSQLオブジェクト。IACは、
CONNECTION型のアプリケーション仕様を使用します。アプリの仕様の詳細については、 Use app specifications to request controlled access をご参照ください。
アプリ間通信のワークフロー¶
接続を確立して使用するには、クライアントアプリとサーバーアプリ間のハンドシェイクプロセスが含まれます。
サーバーアプリプロバイダーからアプリロール名を取得します。クライアントアプリプロバイダーは、Snowflake外部のサーバーアプリプロバイダーと連携し、接続仕様でリクエストするサーバーアプリロールを決定します。
ターゲットアプリを特定 :クライアントアプリは、サーバーアプリの名前をリクエストする構成定義オブジェクトを作成します。コンシューマーは受信リクエストを検出し、構成オブジェクトを通じてサーバーアプリ名をクライアントアプリに提供します。
接続のリクエストと承認 :クライアントアプリは、サーバーアプリへの接続をリクエストするアプリケーション仕様を作成し、コンシューマーは接続リクエストを承認します。
サーバーアプリとの通信 :クライアントアプリは、サーバーアプリのプロシージャや関数を呼び出します。
ターゲットアプリを特定¶
クライアントアプリがサーバーアプリと通信する前に、最初にアプリの正確な名前を特定する必要があります。コンシューマーはインストール時にアプリのカスタム名を選択できるため、クライアントアプリはまずサーバーアプリの正確な名前を識別する必要があります。
クライアントアプリのセットアップスクリプトは、 CONFIGURATION DEFINITION オブジェクトを作成してこの情報をリクエストします。
次の例は、クライアントアプリのセットアップスクリプトが CONFIGURATION DEFINITION オブジェクトを作成して、サーバーアプリの名前をリクエストする方法を示しています。
次の例は、コンシューマーが受信構成定義リクエストをどのようにチェックするかを示しています。
このコマンドは以下のような結果を返します。
次に、コンシューマーは次のコマンドを使用してサーバーアプリ名を提供します。
接続のリクエストと承認¶
クライアントアプリがサーバーアプリの名前を取得すると、クライアントアプリはサーバーアプリへの接続をリクエストするために:code:`APPLICATION SPECIFICATION`を作成します。アプリケーションロール名は、Snowflakeの外部でのオフライン通信を通じて取得されることに注意してください。
次の例は、 my_server_app_name という名前のサーバーアプリへの接続用に APPLICATION SPECIFICATION を作成する方法を示しています。
アプリケーション仕様を作成することにより、クライアントアプリはアプリ仕様で指定されたサーバーアプリロールの付与をリクエストします。
注釈
アプリ仕様の LABEL および DESCRIPTION の値は、ステップ1で作成した CONFIGURATION DEFINITION オブジェクト内の LABEL および DESCRIPTION の値に一致する必要があります。値が一致しない場合、接続は Snowsight に正しく表示されません
効率的な接続ワークフローを作成するには、クライアントアプリにより、before_configuration_change <label-native_apps_configuration_callbacks_before_configuration_change>`同期コールバックでアプリケーション仕様を作成することをお勧めします。このコールバックは、 :code:`ALTER APPLICATION SET CONFIGURATION VALUE コマンドが実行されているときに実行されます。コールバックの詳細については、 コールバック をご参照ください。:ref:`before_configuration_change <label-native_apps_configuration_callbacks_before_configuration_change>`同期コールバック内でアプリケーション仕様を作成するセットアップスクリプトの例については、:ref:`label-native_apps_iac_examples`をご参照ください。
クライアントアプリがアプリ仕様を作成すると、コンシューマーは接続リクエストを確認し、承認または拒否できます。
SQLを使用した接続リクエストの承認¶
次の例は、SQLを使用してコンシューマーが接続リクエストを承認する方法を示しています。
|sf-web-interface|を使用した接続リクエストの承認¶
Snowsight で接続リクエストを表示し、承認するには、次の操作を実行します。
Snowsight にサインインします。
アプリを選択します。Configurations`に、:ui:`Application connections`というタイトルのセクションが表示されます。保留中の各接続には、接続の名前またはラベル、接続の簡単な説明、 :ui:`Review ボタンが表示されます。
Review ボタンをクリックします。接続リクエストの詳細が表示されます。
ターゲットアプリを Select from your apps から選択します。
Next をクリックします。次の情報が表示されます。
クライアントアプリがサーバーアプリに接続することと、アプリが使用するロールを示す図。
接続の詳細。
クライアントアプリに付与されるサーバー権限のサブセット。IACのセキュリティに関する考慮事項については、:ref:`label-native_apps_iac_security_considerations`をご参照ください。
Approve Connection のトグルスイッチ。スイッチは On に設定されています。
接続を承認するには、トグルスイッチを On に設定したままにし、 Save をクリックします。更新された接続リストが表示され、接続のステータスが表示されます。
接続を拒否するには、トグルスイッチを:ui:`Off`に切り替えます。
接続を承認または却下せずにレビューページを終了するには、:ui:`Cancel`ボタンをクリックします。
承認後¶
コンシューマーが接続リクエストを承認すると、 Snowflake Native App Framework は、リクエストされたサーバーアプリのロールをクライアントアプリに付与します。承認はクライアントアプリからサーバーアプリへの USAGE も付与します。これにより、サーバーアプリは、どのクライアントアプリが接続されているかを認識できます。
コンシューマーが接続リクエストを承認すると、クライアントアプリとサーバーアプリで以下のコールバックがそれぞれトリガーされます。
:ref:`after_server_connection_change <label-native_apps_connection_callbacks_after_server_connection_change>`がクライアントアプリでトリガーされる
:ref:`after_client_connection_change <label-native_apps_connection_callbacks_after_client_connection_change>`がサーバーアプリでトリガーされる
これらのコールバックにより、接続が確立されたときに、サーバーアプリとクライアントアプリは追加のアクションを実行できます。
アプリケーション仕様の承認に関する詳細については、次のトピックをご参照ください。
サーバーアプリとの通信¶
接続が確立され、クライアントアプリにリクエストされたサーバーアプリのロールが付与されると、クライアントアプリはサーバーアプリと通信できるようになります。
注釈
サーバーアプリのメソッドを呼び出す前に、クライアントアプリは承認されたアプリケーション仕様から実行時にサーバーアプリの名前を取得し、サーバーアプリの名前が変更された場合に正しい名前が使用されるようにする必要があります。次の例は、実行時にサーバーアプリの名前を取得する方法を示しています。
クライアントアプリは、サーバーアプリと同期的または非同期的に通信できます。
同期通信では、サーバーアプリのプロシージャや関数を直接呼び出します。
非同期通信では、テーブルなどのデータオブジェクトに格納されているキューを使用します。たとえば、サーバーアプリは、リクエストとしてテーブルに記録を挿入するプロシージャを提供でき、サーバーアプリはこれを定期的に処理します。その後、クライアントアプリは、サーバーが提供する別のプロシージャを使用して、テーブルの結果を確認できます。
次の同期操作の例は、Pythonを使用してサーバーアプリのプロシージャを呼び出すクライアントアプリを示しています。
次の非同期操作の例は、Pythonを使用してサーバーアプリのプロシージャを呼び出すクライアントアプリを示しています。クライアントアプリはサーバーアプリのプロシージャを呼び出し、テーブルにリクエストを作成し、サーバーアプリが処理します。クライアントアプリは、テーブルをポーリングして、結果の更新された記録をチェックすることができます。
次に、クライアントアプリはテーブルをポーリングして、結果の更新されたレコードを確認できます。
接続の管理¶
Snowsight で既存の接続を表示するにはの場合は、次の操作を実行します。
Snowsight にサインインします。
ナビゲーションメニューで Catalog » Apps を選択します。
アプリを選択します。すべてのアプリ接続は、 Configurations というタイトルのセクションに表示されます。そのセクションの下には、 Application connections というタイトルのサブセクションがあります。
接続を変更するには、接続の鉛筆アイコンをクリックします。以下を変更できます。
アプリに接続されているアプリ
接続の承認ステータス
接続済みアプリを表示するには、 View app ボタンをクリックします。
接続のセキュリティ設定を変更するには、歯車アイコンをクリックします。
セキュリティに関する考慮事項¶
仕様リクエストを承認する場合、コンシューマーはクライアントアプリにサーバーアプリアクセスを付与すると、クライアントアプリが持つ権限を昇格させる可能性があることに注意する必要があります。たとえば、サーバーアプリに外部アクセスがある場合、クライアントアプリはサーバーアプリを通じてインターネットやその他の外部リソースに間接的にアクセスする可能性があります。サーバーアプリが別のサーバーアプリのクライアントアプリである場合、クライアントアプリは最初のサーバーアプリを通じて他のサーバーアプリのリソースにアクセスできる場合があります。
コンシューマーは接続を承認する前に、サーバーアプリの機能と権限を検査する必要があります。サーバーの機能を検査するには、管理者ロール(例:ACCOUNTADMIN)を使用します。権限の低いロールでサーバーを検査しても、サーバーのすべての機能と権限が明らかになることはありません。コンシューマーは、サーバーアプリのコードがコンシューマーからは見えないこと、そしてコンシューマーが接続を承認した後にサーバーアプリの権限と機能が変更される可能性があることに注意する必要があります。
サーバーアプリの機能と権限を検査するSQLコマンドには以下が含まれますが、これらに限定されません。
SHOW GRANTS TO APPLICATION :このコマンドは、クライアントアプリのサーバーアプリに付与された権限を一覧表示します。
SHOW PRIVILEGES IN APPLICATION :このコマンドは、クライアントアプリに付与できる潜在的なアカウントレベルの権限をリストします。
SHOW REFERENCES IN APPLICATION :このコマンドは、クライアントアプリが付与を使用せずに使用する可能性のある参照をリストします。
SHOW SPECIFICATIONS IN APPLICATION :このコマンドは、外部アクセス統合(EAIs)、セキュリティ統合、共有、リスト、接続など、コンシューマーが承認したアプリケーション仕様をリストします。
SQL 参照情報¶
次のSQLコマンドは、アプリ間の通信を管理するために使用されます。
ALTER APPLICATION SET SPECIFICATION: Creates an app specification that the server app uses to grant access to its objects to the client app.
ALTER APPLICATION DROP SPECIFICATION:アプリの仕様を削除します。
ALTER APPLICATION ... { APPROVE | DECLINE} SPECIFICATION:アプリ仕様のリクエストを承認または却下します。
SHOW に SPECIFICATIONS:アプリ内のすべてのアプリケーション仕様をリストします。
DESCRIBE に SPECIFICATION:アプリのアプリ仕様を説明します。
ALTER APPLICATION SET CONFIGURATION DEFINITION:コンシューマーに別のアプリケーションの名前をリクエストするアプリケーション構成(キーと値のペア)を作成または更新します。
ALTER APPLICATION DROP CONFIGURATION DEFINITION:アプリケーション構成を削除します。
ALTER APPLICATION SET CONFIGURATION VALUE:アプリケーション構成に値を設定します。
ALTER APPLICATION UNSET CONFIGURATION:指定されたアプリケーション構成に値を設定解除します。
SHOW CONFIGURATIONS:アプリ内のすべてのアプリケーション構成をリストします。
DESCRIBE CONFIGURATION:アプリケーション構成の詳細について説明します。
IS_CONFIGURATION_SET(SYS_CONTEXT 関数):構成に値が設定されているかどうかを返します。
GET_CONFIGURATION_VALUE(SYS_CONTEXT 関数):構成の現在の値を返します。
SHOW GRANTS TO APPLICATION :指定されたアプリに付与されたすべての権限とデータベース/アプリケーションロールを一覧表示します。
SHOW GRANTS TO APPLICATION ROLE :アプリケーションロールが持つすべての権限をリストします。
SHOW GRANTS OF APPLICATION ROLE :指定されたアプリケーションロールが付与されているすべてのロールとアプリケーションをリストします。
コールバック¶
|naf|は、アプリ間の通信ワークフロー管理をしえんするために、ライフサイクルコールバックを提供しています。これらのコールバックにより、アプリは構成、接続、仕様の変更に対応することができます。コールバックを使用するには、アプリのマニフェストファイルの:code:`lifecycle_callbacks`セクションにそれらを登録します。
コールバックに関する一般的な情報については、:doc:`callbacks`をご参照ください。
構成コールバック¶
これらのコールバックは、構成値が設定または設定解除されたときにトリガーされます。一般的なユースケースとしては、コンシューマーがサーバーアプリ名を提供した際に、:ref:`before_configuration_change <label-native_apps_configuration_callbacks_before_configuration_change>`コールバックを使用して接続仕様を自動的に作成することです。
- 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`コマンドの完了後に呼び出される非同期コールバック。通知や追跡などの目的で、アプリが変更に対応できるようにします。
接続コールバック¶
これらのコールバックは、接続が確立された場合、拒否された場合、接続がドロップされた場合、接続されたアプリが削除された場合など、接続のステータスが変更されたときにトリガーされます。
- after_server_connection_change
仕様の承認、却下、またはサーバーアプリの削除など、接続状態に影響する操作によりクライアントアプリでトリガーされる非同期コールバック。
- after_client_connection_change
仕様の承認、却下、削除、クライアントアプリの削除など、接続状態に影響する操作によってサーバーアプリでトリガーされる非同期コールバック。
- after_server_version_change
サーバーアプリのバージョンまたはパッチ番号が変更された後、クライアントアプリで呼び出される非同期コールバック。これにより、クライアントアプリはアップグレードまたはダウングレードに対応することができます。
例¶
次の例は、アプリ間通信を使用するためのアプリの構成方法を示しています。
例:セットアップスクリプトとマニフェストファイル¶
次の例は、クライアントアプリのセットアップスクリプト( setup.sql )を示しています。
次の例は、クライアントアプリのマニフェストファイル( manifest.yml )を示しています。
前述のコード例については、次の点に注意してください。
:ref:`before_configuration_change <label-native_apps_configuration_callbacks_before_configuration_change>`コールバック内で、アプリは構成の以前の値に一致する既存の接続仕様をチェックし、存在する場合はドロップします。次に、コールバックは、新しく指定されたサーバーアプリ名の新しい接続仕様を作成します。サーバー名が設定されているときに新しい接続を作成すると、接続仕様が重複して作成されなくなります。
例:アプリ間非同期通信¶
次の例は、サーバーアプリのセットアップスクリプト(setup.sql)を使用して、非同期通信のためのプロシージャを作成する方法を示しています。サーバーアプリは処理待ちキューのテーブルを作成し、アプリロールを通じてクライアントアプリに2つのプロシージャ(キューにリクエストを追加するための``submit_request``、完了したリクエストの結果を取得するための``fetch_response``)を提供します。サーバーアプリは定期的に``process_requests``プロシージャを実行して、保留中のリクエストをすべて処理します。