Jak wygenerować adres URL dostępu klienta dla klientów

Klient, tzn. przeglądarka💻, aplikacja 📱mobilna lub urządzenie 💡IoT, używa adresu URL dostępu klienta do nawiązywania połączenia i uwierzytelniania z zasobem.

Adres URL jest zgodny z poniższym wzorcem:

• W przypadku klientów MQTT jest to wss://<service_name>.webpubsub.azure.com/clients/mqtt/hubs/<hub_name>?access_token=<token>.
• Dla wszystkich innych klientów jest to wss://<service_name>.webpubsub.azure.com/client/hubs/<hub_name>?access_token=<token>.

W tym artykule przedstawiono kilka sposobów uzyskiwania adresu URL dostępu klienta.

• Aby uzyskać szybki start, skopiuj jedną z witryny Azure Portal
• Na potrzeby programowania wygeneruj wartość przy użyciu zestawu SDK serwera Web PubSub
• Jeśli używasz identyfikatora Entra firmy Microsoft, możesz również wywołać interfejs API REST generowania tokenu klienta

Kopiowanie z witryny Azure Portal

Na karcie Klucze w witrynie Azure Portal istnieje narzędzie generatora adresów URL klienta umożliwiające szybkie wygenerowanie adresu URL dostępu klienta, jak pokazano na poniższym diagramie. Dane wejściowe wartości w tym miejscu nie są przechowywane.

Należy pamiętać, że w przypadku klientów MQTT należy wybrać pozycję "Klient MQTT" z menu rozwijanego przed polem tekstowym "Adres URL dostępu klienta".

Generowanie na podstawie zestawu SDK usługi

Ten sam adres URL dostępu klienta można wygenerować przy użyciu zestawu SDK serwera Web PubSub.

JavaScript

1. Postępuj zgodnie z instrukcjami Wprowadzenie do zestawu SDK serwera, aby utworzyć WebPubSubServiceClient obiekt service

2. Wygeneruj adres URL dostępu klienta, wywołując polecenie WebPubSubServiceClient.getClientAccessToken:

   • Generowanie tokenu dostępu klienta

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

   • Konfigurowanie identyfikatora użytkownika

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

   • Konfigurowanie okresu istnienia tokenu

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

   • Konfigurowanie roli, która może dołączać grupę group1 bezpośrednio po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     let token = await serviceClient.getClientAccessToken({
       roles: ["webpubsub.joinLeaveGroup.group1"],
     });
     

   • Konfigurowanie roli, którą klient może wysyłać komunikaty do grupy group1 bezpośrednio po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     let token = await serviceClient.getClientAccessToken({
       roles: ["webpubsub.sendToGroup.group1"],
     });
     

   • Konfigurowanie grupy group1 przyłączonej przez klienta po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     let token = await serviceClient.getClientAccessToken({
       groups: ["group1"],
     });
     

C#

1. Postępuj zgodnie z instrukcjami Wprowadzenie do zestawu SDK serwera, aby utworzyć WebPubSubServiceClient obiekt service

2. Wygeneruj adres URL dostępu klienta, wywołując polecenie WebPubSubServiceClient.GetClientAccessUri:

   • Generowanie tokenu dostępu klienta

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

   • Konfigurowanie identyfikatora użytkownika

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

   • Konfigurowanie okresu istnienia tokenu

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

   • Konfigurowanie roli, która może dołączać grupę group1 bezpośrednio po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     var url = service.GetClientAccessUri(roles: new string[] { "webpubsub.joinLeaveGroup.group1" });
     

   • Konfigurowanie roli, którą klient może wysyłać komunikaty do grupy group1 bezpośrednio po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     var url = service.GetClientAccessUri(roles: new string[] { "webpubsub.sendToGroup.group1" });
     

   • Konfigurowanie grupy group1 przyłączonej przez klienta po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     var url = service.GetClientAccessUri(groups: new string[] { "group1" });
     

Python

1. Postępuj zgodnie z instrukcjami Wprowadzenie do zestawu SDK serwera, aby utworzyć WebPubSubServiceClient obiekt service

2. Wygeneruj adres URL dostępu klienta, wywołując polecenie WebPubSubServiceClient.get_client_access_token:

   • Generowanie tokenu dostępu klienta

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

   • Konfigurowanie identyfikatora użytkownika

     token = service.get_client_access_token(user_id="user1")
     

   • Konfigurowanie okresu istnienia tokenu

     token = service.get_client_access_token(minutes_to_expire=5)
     

   • Konfigurowanie roli, która może dołączać grupę group1 bezpośrednio po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     token = service.get_client_access_token(roles=["webpubsub.joinLeaveGroup.group1"])
     

   • Konfigurowanie roli, którą klient może wysyłać komunikaty do grupy group1 bezpośrednio po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     token = service.get_client_access_token(roles=["webpubsub.sendToGroup.group1"])
     

   • Konfigurowanie grupy group1 przyłączonej przez klienta po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     token = service.get_client_access_token(groups=["group1"])
     

