Verbinden eines Bots zur Suche (Vorschau)

In diesem Artikel wird beschrieben, wie Sie einen benutzerdefinierten Sammelsuche-Anbieter (von Ihrem Bot unterstützt) erstellen und mit dem Suchkanal verbinden. Nachdem der Instanz-Administrator Ihren Anbieter in ihrer Instanz aktiviert hat, können Unternehmensbenutzersuchen von Office.com, SharePoint.com und Bing.com Ergebnisse aus Ihrem benutzerdefinierten Suchanbieter enthalten.

Mit der Microsoft Federated Search Platform können Sie benutzerdefinierte Partnersucheanbieter erstellen, damit Ihre Informationen an den Antworten und vertikalen Erfahrungen von Microsoft Search teilnehmen können, ohne dass diese Informationen mit Ihrem Microsoft 365-Index zusammengeführt werden müssen. Weitere Informationen finden Sie unter Ankündigung der Entwicklervorschau der Microsoft-Partnersucheplattform und der Dynamics 365-Verbundsuche (Vorschau).

Hinweis

Der Suchkanal befindet sich in der privaten Vorschau. Verwenden Sie zum Anfordern des Zugriffs das private Vorschauformular von Microsoft Search Developer. Wählen Sie in Frage 7 die Sammelsuche aus.

Die folgenden Schritte sind erforderlich, um Ihren Bot mit dem Suchkanal zu verbinden. Diese Schritte werden weiter unten in diesem Artikel ausführlicher beschrieben.

1. Implementieren Sie Ihren Bot, um als Suchanbieter zu arbeiten.
2. Wenn Ihr Bot Benutzer auffordert, angemeldet zu sein:
   1. Machen Sie im Azure-Portal die Bot-API für die Suchplattform verfügbar.
   2. Verwenden Sie in Ihrem Bot-Code den generierten Bereichs-URI, um ein Benutzertoken zu generieren.
3. Bereitstellen Ihres Bots in Azure.
4. Fügen Sie den Suchkanal zu Ihrem Bot hinzu.
5. Bitten Sie Ihren IT-Administrator, Ihre Bot-Registrierung zu überprüfen und Ihren Bot in der Instanz zu veröffentlichen.

Tipp

Es wird empfohlen, den Suchanbieter in einer Testinstanz zu aktivieren, bevor Sie ihn in der Produktion aktivieren.

Voraussetzungen

• Kenntnisse über Grundlagen des Bot Framework-Service und das Erstellen eines Bots mit dem Bot Framework SDK.
• Der Bot, der eine Verbindung mit dem Kanal herstellen soll.
• Sollten Sie kein Azure-Konto haben, erstellen Sie zunächst ein kostenloses Konto.

Sie können Ihren Bot in einer der Sprachen implementieren, die vom Bot Framework SDK unterstützt werden. In diesem Artikel wird der C#-Sammelsuch-Bot als Beispiel verwendet.

Bereitstellen der Bot-API für die Suche

Tipp

Dieser Schritt ist nur erforderlich, wenn Ihr Bot Zugriff auf geschützte Benutzerressourcen benötigt.

In einigen Geschäftsworkflows erfordert ein Bot möglicherweise Benutzeranmeldeinformationen, um eine Aktion im Namen des Benutzers auszuführen. Um eine Einmalige Anmeldung (Single Sign-On, SSO) für Ihren Bot im Suchkanal zu erstellen, müssen Sie der Suchplattform erlauben, ein Zugriffstoken von Microsoft Entra ID im Namen des Benutzers zu sichern.

So generieren Sie einen Bereichs-URI und eine Anwendungs-ID für Ihren Bot:

1. Öffnen Sie das Azure-Portal.
2. Erstellen Sie eine Azure Bot-Ressource, falls noch keine Bot-Ressource haben.
3. Gehen Sie zu Microsoft Entra ID.
4. Gehen Sie zum Blatt App-Registrierungen.
5. Wählen Sie die Anwendung aus, die Ihrem Bot zugeordnet ist.
6. Wechseln Sie zum Bereich API verfügbar machen.
7. Wählen Sie Bereich hinzufügen.
   1. Im Bereich Umfang hinzufügen wird empfohlen, den automatisch generierten Anwendungs-ID-URI beizubehalten. Wählen Sie Speichern und fortfahren aus.
   2. Geben Sie einen Umfangsnamen ein.
   3. Für Wer kann zustimmen? werden Administratoren und Benutzer bevorzugt, aber beide Optionen funktionieren.
   4. Geben Sie einen Anzeigenamen der Administratoreinwilligung und eine Beschreibung der Administratoreinwilligung ein.
   5. Geben Sie optional einen Anzeigenamen für die Benutzereinwilligung und eine Beschreibung der Benutzereinwilligung ein.
   6. Vergewissern Sie sich, dass Status auf Aktiviert festgelegt ist.
   7. Wählen Sie Umfang hinzufügen aus.
