Połączenie bota do wyszukiwania (wersja zapoznawcza)

W tym artykule opisano sposób tworzenia niestandardowego federacyjnego dostawcy wyszukiwania (zasilania przez bota) i łączenia go z kanałem wyszukiwania. Gdy administrator dzierżawy włączy dostawcę w swojej dzierżawie, wyszukiwanie użytkowników przedsiębiorstwa, z Office.com, SharePoint.com i Bing.com, może zawierać wyniki od niestandardowego dostawcy wyszukiwania.

Platforma wyszukiwania federacyjnego firmy Microsoft umożliwia tworzenie niestandardowych dostawców wyszukiwania federacyjnego, aby umożliwić udział w środowiskach odpowiedzi i pionowych usługi Microsoft Search bez konieczności scalania tych informacji z indeksem platformy Microsoft 365. Aby uzyskać więcej informacji, zobacz Ogłoszenie wersji zapoznawczej platformy wyszukiwania federacyjnego firmy Microsoft i wyszukiwania federacyjnego usługi Dynamics 365 (wersja zapoznawcza).

Uwaga

Kanał wyszukiwania jest w prywatnej wersji zapoznawczej. Aby zażądać dostępu, użyj formularza podglądu prywatnego dewelopera usługi Microsoft Search. W pytaniu 7 wybierz pozycję Wyszukiwanie federacyjne.

Aby połączyć bota z kanałem wyszukiwania, wymagane są następujące kroki. Te kroki zostały szczegółowo opisane w dalszej części tego artykułu.

1. Zaimplementuj bota, aby pracować jako dostawca wyszukiwania.
2. Jeśli bot będzie wymagać zalogowania użytkowników:
   1. W witrynie Azure Portal uwidocznij interfejs API bota na platformie wyszukiwania.
   2. W kodzie bota użyj wygenerowanego identyfikatora URI zakresu, aby wygenerować token użytkownika.
3. Wdróż bota na platformie Azure.
4. Dodaj kanał wyszukiwania do bota.
5. Poproś administratora IT o przejrzenie rejestracji bota i opublikowanie bota w dzierżawie.

Napiwek

Zalecamy włączenie dostawcy wyszukiwania w dzierżawie testowej przed włączeniem go w środowisku produkcyjnym.

Wymagania wstępne

• Znajomość podstaw usługi Bot Framework i sposobu tworzenia bota przy użyciu zestawu Bot Framework SDK.
• Bot do nawiązania połączenia z kanałem.
• Jeśli nie masz jeszcze konta platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

Bot można zaimplementować w dowolnych językach obsługiwanych przez zestaw SDK platformy Bot Framework. W tym artykule jako przykład użyto federacyjnego bota wyszukiwania w języku C#.

Uwidacznianie interfejsu API bota do wyszukiwania

Napiwek

Ten krok jest wymagany tylko wtedy, gdy bot wymaga dostępu do chronionych zasobów użytkownika.

W niektórych przepływach pracy biznesowych bot może wymagać poświadczeń użytkownika w celu wykonania akcji w imieniu użytkownika. Aby utworzyć środowisko logowania jednokrotnego dla bota w kanale wyszukiwania, musisz zezwolić platformie wyszukiwania na zabezpieczenie tokenu dostępu z identyfikatora Entra firmy Microsoft w imieniu użytkownika.

Aby wygenerować identyfikator URI zakresu i identyfikator aplikacji dla bota:

1. Przejdź do portalu Azure Portal.
2. Jeśli nie masz jeszcze zasobu bota, utwórz zasób usługi Azure Bot.
3. Przejdź do usługi Microsoft Entra ID .
4. Przejdź do okienka Rejestracje aplikacji.
5. Wybierz aplikację skojarzona z botem.
6. Przejdź do okienka Uwidaczniaj interfejs API .
7. Wybierz Dodaj zakres.
   1. W okienku Dodawanie zakresu zalecamy zachowanie automatycznie wygenerowanego identyfikatora URI identyfikatora aplikacji. Wybierz przycisk Zapisz i kontynuuj.
   2. Wprowadź nazwę zakresu.
   3. W przypadku KtoTo może wyrazić zgodę?, preferowane są Administracja i użytkownicy, ale obie opcje będą działać.
   4. Wprowadź nazwę wyświetlaną zgody Administracja i opis zgody Administracja.
   5. Opcjonalnie wprowadź nazwę wyświetlaną zgody użytkownika i opis zgody użytkownika.
   6. Sprawdź, czy stan ma wartość Włączone.
   7. Wybierz Dodaj zakres.
