本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 添加传播属性以丰富消息
<a name="thing-types-propagating-attributes"></a>

在中 AWS IoT Core，您可以通过添加传播属性来丰富来自设备的 MQTT 消息，这些属性是来自事物属性或连接详细信息的上下文元数据。这个过程称为消息丰富，在各种场景中都很有用。例如，您可以为每个入站发布操作丰富消息，而无需进行任何设备端更改或需要使用规则。通过利用传播属性，您可以受益于更高效和更具成本效益的方式来丰富您的物联网数据，而无需配置规则或管理重新发布配置的复杂性。

消息充实功能可供使用[基本采](https://docs.aws.amazon.com//iot/latest/developerguide/iot-basic-ingest.html)集和[消息代理](https://docs.aws.amazon.com//iot/latest/developerguide/mqtt.html)的 AWS IoT Core 客户使用。需要注意的是，虽然发布设备可以使用任何 MQTT 版本，但订阅者（使用消息的应用程序或服务）必须支持 [MQTT 5](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html) 才能接收带有传播属性的丰富消息。丰富的消息将作为 MQTT 5 用户属性添加到从设备发布的每条消息中。如果您使用[规则](https://docs.aws.amazon.com//iot/latest/developerguide/iot-rules.html)，您可以利用 [get\$1user\$1properties](https://docs.aws.amazon.com//iot/latest/developerguide/iot-sql-functions.html#iot-sql-function-get-user-properties) 函数来检索丰富的数据，以便基于该数据进行消息路由或处理。

在中 AWS IoT Core，您可以使用或在创建或更新事物类型时添加传播属性。 AWS 管理控制台 AWS CLI

**重要**  
添加传播属性时，必须确保发布消息的客户端已使用证书进行身份验证。有关更多信息，请参阅 [客户端身份验证](client-authentication.md)。

**注意**  
如果您尝试在控制台内使用 MQTT 测试客户端测试此功能，它可能无法工作，因为此功能要求 MQTT 客户端使用关联的证书进行身份验证。

## AWS 管理控制台
<a name="configure-propagating-attributes-console"></a>

**要添加用于丰富消息的传播属性，请使用 AWS 管理控制台**

1. 在 AWS IoT 控制台中打开[AWS IoT 主页](https://console.aws.amazon.com//iot/home#/home)。在左侧导航栏中，从**管理**下选择**所有设备**。然后选择**事物类型**。

1. 在**事物类型**页面上，选择**创建事物类型**。

   要通过更新事物类型来配置消息丰富，请选择一个事物类型。然后在事物类型详细信息页面上，选择**更新**。

1. 在**创建事物类型**页面上，在**事物类型属性**中选择或输入事物类型信息。

   如果您选择更新事物类型，您将在上一步选择**更新**后看到**事物类型属性**。

1. 在**附加配置**中，展开**传播属性**。然后选择**事物属性**并输入要填充到已发布 MQTT5 消息的事物属性。使用控制台，您最多可以添加三个事物属性。

   在**传播属性**部分，选择**连接属性**并输入属性类型，以及可选的属性名称。

1. 可选地添加标签。然后选择**创建事物类型**。

   如果您选择更新事物类型，请选择**更新事物类型**。

## AWS CLI
<a name="configure-propagating-attributes-cli"></a>

1. 要通过使用创建新的事物类型来添加用于丰富消息的传播属性 AWS CLI，请运行[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/create-thing-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/create-thing-type.html)命令。示例命令如下。

   ```
   aws iot create-thing-type \
       --thing-type-name "LightBulb" \
       --thing-type-properties "{\"mqtt5Configuration\":{\"propagatingAttributes\":[{\"userPropertyKey\":\"iot:ClientId\", \"connectionAttribute\":\"iot:ClientId\"}, {\"userPropertyKey\":\"test\", \"thingAttribute\":\"A\"}]}}" \
   ```

   此命令的输出可能如下所示。

   ```
   {
   	"thingTypeName": "LightBulb",
   	"thingTypeArn": "arn:aws:iot:us-west-2:123456789012:thingtype/LightBulb",
   	"thingTypeId": "ce3573b0-0a3c-45a7-ac93-4e0ce14cd190"
   }
   ```

1. 要使用更新事物类型来配置消息丰富 AWS CLI，请运行[https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-thing-type.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/update-thing-type.html)命令。请注意，运行此命令时您只能更新 `mqtt5Configuration`。示例命令如下。

   ```
   aws iot update-thing-type \
       --thing-type-name "MyThingType" \
       --thing-type-properties "{\"mqtt5Configuration\":{\"propagatingAttributes\":[{\"userPropertyKey\":\"iot:ClientId\", \"connectionAttribute\":\"iot:ClientId\"}, {\"userPropertyKey\":\"test\", \"thingAttribute\":\"A\"}]}}" \
   ```

   此命令不会生成任何输出。

1. 要描述一个事物类型，请运行 `describe-thing-type` 命令。此命令将产生一个输出，其中在 `thing-type-properties` 字段中包含消息丰富配置信息。示例命令如下。

   ```
   aws iot describe-thing-type \
       --thing-type-name "LightBulb"
   ```

   输出类似于以下内容：

   ```
   {
   	"thingTypeName": "LightBulb",
   	"thingTypeId": "bdf72512-0116-4392-8d79-bf39b17ef73d",
   	"thingTypeArn": "arn:aws:iot:us-east-1:123456789012:thingtype/LightBulb",
   	"thingTypeProperties": {
   		"mqtt5Configuration": {
   			"propagatingAttributes": [
   				{
   					"userPropertyKey": "iot:ClientId",
   					"connectionAttribute": "iot:ClientId"
   				},
   				{
   					"userPropertyKey": "test",
   					"thingAttribute": "attribute"
   				}
   			]
   		}
   	},
   	"thingTypeMetadata": {
   		"deprecated": false,
   		"creationDate": "2024-10-18T17:37:46.656000+00:00"
   	}
   }
   ```

有关更多信息，请参阅 [事物类型](thing-types.md)。