8. Wählen Sie Client-Anwendung hinzufügen.
   1. Legen Sie im Bereich Clientanwendung hinzufügen die Client-ID der Suchplattform auf 81473081-50b9-469a-b9d8-303109583ecb fest, die Client-ID der Suchplattform.
   2. Wählen Sie unter autorisierte Umfänge den Umfangs-URI aus, den Sie im vorherigen Schritt erstellt haben.
   3. Wählen Sie Anwendung hinzufügen aus.
9. Wechseln Sie zum Bereich Übersicht. Kopieren Sie den Anwendungs-ID-URI. Sie benötigen dies, wenn Sie Ihren Bot im Suchkanal registrieren.

Implementieren Ihres Bots

Der Suchkanal sendet jede Benutzerabfrage als Aufrufaktivität mit dem Namen "application/search" an Ihren Bot. Ihr Bot gibt die Abfrageergebnisse in der Aufrufantwort zurück. Verwenden Sie das Format für adaptive Karten für die Abfrageergebnisse, die an den Suchkanal zurückgesendet werden.

1. Aktualisieren Sie alle Bot Framework- und adaptive Karten-Pakete in Ihrem Projekt auf die neueste Version.
2. Optional können Sie einen Authentifizierungscode hinzufügen, um ein Benutzertoken zu generieren.
3. Implementieren Sie eine Datensuchmethode für jede Datenquelle, die einbezogen werden soll.
4. Generieren Sie die adaptive Karte, um die Ergebnisse anzuzeigen.

Abrufen der Suchplattform-Ablaufverfolgungs-ID

Die Suchplattform weist jeder Abfrage, die sie an Ihren Bot sendet, eine eindeutige Ablaufverfolgungs-ID zu. Die Plattform fügt dies zu den Kanaldaten der Aufrufaktivität hinzu. Sie können die Ablaufverfolgungs-ID der Anforderung protokollieren. Verwenden Sie die Eigenschaft der Kanaldaten, um die Ablaufverfolgungs-ID traceId abzurufen.

Im Beispiel für die Sammelsuche veranschaulicht die SearchHelper.GetSearchTraceId Methode, wie die Ablaufverfolgungs-ID aus der Aufrufaktivität abgerufen wird.

Hinzufügen der -Authentifizierung

Wenn Sie Ihre Bot-API für die Suche verfügbar gemacht und die Authentifizierung angefordert haben, wenn Sie Ihren Bot mit der Suche verbunden haben, können Sie das Benutzerauthentifizierungstoken aus den Kanaldaten der Aktivität abrufen.

Die Eigenschaft der Kanaldaten kann eine Liste von Authentifizierungstoken authorizations enthalten. Wenn Sie Ihre Bot-API für die Suche verfügbar machen, enthält die Liste das Token im Auftrag des Tokens. Das Token in der Liste hat die folgende Struktur:

Eigenschaftenname	Type	Beschreibung
authType	integer	Der Authentifizierungstokentyp: 0 für Unbekannt oder Standard oder 2 für im Auftrag des Tokens.
token	Zeichenfolge	Das Authentifizierungstoken selbst.

Im Sammelsuchbeispiel:

• Die SearchBotAuthenticationToken Klasse und die AuthenticationTypes Enumeration stellen diese Informationen dar.
• Die SearchHelper.GetSearchOboToken Methode veranschaulicht, wie das Token aus der Aufrufaktivität abgerufen wird.

Sobald Sie das Token haben, können Sie es verwenden, wenn Sie geschützte Ressourcen für den Benutzer anfordern. Weitere Informationen zu On-Behalf-Of-Tokens finden Sie unter Microsoft Identity Platform und der On-Behalf-Of-Fluss von OAuth2.0.

Jeden Datenspeicher abfragen

Der Suchkanal sendet eine Abfrage als invoke Aktivität an den Bot mit den Abfragedetails in der Eigenschaft der Aktivität value , die ein JSON-Objekt mit der folgenden Struktur darstellt:

Eigenschaftenname	Type	Beschreibung
queryText	Zeichenfolge	Der Abfragetext.
kind	Zeichenfolge	Die Art der Abfrage: "Suche", wenn Ergebnisse auf einer benutzerdefinierten vertikalen Registerkarte angezeigt werden, oder "searchAnswer", wenn ein Ergebnis als Antwort auf der Registerkarte Alle angezeigt wird.
queryOptions	Objekt	Zusätzliche Abfrageoptionen, die für die Paginierung verwendet werden.
queryOptions.skip	integer	Der Index des ersten Ergebnisses, das gesendet werden soll.
queryOptions.top	integer	Die maximale Anzahl der zu sendenden Ergebnisse.

