Konfigurieren eines Node.js-Bots für die Erweiterung

Ab dem 1. September 2023 wird dringend empfohlen, die Azure Service Tag-Methode für dieNetzwerkisolation zu verwenden. Die Verwendung von DL-ASE sollte auf hochspezifische Szenarien beschränkt sein. Vor der Implementierung dieser Lösung in einer Produktionsumgebung empfehlen wir Ihnen, Ihr Supportteam um Anleitungen zu bitten.

GILT FÜR: SDK v4

In diesem Artikel erfahren Sie, wie Sie einen Bot für die Verwendung von Named Pipes aktualisieren und die App Service-Erweiterung für Direct Line in der Azure App Service-Ressource aktivieren, in der der Bot gehostet wird.

Voraussetzungen

  • Ein Azure-Konto. Wenn Sie noch nicht über ein Abonnement verfügen, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.
  • Ein Node.js-Bot, der in Azure bereitgestellt wird.
  • Bot Framework SDK für Node.js, 4.7 oder höher.

Aktivieren Sie die App Service-Erweiterung für Direct Line

Dieser Abschnitt beschreibt, wie Sie die App Service-Erweiterung für Direct Line aktivieren, indem Sie den Schlüssel für die App Service-Erweiterung aus der Direct Line-Kanalkonfiguration Ihres Bots verwenden.

Aktualisieren des Bot-Codes

Erlauben Sie der App, die Named Pipe der App Service-Erweiterung für Direct Line zu verwenden:

  1. Bearbeiten der Hostdatei index.js Ihres Bots.

    1. Suchen Sie die Zeile, in der Sie den Adapter des Bots erstellen.

    2. Fügen Sie nach dem Erstellen des Adapters die folgende Anweisung hinzu, die den App-Dienstnamen aus der Umgebung abruft, und weisen Sie den Adapter an, eine Verbindung mit der entsprechenden benannten Pipe herzustellen.

      • Wenn Ihr Bot die CloudAdapter (empfohlen) verwendet:

        adapter.connectNamedPipe(
            process.env.APPSETTING_WEBSITE_SITE_NAME + '.directline',
            async (context) => {
                await myBot.run(context);
            },
            process.env.MicrosoftAppId,
            AuthenticationConstants.ToChannelFromBotOAuthScope);
        
      • Wenn Ihr Bot die veraltete BotFrameworkAdapter verwendet:

        adapter.useNamedPipe(async (context) => {
            await myBot.run(context);
            },
            process.env.APPSETTING_WEBSITE_SITE_NAME + '.directline'
        );
        
    3. Speichern Sie die Änderungen.

  2. Aktualisieren Sie die Datei web.config Ihres Bots, um Handler und Regel AspNetCore hinzuzufügen, die von der Direct Line App Service-Erweiterung benötigt werden, um Anfragen zu bearbeiten.

    1. Bearbeiten der Hostdatei web.config Ihres Bots.

    2. Ändern Sie das enabled Attribut des webSocket Tags in true.

      <webSocket enabled="true" />
      
    3. Fügen Sie im <handlers> Abschnitt eine Registrierung für den folgenden Handler hinzu.

      <add name="aspNetCore" path="*/.bot/*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
      
    4. Fügen Sie im <rewrite> Abschnitt der Regelliste die folgende Regel hinzu.

      <!-- Do not interfere with Direct Line App Service extension requests. (This rule should be as high in the rules section as possible to avoid conflicts.) -->
      <rule name ="DLASE" stopProcessing="true">
        <conditions>
          <add input="{REQUEST_URI}" pattern="^/.bot"/>
        </conditions>
      </rule>
      
    5. Speichern Sie die Änderungen.

  3. Erneute Bereitstellung Ihres aktualisierten Bots in Azure

