如何为客户端生成客户端访问 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 门户复制一个
若要进行开发，请使用 Web PubSub 服务器 SDK 生成值
如果使用 Microsoft Entra ID，还可以调用 Generate 客户端令牌 REST API

从 Azure 门户复制

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

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

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

从服务 SDK 生成

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

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

通过调用 WebPubSubServiceClient.getClientAccessToken 来生成客户端访问 URL：

生成客户端访问令牌

// for web pubsub native clients
let token = await serviceClient.getClientAccessToken();

// for mqtt clients
let token = await serviceClient.getClientAccessToken({ clientProtocol: "mqtt" });

配置用户 ID

let token = await serviceClient.getClientAccessToken({ userId: "user1" });

配置令牌的生存期

let token = await serviceClient.getClientAccessToken({
  expirationTimeInMinutes: 5,
});

配置客户端在使用此客户端访问 URL 进行连接时的角色。有关可分配的其他角色，请参阅 “权限”。

let token = await serviceClient.getClientAccessToken({
  roles: ["webpubsub.joinLeaveGroup.group1"], // This role allows the client to join and leave "group1"
});

配置一个组group1，这样客户端在通过此客户端访问 URL 连接后即可加入该组。
```
let token = await serviceClient.getClientAccessToken({
  groups: ["group1"],
});
```

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

通过调用 WebPubSubServiceClient.GetClientAccessUri 来生成客户端访问 URL：

生成客户端访问令牌

// for web pubsub native clients
var url = service.GetClientAccessUri();

// for mqtt clients
var url = service.GetClientAccessUri(clientProtocol: WebPubSubClientProtocol.Mqtt);

配置用户 ID

var url = service.GetClientAccessUri(userId: "user1");

配置令牌的生命周期

var url = service.GetClientAccessUri(expiresAfter: TimeSpan.FromMinutes(5));

配置使用此客户端访问 URL 进行连接时分配给客户端的角色。有关可分配的其他角色，请参阅 “权限”。

var url = service.GetClientAccessUri(roles: new string[] {
  "webpubsub.joinLeaveGroup.group1", // This role allows the client to join and leave "group1"
  "webpubsub.sendToGroup.group1" // This role allows the client to send messages to "group1"
});

配置组group1，使客户端通过此客户端访问 URL 连接后能加入该组
```
var url = service.GetClientAccessUri(groups: new string[] { "group1" });
```

请参阅服务器 SDK 入门指南以创建 WebPubSubServiceClient 对象 service

通过调用 WebPubSubServiceClient.get_client_access_token 来生成客户端访问 URL：

生成客户端访问令牌

# for web pubsub native clients
token = service.get_client_access_token();

# for mqtt clients
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 进行连接时分配给客户端的角色。有关可分配的其他角色，请参阅 “权限”。

token = service.get_client_access_token(roles=[
  "webpubsub.joinLeaveGroup.group1", # This role allows the client to join and leave "group1"
  "webpubsub.sendToGroup.group1" # This role allows the client to send messages to "group1"
])

配置一个组 group1，客户端将在使用此客户端访问 URL 连接后加入该组。
```
token = service.get_client_access_token(groups=["group1"])
```

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

通过调用 WebPubSubServiceClient.getClientAccessToken 来生成客户端访问 URL：

为 Web PubSub 原生客户端生成客户端访问令牌

GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
WebPubSubClientAccessToken token = service.getClientAccessToken(option);

为 MQTT 客户端生成客户端访问令牌

GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
option.setWebPubSubClientProtocol(WebPubSubClientProtocol.MQTT);
WebPubSubClientAccessToken token = service.getClientAccessToken(option);

配置用户 ID

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 进行连接时分配给客户端的角色。有关可分配的其他角色，请参阅 “权限”。

GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
option.addRole("webpubsub.joinLeaveGroup.group1"); // This role allows the client to join and leave "group1"
option.addRole("webpubsub.sendToGroup.group1"); // This role allows the client to send messages to "group1"
WebPubSubClientAccessToken token = service.getClientAccessToken(option);

配置一个组group1，客户端在通过此客户端访问链接连接后会加入该组。

GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
option.setGroups(Arrays.asList("group1")),
WebPubSubClientAccessToken token = service.getClientAccessToken(option);

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

通过 REST API `:generateToken` 生成

还可以通过调用 Generate 客户端令牌 REST API 来使用Microsoft Entra ID并生成令牌。

注意

Web PubSub 不建议手动为Microsoft Entra ID服务主体创建Microsoft Entra ID令牌。这是因为每个Microsoft Entra ID令牌的生存期较短，通常在一小时内过期。之后，必须手动生成替换Microsoft Entra ID令牌。请改用我们的SDKs，它们会自动为您生成和替换过期的 Microsoft Entra ID 令牌。

通过从应用程序授权启用 Microsoft Entra ID。
获取Microsoft Entra令牌。
使用 Microsoft Entra 令牌调用 :generateToken。

收集以下信息：

值名称	如何获取值
租户ID	TenantId 是您注册的应用程序中“概述”窗格上的“目录（租户）ID”的值。
ClientId	ClientId 是注册的应用程序的“概述”窗格中的“应用程序(客户端) ID”值。
ClientSecret	ClientSecret 是在步骤 1 中添加的客户端机密的值

从Microsoft 标识平台获取Microsoft Entra ID令牌

我们将使用 CURL 工具来演示如何调用 REST API。该工具捆绑到 Windows 10/11 中，可以按照 Install CURL 安装该工具。

# set necessary values, replace the placeholders with your actual values
export TenantId=<your_tenant_id>
export ClientId=<your_client_id>
export ClientSecret=<your_client_secret>

curl -X POST "https://login.chinacloudapi.cn/$TenantId/oauth2/v2.0/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "client_id=$ClientId" \
--data-urlencode "client_secret=$ClientSecret" \
--data-urlencode "scope=https://webpubsub.azure.com/.default"

上述 curl 命令向 Azure 身份终结点发送 POST 请求，以获取 Microsoft Entra ID 令牌。在响应中，你可以在 access_token 字段看到 Microsoft Entra ID 令牌。复制并存储该 URL，以供稍后使用。

使用Microsoft Entra ID令牌调用 :generateToken

# Replace the values in {} with your actual values.
export Hostname={your_service_hostname}
export Hub={your_hub}
export Microsoft_Entra_Token={Microsoft_entra_id_token_from_previous_step}
curl -X POST "https://$Hostname/api/hubs/$Hub/:generateToken?api-version=2024-01-01" \
-H "Authorization: Bearer $Microsoft_Entra_Token" \
-H "Content-Type: application/json"

如果需要为 MQTT 客户端生成令牌，请将 clientType=mqtt 参数追加到 URL 中：

export Hostname={your_service_hostname}
export Hub={your_hub}
export Microsoft_Entra_Token={Microsoft_entra_id_token_from_previous_step}
curl -X POST "https://$Hostname/api/hubs/$Hub/:generateToken?api-version=2024-01-01&clientType=mqtt" \
-H "Authorization: Bearer $Microsoft_Entra_Token" \
-H "Content-Type: application/json"

运行 cURL 命令后，应该收到如下所示的响应：

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

Last updated on 2026-04-13

Compartilhar via

如何为客户端生成客户端访问 URL

从 Azure 门户复制

从服务 SDK 生成

通过 REST API :generateToken 生成

Recursos adicionais

通过 REST API `:generateToken` 生成