Sie geben die Suchergebnisse in der Aufrufantwort zurück:

• Legen Sie immer die Eigenschaft des aufrufenden Antwortobjekts Status auf 200, was angibt, dass die Netzwerkverbindung in Ordnung ist. Die Eigenschaft des Body Objekts weist einen separaten Statuscode auf.

• Die Body Eigenschaft stellt ein JSON-Objekt mit der folgenden Struktur dar:

  Eigenschaftenname	Type	Beschreibung
  statusCode	integer	Ein HTTP-Statuscode, der verwendet wird, um anzugeben, ob der Bot die Abfrage erfolgreich ausführen konnte.
  Typ	Zeichenfolge	Der Typ der Aufrufantwort, der das Format des Wertfelds definiert. Verwenden Sie "application/vnd.microsoft.search.searchResponse" für Suchergebnisse oder "application/vnd.microsoft.error" für eine Fehlermeldung.
  value	Objekt	Ein Wert, der dem Wert typeentspricht.

  Bei Fehlermeldungen enthält das value Objekt Folgendes:

  Eigenschaftenname	Type	BESCHREIBUNG
  code	Zeichenfolge	Ein vom Bot definierter Fehlercode oder null falls nicht angegeben.
  message	Zeichenfolge	Eine Fehlermeldung oder null falls nicht angegeben.

  Für Suchergebnisse enthält das value Objekt Folgendes:

  Eigenschaftenname	Type	Beschreibung
  results	Array von Suchergebnisobjekten	Die Ergebnisse oder null wenn keine.
  displayLayouts	Array von Anzeigelayoutobjekten	Die Anzeigelayouts oder null wenn keines.
  totalResultCount	integer	Die verfügbaren Gesamtergebnisse, wenn die Paginierung unterstützt wird; andernfalls . null
  moreResultsAvailable	Boolean	Gibt an, ob mehr Ergebnisse verfügbar sind.

  Suchergebnisobjekte enthalten:

  Eigenschaftenname	Type	BESCHREIBUNG
  value	Zeichenfolge	Ein eindeutiger Bezeichner oder Wert für dieses Suchergebnis.
  layoutId	Zeichenfolge	Die ID des Anzeigelayouts, das für dieses Ergebnis verwendet werden soll.
  data.searchResultText	Zeichenfolge	Der Text für dieses Ergebnis.

  Anzeigelayoutobjekte enthalten:

  Eigenschaftenname	Type	Beschreibung
  layoutId	Zeichenfolge	Die Layout-ID.
  layoutBody	Zeichenfolge	Der Layout-Körper als JSON-Objekt für adaptive Karten.

Im Sammelsuch-Beispiel veranschaulicht die SearchHelper.RunFederatedSearch Methode, wie die Abfrageinformationen aus der Aufrufaktivität abgerufen und wie die Aufrufantwort formatiert wird.

Anzeigen der Suchergebnisse

Sie können Suchsparten und Ergebnistypen erstellen, um die Suchergebnisse anzupassen, die Benutzern angezeigt werden, wenn sie in SharePoint, Office und Bing suchen. Sparten erleichtern Benutzern das Auffinden der Informationen, für die sie über die Berechtigung zum Anzeigen verfügen. Weitere Informationen finden Sie im Abschnitt Unterstützte adaptive Kartenelemente.

Wenn Ihr Bot eine Abfrage empfängt, für die er keine Antwort hat, sollte seine Antwort eine leere Antwort enthalten.

Registrieren Sie Ihren Bot in Azure.

Um Ihren Bot mit dem Suchkanal zu verbinden, müssen Sie über eine Bot-Ressource in Azure verfügen. Weitere Informationen finden Sie unter Registrieren eines Bots bei Azure oder Bereitstellen Ihres Bots in Azure.

Verbinden Ihres Bots mit der Suche

Die folgenden Anweisungen zeigen, wie Sie einen Bot mit der Suche verbinden.

Tipp

Es wird empfohlen, den Suchanbieter in einer Testinstanz zu aktivieren, bevor Sie ihn in der Produktion aktivieren.

1. Öffnen Sie das Azure-Portal.

2. Öffnen Sie Ihre Bot-Ressource.

3. Öffnen Sie den Bereich Kanäle (Vorschau).

4. Wählen Sie Suchen.

