Legg til en Power Virtual Agents-robot i Azure Bot Service-kanaler

[Dette emnet inneholder dokumentasjon for forhåndsversjonen, og kan bli endret.]

Du kan koble roboten din til eksisterende Azure Bot Service-kanaler. Dette kan være nyttig hvis du vil koble roboten din til sluttbrukere på Azure Bot Service-kanaler.

For å legge til roboten din i Azure Bot Service-kanaler kreves det betydelig utviklingsekspertise. Dette emnet er skrevet for IT-administratorer eller utviklere som har erfaring med å utvikle og skrive kode.

Tips!

Du trenger ikke å følge dette dokumentet for å legge til en Power Virtual Agents-robot på nettstedet ditt, Facebook eller Microsoft Teams. Hvis målet er å koble til en egendefinert nettbasert eller innebygd app, kan utviklerne lære mer på Legge til roboten i mobilapper og egendefinerte apper.

Viktig!

Instruksjonene i denne delen krever programvareutvikling fra deg eller utviklerne. Den er beregnet på erfarne IT-medarbeidere, for eksempel IT-administratorer eller utviklere som har en solid forståelse av utviklerverktøy, og integrerte utviklingsmiljøer (IDE).

Forutsetninger

Du bør også lese Koble roboten til mobilapper og egendefinerte apper før du følger instruksjonene i dette emnet.

Eksempelkoder

Kodesnutter som brukes i dette dokumentet, er fra eksempelkode for relérobot.

Referanser

Instruksjonene i dette dokumentet refererer til følgende:

Opprett eller bruk en eksisterende Azure Bot Service-robot

Du trenger en Azure Bot Service-robot som kan videresende samtaler mellom Power Virtual Agents-roboten og Azure Bot Service-kanaler.

Diagram for relérobot.

Eksempel koden for relérobot er et godt utgangspunkt hvis du ikke har en eksisterende Azure Bot Service-robot. Den er bygget ut ifra Microsoft Bot Framework-roboten eksempelkode som kan kompileres og distribueres til Azure Bot Service. Eksempelkoden er ment å skulle brukes som utgangspunkt, og er ikke ment å brukes direkte i produksjonen. Du må legge til kode og optimalisering som samsvarer med dine forretningsbehov.

Hvis du allerede har en Azure Bot Service-robot, må du legge til en Power Virtual Agents-kobling og kode for å administrere samtaleøkter. Du kan deretter distribuere roboten til Azure Bot Service og koble til kanaler med Azure-portalen.

Hent Power Virtual Agents-robotparameterne dine

Hvis du vil koble til roboten du har bygget med Power Virtual Agents, må du hente robotens navn, robot-ID og leier-ID for å identifisere den.

  1. Kopier navnet på roboten i Power Virtual Agents.

    Hent navnet på roboten.

  2. Velg Behandle i navigasjonsruten på siden, og gå deretter til Kanaler.

  3. Velg kanalen du ønsker å koble til. I dette emnet brukes Slack som eksempel.

    Slack-kanal.

  4. Kopier og lagre verdiene for Robot-ID og leier-ID ved å velge Kopier. Du trenger disse når du kobler roboten til Azure Bot Service-kanalen.

    Hent robotens parametere.

Administrere samtaleøkter med Power Virtual Agents-roboten

Det kan være flere diskusjoner mellom Azure Bot Service-kanalene og Direct Line-tilkoblingen med Power Virtual Agents-roboten.

Azure Bot Service-roboten må tilordne og videresende samtalen fra Azure Bot Service-kanalen til Direct Line-samtalen med Power Virtual Agents-roboten og omvendt.

Eksempel på eksempelkode

