Verbinding maken een bot zoeken (preview)

In dit artikel wordt beschreven hoe u een aangepaste federatieve zoekprovider maakt (power by uw bot) en deze verbindt met het zoekkanaal. Zodra de tenantbeheerder uw provider inschakelt in hun tenant, kunnen enterprise-gebruikerszoekopdrachten, van Office.com, SharePoint.com en Bing.com, resultaten van uw aangepaste zoekprovider bevatten.

Met het Microsoft Federated Search Platform kunt u aangepaste federatieve zoekproviders bouwen zodat uw gegevens kunnen deelnemen aan de Answers & Vertical-ervaringen van Microsoft Search zonder dat u die informatie hoeft samen te voegen met uw Microsoft 365-index. Zie De preview-versie van ontwikkelaars van het Microsoft Federated Search Platform en dynamics 365 federation search (preview) voor meer informatie.

Notitie

Het zoekkanaal bevindt zich in een privévoorbeeld. Als u toegang wilt aanvragen, gebruikt u het microsoft Search Developer Private Preview-formulier. Selecteer Federatief zoeken in vraag 7.

De volgende stappen zijn vereist om uw bot te verbinden met het zoekkanaal. Deze stappen worden verderop in dit artikel uitgebreid beschreven.

1. Implementeer uw bot om als zoekprovider te werken.
2. Als uw bot vereist dat gebruikers zijn aangemeld:
   1. Maak in Azure Portal de bot-API beschikbaar voor het zoekplatform.
   2. Gebruik in uw botcode de gegenereerde bereik-URI om een gebruikerstoken te genereren.
3. Implementeer uw bot in Azure.
4. Voeg het zoekkanaal toe aan uw bot.
5. Vraag uw IT-beheerder om uw botregistratie te controleren en uw bot in de tenant te publiceren.

Tip

U wordt aangeraden de zoekprovider in te schakelen in een testtenant voordat u deze in productie inschakelt.

Vereisten

• Kennis van de basisbeginselen van de Bot Framework-service en het maken van een bot met de Bot Framework SDK.
• De bot om verbinding te maken met het kanaal.
• Als u geen Azure-account hebt, maak dan een gratis account aan voordat u begint.

U kunt uw bot implementeren in een van de talen die worden ondersteund door de Bot Framework SDK. In dit artikel wordt de federatieve C# -zoekbot gebruikt als voorbeeld.

De bot-API beschikbaar maken voor zoeken

Tip

Deze stap is alleen nodig als uw bot toegang nodig heeft tot beveiligde gebruikersbronnen.

In sommige zakelijke werkstromen kan een bot gebruikersreferenties vereisen om namens de gebruiker een actie uit te voeren. Als u een ervaring voor eenmalige aanmelding (SSO) wilt maken voor uw bot in het zoekkanaal, moet u toestaan dat het zoekplatform namens de gebruiker een toegangstoken van Microsoft Entra-id beveiligt.

Een bereik-URI en toepassings-id voor uw bot genereren:

1. Ga naar de Azure-portal.
2. Als u nog geen botresource hebt, maakt u een Azure Bot-resource.
3. Ga naar de Microsoft Entra ID-service .
4. Ga naar het deelvenster App-registraties.
5. Selecteer de toepassing die is gekoppeld aan uw bot.
6. Ga naar het deelvenster Een API beschikbaar maken.
7. Selecteer Een bereik toevoegen.
   1. In het deelvenster Een bereik toevoegen wordt u aangeraden de automatisch gegenereerde toepassings-id-URI te behouden. Selecteer Opslaan en doorgaan.
   2. Voer een bereiknaam in.
   3. Voor Wie kan toestemming worden gegeven?, Beheer s en gebruikers heeft de voorkeur, maar beide opties werken wel.
   4. Voer een weergavenaam voor Beheer toestemming en een beschrijving van Beheer toestemming in.
   5. Voer desgewenst een weergavenaam voor gebruikerstoestemming en een beschrijving van gebruikerstoestemming in.
   6. Controleer of de status is ingesteld op Ingeschakeld.
   7. Selecteer Bereik toevoegen.
