Připojení robota pro vyhledávání (Preview)

Tento článek popisuje, jak vytvořit vlastního federovaného poskytovatele vyhledávání (power by váš robot) a připojit ho ke kanálu Search. Jakmile správce tenanta povolí poskytovateli ve svém tenantovi, může hledání podnikových uživatelů z Office.com, SharePoint.com a Bing.com zahrnovat výsledky od vašeho vlastního poskytovatele vyhledávání.

Platforma Microsoft Federated Search umožňuje vytvářet vlastní federované zprostředkovatele vyhledávání, aby se vaše informace mohly účastnit prostředí Odpovědi a svislé vyhledávání microsoftu, aniž by bylo nutné tyto informace sloučit s indexem Microsoftu 365. Další informace najdete v tématu Oznámení verze Preview pro vývojáře federované vyhledávací platformy Microsoftu a federačního vyhledávání Dynamics 365 (Preview).

Poznámka:

Kanál Vyhledávání je ve verzi Private Preview. Pokud chcete požádat o přístup, použijte formulář Microsoft Search Developer Private Preview. V otázce 7 vyberte federované vyhledávání.

K připojení robota ke kanálu Search jsou potřeba následující kroky. Tyto kroky jsou podrobněji popsány dále v tomto článku.

1. Implementujte robota tak, aby fungoval jako poskytovatel vyhledávání.
2. Pokud robot bude vyžadovat přihlášení uživatelů:
   1. Na webu Azure Portal zpřístupňte rozhraní API robota pro vyhledávací platformu.
   2. V kódu robota použijte vygenerovaný identifikátor URI oboru k vygenerování tokenu uživatele.
3. Nasaďte robota do Azure.
4. Přidejte do robota kanál Search.
5. Požádejte správce IT, aby zkontroloval registraci robota a publikoval robota v tenantovi.

Tip

Než ho povolíte v produkčním prostředí, doporučujeme povolit poskytovatele vyhledávání v testovacím tenantovi.

Požadavky

• Znalost základů služby Bot Framework Service a vytvoření robota pomocí sady SDK služby Bot Framework
• Robot, který se má připojit ke kanálu.
• Pokud nemáte účet Azure, vytvořte si bezplatný účet před tím, než začnete.

Robota můžete implementovat v libovolném jazyce podporovaném sadou SDK služby Bot Framework. V tomto článku se jako příklad používá federovaný vyhledávací robot jazyka C#.

Zveřejnění rozhraní API robota pro vyhledávání

Tip

Tento krok je potřeba jenom v případě, že robot vyžaduje přístup k chráněným uživatelským prostředkům.

V některých obchodních pracovních postupech může robot vyžadovat přihlašovací údaje uživatele k provedení akce jménem uživatele. Pokud chcete vytvořit prostředí jednotného přihlašování (SSO) pro robota ve vyhledávacím kanálu, musíte platformě Search povolit zabezpečení přístupového tokenu od Microsoft Entra ID jménem uživatele.

Vygenerování identifikátoru URI oboru a ID aplikace pro robota:

1. Přejděte na Azure Portal.
2. Pokud ještě prostředek robota nemáte, vytvořte prostředek Robota Azure.
3. Přejděte do služby Microsoft Entra ID .
4. Přejděte do podokna Registrace aplikací.
5. Vyberte aplikaci přidruženou k robotovi.
6. Přejděte do podokna Zveřejnit rozhraní API .
7. Vyberte Přidat rozsah.
   1. V podokně Přidat obor doporučujeme ponechat automaticky vygenerovaný identifikátor URI ID aplikace. Vyberte Uložit a pokračovat.
   2. Zadejte název oboru.
   3. U Kdo může souhlas?, preferuje se Správa a uživatelé, ale obě možnosti budou fungovat.
   4. Zadejte zobrazovaný název Správa souhlasu a popis souhlasu Správa.
   5. Volitelně můžete zadat zobrazované jméno souhlasu uživatele a popis souhlasu uživatele.
   6. Ověřte, že je stav nastavený na Povoleno.
   7. Vyberte Přidat rozsah.
8. Vyberte Přidat klientskou aplikaci.
   1. V podokně Přidat klientskou aplikaci nastavte ID klienta na 81473081-50b9-469a-b9d8-303109583ecbID klienta platformy Search.
   2. V části Autorizované obory vyberte identifikátor URI oboru, který jste vytvořili v předchozím kroku.
   3. Vyberte Přidat aplikaci.
9. Přejděte do podokna Přehled . Zkopírujte identifikátor URI ID aplikace. Budete ho potřebovat, když robota zaregistrujete v kanálu Search.

Implementace robota