Eksemplet nedenfor bruker eksempler fra eksempelkoden for relérobot.

  1. Start en Power Virtual Agents-samtale på alle nye, eksterne Azure Bot Service-kanaler. Se Hente Direct Line-token og Bruke Direct Line til å kommunisere med roboten for instruksjoner om hvordan du starter en ny samtale med roboten.

    using (var httpRequest = new HttpRequestMessage())
    {   
        httpRequest.Method = HttpMethod.Get;
        UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
        uriBuilder.Query = $"botId={BotId}&tenantId={TenantId}";
        httpRequest.RequestUri = uriBuilder.Uri;
        using (var response = await s_httpClient.SendAsync(httpRequest))
        {
            var responseString = await response.Content.ReadAsStringAsync();
            string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
        }
    }
    
    /// <summary>
    /// class for serialization/deserialization DirectLineToken
    /// </summary>
    public class DirectLineToken
    {
        public string Token { get; set; }
    }
    
     // Use the retrieved token to create a DirectLineClient instance
     using (var directLineClient = new DirectLineClient(token))
     {
         var conversation = await directLineClient.Conversations.StartConversationAsync();
         string conversationtId = conversation.ConversationId;
     }
    
  2. Hvis du vil administrere flere økter, må du opprettholde en tilordning av eksterne Azure Bot Service-kanalsamtaler til tilsvarende Power Virtual Agents-samtaler. En Power Virtual Agents-samtale kan identifiseres og kobles til ved hjelp av to egenskaper: ConversationtId og Token.

    Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();  
    
    

    Hvis du vil administrere samtalelivssyklusen, kan du oppdatere Direct Line-tokener eller rydde opp i inaktive diskusjoner. Du kan finne ut mer om oppdatering av token ved å se Oppdatere Direct Line-token. En Power Virtual Agents-samtale for å støtte disse er definert på følgende måte:

    /// <summary>
    /// Data model class for Power Virtual Agents conversation
    /// </summary>
    public class PowerVirtualAgentsConversation
    {
        public string ConversationtId { get; set; } // The Power Virtual Agents conversation ID retrieved from step 1
    
        public string Token { get; set; } // The DirectLine token retrieved from step 1
    
        public string WaterMark { get; set; } // Identify turn in a conversation
    
        public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh
    
        public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to bot
    }
    
  3. Når en ny Power Virtual Agents-samtale starter, legger du til et nøkkelverdipar (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) i tilordningstabellen.

    // After new Power Virtual Agents conversation starts
    ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
      {
        Token = token,
        ConversationtId = conversationId,
        WaterMark = null,
        LastConversationUpdateTime = DateTime.Now,
        LastTokenRefreshTime = DateTime.Now,
      }; 
    
  4. Hvis du vil fortsette med en eksisterende samtale etter å ha mottatt en ny ekstern melding i Azure Bot Service-kanalen, henter du den eksisterende diskusjonen fra tilordningstabellen, videresender den eksterne samtaleaktiviteten til Power Virtual Agents-roboten, og får et svar.

    Eksempelet nedenfor viser videresending av samtale ved overstyring av ActivityHandler.OnMessageActivityAsync((ITurnContext, CancellationToken)-metoden

    // Invoked when a message activity is received from the user
    // Send the user message to Power Virtual Agents bot and get response
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        // Retrieve bot conversation from mapping table
        // If not exists for the given external conversation ID, start a new Power Virtual Agents conversation
        ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
                currentConversation : /*await StartBotConversationAsync(externalCID)*/;
    
        // Create DirectLine client with the token associated to current conversation
        DirectLineClient client = new DirectLineClient(currentConversation.Token);
    
        // Send user message using directlineClient
        await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
        {
          Type = DirectLineActivityTypes.Message,
          From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
          Text = turnContext.Activity.Text,
          TextFormat = turnContext.Activity.TextFormat,
          Locale = turnContext.Activity.Locale,
        });
    
        // Update LastConversationUpdateTime for session management
        currentConversation.LastConversationUpdateTime = DateTime.Now;
    }  
    
  5. Se Bruke Direct Line til å kommunisere med roboten for instruksjoner om hvordan du for svaret fra Power Virtual Agents-roboten. Når Power Virtual Agents-robotens svar er mottatt, kan du se Dele opp samtalens nyttelast fra roboten for hvordan du kan dele opp svaret til svaret i en ekstern Azure Bot Service-kanal.

Et eksempel på svaroppdeling finner du i eksempelkode for relérobot ResponseConverter.cs.

Distribuere til Azure Bot Service

Når du har en Azure Bot Service-relérobot klar, må du distribuere roboten til Azure Bot Service.

Konfigurere Azure Bot Service-kanaler

Du kan angi hvilke kanaler du vil koble til, ved å logge på Azure-portalen og velge ressursgruppen for Azure Bot Service du har distribuert til. Se de spesifikke instruksjonene for hver kanal på Azure Bot Service-kanaler.