Nastavení webových koncových bodů

Důležité

Vlastní příkazy budou vyřazeny 30. dubna 2026. Od 30. října 2023 nemůžete v sadě Speech Studio vytvářet nové aplikace Vlastních příkazů. V souvislosti s touto změnou bude služba LUIS vyřazena 1. října 2025. Od 1. dubna 2023 nemůžete vytvářet nové prostředky LUIS.

V tomto článku se dozvíte, jak nastavit webové koncové body v aplikaci Custom Commands, která umožňuje provádět požadavky HTTP z klientské aplikace. Provedete následující úkoly:

• Nastavení webových koncových bodů webu v aplikaci Vlastní příkazy
• Volání webových koncových bodů webu v aplikaci Vlastní příkazy
• Příjem odpovědí webových koncových bodů
• Integrace odpovědí webových koncových bodů do vlastní datové části JSON, odeslání a vizualizace z klientské aplikace Speech SDK pro UPW v C#

Požadavky

• Visual Studio 2019
• Klíč a oblast prostředku Azure AI Speech: Vytvořte prostředek služby Speech na webu Azure Portal. Další informace najdete v tématu Vytvoření prostředku s více službami.
• Aplikace Vlastní příkazy (viz Vytvoření hlasového asistenta pomocí vlastních příkazů)
• Klientská aplikace s povolenou sadou Speech SDK (viz Integrace s klientskou aplikací pomocí sady Speech SDK)

Nasazení externího webového koncového bodu pomocí aplikace funkcí Azure

Pro účely tohoto kurzu potřebujete koncový bod HTTP, který udržuje stavy pro všechna zařízení, která jste nastavili v příkazu TurnOnOff aplikace Custom Commands.

Pokud už máte webový koncový bod, který chcete volat, přejděte k další části. Další část obsahuje podrobnosti o výchozím hostované webovém koncovém bodu, který můžete použít, pokud chcete tento oddíl přeskočit.

Formát vstupu funkce Azure

Dále nasadíte koncový bod pomocí Azure Functions. Následuje formát události Vlastní příkazy, která se předá vaší funkci Azure. Tyto informace použijte při psaní aplikace Funkcí Azure.

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

Následující tabulka popisuje klíčové atributy tohoto vstupu:

Atribut	Vysvětlení
conversationId	Jedinečný identifikátor konverzace. Všimněte si, že toto ID může klientská aplikace vygenerovat.
currentCommand	Příkaz, který je aktuálně aktivní v konverzaci.
Jméno	Název příkazu. Atribut parameters je mapa s aktuálními hodnotami parametrů.
currentGlobalParameters	Mapa jako parameters, ale používá se pro globální parametry.

V případě funkce Azure DeviceState vypadá příklad události Vlastní příkazy takto. Funguje jako vstup do aplikace funkcí.

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

Výstup funkce Azure pro vlastní aplikaci příkazů

Pokud aplikace Vlastní příkazy využívá výstup funkce Azure Functions, měla by se zobrazit v následujícím formátu. Podrobnosti najdete v tématu Aktualizace příkazu z webového koncového bodu .

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

Výstup funkce Azure Functions pro klientskou aplikaci

Pokud klientská aplikace využívá výstup funkce Azure Functions, může výstup mít jakýkoliv tvar, který klientská aplikace vyžaduje.

U koncového bodu DeviceState se výstup funkce Azure využívá klientskou aplikací místo aplikace Custom Commands. Příklad výstupu funkce Azure by měl vypadat takto:

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

Tento výstup by se měl zapsat do externího úložiště, abyste mohli udržovat stav zařízení. Stav externího úložiště se používá v části Integrace s klientskou aplikací níže.

Nasazení funkce Azure Functions

Nabízíme ukázku, kterou můžete nakonfigurovat a nasadit jako aplikaci Azure Functions. Pokud chcete vytvořit účet úložiště pro naši ukázku, postupujte takto.

