Verwenden des Web PubSub-Diensts mit dem Azure Application Gateway

Das Azure Application Gateway ist ein Lastenausgleich für Webdatenverkehr, der auf Anwendungsebene funktioniert. Es kann als einzelner Kontaktpunkt für Ihre Webclients verwendet werden und kann so konfiguriert werden, dass der Webdatenverkehr basierend auf HTTP-Attributen, z. B. dem URI-Pfad, an Ihre verschiedenen Backends weitergeleitet wird. Das Application Gateway verfügt über systemeigene Unterstützung für WebSocket – Benutzer*innen müssen nichts Spezielles konfigurieren, damit WebSocket aktiviert ist.

In diesem Leitfaden zeigen wir, wie Sie Azure Application Gateway verwenden können, um Ihre Web PubSub-Ressource zu sichern. Wir erreichen ein höheres Sicherheitsniveau, indem nur Datenverkehr vom Application Gateway zugelassen und der öffentliche Datenverkehr zu Ihrer Web PubSub-Ressource deaktiviert wird.

Wie im Diagramm dargestellt, müssen Sie einen privaten Endpunkt für Ihre Web PubSub-Ressource einrichten. Dieser private Endpunkt muss sich im gleichen virtuellen Netzwerk wie Ihr Application Gateway befinden.

Dieser Leitfaden verfolgt einen schrittweisen Ansatz. Zunächst konfigurieren wir das Application Gateway so, dass der Datenverkehr zu Ihrer Web PubSub-Ressource erfolgreich weitergeleitet werden kann. Zweitens wenden wir die Zugriffssteuerungsfeatures von Web PubSub an, um nur Datenverkehr vom Application Gateway zuzulassen.

Schritt 1: Konfigurieren des Application Gateway zum Weiterleiten von Datenverkehr zur Web PubSub-Ressource

Das Diagramm veranschaulicht, was wir in Schritt 1 erreichen werden.

Erstellen einer Azure Application Gateway-Instanz

Suchen Sie im Azure-Portal nach Azure Application Gateway und führen Sie die Schritte zum Erstellen einer Ressource aus. Die wichtigsten Schritte sind im Diagramm hervorgehoben.

Ein virtuelles Netzwerk wird benötigt, damit Azure-Ressourcen sicher miteinander kommunizieren können. Das Azure Application Gateway erfordert ein dediziertes Subnetz, das wir erstellt haben. Aus diesem Grund leitet Ihre Azure Application Gateway-Ressource in Schritt 1 Datenverkehr über das öffentliche Internet an Ihre Web PubSub-Ressource weiter. In Schritt 2 erstellen wir ein weiteres Subnetz, das eine Web PubSub-Ressource enthält, sodass Ihr Azure Application Gateway Datenverkehr sicher über ein virtuelles Netzwerk an Ihre Web PubSub-Ressource weiterleitet.

Konfigurieren von Azure Application Gateway

Das Konfigurieren des Azure Application Gateway umfasst drei Komponenten.

• Front-Ends
• Back-Ends
• Routingregeln

Frontends sind die IP-Adressen Ihres Azure Application Gateway. Da wir Azure Application Gateway als einzigen Kontaktpunkt für unsere Webclients verwenden, müssen wir dafür eine öffentliche IP erstellen.

Backends sind die Ressourcen, an die Ihre Application Gateway-Ressource Datenverkehr senden kann. In unserem Fall haben wir ein Ziel, nämlich unsere Web PubSub-Ressource. Suchen Sie den Hostnamen einer vorhandenen Web PubSub-Ressource, die Sie verwenden möchten, um diesem Leitfaden im Azure-Portal zu folgen. Dieser sollte wie folgt aussehen: xxxx.webpubsub.azure.com.

Bei der Einrichtung von Frontends und Backends müssen wir eine Routingregel konfigurieren, welche die Frontends und die Backends verbindet. Die Routingregel teilt dem Application Gateway mit, wie und wohin der Datenverkehr weitergeleitet werden soll.

Zunächst richten wir einen Listener ein. Diese Konfiguration weist das Application Gateway an, auf HTTP-Datenverkehr auf PORT 80 zu lauschen.

Zweitens richten wir die Backend-Ziele ein. Wir konfigurieren Backend-Ziele für den Backend-Pool, den wir zuvor erstellt haben. Dies ist unsere Web PubSub-Ressource. Darüber hinaus müssen wir angeben, wie das Application Gateway den Datenverkehr weiterleiten soll. Sie erreichen dies über Backend-Einstellungen.