Kanál Search odešle každému uživateli dotaz robota jako aktivitu vyvolání s názvem "aplikace/vyhledávání". Robot vrátí výsledky dotazu v odpovědi vyvolání. Pro výsledky dotazu odeslané zpět do vyhledávacího kanálu použijte formát adaptivní karty.

1. Aktualizujte všechny balíčky Bot Framework a Adaptivní karty v projektu na nejnovější verzi.
2. Volitelně můžete přidat ověřovací kód pro vygenerování tokenu uživatele.
3. Implementujte metodu vyhledávání dat pro každý zdroj dat, který se má zahrnout.
4. Vygenerujte adaptivní kartu, aby se zobrazily výsledky.

Získání ID trasování platformy Search

Platforma Search přiřadí každému dotazu, který odesílá robotovi, jedinečné ID trasování. Platforma to přidá do dat kanálu vyvolání aktivity. Můžete se rozhodnout protokolovat ID trasování požadavku. K získání ID trasování použijte vlastnost dat traceId kanálu.

V ukázce federovaného vyhledávání metoda SearchHelper.GetSearchTraceId ukazuje, jak získat ID trasování z aktivity vyvolání.

Přidání ověřování

Pokud jste vystavili rozhraní API robota pro vyhledávání a požádali jste o ověření, když jste robota připojili ke službě Search, můžete získat ověřovací token uživatele z dat kanálu aktivity.

Vlastnost dat kanálu authorizations může obsahovat seznam ověřovacích tokenů. Pokud zveřejníte rozhraní API robota pro vyhledávání, bude seznam obsahovat token on-behalf-of. Token v seznamu bude mít následující strukturu:

Název vlastnosti	Type	Popis
Authtype	integer	Typ ověřovacího tokenu: 0 pro neznámý nebo výchozí token nebo 2 pro token on-behalf-of.
token	string	Samotný ověřovací token.

V ukázce federovaného vyhledávání:

• Třída SearchBotAuthenticationToken a AuthenticationTypes výčet představují tyto informace.
• Metoda SearchHelper.GetSearchOboToken ukazuje, jak získat token z aktivity vyvolání.

Jakmile token získáte, můžete ho použít, když požádáte o jakékoli chráněné prostředky pro uživatele. Informace o používání tokenů jménem uživatele najdete v tématu Microsoft Identity Platform a tok OAuth 2.0 On-Behalf-Of.

Dotazování na každé úložiště dat

Kanál Search odešle robotovi dotaz jako invoke aktivitu s podrobnostmi dotazu ve vlastnosti aktivity value , která představuje objekt JSON s následující strukturou:

Název vlastnosti	Type	Popis
queryText	string	Text dotazu.
kind	string	Druh dotazu: "search", když se výsledky zobrazí na vlastní svislé kartě, nebo "searchAnswer", když se výsledek zobrazí jako odpověď na kartě Vše.
queryOptions	objekt	Další možnosti dotazu používané pro stránkování
queryOptions.skip	integer	Index prvního výsledku, který se má odeslat.
queryOptions.top	integer	Maximální počet výsledků, které se mají odeslat.

Vrátíte výsledky hledání v odpovědi vyvolání:

• Vždy nastavte vlastnost vyvolání objektu Status odpovědi na 200, což znamená, že síťové připojení je v pořádku. Vlastnost objektu Body má samostatný stavový kód.

• Vlastnost Body představuje objekt JSON s následující strukturou:

  Název vlastnosti	Type	Popis
  statusCode	integer	Stavový kód HTTP, který označuje, jestli byl robot schopen úspěšně spustit dotaz.
  type	string	Typ odpovědi vyvolání definující formát pole hodnoty. Pro výsledky hledání použijte "application/vnd.microsoft.search.searchResponse" nebo "application/vnd.microsoft.error" pro chybovou zprávu.
  hodnota	objekt	Hodnota, která odpovídá hodnotě type.

  U chybových zpráv value objekt obsahuje:

  Název vlastnosti	Type	Popis
  code	string	Kód chyby definovaný robotem nebo null pokud není zadaný.
  zpráva	string	Chybová zpráva nebo null není-li zadána.

  Pro výsledky value hledání objekt obsahuje:

  Název vlastnosti	Type	Popis
  results	pole objektů výsledků hledání	Výsledky nebo null pokud žádné.
  displayLayouts	pole objektů rozložení zobrazení	Rozložení zobrazení nebo null pokud žádné.
  totalResultCount	integer	Celkové dostupné výsledky, pokud je stránkování podporováno; v opačném případě . null
  moreResultsAvailable	Logická hodnota	Určuje, jestli jsou k dispozici další výsledky.

  Objekty výsledků hledání obsahují:

  Název vlastnosti	Type	Popis
  hodnota	string	Jedinečný identifikátor nebo hodnota pro tento výsledek hledání.
  layoutId	string	ID rozložení zobrazení, které se má použít pro tento výsledek.
  data.searchResultText	string	Text pro tento výsledek.

  Objekty rozložení zobrazení obsahují:

  Název vlastnosti	Type	Popis
  layoutId	string	ID rozložení.
  layoutBody	string	Tělo rozložení jako objekt JSON adaptivních karet.