1. Vytvořte úložiště tabulek pro uložení stavu zařízení. Na webu Azure Portal vytvořte nový prostředek typu Účet úložiště podle názvu devicestate.
2. Zkopírujte hodnotu řetězce Připojení ze stavu zařízení –> Přístupové klíče. Tento tajný kód řetězce je potřeba přidat do staženého ukázkového kódu aplikace funkcí.
3. Stáhněte si vzorový kód aplikace funkcí.
4. Otevřete stažené řešení v sadě Visual Studio 2019. V Připojení ions.json nahraďte STORAGE_ACCOUNT_SECRET_CONNECTION_STRING tajným kódem z kroku 2.
5. Stáhněte si kód DeviceStateAzureFunction.

Pokud chcete nasadit ukázkovou aplikaci do Azure Functions, postupujte takto.

1. Nasaďte aplikaci Azure Functions.
2. Počkejte, až nasazení proběhne úspěšně, a přejděte na nasazený prostředek na webu Azure Portal.
3. V levém podokně vyberte Funkce a pak vyberte DeviceState.
4. V novém okně vyberte Kód + Test a pak vyberte Získat adresu URL funkce.

Nastavení webových koncových bodů ve vlastních příkazech

Pojďme připojit funkci Azure k existující aplikaci Custom Commands. V této části použijete existující výchozí koncový bod DeviceState . Pokud jste vytvořili vlastní webový koncový bod pomocí funkce Azure Functions nebo jinak, použijte místo výchozího https://webendpointexample.azurewebsites.net/api/DeviceState.

1. Otevřete aplikaci Vlastní příkazy, kterou jste si vytvořili dříve.

2. Přejděte na webové koncové body a vyberte Nový webový koncový bod.

   

   Nastavení	Navrhovaná hodnota	Description
   Name	UpdateDeviceState	Název webového koncového bodu
   Adresa URL	https://webendpointexample.azurewebsites.net/api/DeviceState	Adresa URL koncového bodu, se ke kterým má vaše aplikace Vlastní příkazy komunikovat
   metoda	POST	Povolené interakce s vaším koncovým bodem (jako jsou GET, POST)
   Hlavičky	Klíč: app, Value: take the first eight digits of your applicationId	Parametry hlavičky, které mají být zahrnuté v hlavičce požadavku

   Poznámka:

   • Ukázkový webový koncový bod vytvořený pomocí služby Azure Functions, který se připojí k databázi, která ukládá stav zařízení televizoru a ventilátoru.
   • Navrhovaná hlavička je potřebná jenom pro ukázkový koncový bod.
   • Pokud chcete mít jistotu, že je hodnota hlavičky v našem ukázkovém koncovém bodu jedinečná, vezměte prvních 8 číslic id vaší aplikace.
   • Ve skutečném světě může být webový koncový bod koncovým bodem centra IOT , který spravuje vaše zařízení.

3. Zvolte Uložit.

Volání webových koncových bodů

1. Přejděte na příkaz TurnOnOff, jako pravidlo dokončení vyberte ConfirmationResponse a potom vyberte Přidat akci.

2. V části New Action-Type (Nový typ akce) vyberte Call web endpoint (Volání koncového bodu).

3. V části Edit Action - Endpoints (Akce pro úpravy – koncové body) vyberte UpdateDeviceState. To je webový koncový bod, který jsme vytvořili.

4. V části Configuration (Konfigurace) zadejte následující hodnoty:

   

   Nastavení	Navrhovaná hodnota	Popis
   Koncové body	UpdateDeviceState	Webový koncový bod, který chcete volat v této akci
   Parametry dotazů	item={SubjectDevice}&&value={OnOff}	Parametry dotazu, které se mají připojit k adrese URL webového koncového bodu
   Textový obsah	–	Textový obsah požadavku

   Poznámka:

   • Navrhované parametry dotazů jsou nutné jenom pro ukázkový koncový bod.