8. Selecteer Een clienttoepassing toevoegen.
   1. Stel in het deelvenster Een clienttoepassing toevoegen de client-id 81473081-50b9-469a-b9d8-303109583ecb in op de client-id van het zoekplatform.
   2. Selecteer onder Geautoriseerde bereiken de bereik-URI die u in de vorige stap hebt gemaakt.
   3. Selecteer Toepassing toevoegen.
9. Ga naar het deelvenster Overzicht . Kopieer de toepassings-id-URI. U hebt deze nodig wanneer u uw bot registreert in het zoekkanaal.

Uw bot implementeren

Het zoekkanaal verzendt elke gebruikersquery naar uw bot als een aanroepactiviteit met de naam 'application/search'. Uw bot retourneert de queryresultaten in het aanroepende antwoord. Gebruik de adaptieve kaartindeling voor de queryresultaten die naar het zoekkanaal worden verzonden.

1. Werk alle Bot Framework- en Adaptieve kaartenpakketten in uw project bij naar de nieuwste versie.
2. Voeg eventueel verificatiecode toe om een gebruikerstoken te genereren.
3. Implementeer een gegevenszoekmethode voor elke gegevensbron die moet worden opgenomen.
4. Genereer de adaptieve kaart om de resultaten weer te geven.

De tracerings-id van het zoekplatform ophalen

Het Zoekplatform wijst een unieke tracerings-id toe aan elke query die naar uw bot wordt verzonden. Het platform voegt dit toe aan de kanaalgegevens van de aanroepactiviteit. U kunt besluiten om de tracerings-id van de aanvraag te registreren. Gebruik de eigenschap van traceId de kanaalgegevens om de tracerings-id op te halen.

In het federatieve zoekvoorbeeld laat de SearchHelper.GetSearchTraceId methode zien hoe u de tracerings-id opgeeft van de aanroepactiviteit.

Verificatie toevoegen

Als u uw bot-API beschikbaar hebt gemaakt voor Zoeken en u hebt verificatie aangevraagd bij het verbinden van uw bot met Zoeken, kunt u het token voor gebruikersverificatie ophalen uit de kanaalgegevens van de activiteit.

De eigenschap van authorizations de kanaalgegevens kan een lijst met verificatietokens bevatten. Als u de bot-API beschikbaar maakt voor zoeken, bevat de lijst het token namens het token. Het token in de lijst heeft de volgende structuur:

Eigenschapsnaam	Type	Description
authType	geheel getal	Het verificatietokentype: 0 voor onbekend of standaard, of 2 voor namens-token.
token	tekenreeks	Het verificatietoken zelf.

In het federatieve zoekvoorbeeld:

• De SearchBotAuthenticationToken klasse en de AuthenticationTypes opsomming vertegenwoordigen deze informatie.
• De SearchHelper.GetSearchOboToken methode laat zien hoe u het token kunt ophalen uit de aanroepactiviteit.

Zodra u het token hebt, kunt u dit gebruiken wanneer u beveiligde resources voor de gebruiker aanvraagt. Zie Microsoft Identity Platform en OAuth 2.0 On-Behalf-Of-stroom voor informatie over het gebruik van tokens namens.

Query's uitvoeren op elk gegevensarchief

Het zoekkanaal verzendt een query naar de bot als activiteit invoke , met de querydetails in de eigenschap van value de activiteit, die een JSON-object met de volgende structuur vertegenwoordigt:

Eigenschapsnaam	Type	Description
queryTekst	tekenreeks	De querytekst.
soort	tekenreeks	Het type query: 'zoeken' wanneer resultaten worden weergegeven op een aangepast verticaal tabblad of 'searchAnswer' wanneer een resultaat wordt weergegeven als antwoord op het tabblad Alles .
queryOptions	object	Aanvullende queryopties die worden gebruikt voor paginering.
queryOptions.skip	geheel getal	De index van het eerste resultaat dat moet worden verzonden.
queryOptions.top	geheel getal	Het maximum aantal resultaten dat moet worden verzonden.