Aktivieren Sie die Bot-App Service-Erweiterung für Direct Line

  1. Wechseln Sie im Azure-Portal zu Ihrer Azure Bot-Ressource.

    1. Wählen Sie unter EinstellungenKanäle, um die Kanäle zu konfigurieren, von denen Ihr Bot Nachrichten akzeptiert.
    2. Wenn er noch nicht aktiviert ist, wählen Sie den Direct Line-Kanal aus der Liste der verfügbaren Kanäle aus, um den Kanal zu aktivieren.
    3. Nachdem Sie Direct Line aktiviert haben, wählen Sie es erneut unter Kanäle aus.
    4. Wählen Sie die Registerkarte App Service-Erweiterung.
    5. Wählen Sie unter App Service-Erweiterungsschlüssel das Augensymbol neben dem entsprechenden Schlüssel aus.
  2. Wechseln Sie zur Startseite und wählen Sie oben auf der Seite App Services aus. Alternativ können Sie das Portalmenü aufrufen und dann das Menüelement App Services auswählen. Azure zeigt die Seite App Services an.

  3. Geben Sie im Suchfeld Ihren Azure Bot-Ressourcennamen ein. Ihre Ressource wird aufgelistet.

    Beachten Sie, dass eine Liste der zuletzt angezeigten Ressourcen angezeigt wird, wenn Sie den Cursor über dem Symbol oder Menüelement halten. Ihre Azure Bot-Ressource wird wahrscheinlich aufgelistet.

  4. Wählen Sie Ihren Ressourcen-Link.

    1. Wählen Sie im Abschnitt Einstellungen die Option Konfiguration aus.

    2. Geben Sie im rechten Panel die folgenden Einstellungen ein:

      Name Wert
      DirectLineExtensionKey Der Wert des App Service-Erweiterungsschlüssels, den Sie zuvor kopiert haben.
      DIRECTLINE_EXTENSION_VERSION latest
    3. Wenn Ihr Bot in einer souveränen oder anderweitig eingeschränkten Azure-Cloud gehostet wird, bei der Sie nicht über das öffentliche Portal auf Azure zugreifen, müssen Sie auch die folgende Einstellung hinzufügen:

      Name Wert
      DirectLineExtensionABSEndpoint Der Endpunkt, der für die Azure-Cloud spezifisch ist, in der Ihr Bot gehostet wird. Für die USGov-Cloud z. B. lautet der Endpunkt https://directline.botframework.azure.us/v3/extension.
    4. Klicken Sie im Abschnitt Konfiguration auf den Einstellungsabschnitt Allgemein, und aktivieren Sie Websockets.

    5. Klicken Sie auf Speichern, um die Einstellungen zu speichern. Daraufhin wird die Azure App Service-Instanz neu gestartet.

Bestätigen Sie, dass die Direct Line-Erweiterung und der Bot konfiguriert sind

Wechseln Sie in Ihrem Browser zu https://<your_app_service>.azurewebsites.net/.bot. Ist alles ordnungsgemäß konfiguriert, gibt die Seite den folgenden JSON-Inhalt zurück:

    {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}
  • v zeigt die Build-Version der App Service-Erweiterung für Direct Line an.
  • k gibt an, ob die Erweiterung einen Erweiterungsschlüssel aus seiner Konfiguration lesen konnte.
  • initialisiert gibt an, ob die Erweiterung Bot-Metadaten aus dem Azure AI Bot-Dienst herunterladen konnte.
  • ib gibt an, ob die Erweiterung eine eingehende Verbindung mit dem Bot herstellen konnte.
  • ob angibt, ob die Erweiterung eine ausgehende Verbindung vom Bot herstellen konnte.

Problembehandlung

  • Wenn die ib- und ob-Werte, die vom BOT-Endpunkt angezeigt werden, falsch sind, können der Bot und die Direct Line App Service-Erweiterung keine Verbindung zueinander herstellen.

    1. Überprüfen Sie den Code erneut, ob der Code für die Verwendung von Named Pipes dem Bot hinzugefügt wurde.
    2. Vergewissern Sie sich, dass der Bot gestartet und ausgeführt werden kann. Nützliche Tools sind Testen in WebChat, einen zusätzlichen Kanal verbinden, Remote-Debugging oder Protokollierung.
    3. Starten Sie den gesamten Azure-App-Service neu, in dem der Bot gehostet wird, um sicherzustellen, dass alle Prozesse sauber gestartet werden.
  • Wenn der initialisierte Wert des Bot-Endpunkts falsch lautet, kann die Direct Line App Service-Erweiterung den App Service-Erweiterungsschlüssel nicht überprüfen, der den Anwendungseinstellungen des Bots oben hinzugefügt wurde.

    1. Bestätigen Sie, dass der Wert richtig eingegeben wurde.
    2. Wechseln Sie zu dem alternativen Erweiterungsschlüssel, der auf der Seite Direct Line konfigurieren Ihres Bots angezeigt wird.

Nächste Schritte