Web PubSub-Dienst akzeptiert nur HTTPs-Datenverkehr. Daher weisen wir das Application Gateway an, mit Web PubSub mithilfe von HTTPs zu kommunizieren. Um diesen Leitfaden fokussiert zu halten, lassen wir das Application Gateway den Host auswählen. Die empfohlene Vorgehensweise besteht darin, eine benutzerdefinierte Domäne in der Produktion einzurichten.

Wenn die drei Komponenten konfiguriert sind, sollte etwas wie der Screenshot angezeigt werden. Sie können den Datenverkehrsfluss über das Application Gateway so visualisieren:

1. Webclients senden Anforderungen an die öffentliche IP Ihrer Application Gateway-Ressource.
2. Das Application Gateway leitet Datenverkehr weiter, indem die vom Benutzer konfigurierten Routingregeln konsultiert werden.
3. Wenn die Routingregel übereinstimmt, wird der Datenverkehr an das angegebene Backend-Ziel weitergeleitet.

Es lohnt sich, hervorzuheben, dass Sie Nicht-WebSocket--Verbindungen genau auf die gleiche Weise konfigurieren. Weitere Informationen zur nativen Unterstützung des Application Gateway für Weiterleitung an WebSocket-Verbindungen

Zuletzt muss der Integritätstest im Back-End aktualisiert werden. Wählen Sie Einstellungen –>Integritätstests aus, wählen Sie die generierten Integritätstesteinstellungen aus, aktualisieren Sie den Pfad auf /api/health, und behalten Sie andere unverändert bei.

Testen und Überprüfen der ordnungsgemäßen Konfiguration des Application Gateway

Überprüfen, ob Ihre Web PubSub-Ressource fehlerfrei ist

Senden Sie eine Anforderung an einen ungültigen Endpunkt Ihrer Web PubSub-Ressource, und erwarten Sie eine Fehlermeldung von Web PubSub.

curl https://<your-web-pubsub-resource-endpoint>/client

Die Fehlermeldung „Ungültiger Wert von für Hub“ sollte angezeigt werden. Dieser Fehler zeigt, dass der Web PubSub-Dienst Ihre Anforderung erfolgreich empfangen und entsprechend geantwortet hat.

Überprüfen, ob Application Gateway den Datenverkehr zu Ihrer Web PubSub-Ressource weiterleitet

Wiederholen Sie einen ähnlichen Schritt und erwarten Sie dieselbe Fehlermeldung.

curl http://<public-ip-of-your-application-gateway-resource>/client

Die gleiche Fehlermeldung „Ungültiger Wert von für Hub“ sollte angezeigt werden. Dieser Fehler zeigt, dass die Application Gateway-Ressource den Datenverkehr erfolgreich mithilfe der konfigurierten Routingregel weitergeleitet hat.

Testen und Überprüfen, ob das Application Gateway an WebSocket-Verbindungen weiterleiten kann

Veröffentlichen von Nachrichten über Web PubSub

Wir erstellen ein einfaches Programm, um regelmäßige Serververöffentlichungsnachrichten über Web PubSub zu simulieren. Wir führen das Programm lokal in Schritt 1 aus, um zu überprüfen, ob alles funktioniert, und in Schritt 2 stellen wir dieselbe App für Azure App Service bereit.

Erstellen der Ordnerstruktur

mkdir server && cd server
touch package.json && touch publish.js

Quellcode kopieren

Kopieren Sie den Code in die erstellte package.json-Datei.

{
  "scripts": {
    "start": "node ./publish.js"
  },
  "dependencies": {
    "@azure/web-pubsub": "^1.1.1",
    "express": "^4.19.2"
  }
}

Kopieren Sie den Code in die erstellte publish.js-Datei.

const express = require("express")
// Uses the service SDK, which makes it easy to consume the capabilities of the service
const { WebPubSubServiceClient } = require('@azure/web-pubsub');

const app = express()
const PORT = 3000

// Hardcodes the hub name 
const hub = "myHub1";

// Grabs the connection string stored as an environment variable
let webpubsub = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, hub);

// Serves the files found in the "public" directory  
app.use(express.static("public"))

