你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

MQTT 客户端

项目
11/16/2023

本文介绍如何配置 MQTT 客户端和客户端组。

客户端

客户端可以是设备或应用程序，例如发送/接收 MQTT 消息的设备或车辆。

例如，假设某家车队管理公司拥有数百辆卡车和其他货运车。你可以通过向/从云服务发送和接收 MQTT 消息来改进其路线规划、跟踪、驾驶员安全保障和可预测维护功能。

在此方案中，可以将车辆配置为发布/订阅各种主题的客户端，例如天气信息、路况、地理定位、引擎性能以及车辆的其他磨损情况。而且，在将车辆配置为客户端时，还可以在客户端元数据中包括一组属性，例如车辆类型、年份、制造和型号、最大负载容量等。

注意

客户端名称的长度为 1-128 个字符。
客户端名称可以包含字母数字、连字符 (-)、冒号 (:)、点 (.) 和下划线 (_)，不能包含空格。它区分大小写，并且在每个命名空间中必须唯一。

客户端元数据的关键术语

客户端身份验证名称：可为没有 Azure 资源管理器命名约束的客户端提供唯一标识符。该名称是必填字段，如果未显式提供，则默认会使用客户端名称。

在命名空间内，不能有任何两个客户端使用相同的身份验证名称。在对客户端进行身份验证时，我们会将客户端身份验证名称视为不区分大小写。

我们会保留你在客户端中配置的客户端身份验证名称的原始大小写。我们在路由扩充、主题空间匹配等功能中使用在创建客户端时提供的原始客户端身份验证名称（区分大小写）。

注意

客户端身份验证名称的长度为 1-128 个字符，它应该是 UTF-8 字符串，此外没有其他限制
客户端身份验证名称区分大小写，并且在每个命名空间中必须唯一（在确定唯一性时忽略大小写）

客户端证书身份验证验证方案：若要使用 CA 证书进行身份验证，可以选择以下选项之一来指定客户端标识在客户端证书中的位置。当客户端尝试连接到服务时，服务将在此证书字段中查找客户端标识，并将其与客户端身份验证名称相匹配，以便对客户端进行身份验证。

支持五个证书字段：

使用者与身份验证名称匹配
DNS 与身份验证名称匹配
URI 与身份验证名称匹配
IP 与身份验证名称匹配
电子邮件与身份验证名称匹配

使用自签名证书对客户端进行身份验证时，请使用“指纹匹配”选项。

注意

clientCertificateAuthentication 始终需要包含有效的 validationScheme 值。
authenticationName 不是必需的，但在首次创建请求后，authenticatioName 值默认为 ARM 名称，然后无法更新。
无法更新 authenticationName。
如果 validationScheme 不是 ThumbprintMatch，则无法提供 allowedThumbprints 列表。
仅当 validationScheme 是 ThumbprintMatch 且至少提供一个指纹时，才能提供 allowedThumbprints 列表，并且在这种情况下必须提供该列表。
allowedThumbprints 最多只能保存 2 个指纹。
允许的 validationScheme 值为 SubjectMatchesAuthenticationName、DnsMatchesAuthenticationName、UriMatchesAuthenticationName、IpMatchesAuthenticationName、EmailMatchesAuthenticationName、ThumbprintMatch
使用指纹可以跨多个客户端重复使用同一证书。对于其他类型的验证，身份验证名称需要位于客户端证书的所选字段中。

客户端属性

客户端属性是用户定义的一组键值对或标记，用于提供有关客户端的信息。

这些客户端属性可用于创建客户端组。例如，可以将半挂卡车类型的所有车辆分组到一组，将皮卡类型的所有车辆分组到另一组。

这些属性在客户端组查询中用于筛选一组客户端。属性可以描述客户端的物理或功能特征。典型的属性可能是客户端的“类型”。

下面是一个示例：

类型：值可以是“传感器”、“恒温器”或“车辆”

下面是具有属性定义的客户端的示例架构：

{  
    "id": "device123",  
    "attributes": {  
        "type": "home-sensors",
        "sensors": ["motion", "noise", "light"]
     }
}

配置客户端属性时，请考虑客户端发布（订阅）的主题。从主题到客户端反向分析有助于更轻松地识别客户端角色之间的共性，并定义客户端属性，使客户端分组变得更简单。

注意

客户端属性键在客户端中必须唯一。键不能重复。
客户端属性值的类型可为 string、integer 或 array of strings。
客户端的客户端属性总大小必须始终小于 4KB。
客户端属性名称（键）只能包含字母数字字符和下划线 (_)。

示例合约

基于证书链的客户端身份验证示例

{
    "properties": {
        "authenticationName": "127.0.0.1",
        "state": "Enabled",
        "clientCertificateAuthentication": {
            "validationScheme": "IpMatchesAuthenticationName"
        },
        "attributes": {
            "room": "345",
            "floor": 3,
            "bldg": "17"
        },
        "description": "Description of the client"
    }
}

基于自签名证书指纹的客户端身份验证示例

{
    "properties": {
        "authenticationName": "abcd@domain.com-1",
        "state": "Enabled",
        "clientCertificateAuthentication": {
            "validationScheme": "ThumbprintMatch",
            "allowedThumbprints": ["primary", "secondary"]
        },
        "attributes": {
            "room": "345",
            "floor": "3",
            "bldg": 17
        },
        "description": "Description of the client"
    }
}

Azure 门户配置

使用以下步骤创建客户端：

在 Azure 门户中转到你的命名空间
在“客户端”下，选择“+ 客户端”。
选择客户端证书身份验证验证方案。有关客户端身份验证配置的详细信息，请参阅客户端身份验证一文。

添加客户端属性。

选择“创建”

Azure CLI 配置

使用以下命令创建/显示/删除客户端

创建客户端

az eventgrid namespace client create -g myRG --namespace-name myNS -n myClient

获取客户端

az eventgrid namespace client show -g myRG --namespace-name myNS -n myClient

删除客户端

az eventgrid namespace client delete -g myRG --namespace-name myNS -n myClient

后续步骤

了解客户端身份验证

通过