5. Geben Sie auf der Registerkarte Sucheinstellungen Informationen für Ihren Bot ein.

   

   1. Geben Sie unter Metadaten des Suchanbieters den Namen ein, der in der Such-UI angezeigt werden soll.

   2. Definieren Sie unter Triggerausdrücke die Ausdrücke, die die Abfragen darstellen, die Ihr Bot beantworten kann.

      Hinweis

      Für Erstversionen ist nur Englisch (en-US) verfügbar.

      • Laden Sie eine .csv Datei hoch, die die Ausdrücke enthält. Die Datei sollte eine Datenspalte ohne Kopfzeilen enthalten.
      • Wählen Sie in der Liste Spracheinstellungen die Sprache aus, in der die Triggerausdrücke geschrieben werden.

   3. Geben Sie unter Authentifizierung an, ob Ihr Suchanbieter eine Benutzerauthentifizierung erfordert.

      • Wenn die Authentifizierung erforderlich ist, geben Sie die Authentifizierungs-URL ein. Verwenden Sie den Anwendungs-ID-URI, den Sie kopiert haben, wenn Sie die API für Ihren Bot verfügbar gemacht haben.

   4. Wählen Sie Weiter aus.

6. Wenn die Ergebnisse ihres Suchanbieters auf der Registerkarte Sparten in einer eigenen benutzerdefinierten Sparte auf der Suchergebnisseite angezeigt werden sollen, geben Sie den Sparten-Namen in das Feld ein, andernfalls lassen Sie dieses Feld leer. Wählen Sie anschließend Weiter aus.
   Die Suchergebnisseite ist für Office.com, SharePoint.com und Bing.com.

7. Überprüfen Sie auf der Registerkarte Instanz-Veröffentlichung Ihre Einstellungen und fügen Sie Veröffentlichungsinformationen hinzu.

   1. Überprüfen Sie den Namen des Suchanbieters und Beispielabfragen. Wechseln Sie bei Bedarf zurück zu den vorherigen Registerkarten, um diese Informationen zu ändern.
   2. Geben Sie eine Beschreibung Ihres Suchanbieters ein.
   3. E-Mail-Adresse des Supportkontakts eingeben. Verwenden Sie die E-Mail-Adresse eines Entwicklers oder einerr Entwicklergruppe, die Zugriff auf den Suchanbieter haben.

8. Wählen Sie Hinzufügen aus, um die Genehmigung von Ihrem IT-Administrator anzufordern.

Genehmigen eines Suchanbieters in einer Instanz

Die Genehmigung des Suchanbieters im Mandanten wird von einem IT-Administrator auf der Seite "Suche und Intelligenz " im Microsoft 365 Admin Center vorgenommen.

Testen der Verbindung

Es wird empfohlen, den Suchanbieter in einer Testinstanz zu aktivieren, bevor Sie ihn in der Produktion aktivieren.

Ändern eines Suchanbieters

Sie können den Suchanbieter bearbeiten, bevor Sie ihn zur Überprüfung durch den IT-Administrator übermitteln. Möglicherweise müssen Sie dies tun, wenn Ihre anfängliche Anforderung abgelehnt wird oder Ihr Dienst deaktiviert wird.

1. Wechseln Sie im Azure-Portal zu der Bot-Ressource, die den Suchanbieter enthält, den Sie bearbeiten möchten.
2. Wechseln Sie zum Bereich Kanäle (Vorschau).
3. Wählen Sie den Suchkanal und dann Bearbeiten.
   1. Azure zeigt den Suchkanalbereich an. In diesem Bereich können Sie Ihre Einstellungen bearbeiten.
   2. Um die Triggerausdrücke zu ändern, laden Sie die Datei herunter, bearbeiten Sie sie lokal, und laden Sie die Datei hoch.
   3. Nachdem Sie Ihre Bearbeitungen abgeschlossen haben, wählen Sie Erneut hinzufügen aus, um den Suchanbieter zur Überprüfung durch den IT-Administrator zu übermitteln.

Löschen eines Suchanbieters

Ihr Suchanbieter wird gelöscht, wenn Sie den Suchkanal aus der Bot-Ressource entfernen.

So entfernen Sie den Suchkanal aus Ihrem Bot:

1. Wechseln Sie im Azure-Portal zu Ihrer Bot-Ressource.
2. Wechseln Sie zum Bereich Kanäle (Vorschau).
3. Wählen Sie den Suchkanal.
4. Wählen Sie oben im Bereich Suchkanal die Option Kanal löschen.
5. Klicken Sie auf Ja, um den Vorgang zu bestätigen.

So löschen Sie die Bot-Ressource:

1. Wechseln Sie im Azure-Portal zu Ihrer Bot-Ressource.
2. Wenn Sie dies noch nicht getan haben, entfernen Sie den Suchkanal aus Ihrem Bot.
3. Wählen Sie oben im Bereich Übersicht die Option Löschen aus.
4. Wählen Sie OK aus, um den Vorgang zu bestätigen.

Weitere Informationen

Der Suchkanal verwendet die Sammelsuche und das Schema für adaptive Karten:

Weitere Informationen zum Schema für adaptive Karten finden Sie unter Adaptive Karten für Botentwickler.

Informationen zu Triggerausdrücken

Ein Triggerausdruck ist ein Ausdruck, den die Suchplattform verwendet, um eine Abfrage an Ihren benutzerdefinierten Suchanbieter weiterzuleiten, der von Ihrem Bot unterstützt wird. Die Sammelsuche leitet die Äußerung eines Benutzers an Ihren Suchanbieter weiter, wenn die Äußerung eine enge Übereinstimmung mit einem der Triggerausdrücke hat.

Tipp

Wenn mehr als ein Suchanbieter verfügbar ist, wählt die Sammelsuche nur einen, basierend auf den bereitgestellten Triggerausdrücken und der Abfrage des Benutzers.

Denken Sie beispielsweise an einen Bot, der Flugpläne und -status verwaltet.

1. Stellen Sie sich einige gängige Methoden vor, auf die ein Benutzer verweisen oder Ihren Bot verwenden würde. Achten Sie darauf, Ihren Bot von anderen zu unterscheiden.

   Anstelle eines allgemeinen Begriffs, z. B. „Zeitplan“, der für Schulen und Fernsehprogramme gelten kann, verwenden Sie spezifischere Ausdrücke wie „Flugzeittabelle“ und „Flugplan“.

2. Schließen Sie verschiedene Ausdrücke ein, die den Umfang der Features Ihres Bots abdecken, z. B. Abflugzeit und aktueller Status.

   Geben Sie beispielsweise Abfragen zu: Ankunfts- oder Abflugzeiten und Flughäfen.

Die Troggerausdrücke für einen solchen Flugplan- und Statusbot können Folgendes umfassen:

• Flugplan
• Flug-Status
• Flug 675 Abflugzeit
• Wann startet mein Flug
• Flug 468 Ankunftszeit
• Seattle Tacoma-Flugstatus
• Heathrow Flugstatus

Als weiteres Beispiel können die Triggerausdrücke für einen Wettervorhersage-Bot Folgendes umfassen:

• Lokale Wettervorhersage
• Wetterinformationen
• Morgiges Wetter
• 10-Tages-Wettervorhersage
• Heutige Höchsttemperatur
• Heutige Regenwahrscheinlichkeit
• Wird es morgen schneien
• Windgeschwindigkeit morgen
• Ist es windig draußen
• London Wetter

Unterstützte Elemente für adaptive Karten

Eine Teilmenge des Schemas für adaptive Karten wird in der Sammelsuche unterstützt. Informationen zum Formatieren Ihrer Suchergebnisse finden Sie unter Anpassen der Suchergebnisseite.

Die Unterstützung umfasst die folgenden Elemente für adaptive Karten: TextBlock, RichTextBlock, Bild, ColumnSet, ImageSet und FactSet. Weitere Informationen finden Sie unter Verwalten von Suchergebnislayouts und im Schema-Explorer für adaptive Karten von Microsoft Search.

Sie können jede Karte direkt als JSON erstellen oder das AdaptiveCards NuGet-Paket verwenden.

Die Sammelsuche unterstützt kein HTML

Wichtig

Die Sammelsuche rendert keinen Text für adaptive Karten, der HTML enthält.

Die Suchplattform enthält keinen HTML-Parser. Sie können jedoch einige der Tags beseitigen und das Html2Markdown NuGet-Paket verwenden, um HTML in Markdown zu konvertieren:

1. Entfernt <span> und <u> Elemente.
2. Ersetzen Sie <div> und <br> Elemente durch Absatzelemente (<p>)
3. Konvertieren Sie den verbleibenden HTML-Code in Markdown.

Nächste Schritte

• Informationen zur Kanalunterstützung im Bot-Konnektor-Dienst finden Sie unter Einen Bot mit Kanälen verbinden.
• Informationen zum Erstellen von Bots finden Sie unter Wie Bots funktionieren und in der Kurzanleitung Mit dem Bot Framework SDK einen Bot erstellen.
• Informationen zum Bereitstellen von Bots finden Sie unter Ihren Bot einsetzen und Continuous Deployment einrichten.