U retourneert de zoekresultaten in het aanroepende antwoord:

• Stel altijd de eigenschap 200van Status het aanroepende antwoordobject in op, wat aangeeft dat de netwerkverbinding in orde is. De eigenschap van Body het object heeft een afzonderlijke statuscode.

• De Body eigenschap vertegenwoordigt een JSON-object met de volgende structuur:

  Eigenschapsnaam	Type	Description
  statuscode	geheel getal	Een HTTP-statuscode die wordt gebruikt om aan te geven of de bot de query kan uitvoeren.
  type	tekenreeks	Het type aanroepantwoord, waarmee de indeling van het waardeveld wordt gedefinieerd. Gebruik 'application/vnd.microsoft.search.searchResponse' voor zoekresultaten of 'application/vnd.microsoft.error' voor een foutbericht.
  waarde	object	Een waarde die overeenkomt met de waarde type.

  Voor foutberichten bevat het value object:

  Eigenschapsnaam	Type	Description
  code	tekenreeks	Een foutcode die is gedefinieerd door de bot of null als deze niet is opgegeven.
  bericht	tekenreeks	Een foutbericht of null als dit niet is opgegeven.

  Voor zoekresultaten bevat het value object:

  Eigenschapsnaam	Type	Description
  Resultaten	matrix met zoekresultaatobjecten	De resultaten, of null als er geen.
  displayLayouts	matrix van weergave-indelingsobjecten	De weergave-indelingen of null als er geen zijn.
  totalResultCount	geheel getal	De totale beschikbare resultaten, als paginering wordt ondersteund; anders, null.
  moreResultsAvailable	Booleaanse waarde	Geeft aan of er meer resultaten beschikbaar zijn.

  Zoekresultaatobjecten bevatten:

  Eigenschapsnaam	Type	Description
  waarde	tekenreeks	Een unieke id of waarde voor dit zoekresultaat.
  layoutId	tekenreeks	De id van de weergave-indeling die voor dit resultaat moet worden gebruikt.
  data.searchResultText	tekenreeks	De tekst voor dit resultaat.

  Weergave-indelingsobjecten bevatten:

  Eigenschapsnaam	Type	Description
  layoutId	tekenreeks	De indelings-id.
  layoutBody	tekenreeks	De hoofdtekst van de indeling als een JSON-object voor adaptieve kaarten.

In het federatieve zoekvoorbeeld laat de SearchHelper.RunFederatedSearch methode zien hoe u de querygegevens opvraagt uit de aanroepactiviteit en hoe u het aanroepende antwoord opmaken.

Zoekresultaten weergeven

U kunt zoekverticalen en resultaattypen maken om de zoekresultaten aan te passen die gebruikers zien wanneer ze zoeken in SharePoint, Office en Bing. Met verticalen kunnen gebruikers gemakkelijker de informatie vinden die ze mogen zien. Zie de sectie Ondersteunde adaptieve kaartelementen voor meer informatie.

Als uw bot een query ontvangt waarvoor deze geen antwoord heeft, moet het antwoord een leeg antwoord bevatten.

Uw bot registreren in Azure

Als u uw bot wilt verbinden met het zoekkanaal, moet er een botresource zijn ingericht in Azure. Zie voor meer informatie hoe u een bot registreert bij Azure of hoe u uw bot implementeert in Azure.

Verbinding maken uw bot zoeken

In de volgende instructies ziet u hoe u een bot verbindt met Zoeken.

Tip

U wordt aangeraden de zoekprovider in te schakelen in een testtenant voordat u deze in productie inschakelt.

1. Ga naar de Azure-portal.

2. Open uw botresource.

3. Open het deelvenster Kanalen (preview).

4. Selecteer Zoeken.

