Konfigurera webbslutpunkter

Viktigt!

Anpassade kommandon dras tillbaka den 30 april 2026. Från och med den 30 oktober 2023 kan du inte skapa nya program för anpassade kommandon i Speech Studio. I samband med den här ändringen dras LUIS tillbaka den 1 oktober 2025. Från och med den 1 april 2023 kan du inte skapa nya LUIS-resurser.

I den här artikeln får du lära dig hur du konfigurerar webbslutpunkter i ett program för anpassade kommandon som gör att du kan göra HTTP-begäranden från ett klientprogram. Du utför följande uppgifter:

• Konfigurera webbslutpunkter i programmet Anpassade kommandon
• Anropa webbslutpunkter i programmet Anpassade kommandon
• Ta emot webbslutpunkternas svar
• Integrera webbslutpunkternas svar i en anpassad JSON-nyttolast, samt skicka och visualisera det från ett Speech SDK-klientprogram för C# UWP

Förutsättningar

• Visual Studio 2019
• En Azure AI Speech-resursnyckel och -region: Skapa en Speech-resurs på Azure-portalen. Mer information finns i Skapa en resurs med flera tjänster.
• En app för anpassade kommandon (se Skapa en röstassistent med anpassade kommandon)
• En Speech SDK-aktiverad klientapp (se Integrera med ett klientprogram med Speech SDK)

Distribuera en extern webbslutpunkt med hjälp av Azure Function-appen

I den här självstudien behöver du en HTTP-slutpunkt som underhåller tillstånd för alla enheter som du har konfigurerat i TurnOnOff-kommandot för ditt program för anpassade kommandon.

Om du redan har en webbslutpunkt som du vill anropa går du vidare till nästa avsnitt. I nästa avsnitt finns också information om en standardwebbslutpunkt som du kan använda om du vill hoppa över det här avsnittet.

Indataformat för Azure-funktionen

Sedan distribuerar du en slutpunkt med Hjälp av Azure Functions. Följande är formatet för en händelse med anpassade kommandon som skickas till din Azure-funktion. Använd den här informationen när du skriver azure-funktionsappen.

{
  "conversationId": "string",
  "currentCommand": {
    "name": "string",
    "parameters": {
      "SomeParameterName": "string",
      "SomeOtherParameterName": "string"
    }
  },
  "currentGlobalParameters": {
      "SomeGlobalParameterName": "string",
      "SomeOtherGlobalParameterName": "string"
  }
}

I följande tabell beskrivs nyckelattributen för dessa indata:

Attribut	Förklaring
conversationId	Konversationens unika identifierare. Observera att det här ID:t kan genereras av klientappen.
currentCommand	Kommandot som för närvarande är aktivt i konversationen.
Namn	Namnet på kommandot. Attributet parameters är en karta med parametrarnas aktuella värden.
currentGlobalParameters	En karta som parameters, men används för globala parametrar.

För DeviceState Azure-funktionen ser en exempelhändelse med anpassade kommandon ut som följande. Detta fungerar som indata till funktionsappen.

{
  "conversationId": "someConversationId",
  "currentCommand": {
    "name": "TurnOnOff",
    "parameters": {
      "item": "tv",
      "value": "on"
    }
  }
}

Azure Function-utdata för en anpassad kommandoapp

Om utdata från din Azure-funktion används av en app för anpassade kommandon bör den visas i följande format. Mer information finns i Uppdatera ett kommando från en webbslutpunkt .

{
  "updatedCommand": {
    "name": "SomeCommandName",
    "updatedParameters": {
      "SomeParameterName": "SomeParameterValue"
    },
    "cancel": false
  },
  "updatedGlobalParameters": {
    "SomeGlobalParameterName": "SomeGlobalParameterValue"
  }
}

Azure Function-utdata för ett klientprogram

Om utdata från din Azure-funktion används av ett klientprogram kan utdata ha det format som klientprogrammet kräver.

För vår DeviceState-slutpunkt förbrukas utdata från din Azure-funktion av ett klientprogram i stället för programmet Anpassade kommandon. Exempelutdata för Azure-funktionen bör se ut så här:

{
  "TV": "on",
  "Fan": "off"
}

Dessa utdata ska skrivas till en extern lagringsplats så att du kan behålla enheternas tillstånd. Det externa lagringstillståndet används i avsnittet Integrera med klientprogram nedan.

Distribuera en Azure-funktion