8. Wybierz Dodaj aplikację klienta.
   1. W okienku Dodawanie aplikacji klienckiej ustaw wartość Identyfikator klienta na 81473081-50b9-469a-b9d8-303109583ecb, identyfikator klienta platformy wyszukiwania.
   2. W obszarze Autoryzowane zakresy wybierz identyfikator URI zakresu utworzony w poprzednim kroku.
   3. Wybierz Dodaj aplikację.
9. Przejdź do okienka Przegląd . Skopiuj identyfikator URI identyfikatora aplikacji. Będzie to konieczne podczas rejestrowania bota w kanale wyszukiwania.

Implementowanie bota

Kanał wyszukiwania wysyła do bota każde zapytanie użytkownika jako działanie wywołania o nazwie "application/search". Bot zwraca wyniki zapytania w odpowiedzi wywołania. Użyj formatu karty adaptacyjnej dla wyników zapytania wysyłanych z powrotem do kanału wyszukiwania.

1. Zaktualizuj wszystkie pakiety bot framework i kart adaptacyjnych w projekcie do najnowszej wersji.
2. Opcjonalnie dodaj kod uwierzytelniania, aby wygenerować token użytkownika.
3. Zaimplementuj metodę wyszukiwania danych dla każdego źródła danych do uwzględnienia.
4. Wygeneruj kartę adaptacyjną, aby wyświetlić wyniki.

Pobieranie identyfikatora śledzenia platformy wyszukiwania

Platforma wyszukiwania przypisuje unikatowy identyfikator śledzenia do każdego zapytania wysyłanego do bota. Platforma dodaje je do danych kanału wywołania. Możesz zdecydować się na zarejestrowanie identyfikatora śledzenia żądania. Użyj właściwości danych traceId kanału, aby uzyskać identyfikator śledzenia.

W przykładzie wyszukiwania federacyjnego metoda pokazuje, SearchHelper.GetSearchTraceId jak uzyskać identyfikator śledzenia z działania invoke.

Dodawanie uwierzytelniania

Jeśli uwidoczniono interfejs API bota do wyszukiwania i zażądano uwierzytelnienia po połączeniu bota z usługą Search, możesz pobrać token uwierzytelniania użytkownika z danych kanału działania.

Właściwość danych authorizations kanału może zawierać listę tokenów uwierzytelniania. Jeśli uwidocznisz interfejs API bota do wyszukiwania, lista będzie zawierać token on-behalf-of. Token na liście będzie miał następującą strukturę:

Nazwa właściwości	Typ	Opis
Authtype	integer	Typ tokenu uwierzytelniania: 0 dla nieznanego lub domyślnego lub 2 dla tokenu w imieniu.
token	string	Sam token uwierzytelniania.

W przykładzie wyszukiwania federacyjnego:

• Klasa SearchBotAuthenticationToken i AuthenticationTypes wyliczenie reprezentują te informacje.
• Metoda SearchHelper.GetSearchOboToken pokazuje, jak uzyskać token z działania invoke.

Po utworzeniu tokenu możesz go użyć podczas żądania jakichkolwiek chronionych zasobów dla użytkownika. Aby uzyskać informacje na temat używania tokenów w imieniu użytkownika, zobacz Platforma tożsamości Microsoft i przepływ OAuth 2.0 On-Behalf-Of.

Wykonywanie zapytań względem każdego magazynu danych

Kanał wyszukiwania wysyła zapytanie do bota jako invoke działanie, ze szczegółami zapytania we właściwości działania value , która reprezentuje obiekt JSON o następującej strukturze:

Nazwa właściwości	Typ	Opis
queryText	string	Tekst zapytania.
kind	string	Rodzaj zapytania: "wyszukiwanie", gdy wyniki będą wyświetlane na niestandardowej karcie pionowej lub "searchAnswer", gdy wynik zostanie wyświetlony jako odpowiedź na karcie Wszystkie.
queryOptions	obiekt	Dodatkowe opcje zapytania używane do stronicowania.
queryOptions.skip	integer	Indeks pierwszego wyniku do wysłania.
queryOptions.top	integer	Maksymalna liczba wyników do wysłania.