5. Voer op het tabblad Zoeken Instellingen gegevens in voor uw bot.

   

   1. Voer onder Metagegevens van de zoekprovider de naam in die moet worden weergegeven in de gebruikersinterface van de zoekfunctie.

   2. Definieer onder Triggertermen de zinnen die de query's vertegenwoordigen die uw bot kan beantwoorden.

      Notitie

      Voor initiële releases is alleen Engels (en-US) beschikbaar.

      • Upload een .csv bestand met de woordgroepen. Het bestand moet één kolom met gegevens bevatten, zonder kopteksten.
      • Selecteer in de lijst taalvoorkeur de taal waarin de triggertermen zijn geschreven.

   3. Geef onder Verificatie aan of uw zoekprovider gebruikersverificatie vereist.

      • Als verificatie is vereist, voert u de verificatie-URL in. Gebruik de URI van de toepassings-id die u hebt gekopieerd toen u de API voor uw bot beschikbaar maakte.

   4. Selecteer Volgende.

6. Als u op het tabblad Verticals de resultaten van uw zoekprovider wilt weergeven in een eigen aangepaste verticale kolom op de pagina met zoekresultaten, voert u de verticale naam in het veld in. Anders laat u dit veld leeg. Selecteer vervolgens Volgende.
   De pagina met zoekresultaten is bedoeld voor Office.com, SharePoint.com en Bing.com.

7. Controleer uw instellingen op het tabblad Tenantpublicatie en voeg publicatiegegevens toe.

   1. Controleer de naam en voorbeeldquery's van de zoekprovider. Ga zo nodig terug naar de vorige tabbladen om deze informatie te wijzigen.
   2. Voer een beschrijving in van uw zoekprovider.
   3. Voer een e-mailadres van een ondersteuningsmedewerker in. Gebruik het e-mailadres van een ontwikkelaar of ontwikkelaarsgroep die toegang heeft tot de zoekprovider.

8. Selecteer Toevoegen om goedkeuring aan te vragen bij uw IT-beheerder.

Een zoekprovider in een tenant goedkeuren

De goedkeuring van de zoekprovider in de tenant wordt gemaakt door een IT-beheerder op de pagina Search & Intelligence in de Microsoft 365-beheercentrum.

Test de verbinding

U wordt aangeraden de zoekprovider in te schakelen in een testtenant voordat u deze in productie inschakelt.

Een zoekprovider wijzigen

U kunt de zoekprovider bewerken voordat u deze indient voor beoordeling door de IT-beheerder. Mogelijk moet u dit doen als uw eerste aanvraag wordt geweigerd of als uw service is gedeactiveerd.

1. Ga in Azure Portal naar de botresource die de zoekprovider bevat die u wilt bewerken.
2. Ga naar het deelvenster Kanalen (preview).
3. Selecteer het zoekkanaal en selecteer Bewerken.
   1. Azure geeft het deelvenster Zoekkanaal weer. In dit deelvenster kunt u uw instellingen bewerken.
   2. Als u de triggertermen wilt wijzigen, downloadt u het bestand, bewerkt u het lokaal en uploadt u het bestand.
   3. Zodra u klaar bent met uw bewerkingen, selecteert u Opnieuw toevoegen om de zoekprovider in te dienen voor controle door de IT-beheerder.

Een zoekprovider verwijderen

Uw zoekprovider wordt verwijderd als u het zoekkanaal uit de botresource verwijdert.

Het zoekkanaal verwijderen uit uw bot:

1. Ga in Azure Portal naar uw botresource.
2. Ga naar het deelvenster Kanalen (preview).
3. Selecteer het zoekkanaal.
4. Selecteer Het kanaal verwijderen bovenaan het deelvenster Zoekkanaal.
5. Selecteer Ja om de bewerking te bevestigen.

Uw botresource verwijderen:

1. Ga in Azure Portal naar uw botresource.
2. Als u dit nog niet hebt gedaan, verwijdert u het zoekkanaal uit uw bot.
3. Selecteer Verwijderen bovenaan het deelvenster Overzicht.
4. Selecteer OK om de bewerking te bevestigen.