Vi tillhandahåller ett exempel som du kan konfigurera och distribuera som en Azure Functions-app. Följ dessa steg för att skapa ett lagringskonto för vårt exempel.

1. Skapa tabelllagring för att spara enhetens tillstånd. I Azure-portalen skapar du en ny resurs av typen Lagringskonto efter namn devicestate.
2. Kopiera värdet för Anslut ionssträngen från devicestate –> Åtkomstnycklar. Du måste lägga till den här stränghemligheten i den nedladdade funktionsappens kodexempel.
3. Ladda ned exempelkod för funktionsappen.
4. Öppna den nedladdade lösningen i Visual Studio 2019. I Anslut ions.json ersätter du STORAGE_ACCOUNT_SECRET_CONNECTION_STRING med hemligheten från steg 2.
5. Ladda ned DeviceStateAzureFunction-koden.

Följ dessa steg för att distribuera exempelappen till Azure Functions.

1. Distribuera Azure Functions-appen.
2. Vänta tills distributionen har slutförts och gå till den distribuerade resursen på Azure-portalen.
3. Välj Funktioner i den vänstra rutan och välj sedan DeviceState.
4. I det nya fönstret väljer du Kod + Test och sedan Hämta funktions-URL.

Konfigurera webbslutpunkter i anpassade kommandon

Nu ska vi ansluta Azure-funktionen till det befintliga programmet Anpassade kommandon. I det här avsnittet använder du en befintlig standardslutpunkt för DeviceState . Om du har skapat en egen webbslutpunkt med Hjälp av Azure-funktionen eller på annat sätt använder du den i stället för standardvärdet https://webendpointexample.azurewebsites.net/api/DeviceState.

1. Öppna programmet Anpassade kommandon som du skapade tidigare.

2. Gå till Webbslutpunkter och välj Ny webbslutpunkt.

   

   Inställning	Föreslaget värde	Description
   Name	UpdateDeviceState	Namnet på webbslutpunkten.
   webbadress	https://webendpointexample.azurewebsites.net/api/DeviceState	URL-adressen till den slutpunkt som du vill att din anpassade kommandoapp ska kommunicera med.
   Metod	POST	Tillåtna interaktioner (till exempel GET, POST) med din slutpunkt.
   Sidhuvuden	Nyckel: app, Värde: ta de första åtta siffrorna i ditt applicationId	De rubrikparametrar som ska ingå i begärandets rubrik.

   Kommentar

   • Exempelwebbslutpunkten som skapats med Hjälp av Azure Functions, som ansluter till databasen som sparar enhetens tillstånd för tv och fläkt.
   • Det föreslagna huvudet behövs bara för exempelslutpunkten.
   • Kontrollera att värdet för rubriken är unikt i vår exempelslutpunkt genom att ta de första 8 siffrorna i ditt applicationId.
   • I verkligheten kan webbslutpunkten vara slutpunkten till den IOT-hubb som hanterar dina enheter.

3. Välj Spara.

Anropa webbslutpunkter

1. Gå till kommandot TurnOnOff, välj ConfirmationResponse under slutföranderegeln och välj sedan Lägg till en åtgärd.

2. Under Ny åtgärdstyp väljer du Anropa webbslutpunkt

3. I Redigera åtgärd – Slutpunkter väljer du UpdateDeviceState, som är webbslutpunkten vi skapade nyss.

4. I Konfiguration anger du följande värden:

   

   Inställning	Föreslaget värde	beskrivning
   Slutpunkter	UpdateDeviceState	Den webbslutpunkt som du vill anropa med åtgärden.
   Frågeparametrar	item={SubjectDevice}&&value={OnOff}	Frågeparametrarna som ska läggas till i webbslutpunktens URL.
   Brödtextinnehåll	Ej tillämpligt	Brödtextinnehållet i begärandet.

   Kommentar

   • De föreslagna frågeparametrarna behövs bara i slutpunktsexemplet

5. I Vid lyckad åtgärd – Åtgärd att utföra väljer du Skicka talsvar.

   I Enkelt redigeringsprogram anger du {SubjectDevice} is {OnOff}.

   

   Inställning	Föreslaget värde	beskrivning
   Åtgärd att utföra	Skicka talsvar	Åtgärd att utföra om begäran till webbslutpunkten lyckas

   Kommentar

   • Du kan också få direkt åtkomst till fälten i http-svaret med hjälp av {YourWebEndpointName.FieldName}. Till exempel: {UpdateDeviceState.TV}