// Returns Web PubSub's access token
app.get("/negotiate", async (req, res) => {
  let token = await webpubsub.getClientAccessToken()
  let url = token.url
  res.json({
    url
  })
}
// Every 2 seconds, we ask Web PubSub service to send all connected clients the message "hello, world"
setInterval(() => {
  webpubsub.sendToAll("hello, world", { contentType: "text/plain" });
}, 2000);

// Starts the server
app.listen(process.env.PORT || PORT, () => console.log(`server running on ${PORT}`));

Installieren von Abhängigkeiten und Ausführen des Programms

Suchen Sie im Azure-Portal die connection stringIhrer Web PubSub-Ressource.

npm install

## Set environment variable
export WebPubSubConnectionString="<replace with the connection string of your Web PubSub resource>"

npm run start

In der Konsole sollte „Server läuft auf 3000“ angezeigt werden. Alle 2 Sekunden fordert das Programm den Web PubSub-Dienst auf, eine Nachricht an alle verbundenen Webclients zu übertragen. Obwohl derzeit keine Webclients mit Ihrer Web PubSub-Ressource verbunden sind, können Sie diesen Fluss in Aktion sehen, indem Sie das “Live Trace Tool“-Feature aktivieren, wo Sie wichtige Protokollierungen in Echtzeit verfolgen können.

Empfangen von Nachrichten im Browser

Es wäre nicht aufklärend, wenn wir die übertragenen Nachrichten nicht empfingen. Im Serverordner haben Sie zuvor eine einfache HTML-Datei erstellt, in welcher der Clientcode abgelegt wird. Die express-App dient dieser statischen Datei.

mkdir public && cd public 
touch index.html

Kopieren von Clientcode

Kopieren des Codes in index.html

<!DOCTYPE html>

<body>
  <script type="module">
    const endpoint = "http://localhost:3000"

    // Gets an access token through which the client connects with your Web PubSub resource
    const webPubSubUrl = await getWebPubSubAccessToken(endpoint)

    // Opens a WebSocket connection with your Web PubSub resource using browser native WebSocket API 
    const socket = new WebSocket(webPubSubUrl)

    socket.addEventListener("open", () => {
      console.log("connection opened")
    })

    // Prints out the message when it arrives
    socket.addEventListener("message", (msg) => {
      console.log(msg)
    })

    async function getWebPubSubAccessToken(endpoint) {
      const response = await fetch(endpoint + "/negotiate")
      const { url } = await response.json()
      return url
    }
  </script>
</body>

</html>

Ausführen des Clientprogramms

Öffnen Sie Ihren bevorzugten Webbrowser und besuchen Sie http://localhost:3000, wo unser Server zuhört.

Stellen Sie sicher, dass sie publish.js noch ausführen. Wenn Sie die Seite überprüfen, öffnen Sie die Netzwerk- und Konsolenbereiche und Sie sollten sehen, dass der Client erfolgreich mit Ihren Web PubSub-Ressourcen verbunden ist und die übertragenen Nachrichten abruft.

Proxy-WebSocket-Verbindungen über das Anwendungsgateway

Da das Application Gateway systemeigene Unterstützung für WebSocket hat, müssen wir die Konfiguration in unserer Application Gateway-Ressource nicht ändern. Wir müssen lediglich den Endpunkt ändern, auf den unser Client verweist.

Suchen Sie die publish.js-Datei und nehmen Sie zwei Änderungen vor.

• Deklarieren Sie eine Variable, um die öffentliche IP Ihrer Application Gateway-Ressource zu speichern.
• Ändern Sie die Zeile, in der die Variable url initialisiert wird, let url=token.url.

// ... code omitted from before
const appGatewayEndpoint = process.env.appGatewayEndpoint

app.get("/negotiate", async (req, res) => {
  const token = await webpubsub.getClientAccessToken()
  const url = "ws://" + appGatewayEndpoint + token.url.split(".com")[1]
  // ... code omitted from before
})
 
// ... code omitted from before

Suchen Sie die öffentliche IP Ihrer Application Gateway-Ressource, und legen Sie die Umgebungsvariable fest.

export appGatewayEndpoint="<replace with the public IP of your Application Gateway resource>"

Drei zu beachtende Punkte.

• Wir verwenden die ws:// statt wss://, da Ihr Application Gateway so konfiguriert ist, dass nur der http-Datenverkehr überwacht wird.
• In der Produktion empfiehlt es sich wahrscheinlich, eine benutzerdefinierte Domäne für Ihre Application Gateway-Ressource einzurichten und sie so konfiguriert, dass nur HTTPs akzeptiert werden.
• Wir müssen das Zugriffstoken beibehalten, da es Anmeldeinformationen für Ihren Client codiert, um eine Verbindung mit Ihrer Web PubSub-Ressource herzustellen.

Öffnen Sie Ihren Browser, und besuchen Sie http://localhost:3000 erneut, um zu überprüfen, ob das WebSocket erfolgreich über das Application Gateway weitergeleitet wird und ungefähr alle 2 Sekunden Nachrichten von Application Gateway empfängt.

Zusammenfassung von Schritt 1

Wir haben das Ende von Schritt 1 erreicht. Wenn Sie Schritt 1 ausgeführt haben, sollten Sie sehen, dass Ihre Web PubSub-Ressource direkt über Ihre Webclients und indirekt über das Application Gateway zugänglich ist. Sie haben auch die native Unterstützung von Application Gateway für WebSocket in Aktion gesehen. Für die Aktivierung sind keine Konfigurationsänderungen erforderlich. Wir müssen nur sicherstellen, dass ein Webclient auf einen Application Gateway-Endpunkt verweist. Der Rest der Zugriffs-URL, die aus dem Web PubSub-Dienst-SDK generiert wird, sollte unverändert bleiben.

In Schritt 2 schließen wir den öffentlichen Zugriff auf Ihre Web PubSub-Ressource, wodurch sie sicherer wird.

Schritt 2: Deaktivieren des öffentlichen Zugriffs auf Ihre Web PubSub-Ressource

Das Ergebnis von Schritt 1 besteht darin, dass ihre Web PubSub-Ressource über das öffentliche Internet und das Application Gateway zugänglich ist. Da sich Ihre Web PubSub-Ressource nicht im gleichen virtuellen Netzwerk befindet, erreicht das Application Gateway, wenn es Datenverkehr an Ihre Web PubSub-Ressource weiterleitet, den öffentlichen Endpunkt von Web PubSub über das öffentliche Internet. Diese Situation ist nicht wünschenswert.

Der Web PubSub-Dienst unterstützt das Konfigurieren von Zugriffssteuerungen. Eine solche Konfiguration ist dafür, den Zugriff aus dem öffentlichen Internet zu unterbinden. Stellen Sie sicher, dass Sie auf „Speichern“ klicken, wenn Sie fertig sind.

Wenn Sie nun denselben Befehl ausführen, wird anstelle von „Ungültiger Hubname“ 403 Forbidden angezeigt.

curl https://<your-web-pubsub-resource-endpoint>/client

Jetzt ist der öffentliche Zugriff in Ihrer Web PubSub-Ressource deaktiviert. Eine Auswirkung ist, dass das Application Gateway, wie es in Schritt 1 eingerichtet wurde, sie auch nicht erreichen kann. Wenn Sie denselben Befehl für Ihren Application Gateway-Endpunkt ausführen, wird 504 Gateway Time-out angezeigt.

curl http://<public-ip-of-your-application-gateway-resource>/client

Wir müssen Ihre Web PubSub-Ressource in dasselbe virtuelle Netzwerk einbinden, in dem sich Ihr Application Gateway befindet. Wir erreichen dies, indem wir einen privaten Endpunkt erstellen. Weitere Informationen zu privaten Endpunkten finden Sie hier.

Erstellen eines separaten Subnetzes für Ihren privaten Endpunkt

In Schritt 1 haben wir ein Subnetz erstellt, welches das Application Gateway enthält. Für das Application Gateway ist ein eigenes Subnetz erforderlich, daher müssen wir ein anderes Subnetz für Ihren privaten Endpunkt erstellen.

Suchen Sie die virtuelle Netzwerkressource, die wir zuvor erstellt haben, und erstellen Sie ein neues Subnetz.

Erstellen eines privaten Endpunkts für Ihre Web PubSub-Ressource

Suchen Sie Ihre Web PubSub-Ressource im Azure-Portal, und wechseln Sie zum Blatt „Netzwerk“.

Erstellen Sie einen privaten Endpunkt in derselben Region wie Ihre Web PubSub-Ressource.

Wählen Sie das soeben erstellte separate Subnetz aus.

Aktivieren der privaten DNS-Integration

Aktualisieren des Backend-Pools Ihrer Application Gateway-Ressource

Ihre Application Gateway-Ressource weiß nicht, dass Sie einen privaten Endpunkt für Ihre Web PubSub-Ressource erstellt haben. Suchen Sie Ihre Application Gateway-Ressource und aktualisieren Sie die Backend-Pools.

Wenn Sie diesen Befehl jetzt erneut ausführen, sollte wieder „Ungültiger Hubname“ angezeigt werden, was erwartet wird. Es zeigt, dass Application Gateway Proxys über das virtuelle Netzwerk anstelle des öffentlichen Internets weiterleiten.

curl http://<public-ip-of-your-application-gateway-resource>/client

Bereitstellen des Veröffentlichungsprogramms als App Service Web App

Da der öffentliche Zugriff auf Ihre Web PubSub-Ressource deaktiviert ist, kann unser lokales publish.js-Programm die Ressource nicht erreichen. Wir müssen das Programm als Web App in demselben virtuellen Netzwerk bereitstellen, in dem sich unsere Web PubSub-Ressource befindet.

Bereitstellen einer Web App als ZIP-Datei

Bevor wir unseren Quellcode zippen und in Azure App Service bereitstellen können, müssen wir eine kleine Änderung am Clientcode vornehmen. Der /negotiate-Endpunkt wird nicht mehr von localhost bedient.

Suchen Sie index.html im öffentlichen Ordner und ändern Sie die Zeile, in der die endpoint-Variable deklariert wird. Sie müssen sie durch den Domänennamen Ihrer Web App ersetzen.

  <script>
    // ...code omitted from before
   
   const endpoint = "<replace with your default domain name of your web app>"
    
    // ...code omitted from before
  </script>

Web App bietet einen praktischen Befehl zum Bereitstellen einer App als ZIP-Datei. Erfahren Sie mehr über den az webapp up-Befehl und die Aufgaben, die er für Sie automatisiert.

Suchen Sie den Serverordner, den Sie in Schritt 1 erstellt haben.

## Makes sure you are in the right working directory
cd server 

## Make sure you have Azure CLI installed and log into your Azure account.
az login 

## Creates a ZIP file with the content in the server folder and deploys it as a Web App
az webapp up \
--sku B1 \
--name <the-name-of-your-web-app> \
--location <the-same-location-as-your-Web-PubSub-resource>

Hinweis

Möglicherweise müssen Sie zum Azure-Abonnement wechseln, in dem die bisher erstellten Ressourcen verwendet wurden, wenn Sie den Leitfaden befolgt haben. Um das Abonnement zu wechseln, folgen Sie dem Befehl, der in diesem Dokumentationsartikel erwähnt wird.

Umgebungsvariable festlegen

Wenn das publish.js-Programm gestartet wird, stellt App Service die Umgebungsvariablen für Ihr Programm zur Verfügung.

Es gibt zwei Umgebungsvariablen, die festgelegt und für publish.js zur Verfügung gestellt werden müssen.

• Suchen Sie Ihre Verbindungszeichenfolge mit dem Web PubSub-Dienst im Azure-Portal und legen Sie die WebPubSubConnectionString-Umgebungsvariable fest.
• Suchen Sie die öffentliche Frontend-IP Ihrer Application Gateway-Ressource und legen Sie die appGatewayEndpoint-Umgebungsvariable fest.

Aktivieren Sie die Integration virtueller Netzwerke in Ihrer Web App

Der App-Dienst erfordert ein dediziertes Subnetz in Ihrem virtuellen Netzwerk. Wechseln Sie zu Ihrer Ressource für virtuelle Netzwerke, und erstellen Sie ein neues Subnetz wie Sie es für Ihre Web PubSub-Ressource getan haben.

Nachdem ein neues Subnetz erstellt wurde, wechseln Sie zum Blatt „Netzwerk“ Ihrer Web App-Ressource, und aktivieren Sie die Integration des virtuellen Netzwerks.

Stellen Sie sicher, dass Sie dasselbe virtuelle Netzwerk auswählen, in dem sich Ihre Web PubSub-Ressource befindet.

Deaktivieren der automatischen HTTP-Umleitung

Standardmäßig leitet die Web App HTTP-Datenverkehr an HTTPs um. Dieses Standardverhalten muss deaktiviert werden. Dies wird für Produktionsworkloads nicht empfohlen.

Überprüfen, ob alles funktioniert

Bisher haben Sie in Schritt 2

1. den öffentlichen Zugriff auf Ihre Web PubSub-Ressource deaktiviert,
2. einen privaten Endpunkt dafür erstellt,
3. die Backend-Pools Ihrer Application Gateway-Ressource aktualisiert, damit sie Ihre Web PubSub-Ressource erreichen kann,
4. den Endpunkt aktualisiert, mit dem ein Client ein Zugriffstoken für die Verbindung mit Ihrer Web PubSub-Ressource erhält,
5. publish.js als Web App im selben virtuellen Netzwerk bereitgestellt,
6. zwei Umgebungsvariablen für Ihre Web App-Ressource festgelegt,
7. das Standardverhalten von Web App zum Umleiten von HTTP-Datenverkehr zu HTTPs deaktiviert.

Öffnen Sie nun Ihren Webbrowser und geben Sie den Domänennamen Ihrer Web App ein. Wenn Sie die Seite prüfen, öffnen Sie den Netzwerkbereich, um zu sehen, dass der Client für das Zugriffstoken zur Web App wechselt und dann das Token verwendet, um eine WebSocket-Verbindung mit dem Application Gateway herzustellen.

Wenn der Konsolenbereich geöffnet ist, werden auch die übertragenen Nachrichten angezeigt.