Wyniki wyszukiwania są zwracane w odpowiedzi wywołania:

• Zawsze ustaw właściwość obiektu Status odpowiedzi wywołania na 200, która wskazuje, że połączenie sieciowe jest w porządku. Właściwość obiektu Body ma oddzielny kod stanu.

• Właściwość Body reprezentuje obiekt JSON o następującej strukturze:

  Nazwa właściwości	Typ	Opis
  statusCode	integer	Kod stanu HTTP używany do wskazania, czy bot mógł pomyślnie uruchomić zapytanie.
  type	string	Typ odpowiedzi wywołania definiujący format pola wartości. Użyj polecenia "application/vnd.microsoft.searchResponse" dla wyników wyszukiwania lub "application/vnd.microsoft.error" w przypadku komunikatu o błędzie.
  wartość	obiekt	Wartość odpowiadająca wartości type.

  W przypadku komunikatów o błędach value obiekt zawiera:

  Nazwa właściwości	Typ	Opis
  code	string	Kod błędu zdefiniowany przez bota lub null , jeśli nie został określony.
  wiadomość	string	Komunikat o błędzie lub null jeśli nie zostanie określony.

  W przypadku wyników value wyszukiwania obiekt zawiera:

  Nazwa właściwości	Typ	Opis
  Wyniki	tablica obiektów wyników wyszukiwania	Wyniki lub null jeśli nie.
  displayLayouts	tablica obiektów układu wyświetlania	Układy wyświetlania lub null jeśli nie.
  totalResultCount	integer	Łączna liczba dostępnych wyników, jeśli jest obsługiwana stronicowanie; w przeciwnym razie, null.
  moreResultsAvailable	Wartość logiczna	Wskazuje, czy są dostępne więcej wyników.

  Obiekty wyników wyszukiwania zawierają:

  Nazwa właściwości	Typ	Opis
  wartość	string	Unikatowy identyfikator lub wartość dla tego wyniku wyszukiwania.
  layoutId	string	Identyfikator układu wyświetlania do użycia dla tego wyniku.
  data.searchResultText	string	Tekst dla tego wyniku.

  Obiekty układu wyświetlania zawierają:

  Nazwa właściwości	Typ	Opis
  layoutId	string	Identyfikator układu.
  layoutBody	string	Treść układu jako obiekt JSON kart adaptacyjnych.

W przykładzie wyszukiwania federacyjnego metoda pokazuje, SearchHelper.RunFederatedSearch jak uzyskać informacje o zapytaniu z działania wywołania i jak sformatować odpowiedź wywołania.

Wyświetlanie wyników wyszukiwania

Możesz utworzyć typy wyszukiwania w pionie i wynikach, aby dostosować wyniki wyszukiwania widoczne dla użytkowników podczas wyszukiwania w programie SharePoint, pakiecie Office i usłudze Bing. Pionowe ułatwiają użytkownikom znajdowanie informacji, które mają uprawnienia do wyświetlania. Aby uzyskać więcej informacji, zobacz sekcję Obsługiwane elementy karty adaptacyjnej.

Jeśli bot otrzyma zapytanie, dla którego nie ma odpowiedzi, jego odpowiedź powinna zawierać pustą odpowiedź.

Rejestrowanie bota na platformie Azure

Aby połączyć bota z kanałem wyszukiwania, musisz mieć zasób bota aprowizowany na platformie Azure. Aby uzyskać więcej informacji, zobacz jak zarejestrować bota na platformie Azure lub jak wdrożyć bota na platformie Azure.

Połączenie bota do wyszukiwania

Poniższe instrukcje pokazują, jak połączyć bota z usługą Search.

Napiwek

Zalecamy włączenie dostawcy wyszukiwania w dzierżawie testowej przed włączeniem go w środowisku produkcyjnym.

1. Przejdź do portalu Azure Portal.

2. Otwórz zasób bota.

3. Otwórz okienko Kanały (wersja zapoznawcza).

4. Wybierz Wyszukaj.