Java

1. Postępuj zgodnie z instrukcjami Wprowadzenie do zestawu SDK serwera, aby utworzyć WebPubSubServiceClient obiekt service

2. Wygeneruj adres URL dostępu klienta, wywołując polecenie WebPubSubServiceClient.getClientAccessToken:

   • Generowanie tokenu dostępu klienta dla klientów natywnych web PubSub

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

   • Generowanie tokenu dostępu klienta dla klientów MQTT

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

   • Konfigurowanie identyfikatora użytkownika

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

   • Konfigurowanie okresu istnienia tokenu

     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
     option.setExpiresAfter(Duration.ofDays(1));
     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
     

   • Konfigurowanie roli, która może dołączać grupę group1 bezpośrednio po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
     option.addRole("webpubsub.joinLeaveGroup.group1");
     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
     

   • Konfigurowanie roli, którą klient może wysyłać komunikaty do grupy group1 bezpośrednio po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

     GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
     option.addRole("webpubsub.sendToGroup.group1");
     WebPubSubClientAccessToken token = service.getClientAccessToken(option);
     

   • Konfigurowanie grupy group1 przyłączonej przez klienta po nawiązaniu połączenia przy użyciu tego adresu URL dostępu klienta

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

W rzeczywistym kodzie zwykle po stronie serwera jest hostowana logika generująca adres URL dostępu klienta. Po wystąpieniu żądania klienta po stronie serwera można użyć ogólnego przepływu pracy uwierzytelniania/autoryzacji w celu zweryfikowania żądania klienta. Tylko prawidłowe żądania klienta mogą odzyskać adres URL dostępu klienta.

Generowanie na podstawie interfejsu API REST :generateToken

Możesz również użyć identyfikatora Entra firmy Microsoft i wygenerować token, wywołując wywołanie interfejsu API REST generowania tokenu klienta.

Uwaga

Usługa Web PubSub nie zaleca ręcznego tworzenia tokenów identyfikatorów entra firmy Microsoft dla jednostek usługi Microsoft Entra ID. Dzieje się tak, ponieważ każdy token identyfikatora Entra firmy Microsoft jest krótkotrwały, zazwyczaj wygasa w ciągu jednej godziny. Po tym czasie należy ręcznie wygenerować zastępczy token identyfikatora entra firmy Microsoft. Zamiast tego użyj naszych zestawów SDK , które automatycznie generują i zastępują wygasłe tokeny identyfikatora Entra firmy Microsoft.

1. Postępuj zgodnie z instrukcjami Autoryzuj z aplikacji , aby włączyć identyfikator Entra firmy Microsoft.

2. Pobierz token Entra firmy Microsoft.

3. Użyj tokenu Microsoft Entra, aby wywołać element :generateToken.

4. Zbierz następujące informacje:

   Nazwa wartości	Jak uzyskać wartość
   TenantId	TenantId to wartość identyfikatora katalogu (dzierżawy) w okienku Przegląd zarejestrowanej aplikacji.
   ClientId	ClientId to wartość identyfikatora aplikacji (klienta) w okienku Przegląd zarejestrowanej aplikacji.
   ClientSecret	ClientSecret to wartość wpisu tajnego klienta, który został właśnie dodany w kroku 1

5. Uzyskiwanie tokenu identyfikatora entra firmy Microsoft z Platforma tożsamości Microsoft

   Używamy narzędzia CURL , aby pokazać sposób wywoływania interfejsów API REST. Narzędzie jest dołączone do systemu Windows 10/11 i można zainstalować to narzędzie po zainstalowaniu narzędzia 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"
   
   

   Powyższe polecenie curl wysyła żądanie POST do punktu końcowego tożsamości firmy Microsoft, aby odzyskać token identyfikatora Entra firmy Microsoft. W odpowiedzi zobaczysz token Microsoft Entra ID w access_token polu . Skopiuj go i zapisz do późniejszego użycia.

6. Wywoływanie tokenu identyfikatora entra firmy Microsoft :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"
   

   Jeśli musisz wygenerować token dla klientów MQTT, dołącz clientType=mqtt parametr do adresu 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"
   

   Po uruchomieniu cURL polecenia powinna zostać wyświetlona odpowiedź podobna do następującej:

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