V ukázce federovaného vyhledávání metoda SearchHelper.RunFederatedSearch ukazuje, jak získat informace o dotazu z aktivity vyvolání a jak naformátovat odpověď vyvolání.

Zobrazení výsledků hledání

Můžete vytvořit svislé vyhledávání a typy výsledků a přizpůsobit tak výsledky hledání, které uživatelé uvidí při hledání v SharePointu, Office a Bingu. Svislé svisle usnadňují uživatelům vyhledání informací, které mají oprávnění k zobrazení. Další informace najdete v části Podporované prvky adaptivní karty.

Pokud robot obdrží dotaz, pro který nemá odpověď, měla by odpověď obsahovat prázdnou odpověď.

Registrace robota v Azure

Pokud chcete robota připojit ke kanálu Search, musíte mít zřízený prostředek robota v Azure. Další informace najdete v tématu registrace robota v Azure nebo nasazení robota v Azure.

Připojení robota ke vyhledávání

Následující pokyny ukazují, jak připojit robota ke službě Search.

Tip

Než ho povolíte v produkčním prostředí, doporučujeme povolit poskytovatele vyhledávání v testovacím tenantovi.

1. Přejděte na Azure Portal.

2. Otevřete prostředek robota.

3. Otevřete podokno Kanály (Preview).

4. Vyberte Hledat.

5. Na kartě Hledat Nastavení zadejte informace o robotovi.

   

   1. V části Metadata zprostředkovatele vyhledávání zadejte název, který se má zobrazit v uživatelském rozhraní vyhledávání.

   2. V části Aktivační fráze definujte fráze, které představují dotazy, na které může robot odpovědět.

      Poznámka:

      V počátečních verzích je k dispozici pouze angličtina (en-US).

      • .csv Nahrajte soubor, který obsahuje fráze. Soubor by měl obsahovat jeden sloupec dat bez záhlaví.
      • V seznamu předvoleb jazyka vyberte jazyk, ve kterém se zapisují aktivační fráze.

   3. V části Ověřování určete, jestli váš zprostředkovatel vyhledávání vyžaduje ověření uživatele.

      • Pokud se vyžaduje ověřování, zadejte ověřovací adresu URL. Při zveřejnění rozhraní API robota použijte identifikátor URI ID aplikace, který jste zkopírovali.

   4. Vyberte Další.

6. Pokud chcete, aby se výsledky z vašeho poskytovatele vyhledávání zobrazovaly na vlastní svislé stránce výsledků hledání na kartě Svisle, zadejte do pole svislý název. Jinak nechte toto pole prázdné. Pak vyberte Další.
   Stránka výsledků hledání je určená pro Office.com, SharePoint.com a Bing.com.

7. Na kartě Publikování tenanta zkontrolujte nastavení a přidejte informace o publikování.

   1. Zkontrolujte název zprostředkovatele vyhledávání a ukázkové dotazy. V případě potřeby se vraťte na předchozí karty a změňte tyto informace.
   2. Zadejte popis svého poskytovatele vyhledávání.
   3. Zadejte kontaktní e-mail podpory. Použijte e-mail vývojáře nebo skupiny vývojářů, kteří mají přístup k poskytovateli vyhledávání.

8. Pokud chcete požádat o schválení od správce IT, vyberte Přidat .

Schválení poskytovatele vyhledávání v tenantovi

Schválení poskytovatele vyhledávání v tenantovi provádí správce IT na stránce Vyhledávání a analýzy v Centrum pro správu Microsoftu 365.

Test připojení

Než ho povolíte v produkčním prostředí, doporučujeme povolit poskytovatele vyhledávání v testovacím tenantovi.

Úprava zprostředkovatele vyhledávání

Než ho odešlete ke kontrole správcem IT, můžete poskytovatele vyhledávání upravit. Možná to budete muset udělat, pokud se váš počáteční požadavek odmítne nebo se vaše služba deaktivuje.