5. Na karcie Wyszukaj Ustawienia wprowadź informacje dotyczące bota.

   

   1. W obszarze Metadane dostawcy wyszukiwania wprowadź nazwę do wyświetlenia w interfejsie użytkownika wyszukiwania.

   2. W obszarze Frazy wyzwalacza zdefiniuj frazy reprezentujące zapytania, na które bot może odpowiedzieć.

      Uwaga

      W przypadku wersji początkowych dostępna jest tylko wersja angielska (en-US).

      • .csv Przekaż plik zawierający frazy. Plik powinien zawierać jedną kolumnę danych bez nagłówków.
      • Z listy preferencji Język wybierz język, w którym są zapisywane frazy wyzwalacza.

   3. W obszarze Uwierzytelnianie wskaż, czy dostawca wyszukiwania wymaga uwierzytelniania użytkownika.

      • Jeśli wymagane jest uwierzytelnianie, wprowadź adres URL uwierzytelniania. Użyj identyfikatora URI identyfikatora aplikacji skopiowanego podczas uwidocznienia interfejsu API bota.

   4. Wybierz Dalej.

6. Jeśli na karcie Pionowo wyniki od dostawcy wyszukiwania mają być wyświetlane we własnym niestandardowym pionie na stronie wyników wyszukiwania, wprowadź nazwę pionową w polu. W przeciwnym razie pozostaw to pole puste. Następnie wybierz Dalej.
   Strona wyników wyszukiwania dotyczy Office.com, SharePoint.com i Bing.com.

7. Na karcie Publikowanie dzierżawy przejrzyj ustawienia i dodaj informacje o publikowaniu.

   1. Przejrzyj nazwę dostawcy wyszukiwania i przykładowe zapytania. Wróć do poprzednich kart, aby w razie potrzeby zmienić te informacje.
   2. Wprowadź opis dostawcy wyszukiwania.
   3. Wprowadź adres e-mail kontaktu z pomocą techniczną. Użyj adresu e-mail dewelopera lub grupy deweloperów, który ma dostęp do dostawcy wyszukiwania.

8. Wybierz pozycję Dodaj , aby zażądać zatwierdzenia od administratora IT.

Zatwierdzanie dostawcy wyszukiwania w dzierżawie

Zatwierdzenie dostawcy wyszukiwania w dzierżawie jest wykonywane przez administratora IT na stronie Wyszukiwanie i analiza w Centrum administracyjne platformy Microsoft 365.

Testowanie połączenia

Zalecamy włączenie dostawcy wyszukiwania w dzierżawie testowej przed włączeniem go w środowisku produkcyjnym.

Modyfikowanie dostawcy wyszukiwania

Możesz edytować dostawcę wyszukiwania przed przesłaniem go do przeglądu przez administratora IT. Może być konieczne, jeśli początkowe żądanie zostanie odrzucone lub usługa zostanie zdezaktywowana.

1. W witrynie Azure Portal przejdź do zasobu bota zawierającego dostawcę wyszukiwania, który chcesz edytować.
2. Przejdź do okienka Kanały (wersja zapoznawcza).
3. Wybierz kanał wyszukiwania, a następnie wybierz pozycję Edytuj.
   1. Platforma Azure wyświetla okienko Kanał wyszukiwania. W tym okienku możesz edytować ustawienia.
   2. Aby zmodyfikować frazy wyzwalające, pobierz plik, edytuj go lokalnie i przekaż plik.
   3. Po zakończeniu edycji wybierz ponownie pozycję Dodaj , aby przesłać dostawcę wyszukiwania do przeglądu przez administratora IT.

Usuwanie dostawcy wyszukiwania

Dostawca wyszukiwania zostanie usunięty, jeśli usuniesz kanał wyszukiwania z zasobu bota.

Aby usunąć kanał wyszukiwania z bota:

1. W witrynie Azure Portal przejdź do zasobu bota.
2. Przejdź do okienka Kanały (wersja zapoznawcza).
3. Wybierz kanał wyszukiwania.
4. W górnej części okienka Kanał wyszukiwania wybierz pozycję Usuń kanał.
5. Wybierz pozycję Tak , aby potwierdzić operację.

Aby usunąć zasób bota:

1. W witrynie Azure Portal przejdź do zasobu bota.
2. Jeśli jeszcze tego nie zrobiono, usuń kanał wyszukiwania z bota.
3. W górnej części okienka Przegląd wybierz pozycję Usuń.
4. Wybierz pozycję OK, aby potwierdzić operację.