5. V části On Success - Action to execute (Při úspěchu – Akce, která se má provést) vyberte Send speech response (Odeslat odpověď v řeči).

   V části Simple editor (Jednoduchý editor) zadejte {SubjectDevice} is {OnOff}.

   

   Nastavení	Navrhovaná hodnota	Popis
   Akce, která se má provést	Send speech response (Odeslat odpověď v řeči)	Akce, která se má provést, pokud se požadavek na webový koncový bod zdaří

   Poznámka:

   • K polím v odpovědi HTTP můžete také získat přímý přístup pomocí {YourWebEndpointName.FieldName}. Příklad: {UpdateDeviceState.TV}

6. V části On Failure - Action to execute (Při neúspěchu – Akce, která se má provést) vyberte Send speech response (Odeslat odpověď v řeči).

   V části Simple editor (Jednoduchý editor) zadejte Sorry, {WebEndpointErrorMessage}.

   

   Nastavení	Navrhovaná hodnota	Popis
   Akce, která se má provést	Send speech response (Odeslat odpověď v řeči)	Akce, která se má provést, pokud se požadavek na webový koncový bod nezdaří

   Poznámka:

   • {WebEndpointErrorMessage} je volitelné. Pokud nechcete zpřístupnit žádnou chybovou zprávu, můžete ho bez obav odebrat.
   • V rámci našeho ukázkového koncového bodu vracíme odpověď HTTP s podrobnými chybovými zprávami pro běžné chyby, jako jsou například chybějící parametry hlavičky.

Vyzkoušení na testovacím portálu

• Při odpovědi na úspěch uložte, trénujte a otestujte.

  

• Při odpovědi na selhání odeberte jeden z parametrů dotazu, uložte, znovu natrénujte a otestujte.

  

Integrace s klientskou aplikací

V části Odeslat vlastní příkazy do klientské aplikace jste přidali aktivitu Odeslat do akce klienta . Aktivita se odešle do klientské aplikace bez ohledu na to, jestli je akce volání webového koncového bodu úspěšná. Obvykle ale chcete do klientské aplikace posílat aktivitu jenom v případě, že je volání webového koncového bodu úspěšné. V tomto příkladu je to tehdy, když se úspěšně aktualizuje stav zařízení.

1. Odstraňte dříve přidanou akci Send activity to client (Odeslání aktivity do klientské aplikace).
2. Upravit webový koncový bod volání:
   1. V části Konfigurace zkontrolujte, že hodnota Parametry dotazu je item={SubjectDevice}&&value={OnOff}
   2. V části On Success (Při úspěchu) změňte Action to execute (Akce, která se má provést) na Send activity to client (Odeslání aktivity do klientské aplikace).
   3. Následující kód JSON zkopírujte do části Activity Content (Obsah aktivity).

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

Teď do klienta odesíláte aktivitu jenom v případech, kdy je požadavek na webový koncový bod úspěšný.

Vytváření vizuálů pro synchronizaci stavu zařízení

Přidejte následující kód XML nad MainPage.xamlblok EnableMicrophoneButton .

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

Synchronizace stavu zařízení

V části MainPage.xaml.cs přidejte odkaz using Windows.Web.Http;. Do třídy MainPage přidejte následující kód. Tato metoda odešle požadavek GET do ukázkového koncového bodu a extrahuje aktuální stav zařízení pro vaši aplikaci. Nezapomeňte změnit <your_app_name> to, co jste použili v hlavičce ve webovém koncovém bodu Vlastní příkaz.

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}");
    }
}

Vyzkoušejte si to.

1. Spusťte aplikaci.
2. Vyberte Synchronizovat stav zařízení.
   Pokud jste aplikaci otestovali v turn on tv předchozí části, uvidíte televizní pořady jako zapnuté.

   

3. Vyberte Povolit mikrofon.
4. Vyberte tlačítko Talk (Talk).
5. Řekněme turn on the fan. Vizuální stav ventilátoru by se měl změnit na zapnutý.

   

Další kroky

Aktualizace příkazu z klientské aplikace