1. Na webu Azure Portal přejděte k prostředku robota, který obsahuje zprostředkovatele vyhledávání, kterého chcete upravit.
2. Přejděte do podokna Kanály (Preview).
3. Vyberte kanál Hledání a vyberte Upravit.
   1. Azure zobrazí podokno Prohledat kanál . V tomto podokně můžete upravit nastavení.
   2. Pokud chcete upravit aktivační fráze, stáhněte soubor, upravte ho místně a nahrajte soubor.
   3. Po dokončení úprav znovu vyberte Přidat a odešlete poskytovatele vyhledávání ke kontrole správcem IT.

Odstranění zprostředkovatele vyhledávání

Pokud z prostředku robota odeberete kanál Search, váš poskytovatel vyhledávání se odstraní.

Odebrání kanálu Search z robota:

1. Na webu Azure Portal přejděte k prostředku robota.
2. Přejděte do podokna Kanály (Preview).
3. Vyberte kanál Hledání.
4. V horní části podokna Kanál hledání vyberte Odstranit kanál.
5. Kliknutím na Ano operaci potvrďte.

Odstranění prostředku robota:

1. Na webu Azure Portal přejděte k prostředku robota.
2. Pokud jste to ještě neudělali, odeberte kanál Search z robota.
3. V horní části podokna Přehled vyberte Odstranit.
4. Výběrem OK operaci potvrďte.

Další informace

Vyhledávací kanál používá federované vyhledávání a schéma adaptivních karet:

Další informace o schématu adaptivní karty najdete v tématu Adaptivní karty pro vývojáře robotů.

Informace o aktivačních frázích

Aktivační frází je fráze, kterou vyhledávací platforma používá ke směrování dotazu na vašeho vlastního poskytovatele vyhledávání využívajícího robota. Federované vyhledávání předává promluvu uživatele poskytovateli vyhledávání, když se promluva blíží jedné z aktivačních frází.

Tip

Pokud je k dispozici více než jeden poskytovatel vyhledávání, federované vyhledávání zvolí jenom jedno na základě zadaných frází triggeru a dotazu uživatele.

Představte si například robota, který spravuje plány letů a stav.

1. Představte si několik běžných způsobů, jak by uživatel odkazoval nebo používal robota. Nezapomeňte robota odlišit od ostatních.

   Místo obecného termínu, například "rozvrhu", který se může vztahovat na školy a televizní programy, použijte konkrétnější fráze, jako je například "tabulka letového času" a "letový plán".

2. Zahrňte různorodé fráze, které pokrývají rozsah funkcí robota, jako je čas odletu a aktuální stav.

   Můžete například uvést dotazy týkající se příletu nebo odletu a letiště.

Aktivační fráze pro takový letový plán a stavový robot můžou zahrnovat:

• Letový řád
• Stav letu
• Let 675 čas odletu
• Kdy bude můj let odletět
• Let 468 čas příjezdu
• Stav letu Seattle Tacoma
• Stav letu Heathrow

Jako další příklad můžou triggerové fráze robota předpovědi počasí zahrnovat:

• Místní předpověď počasí
• Informace o počasí
• Zítra počasí
• 10denní předpověď počasí
• Dnešní vysoká
• Dnešní šance na déšť
• Bude zítra sněžovat
• Rychlost větru zítra
• Je to větrný venku
• Londýn počasí

Podporované prvky adaptivní karty

Federované vyhledávání podporuje podmnožinu schématu adaptivní karty. Informace o formátování výsledků hledání najdete v tématu Přizpůsobení stránky výsledků hledání.

Podpora zahrnuje následující prvky adaptivní karty: TextBlock, RichTextBlock, Image, ColumnSet, ImageSet a FactSet. Další informace najdete v tématu Správa rozložení výsledků hledání ve službě Microsoft Search a v Průzkumníku schémat adaptivních karet.

Každou kartu můžete vytvořit přímo ve formátu JSON nebo můžete použít balíček NuGet AdaptiveCards .

Federované vyhledávání nepodporuje HTML

Důležité

Federované vyhledávání nevykreslí text adaptivní karty, který obsahuje kód HTML.

Vyhledávací platforma neobsahuje analyzátor HTML. Některé značky ale můžete eliminovat a pomocí balíčku NuGet Html2Markdown převést HTML na Markdown:

1. Odebrat <span> a <u> prvky
2. Nahraďte <div> prvky odstavcem a<p><br> prvky.
3. Převeďte zbývající kód HTML na Markdown.

Další kroky

• Informace o podpoře kanálů ve službě Bot Připojení or Service najdete v tématu Připojení robota do kanálů.
• Informace o vytváření robotů najdete v tématu Jak roboti fungují a jak vytvořit robota pomocí rychlého startu sady Bot Framework SDK .
• Informace o nasazování robotů najdete v tématu Nasazení robota a nastavení průběžného nasazování.