如何產生用戶端的用戶端存取 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
• 若要進行開發，請使用 Web PubSub 伺服器 SDK 產生此值
• 如果使用 Microsoft Entra ID，也可以叫用產生用戶端權杖 REST API

從 Azure 入口網站複製

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

請注意，針對 MQTT 用戶端，您應該在 [用戶端存取 URL] 文字輸入框前面的下拉式功能表中選取 [MQTT 用戶端]。

從服務 SDK 產生

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

JavaScript

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

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

   • 產生用戶端存取權杖

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

   • 設定使用者識別碼

     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：

   • 產生用戶端存取權杖

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

   • 設定使用者識別碼

     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：

   • 產生用戶端存取權杖

     # for web pubsub native clients
     token = service.get_client_access_token();
     
     # for mqtt clients
     token = service.get_client_access_token(client_protocol="MQTT")
     

   • 設定使用者識別碼

     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：

   • 為 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);
     

   • 設定使用者識別碼

   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 :generateToken 產生

您也可以使用 Microsoft Entra ID，並叫用產生用戶端權杖 REST API (部分機器翻譯) 來產生權杖。

注意

Web PubSub 不建議手動為 Microsoft Entra ID 服務主體建立 Microsoft Entra ID 權杖。 這是因為每個 Microsoft Entra ID 權杖都是短期的，通常會在一小時內到期。 在這段時間過後，您必須手動產生取代用 Microsoft Entra ID 權杖。 請改為使用我們的 SDK，其會自動為您產生並取代過期的 Microsoft Entra ID 權杖。

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

2. 取得 Microsoft Entra 權杖。

3. 使用 Microsoft Entra 權杖叫用 :generateToken。

4. 收集以下資訊：

   值名稱	如何取得值
   TenantId	TenantId 是您註冊之應用程式的 [概觀] 窗格上的 [目錄 (租用戶) 識別碼] 值。
   ClientId	ClientId 是您註冊之應用程式 [概觀] 窗格的 [應用程式 (用戶端)] 識別碼] 值。
   ClientSecret	ClientSecret 是您剛在步驟 #1 中新增之用戶端密碼的值

5. 從 Microsoft 身分識別平台取得 Microsoft Entra ID 權杖

   我們使用 CURL (英文) 工具來示範如何叫用 REST API。 此工具隨附於 Windows 10/11，而且您也可以依照安裝 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.microsoftonline.com/$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 命令會將 POST 要求傳送至 Microsoft 身分識別端點，以取得傳回的 Microsoft Entra ID 權杖。 在回應中，您會在 access_token 欄位中看到 Microsoft Entra ID 權杖。 請複製並儲存此 URL，以供稍後使用。

6. 使用 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"
   }