通过

如何为客户端生成客户端访问 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 门户复制

在 Azure 门户 的“密钥”选项卡中，有一个“客户端 URL 生成器”工具，可用于为你快速生成客户端访问 URL，如下图所示。 不存储此处输入的值。

注意，对于 MQTT 客户端，应该在“客户端访问 URL”文本框前面的下拉菜单中选择“MQTT 客户端”。

Azure Web PubSub 客户端 URL 生成器的屏幕截图。

从服务 SDK 生成

可以使用 Web PubSub 服务器 SDK 生成相同的客户端访问 URL。

  1. 按照服务器 SDK 入门创建 WebPubSubServiceClient 对象 service

  2. 通过调用 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"],
});

在实际代码中，我们通常有一个服务器端来托管生成客户端访问 URL 的逻辑。 当客户端请求传入时，服务器端可以使用常规身份验证/授权工作流来验证客户端请求。 只有有效的客户端请求才能取回客户端访问 URL。

调用“生成客户端令牌”REST API

可以在服务中启用 Microsoft Entra ID，并使用 Microsoft Entra 令牌来调用生成客户端令牌 REST API，以获取供客户端使用的令牌。

  1. 按照从应用程序授权中的要求启用 Microsoft Entra ID。

  2. 按照获取 Microsoft Entra 令牌中的要求，使用 Postman 获取 Microsoft Entra 令牌。

  3. 通过 Postman 使用 Microsoft Entra 令牌调用 :generateToken：

    注意

    请使用最新版本的 Postman。 旧版本的 Postman 在支持路径中的冒号 : 时存在一些问题。

    1. 对于 URI，请输入 https://{Endpoint}/api/hubs/{hub}/:generateToken?api-version=2024-01-01。 如果要为 MQTT 客户端生成令牌，请将查询参数 &clientType=mqtt 附加到 URL。

    2. 在“身份验证”选项卡上，选择“持有者令牌”，并粘贴在上一步获取的 Microsoft Entra 令牌

    3. 选择“发送”，然后就会在响应中看到“客户端访问令牌”：

      {
  "token": "ABCDEFG.ABC.ABC"
}