如何为客户端生成客户端访问 URL
客户端(无论是浏览器 💻、移动应用 📱 还是 IoT 设备 💡)使用客户端访问 URL 来连接资源并对其进行身份验证。
URL 遵循以下模式:
- 对于 MQTT 客户端,是
wss://<service_name>.webpubsub.azure.com/clients/mqtt/hubs/<hub_name>?access_token=<token>
。
- 对于所有其他客户端,是
wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>
。
本文介绍获取客户端访问 URL 的几种方法。
在 Azure 门户 的“密钥”选项卡中,有一个“客户端 URL 生成器”工具,可用于为你快速生成客户端访问 URL,如下图所示。 不存储此处输入的值。
注意,对于 MQTT 客户端,应该在“客户端访问 URL”文本框前面的下拉菜单中选择“MQTT 客户端”。
可以使用 Web PubSub 服务器 SDK 生成相同的客户端访问 URL。
按照服务器 SDK 入门创建 WebPubSubServiceClient
对象 service
通过调用 WebPubSubServiceClient.getClientAccessToken
来生成客户端访问 URL:
生成 MQTT 客户端访问令牌
let token = await serviceClient.getClientAccessToken({ clientProtocol: "mqtt" });
配置用户 ID
let token = await serviceClient.getClientAccessToken({ userId: "user1" });
配置令牌的生存期
let token = await serviceClient.getClientAccessToken({
expirationTimeInMinutes: 5,
});
配置一个角色,以便在使用此客户端访问 URL 进行连接时可以直接加入组 group1
let token = await serviceClient.getClientAccessToken({
roles: ["webpubsub.joinLeaveGroup.group1"],
});
配置一个角色,以便在使用此客户端访问 URL 进行连接时,客户端可以直接将消息发送到组 group1
let token = await serviceClient.getClientAccessToken({
roles: ["webpubsub.sendToGroup.group1"],
});
配置组 group1
,以便在使用此客户端访问 URL 进行连接后,客户端可以加入它
let token = await serviceClient.getClientAccessToken({
groups: ["group1"],
});
按照服务器 SDK 入门创建 WebPubSubServiceClient
对象 service
通过调用 WebPubSubServiceClient.GetClientAccessUri
来生成客户端访问 URL:
生成 MQTT 客户端访问令牌
var url = service.GetClientAccessUri(clientProtocol: WebPubSubClientProtocol.Mqtt);
配置用户 ID
var url = service.GetClientAccessUri(userId: "user1");
配置令牌的生存期
var url = service.GetClientAccessUri(expiresAfter: TimeSpan.FromMinutes(5));
配置一个角色,以便在使用此客户端访问 URL 进行连接时可以直接加入组 group1
var url = service.GetClientAccessUri(roles: new string[] { "webpubsub.joinLeaveGroup.group1" });
配置一个角色,以便在使用此客户端访问 URL 进行连接时,客户端可以直接将消息发送到组 group1
var url = service.GetClientAccessUri(roles: new string[] { "webpubsub.sendToGroup.group1" });
配置组 group1
,以便在使用此客户端访问 URL 进行连接后,客户端可以加入它
var url = service.GetClientAccessUri(groups: new string[] { "group1" });
按照服务器 SDK 入门创建 WebPubSubServiceClient
对象 service
通过调用 WebPubSubServiceClient.get_client_access_token
来生成客户端访问 URL:
生成 MQTT 客户端访问令牌
token = service.get_client_access_token(client_protocol="MQTT")
配置用户 ID
token = service.get_client_access_token(user_id="user1")
配置令牌的生存期
token = service.get_client_access_token(minutes_to_expire=5)
配置一个角色,以便在使用此客户端访问 URL 进行连接时可以直接加入组 group1
token = service.get_client_access_token(roles=["webpubsub.joinLeaveGroup.group1"])
配置一个角色,以便在使用此客户端访问 URL 进行连接时,客户端可以直接将消息发送到组 group1
token = service.get_client_access_token(roles=["webpubsub.sendToGroup.group1"])
配置组 group1
,以便在使用此客户端访问 URL 进行连接后,客户端可以加入它
token = service.get_client_access_token(groups=["group1"])
按照服务器 SDK 入门创建 WebPubSubServiceClient
对象 service
通过调用 WebPubSubServiceClient.getClientAccessToken
来生成客户端访问 URL:
GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
option.setUserId(id);
WebPubSubClientAccessToken token = service.getClientAccessToken(option);
配置令牌的生存期
GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
option.setExpiresAfter(Duration.ofDays(1));
WebPubSubClientAccessToken token = service.getClientAccessToken(option);
配置一个角色,以便在使用此客户端访问 URL 进行连接时可以直接加入组 group1
GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
option.addRole("webpubsub.joinLeaveGroup.group1");
WebPubSubClientAccessToken token = service.getClientAccessToken(option);
配置一个角色,以便在使用此客户端访问 URL 进行连接时,客户端可以直接将消息发送到组 group1
GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
option.addRole("webpubsub.sendToGroup.group1");
WebPubSubClientAccessToken token = service.getClientAccessToken(option);
配置组 group1
,以便在使用此客户端访问 URL 进行连接后,客户端可以加入它
GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
option.setGroups(Arrays.asList("group1")),
WebPubSubClientAccessToken token = service.getClientAccessToken(option);
在实际代码中,我们通常有一个服务器端来托管生成客户端访问 URL 的逻辑。 当客户端请求传入时,服务器端可以使用常规身份验证/授权工作流来验证客户端请求。 只有有效的客户端请求才能取回客户端访问 URL。
可以在服务中启用 Microsoft Entra ID,并使用 Microsoft Entra 令牌来调用生成客户端令牌 REST API,以获取供客户端使用的令牌。
按照从应用程序授权中的要求启用 Microsoft Entra ID。
按照获取 Microsoft Entra 令牌中的要求,使用 Postman 获取 Microsoft Entra 令牌。
通过 Postman 使用 Microsoft Entra 令牌调用 :generateToken
:
备注
请使用最新版本的 Postman。 旧版本的 Postman 在支持路径中的冒号 :
时存在一些问题。
对于 URI,请输入 https://{Endpoint}/api/hubs/{hub}/:generateToken?api-version=2024-01-01
。 如果要为 MQTT 客户端生成令牌,请将查询参数 &clientType=mqtt
附加到 URL。
在“身份验证”选项卡上,选择“持有者令牌”,并粘贴在上一步获取的 Microsoft Entra 令牌
选择“发送”,然后就会在响应中看到“客户端访问令牌”:
{
"token": "ABCDEFG.ABC.ABC"
}