6. I Vid fel – Åtgärd att utföra väljer du Skicka talsvar

   I Enkelt redigeringsprogram anger du Sorry, {WebEndpointErrorMessage}.

   

   Inställning	Föreslaget värde	beskrivning
   Åtgärd att utföra	Skicka talsvar	Åtgärd att utföra om begäran till webbslutpunkten misslyckas

   Kommentar

   • {WebEndpointErrorMessage} är valfritt. Du kan ta bort den om du inte vill visa något felmeddelande.
   • I vårt slutpunktsexempel skickar vi tillbaka http-svar med detaljerade felmeddelanden om vanliga fel som t.ex. saknade rubrikparametrar.

Testa i testportalen

• Spara, träna och testa när svaret lyckades.

  

• Vid felsvar tar du bort en av frågeparametrarna, sparar, tränar om och testar.

  

Integrera med klientprogram

I Skicka aktivitet för anpassade kommandon till klientprogrammet lade du till en skicka-aktivitet till klientåtgärden . Aktiviteten skickas till klientprogrammet oavsett om åtgärden Anropa webbslutpunkt har slutförts eller inte. Vanligtvis vill du dock bara skicka aktivitet till klientprogrammet när anropet till webbslutpunkten lyckas. I det här exemplet sker det när enhetens status har uppdaterats.

1. Ta bort åtgärden Skicka aktivitet till klient som du tidigare lade till.
2. Redigera anropswebbslutpunkt:
   1. I Konfiguration kontrollerar du att Frågeparametrar är item={SubjectDevice}&&value={OnOff}
   2. I Vid lyckad åtgärd ändrar du Åtgärd att utföra till Skicka aktivitet till klient
   3. Kopiera JSON-filen nedan till Aktivitetsinnehåll

   {
      "type": "event",
      "name": "UpdateDeviceState",
      "value": {
        "state": "{OnOff}",
        "device": "{SubjectDevice}"
      }
    }
   

Nu skickar du bara aktivitet till klienten när begäran till webbslutpunkten lyckas.

Skapa visuella objekt som synkroniserar enhetstillstånd

Lägg till följande XML MainPage.xaml ovanför blocket EnableMicrophoneButton .

<Button x:Name="SyncDeviceStateButton" Content="Sync Device State"
        Margin="0,10,10,0" Click="SyncDeviceState_ButtonClicked"
        Height="35"/>
<Button x:Name="EnableMicrophoneButton" ......
        .........../>

Synkronisera enhetstillstånd

I MainPage.xaml.cs lägger du till referensen using Windows.Web.Http;. Lägg till följande kod i klassen MainPage. Den här metoden skickar en GET-begäran till exempelslutpunkten och extraherar appens aktuella enhetstillstånd. Se till att ändra <your_app_name> till det du använde i rubriken i webbslutpunkten för anpassat kommando.

private async void SyncDeviceState_ButtonClicked(object sender, RoutedEventArgs e)
{
    //Create an HTTP client object
    var httpClient = new HttpClient();

    //Add a user-agent header to the GET request.
    var your_app_name = "<your-app-name>";

    Uri endpoint = new Uri("https://webendpointexample.azurewebsites.net/api/DeviceState");
    var requestMessage = new HttpRequestMessage(HttpMethod.Get, endpoint);
    requestMessage.Headers.Add("app", $"{your_app_name}");

    try
    {
        //Send the GET request
        var httpResponse = await httpClient.SendRequestAsync(requestMessage);
        httpResponse.EnsureSuccessStatusCode();
        var httpResponseBody = await httpResponse.Content.ReadAsStringAsync();
        dynamic deviceState = JsonConvert.DeserializeObject(httpResponseBody);
        var TVState = deviceState.TV.ToString();
        var FanState = deviceState.Fan.ToString();
        await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync(
            CoreDispatcherPriority.Normal,
            () =>
            {
                State_TV.Text = TVState;
                State_Fan.Text = FanState;
            });
    }
    catch (Exception ex)
    {
        NotifyUser(
            $"Unable to sync device status: {ex.Message}");
    }
}

Prova nu

1. Starta programmet.
2. Välj Synkronisera enhetstillstånd.
   Om du testade appen med turn on tv i föregående avsnitt skulle du se TV-programmen som på.

   

3. Välj Aktivera mikrofon.
4. Välj knappen Samtal .
5. Säg turn on the fan. Fläktens visuella tillstånd bör ändras till på.

   

Nästa steg

Uppdatera ett kommando från en klientapp