Dodatkowe informacje

Kanał wyszukiwania używa wyszukiwania federacyjnego i schematu kart adaptacyjnych:

Aby uzyskać więcej informacji na temat schematu karty adaptacyjnej, zobacz Adaptacyjne karty dla deweloperów botów.

Informacje o frazach wyzwalacza

Fraza wyzwalacza to fraza używana przez platformę wyszukiwania do kierowania zapytania do niestandardowego dostawcy wyszukiwania obsługiwanego przez bota. Wyszukiwanie federacyjne przekazuje do dostawcy wyszukiwania wypowiedź użytkownika, gdy wypowiedź jest zbliżona do jednej z fraz wyzwalacza.

Napiwek

Jeśli jest dostępny więcej niż jeden dostawca wyszukiwania, wyszukiwanie federacyjne wybiera tylko jedno, na podstawie podanych fraz wyzwalacza i zapytania użytkownika.

Na przykład pomyśl o botze, który zarządza harmonogramami lotów i stanem.

1. Pomyśl o kilku typowych sposobach, w jaki użytkownik odwołuje się do bota lub korzysta z niego. Pamiętaj, aby odróżnić bota od innych.

   Zamiast ogólnego terminu, takiego jak "harmonogram", który może mieć zastosowanie do szkół i programów telewizyjnych, użyj bardziej szczegółowych fraz, takich jak "tabela czasowa lotu" i "harmonogram lotu".

2. Uwzględnij różne frazy, które obejmują zakres funkcji bota, takich jak czas odlotu i bieżący stan.

   Na przykład obejmują zapytania dotyczące czasu przylotu lub wyjazdu i lotnisk.

Frazy wyzwalacza dla takiego harmonogramu lotów i bota stanu mogą obejmować:

• Rozkład lotów
• Stan lotu
• Lot 675 czas odlotu
• Kiedy mój lot odlatuje
• Czas przylotu 468 lotów
• Stan lotu Seattle Tacoma
• Status lotu Heathrow

W innym przykładzie frazy wyzwalacza dla bota prognozy pogody mogą obejmować:

• Lokalna prognoza pogody
• Informacje o pogodzie
• Jutro pogoda
• 10-dniowa prognoza pogody
• Dzisiejsze wysokie
• Dzisiejsza szansa na deszcz
• Czy jutro będzie śnieg
• Prędkość wiatru jutro
• Czy jest wietrznie na zewnątrz
• Pogoda w Londynie

Obsługiwane elementy karty adaptacyjnej

Podzbiór schematu karty adaptacyjnej jest obsługiwany w wyszukiwaniu federacyjnym. Aby uzyskać informacje na temat formatowania wyników wyszukiwania, zobacz Dostosowywanie strony wyników wyszukiwania.

Obsługa obejmuje następujące elementy karty adaptacyjnej: TextBlock, RichTextBlock, Image, ColumnSet, ImageSet i FactSet. Aby uzyskać więcej informacji, zobacz Zarządzanie układami wyników wyszukiwania w usłudze Microsoft Search i Eksploratorem schematu kart adaptacyjnych.

Każdą kartę można utworzyć bezpośrednio w formacie JSON lub użyć pakietu NuGet AdaptiveCards .

Wyszukiwanie federacyjne nie obsługuje kodu HTML

Ważne

Wyszukiwanie federacyjne nie będzie renderować tekstu karty adaptacyjnej zawierającego kod HTML.

Platforma wyszukiwania nie zawiera analizatora HTML. Można jednak wyeliminować niektóre tagi i użyć pakietu NuGet Html2Markdown , aby przekonwertować kod HTML na język Markdown:

1. Usuń <span> elementy i <u> .
2. Zastąp <div> elementy i <br> elementami akapitu (<p>).
3. Przekonwertuj pozostały kod HTML na język Markdown.

Następne kroki

• Aby uzyskać informacje na temat obsługi kanałów w usłudze Bot Połączenie or Service, zobacz Połączenie bota do kanałów.
• Aby uzyskać informacje na temat tworzenia botów, zobacz Jak działają boty i przewodnik Szybki start Tworzenie bota przy użyciu zestawu SDK platformy Bot Framework.
• Aby uzyskać informacje na temat wdrażania botów, zobacz Wdrażanie bota i Konfigurowanie ciągłego wdrażania.