メッセージングユーザーガイド
このガイドでは、Vega SDKのVega Messagingライブラリ（com.amazon.kepler.experimental_mr33.messaging）の使用方法について詳しく説明します。このライブラリは、メッセージを伝達するための通信メカニズムを提供します。
Vega Messagingは、アプリの起動、ブロードキャストによるシステム変更の公開、アプリ間通信など、さまざまな目的に使用できます。プロシージャコールとは対照的に、メッセージ指向の通信では、送信者と受信者の処理が切り離されるため、両者が同時に実行されている必要はありません。これは、メッセージルーターと呼ばれる一元化されたブローカーサービスを使用して実現されます。
このメカニズムは、Vega Tasksライブラリ（com.amazon.kepler.tasks）による遅延実行の基盤にもなっています。
メッセージ定義とセキュリティ
重要となるのが、メッセージは送信者と受信者の間のAPIコントラクトとして扱われるという概念です。メッセージURI、添付ファイルの種類、送信者、受信者の権限は、通信を成功させるために当事者双方が遵守する必要のあるコントラクトです。メッセージを一方的に変更するとAPIの動作が妨げられ、配信や解釈に問題が生じます。メッセージコントラクトの整合性を維持するために、コントラクトを事前に指定するメッセージ定義は静的でなければなりません。システムサービスとアプリの両方が、以下の説明に従って新しいメッセージを定義できます。メッセージのバージョン管理と依存関係の指定には、既存のVegaモジュールが使用されます。Vegaモジュールは、コントラクトおよびコントラクトに対する依存関係を表現するためのVega SDKのメカニズムです。モジュールの詳細については、マニフェストのoffers、wants、needsのドキュメントにあるモジュールの説明を参照してください。
メッセージの作成
メッセージを作成するには、次の手順に従います。
- モジュールを定義します。
- モジュールの一部となるメッセージを定義します。
- 実行時にメッセージを使用するための権限を定義します。
モジュールの定義
モジュールを定義し、そのモジュールの一部となるメッセージをすべて含めます。メッセージルーター経由のURIは、それがモジュールの一部でない限り使用しないでください。
[offers]
[[offers.module]]
id = "/com.amazon.samplepkg.module@IMod1"
includes-messages = [
"pkg://com.amazon.messaging.mr33.testSendPriv.main",
"pkg://com.amazon.messaging.mr33.testSendPriv.self_privileges"
]
メッセージの定義
[[message]]ブロックを必要なだけ追加して、複数のメッセージを定義します。メッセージのURIをクエリパラメーターなしで指定します。フラグメントを含めるのは、従来のURIを定義する場合だけにしてください（非推奨）。vpkgの外部で使用されないpkg://スキームのURIについては、[[message]]の追加を省略します。詳細については、メッセージアドレス指定スキームを参照してください。
[[message]]
uri = "pkg://com.amazon.messaging.mr33.testSendPriv.main"
[[message]]
uri = "pkg://com.amazon.messaging.mr33.testSendPriv.self_privileges"
セキュリティルールの追加
メッセージの送信者または受信者を制限するには、送信者と受信者に必要な権限をmessageセクションに指定します。
たとえば、「com.amazon.messaging.mr33.testSendPriv」というパッケージがあり、com.amazon.security.example1権限を持つ送信者とcom.amazon.security.example2権限を持つ受信者だけがそれを使用できるように制限するには、次のようにメッセージを定義します。
[[message]]
uri = "pkg://com.amazon.messaging.mr33.testSendPriv.main"
sender-privileges = ["com.amazon.security.example1"]
receiver-privileges = ["com.amazon.security.example2"]
複数の権限を指定した場合、送信者または受信者がロールを引き受けるには、リスト内のすべての権限が必要になります。必要に応じて、特定の権限文字列の代わりに*またはselfを使用できます。
- すべてにメッセージの使用を許可するには、
*を使用します。 - モジュールが含まれているvpkgにのみメッセージの使用を許可するには、
selfを使用します。
これらの予約済みの値は、sender-privilegesとreceiver-privilegesで別々に使用できます。
メッセージの使用
モジュール依存関係の追加
注： 以下のセクションは、メッセージが独自のvpkg内で定義されている場合は適用されません。
メッセージを別のvpkgで使用するには、マニフェストに以下の指定を追加します。メッセージの送信者と受信者のどちらも同じ構文を使用します。依存関係の指定の単位はモジュールです。あるモジュールに依存している場合、そのモジュールで定義されたすべてのメッセージを使用できます。
[[wants.module]]
id = "/com.amazon.samplepkg.module@IMod1"
または
[[needs.module]]
id = "/com.amazon.samplepkg.module@IMod1"
needs構文の方が強力な依存関係の指定形式で、アプリをデバイスにインストールする前に依存関係が存在することを要求します。詳細については、アプリマニフェストのユーザーガイドを参照してください。
権限のリクエスト
目的のメッセージにselfまたは*が指定されている場合を除き、以下のセクションを追加して必要な権限をリクエストします。以下のスニペットは、/com.amazon.samplepkg.module@IMod1に定義されているtestSendPriv.mainメッセージを使用する権限がアプリに必要であることを指定する方法を示しています。
[wants]
[[wants.privilege]]
id = "com.amazon.security.example1"
または
[needs]
[[needs.privilege]]
id = "com.amazon.security.example1"
needs構文の指定はwants構文よりも強力です。needsの詳細については、needsを参照してください。
com.amazon.kepler.security.IKeplerSecurityModuleを呼び出す必要があります。メッセージから起動コンポーネントへのマッピング
すべてのライフサイクルコンポーネントは名前によって起動できます。そのためには、pkg://スキームに続けて起動するコンポーネントの名前を指定します。ただし、メッセージアドレス指定のドキュメントに記載されているように、起動するコンポーネントを直接識別しないほかのURIスキームもあります。このような場合は、マニフェストのoffers.message-targetセクションに追加情報を指定します。
[[offers.message-target]]
uris = [
"https://demo.com",
"https://demo.com/example/path"
]
uses-component = "com.demo.main"
デバッグに関するよくある質問（FAQ）
フィルターを登録したのにメッセージを受信しないのはなぜですか？
メッセージを受信するには、フィルターを登録したメッセージチャネルを有効にしておく必要があります。チャネルが強制終了されたり、範囲外になったりすると、メッセージは受信できなくなります。
チャネルがライブであるにも関わらず、メッセージを受信しないのはなぜですか？
送信者がメッセージを送信する前に、チャネルでフィルターを登録していることを確認してください。チャネルは、フィルターが正常に登録された後に送信されたメッセージのみを受信します。
目的のブロードキャスト／ユニキャストが送信されているかどうかを確認するには、デバイスでvmsgr CLIを使用します。
メッセージが送信されていてもアプリで受信されない場合は、vmsgr listenコマンドを使用して、メッセージが伝達されているかどうかを確認できます。このCLIは、ルートシェルまたは非ルートシェルから実行します。
$ vmsgr listen broadcast://com.amazon.test1
CLI Listener Message Channel: Received: broadcast://com.amazon.test1
CLI Listener Message Channel: Received: broadcast://com.amazon.test1
^CSignal received, stopping
CLIでメッセージを受信しているにも関わらずアプリでメッセージが受信されない場合は、構成に誤りがあるか、APIの使用方法に問題がある可能性があります。
メッセージのアクセス制御が正しく設定されていることを確認するにはどうすればよいですか？
マニフェストに必要なメッセージアクセス制御が含まれていない、または正しく設定されていない場合、実行時にアプリが正常に動作しなくなる場合があります。アプリの起動に失敗したり、アプリから他のアプリを起動しようとした際にエラーが発生したり、システムイベントメッセージ（ブロードキャストやユニキャスト）を受信しようとした際にエラーが発生したりする可能性があります。
次のデバッグのヒントを参考にして、アプリの問題の根本原因を特定します。
-
アプリをサイドロードする前に、開発マシンで
vpt validateを実行します。vpt validateコマンドには静的解析チェックが組み込まれており、開発者が古い起動構成構文からこのドキュメントで説明されている新しい起動構成構文に移行する際に役立ちます。警告とエラーの両方に対処します。具体的なエラー文字列と修正アクションについては、移行エラーを参照してください。Amazonでは、今後より多くの静的チェックを提供することで、アプリ開発を一層効果的に支援し、アプリの市場投入までの時間を短縮できるようにする予定です。VegaパッケージングツールをVegaアプリパッケージで使用する方法を参照してください。 -
今後のリリースではアクセス制御を有効にし、アプリ開発者がマニフェストを適切に構成する時間を確保できるようにする予定です。ただし、アプリに対してローカルでの強制を有効にすることで、アプリが準拠していることを検証できます。強制を有効にするには、
vmsgr enforce-securityを使用します。ログから違反を検出する方法の詳細については、アクセス制御によるテストを参照してください。違反を検出したら、機能のドキュメントを使用して、マニフェストに追加する適切なスニペットを特定できます。特定のエラーが出力される理由がわからない場合は、次のヒントを使用して不足しているモジュールを特定することもできます。 -
項目1で説明されている静的チェックは、古い構文と新しい構文の一貫性のみを確認できます。ただし、両方のセクションで同じ間違いを犯した場合（間違った権限を要求した場合など）、またはこれまで存在しなかったまったく新しい機能を統合した場合は、
vmsgr check-accessコマンドをデバイスで使用することで、メッセージアクセス制御が正しく構成されていることをさらに確認できます。開発者は開発サイクルでこのCLIを使用することで、マニフェスト内のエラーを検出できます。このCLIは、QAで発見された問題をデバッグするためにも使用できます。このCLIの使用方法の詳細については、アクセス制御の確認を参照してください。
移行エラー
警告やエラーを解釈する際は、以下の例を参考にしてください。この手順により、アプリをプログラムで起動する場合とCLIを使用する場合との間で不整合が発生していないことを確認できます。
[[message]]セクションがない場合
manifest.toml:21:6 error: [offers.interaction.id] Component 'com.amazon.samplepkg.component.task' is found in [[offers.interaction]] but corresponding 'pkg://com.amazon.samplepkg.component.task' is not found in [[message]]
help: For all components declared as interactions, add corresponding 'pkg://<componentId>' URI as a [[message]] in your manifest
[[offers.message-target]]セクションがない場合
manifest.toml:18:16 error: [offers.interaction.launch_uris] URI 'samplepkg://main' found in [[offers.interaction]] but not in [[offers.message-target]]
help: For all launch-uris listed as interactions in [[offers.interaction]], add corresponding [[offers.message-target]].May also require definition of a [[message]] section if you are the owner of the URI, otherwise add a [[wants.module]] entry to the manifest to make the URI accessible to your app.
URIが[[offers.message-target]]に指定されていない場合
manifest.toml:18:16 error: [offers.interaction.launch_uris] For URI 'samplepkg://main', [[offers.interaction]] component '{"com.amazon.samplepkg.component.main"}' is different from [[offers.message-target]] component 'com.amazon.samplepkg.component.task'
help: Use same component for a URI in [[offers.interaction]] and [[offers.message-target]]
アプリマニフェストの詳細については、Vegaアプリのマニフェストファイルの概要を参照してください。
アクセス制御によるテスト
enforce-security CLIは、特定のパッケージの強制をローカルで有効にするようにシステムを構成します。有効にした後、さまざまなアプリの使用シナリオを実行して、どこで不具合が発生するかを検出します。デバイスログを収集し、以下に示すエラー文字列をフィルタリングして、記載されている適切なアクションを実行します。設定は再起動時に自動的にクリアされることに注意してください。再起動後にコマンドを再実行して、再度設定を適用します。
使用方法：
vmsgr enforce-security --package <パッケージID>
ここで、パッケージIDは送信者または受信者のパッケージIDです。
以下に例を示します。
vmsgr enforce-security --package com.amazon.messaging.mr33.okidl.ac.example1
コマンドを適用すると、特定のログパターンを検索して次の欠落セクションを検出できます。
[[wants.module]]セクションがない場合：
ERROR com.amazon.message_router.external: [...] Message is not accessible for package: 'com.amazon.messaging.mr33.okidl.ac.example1'
アプリは、マニフェスト内のモジュールへのアクセスをリクエストしていません。マニフェストに[[wants.module]]エントリを追加します。
[[wants.privilege]]セクションがない場合：
ERROR com.amazon.message_router.external: [...] Package: 'com.amazon.messaging.mr33.okidl.ac.example2' is missing privileges for URI: 'launch://com.amazon.messaging.mr33.okidl.ac.example2/component'
アプリがマニフェストでこの権限をリクエストしていないか、デバイスユーザーによって権限が付与されていません。マニフェストに[[wants.privilege]]エントリを追加し、実行時権限の場合はユーザーに権限の付与をリクエストします。実行時権限を必要とする機能については、機能ドキュメントを確認してください。
[[offers.message-target]]セクションがない場合：
ERROR com.amazon.message_router.core: [...] Failed to get package and ACL info for the uri: launch://com.amazon.messaging.mr33.okidl.ac.example2/component pid: 25509, status: Unspecified run-time error
アプリは、このURIに応答して起動するよう構成されていません。このURIに[[offers.message-target]]エントリを追加し、それに応じて起動するライフサイクルコンポーネントを指定します。エラーがアプリに関連しているかどうかわからない場合は、Amazonにお問い合わせください。
- メッセージ定義がない場合：
ERROR com.amazon.message_router.external: [...] Message uri 'broadcast://*/com.amazon.messaging/messaging-mr33-example/subtopic' is not defined in any module inside manifest/conf
アプリ開発者がこのエラーに遭遇することは想定されていません。このエラーが生じた場合は、バグを報告してAmazonに調査を依頼してください。
アクセス制御の確認
check-access CLI は、アプリがモジュールと権限のチェックに合格したかどうかを確認し、シェルに情報を出力します。たとえば、パッケージIDがcom.amazon.messaging.mr33.okidl.ac.example1で、URI pkg://com.amazon.messaging.mr33.okidl.ac.example2.explicit_privilegesを取得したい場合、次のCLIコマンドを使用します。
使用方法：
vmsgr check-access --package <パッケージID> <URI>
ここで、パッケージIDは送信者または受信者のパッケージID、URIはアクセス制御をテストするためのURIです。
例：
vmsgr check-access \
--package com.amazon.messaging.mr33.okidl.ac.example1 \
pkg://com.amazon.messaging.mr33.okidl.ac.example2.explicit_privileges
Checking access for package: com.amazon.messaging.mr33.okidl.ac.example1
Dependencies for: pkg://com.amazon.messaging.mr33.okidl.ac.example2.explicit_privileges
Canonical Uri: pkg://com.amazon.messaging.mr33.okidl.ac.example2.explicit_privileges
Required Module: /com.amazon.messaging.mr33.okidl.ac.example2@IAcExample2 [PASS]
Required Sender Privilege(s): [com.amazon.security.example1]
Sender Privilege Check: [PASS]
Message Target Check (Not applicable to broadcast or unicast): [PASS]
Required Receiver Privilege(s): [com.amazon.security.example2]
Receiver Privilege Check: [FAIL]
メッセージ送信者の場合は、「Required Module」と「Sender Privilege(s)」のチェックに合格していることを確認してください。ブロードキャストメッセージやユニキャストメッセージの受信者の場合は、「Required Module」と「Receiver Privilege(s)」のチェックに合格していることを確認してください。メッセージURIに応答してアプリを起動する必要がある場合は、「Required Module」、「Receiver Privilege(s)」、「Message Target」のチェックに合格していることを確認してください。
この例の場合、アプリの[[wants.module]]は正常に存在していますが、メッセージを受信するための適切な権限がありません。これは[[wants.privilege]]が欠落していることが原因である可能性があります。必要に応じて追加してください。マニフェストエントリが適切で、タイプミスがないことを確認した後にも権限チェックに失敗する場合は、権限にユーザーの同意が必要であるもののその同意がまだされていないことが原因である可能性があります。
関連トピック
- メッセージアドレス指定スキーム
- Linking（英語のみ）
Last updated: 2025年9月30日
