消息传递用户指南
本指南详细介绍了Vega SDK中Vega消息传递库 (com.amazon.kepler.experimental_mr33.messaging) 的用法，它可提供消息传递通信机制。
您可以通过多种方式使用Vega消息传递，例如启动应用、使用广播发布系统变更以及应用间通信。与过程调用相比，面向消息的通信将发送者和接收者的执行分离，因此它们不必同时运行。这通过使用名为消息路由器的集中代理服务来实现。
这种机制也是使用Vega任务库 (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"
添加安全规则
您可以通过为消息部分指定必要的发送者和接收者权限来限制可以发送或接收消息的人员。
例如，假设您有一个名为"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"
调试常见问题解答
为什么即使我注册了筛选器仍未收到我的消息？
要接收消息，注册筛选器的消息通道应保持活动状态。如果该通道被终止或超出作用域，则无法再接收消息。
为什么即使通道已处于活动状态也没有收到我的消息？
请确保在发送者发送消息之前，您的频道注册了筛选器。您的频道只会接收筛选器成功注册后发送的消息。
在设备上使用vmsgr CLI（命令行界面）确认是否正在发送所关注的广播/单播。
在正在发送消息但应用未收到消息的情况下，vmsgr listen命令允许开发者确认消息是否正在发送。从根shell或非根shell运行此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命令中，可以帮助开发者尝试从旧的启动配置语法迁移到本文档中描述的新启动配置语法。解决警告和错误。有关特定的错误字符串和更正措施，请参阅迁移错误。随着时间推移，亚马逊将提供额外的静态检查，以更好地协助您的应用开发过程并缩短应用的上市时间。请参阅使用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.
[[offers.message-target]] 中缺少URI
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>
其中package-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]] 条目，并指定作为响应而要启动的生命周期组件。如果不确定错误是否与您的应用有关，请联系亚马逊。
- 缺少消息定义:
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
预计应用开发者不会遇到此错误。如果您遭遇该错误，请提交错误供亚马逊调查。
验证访问控制
check-access CLI验证应用是否通过了模块和权限检查，并在shell上列出信息性输出。例如，如果您的程序包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]]] 。如果缺少该项，请进行添加。如果您拥有正确的清单条目并且已确认没有打错字，则如果所需权限需要用户同意，但尚未获得用户授予的同意，则权限检查将失败。
相关主题
Last updated: 2025年9月30日
