如何產生用戶端的用戶端存取 URL

用戶端 (可以是瀏覽器 💻、行動應用程式 📱 或 IoT 裝置 💡) 會使用用戶端存取 URL 來連線您的資源並進行驗證。 此 URL 遵循 wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token> 模式。 本文說明取得用戶端存取 URL 的數種方式。

• 如需快速開始，請從 Azure 入口網站複製一個 URL
• 若要進行開發，請使用 Web PubSub 伺服器 SDK 產生此值
• 如果使用 Microsoft Entra ID，也可以叫用產生用戶端權杖 REST API

從 Azure 入口網站複製

在 Azure 入口網站的 [金鑰] 索引標籤中，有用戶端 URL 產生器工具可快速為您產生用戶端存取 URL，如下圖所示。 不會儲存在此輸入的值。

從服務 SDK 產生

您可使用 Web PubSub 伺服器 SDK 來產生相同的用戶端存取 URL。

JavaScript

1. 請遵循開始使用伺服器 SDK，以建立 WebPubSubServiceClient 物件 service

2. 呼叫 WebPubSubServiceClient.getClientAccessToken 以產生用戶端存取 URL：

   • 設定使用者識別碼

     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"],
     });
     

C#

1. 請遵循開始使用伺服器 SDK，以建立 WebPubSubServiceClient 物件 service

2. 呼叫 WebPubSubServiceClient.GetClientAccessUri 以產生用戶端存取 URL：

   • 設定使用者識別碼

     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" });
     

Python

1. 請遵循開始使用伺服器 SDK，以建立 WebPubSubServiceClient 物件 service

2. 呼叫 WebPubSubServiceClient.get_client_access_token 以產生用戶端存取 URL：

   • 設定使用者識別碼

     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"])
     

Java

1. 請遵循開始使用伺服器 SDK，以建立 WebPubSubServiceClient 物件 service

2. 呼叫 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。

叫用產生用戶端權杖 REST API

您可以在服務中啟用 Microsoft Entra ID，並使用 Microsoft Entra 權杖來叫用產生用戶端權杖 REST API，以取得用戶端要使用的權杖。

1. 請遵循從應用程式授權以啟用 Microsoft Entra ID。

2. 請遵循取得 Microsoft Entra 權杖，以使用 Postman 取得 Microsoft Entra 權杖。

3. 使用 Microsoft Entra 權杖搭配 Postman 叫用 :generateToken：

   注意

   請使用最新版的 Postman。 舊版 Postman 在路徑中支援冒號 : 有某種問題。

   1. 針對 URI，輸入 https://{Endpoint}/api/hubs/{hub}/:generateToken?api-version=2022-11-01

   2. 在 [驗證] 索引標籤上，選取 [持有人權杖] 並貼上在上一個步驟中擷取的 Microsoft Entra 權杖

   3. 選取 [傳送]，而您會在回應中看到用戶端存取權杖：

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

4. 用戶端存取 URI 的格式為 wss://<endpoint>/client/hubs/<hub_name>?access_token=<token>