Aanvullende informatie

Het zoekkanaal maakt gebruik van federatieve zoekopdrachten en het schema adaptieve kaarten:

Zie Adaptieve kaarten voor botontwikkelaars voor meer informatie over het adaptieve kaartschema.

Over triggertermen

Een triggerterm is een woordgroep die door het zoekplatform wordt gebruikt om een query te routeren naar uw aangepaste zoekprovider, mogelijk gemaakt door uw bot. Federatieve zoekopdracht stuurt de uiting van een gebruiker door naar uw zoekprovider wanneer de uiting een nauwe overeenkomst is met een van de triggertermen.

Tip

Als er meer dan één zoekprovider beschikbaar is, kiest federatieve zoekopdracht slechts één, op basis van de opgegeven triggertermen en de query van de gebruiker.

Denk bijvoorbeeld aan een bot die vluchtschema's en status beheert.

1. Denk aan een aantal veelvoorkomende manieren waarop een gebruiker naar uw bot verwijst of gebruikt. Zorg ervoor dat u uw bot onderscheidt van anderen.

   In plaats van een algemene term, zoals 'tijdschema' die van toepassing kunnen zijn op scholen en tv-programma's, gebruikt u specifiekere zinnen, zoals "vliegtijdtabel" en "vluchtschema".

2. Neem diverse zinnen op die betrekking hebben op het bereik van de functies van uw bot, zoals vertrektijd en huidige status.

   Neem bijvoorbeeld query's op over: aankomst- of vertrektijden en luchthavens.

De triggertermen voor een dergelijke vluchtplanning en statusbot kunnen het volgende omvatten:

• Vluchtrooster
• Vluchtstatus
• Vlucht 675 vertrektijd
• Wanneer vertrekt mijn vlucht
• Vlucht 468 aankomsttijd
• Seattle Tacoma vluchtstatus
• Vluchtstatus Van Heathrow

In een ander voorbeeld kunnen de triggertermen voor een weersvoorspellingsbot het volgende omvatten:

• Lokale weersvoorspelling
• Weersinformatie
• Het weer van morgen
• 10-daagse weersvoorspelling
• Vandaag hoog
• De kans op regen van vandaag
• Zal het morgen sneeuwen
• Windsnelheid morgen
• Is het winderig buiten
• Weer in Londen

Ondersteunde adaptieve kaartelementen

Een subset van het adaptieve kaartschema wordt ondersteund in federatieve zoekopdrachten. Zie De pagina met zoekresultaten aanpassen voor informatie over het opmaken van uw zoekresultaten.

Ondersteuning omvat de volgende adaptieve kaartelementen: TextBlock, RichTextBlock, Image, ColumnSet, ImageSet en FactSet. Zie de indelingen voor zoekresultaten beheren van Microsoft Search en de Schemaverkenner voor adaptieve kaarten voor meer informatie.

U kunt elke kaart rechtstreeks als JSON ontwerpen of u kunt het NuGet-pakket AdaptiveCards gebruiken.

Federatieve zoekopdrachten bieden geen ondersteuning voor HTML

Belangrijk

Federatieve zoekopdracht geeft geen adaptieve kaarttekst weer die HTML bevat.

Het Zoekplatform bevat geen HTML-parser. U kunt echter enkele tags verwijderen en het NuGet-pakket Html2Markdown gebruiken om HTML te converteren naar Markdown:

1. Verwijderen <span> en <u> elementen.
2. Vervangen en <br> elementen door <div> alinea-elementen (<p>)
3. Converteer de resterende HTML naar Markdown.

Volgende stappen

• Zie Verbinding maken een bot naar kanalen voor informatie over kanaalondersteuning in de Bot Verbinding maken or Service.
• Zie Hoe bots werken en hoe bots werken en hoe een bot met de Bot Framework SDK-quickstart werkt voor meer informatie over het bouwen van bots.
• Zie Uw bot implementeren en continue implementatie instellen voor meer informatie over het implementeren van bots.