Konfigurowanie internetowych punktów końcowych

Artykuł
01/18/2024

Ważne

Polecenia niestandardowe zostaną wycofane 30 kwietnia 2026 r. Od 30 października 2023 r. nie można tworzyć nowych aplikacji poleceń niestandardowych w programie Speech Studio. W związku z tą zmianą usługa LUIS zostanie wycofana 1 października 2025 r. Od 1 kwietnia 2023 r. nie można tworzyć nowych zasobów usługi LUIS.

W tym artykule dowiesz się, jak skonfigurować internetowe punkty końcowe w aplikacji Niestandardowe polecenia, które umożliwiają wykonywanie żądań HTTP z aplikacji klienckiej. Wykonasz następujące zadania:

Konfigurowanie internetowych punktów końcowych dla aplikacji Polecenia niestandardowe
Wywoływanie internetowych punktów końcowych dla aplikacji Polecenia niestandardowe
Odbieranie odpowiedzi z internetowych punktów końcowych
Integrowanie odpowiedzi z internetowych punktów końcowych w niestandardowym ładunku JSON, wysyłanie i wizualizowanie ich z aplikacji klienckiej zestawu SDK usługi Mowa na platformie uniwersalnej systemu Windows w języku C#

Wymagania wstępne

Visual Studio 2019
Klucz zasobu usługi Mowa azure AI i region: utwórz zasób usługi Mowa w witrynie Azure Portal. Aby uzyskać więcej informacji, zobacz Tworzenie zasobu z wieloma usługami.
Aplikacja Poleceń niestandardowych (zobacz Tworzenie asystenta głosowego przy użyciu poleceń niestandardowych)
Aplikacja kliencka z obsługą zestawu SPEECH SDK (zobacz Integrowanie z aplikacją kliencką przy użyciu zestawu Speech SDK)

Wdrażanie zewnętrznego internetowego punktu końcowego przy użyciu aplikacji funkcji platformy Azure

Na potrzeby tego samouczka potrzebny jest punkt końcowy HTTP, który obsługuje stany dla wszystkich urządzeń skonfigurowanych w poleceniu TurnOnOff aplikacji Custom Commands.

Jeśli masz już internetowy punkt końcowy, który chcesz wywołać, przejdź do następnej sekcji. Alternatywnie następna sekcja zawiera szczegółowe informacje na temat domyślnego hostowanego internetowego punktu końcowego, którego można użyć, jeśli chcesz pominąć tę sekcję.

Format wejściowy funkcji platformy Azure

Następnie wdrożysz punkt końcowy przy użyciu usługi Azure Functions. Poniżej przedstawiono format zdarzenia Polecenia niestandardowe, które jest przekazywane do funkcji platformy Azure. Użyj tych informacji podczas pisania aplikacji funkcji platformy Azure.

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

W poniższej tabeli opisano kluczowe atrybuty tych danych wejściowych:

Atrybut	Wyjaśnienie
identyfikator konwersacji	Unikatowy identyfikator konwersacji. Należy pamiętać, że ten identyfikator może zostać wygenerowany przez aplikację kliencka.
currentCommand	Polecenie, które jest obecnie aktywne w konwersacji.
name	Nazwa polecenia. Atrybut `parameters` jest mapą z bieżącymi wartościami parametrów.
currentGlobalParameters	Mapa, na przykład `parameters`, ale używana do parametrów globalnych.

W przypadku funkcji Platformy Azure DeviceState przykładowe zdarzenie Polecenia niestandardowe wygląda następująco. Działa to jako dane wejściowe aplikacji funkcji.

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

Dane wyjściowe funkcji platformy Azure dla niestandardowej aplikacji poleceń

Jeśli dane wyjściowe z funkcji platformy Azure są używane przez aplikację Polecenia niestandardowe, powinny być wyświetlane w następującym formacie. Aby uzyskać szczegółowe informacje, zobacz Aktualizowanie polecenia z internetowego punktu końcowego .

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

Dane wyjściowe funkcji platformy Azure dla aplikacji klienckiej

Jeśli dane wyjściowe funkcji platformy Azure są używane przez aplikację kliencką, dane wyjściowe mogą mieć dowolny formularz wymagany przez aplikację kliencką.

W przypadku naszego punktu końcowego DeviceState dane wyjściowe funkcji platformy Azure są używane przez aplikację kliencką zamiast aplikacji Custom Commands. Przykładowe dane wyjściowe funkcji platformy Azure powinny wyglądać następująco:

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

Te dane wyjściowe powinny być zapisywane w magazynie zewnętrznym, aby można było zachować stan urządzeń. Stan magazynu zewnętrznego jest używany w sekcji Integracja z aplikacją kliencka poniżej.

Wdróż funkcję platformy Azure

Udostępniamy przykład, który można skonfigurować i wdrożyć jako aplikację usługi Azure Functions. Aby utworzyć konto magazynu dla naszego przykładu, wykonaj następujące kroki.

Tworzenie magazynu tabel w celu zapisania stanu urządzenia. W witrynie Azure Portal utwórz nowy zasób typu Konto magazynu według nazwy devicestate.
Skopiuj wartość ciągu Połączenie ion z parametru devicestate —> klucze dostępu. Ten wpis tajny ciągu należy dodać do pobranego przykładowego kodu aplikacji funkcji.
Pobierz przykładowy kod aplikacji funkcji.
Otwórz pobrane rozwiązanie w programie Visual Studio 2019. W Połączenie ions.json zastąp STORAGE_ACCOUNT_SECRET_CONNECTION_STRING wpisem tajnym z kroku 2.
Pobierz kod DeviceStateAzureFunction.

Aby wdrożyć przykładową aplikację w usłudze Azure Functions, wykonaj następujące kroki.

Wdrażanie aplikacji usługi Azure Functions.
Poczekaj na pomyślne wdrożenie i przejdź do wdrożonego zasobu w witrynie Azure Portal.
Wybierz pozycję Funkcje w okienku po lewej stronie, a następnie wybierz pozycję DeviceState.
W nowym oknie wybierz pozycję Kod i test , a następnie wybierz pozycję Pobierz adres URL funkcji.

Konfigurowanie internetowych punktów końcowych w poleceniach niestandardowych

Podłączmy funkcję platformy Azure za pomocą istniejącej aplikacji Polecenia niestandardowe. W tej sekcji użyjesz istniejącego domyślnego punktu końcowego DeviceState . Jeśli utworzono własny internetowy punkt końcowy przy użyciu funkcji platformy Azure lub w inny sposób, użyj go zamiast domyślnego https://webendpointexample.azurewebsites.net/api/DeviceState.

Otwórz utworzoną wcześniej aplikację Polecenia niestandardowe.

Przejdź do pozycji Internetowe punkty końcowe, wybierz pozycję Nowy internetowy punkt końcowy.

New web endpoint

Ustawienie	Sugerowana wartość	opis
Nazwa/nazwisko	UpdateDeviceState	Nazwa internetowego punktu końcowego.
URL	`https://webendpointexample.azurewebsites.net/api/DeviceState`	Adres URL punktu końcowego, z którym ma się komunikować aplikacja Polecenia niestandardowe.
Method	POST	Dozwolone interakcje (np. GET, POST) z punktem końcowym.
Nagłówki	Klucz: aplikacja, Wartość: weź pierwsze osiem cyfr identyfikatora applicationId	Parametry nagłówka do uwzględnienia w nagłówku żądania.

Uwaga

Przykładowy internetowy punkt końcowy utworzony przy użyciu usługi Azure Functions, który podłącza się do bazy danych, która zapisuje stan urządzenia telewizora i wentylatora.
Sugerowany nagłówek jest potrzebny tylko dla przykładowego punktu końcowego.
Aby upewnić się, że wartość nagłówka jest unikatowa w naszym przykładowym punkcie końcowym, użyj pierwszych 8 cyfr identyfikatora applicationId.
W świecie rzeczywistym internetowy punkt końcowy może być punktem końcowym centrum IOT, które zarządza urządzeniami.

Wybierz pozycję Zapisz.

Wywoływanie internetowych punktów końcowych

Przejdź do polecenia TurnOnOff, w regule ukończenia wybierz pozycję ConfirmationResponse, a następnie wybierz pozycję Dodaj akcję.
W obszarze Nowa akcja — Typ wybierz pozycję Wywołaj internetowy punkt końcowy
W obszarze Edytuj akcję — Punkty końcowe wybierz pozycję UpdateDeviceState, która jest utworzonym przez nas internetowym punktem końcowym.

W obszarze Konfiguracja umieść następujące wartości:

Call web endpoints action parameters

Ustawienie	Sugerowana wartość	opis
Punkty końcowe	UpdateDeviceState	Internetowy punkt końcowy, który ma zostać wywołany w ramach tej akcji.
Parametry zapytań	item={SubjectDevice}&&value={OnOff}	Parametry zapytania, które mają zostać dołączone do adresu URL internetowego punktu końcowego.
Zawartość treści	Nie dotyczy	Zawartość treści żądania.

Uwaga

Sugerowane parametry zapytania są wymagane tylko w przypadku przykładowego punktu końcowego

W obszarze W przypadku powodzenia — Akcja do wykonania wybierz pozycję Wyślij odpowiedź na mowę.

W obszarze Prosty edytor wprowadź wartość {SubjectDevice} is {OnOff}.

Ustawienie Sugerowana wartość opis

Akcja do wykonania Wyślij odpowiedź na mowę Akcja do wykonania, jeśli żądanie internetowego punktu końcowego zakończy się pomyślnie
Uwaga
- Możesz również uzyskać dostęp do pól w odpowiedzi HTTP bezpośrednio, używając parametru {YourWebEndpointName.FieldName}. Na przykład: {UpdateDeviceState.TV}.
W obszarze W przypadku niepowodzenia — Akcja do wykonania wybierz pozycję Wyślij odpowiedź na mowę

W obszarze Prosty edytor wprowadź wartość Sorry, {WebEndpointErrorMessage}.

Ustawienie Sugerowana wartość opis

Akcja do wykonania Wyślij odpowiedź na mowę Akcja do wykonania, jeśli żądanie internetowego punktu końcowego zakończy się niepowodzeniem
Uwaga
- Element {WebEndpointErrorMessage} jest opcjonalny. Możesz go usunąć, jeśli nie chcesz uwidaczniać żadnego komunikatu o błędzie.
- W naszym przykładowym punkcie końcowym wysyłamy odpowiedź HTTP ze szczegółowymi komunikatami o błędach dotyczącymi typowych błędów, takich jak brakujące parametry nagłówka.

Ustawienie	Sugerowana wartość	opis
Akcja do wykonania	Wyślij odpowiedź na mowę	Akcja do wykonania, jeśli żądanie internetowego punktu końcowego zakończy się pomyślnie

Ustawienie	Sugerowana wartość	opis
Akcja do wykonania	Wyślij odpowiedź na mowę	Akcja do wykonania, jeśli żądanie internetowego punktu końcowego zakończy się niepowodzeniem

Wypróbowywanie działania w portalu testowym

W obszarze Odpowiedź na powodzenie zapisz, przeszkolij i przetestuj.
W obszarze odpowiedź Niepowodzenie usuń jeden z parametrów zapytania, zapisz, przetrenuj i przetestuj.

Integracja z aplikacją kliencką

W obszarze Działanie Wyślij polecenia niestandardowe do aplikacji klienckiej dodano akcję Wyślij do klienta . Aktywność jest wysyłana do aplikacji klienckiej, niezależnie od tego, czy akcja Wywołaj internetowy punkt końcowy zakończyła się pomyślnie. Zazwyczaj jednak chcesz wysłać działanie tylko do aplikacji klienckiej, gdy wywołanie do internetowego punktu końcowego zakończy się pomyślnie. W tym przykładzie ma to miejsce po pomyślnym zaktualizowaniu stanu urządzenia.

Usuń dodaną wcześniej akcję Wyślij aktywność do klienta.
Edytuj internetowy punkt końcowy wywołania:
1. W obszarze Konfiguracja upewnij się, że Parametry zapytania to item={SubjectDevice}&&value={OnOff}
2. W obszarze W przypadku powodzenia zmień wartość pola Akcja do wykonania na Wyślij aktywność do klienta
3. Skopiuj poniższy kod JSON do pola Zawartość aktywności
```
{
   "type": "event",
   "name": "UpdateDeviceState",
   "value": {
     "state": "{OnOff}",
     "device": "{SubjectDevice}"
   }
 }
```

Teraz wysyłasz działanie tylko do klienta, gdy żądanie do internetowego punktu końcowego zakończy się pomyślnie.

Tworzenie wizualizacji w celu synchronizowania stanu urządzenia

Dodaj następujący kod XML powyżej MainPage.xamlbloku EnableMicrophoneButton .

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

Synchronizowanie stanu urządzeń

W pliku MainPage.xaml.cs dodaj odwołanie using Windows.Web.Http;. Dodaj poniższy kod do klasy MainPage. Ta metoda wysyła żądanie GET do przykładowego punktu końcowego i wyodrębnia bieżący stan urządzenia dla aplikacji. Pamiętaj, aby zmienić <your_app_name> element na to, co zostało użyte w nagłówku w internetowym punkcie końcowym polecenia niestandardowego.

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

Czas to wypróbować

Uruchom aplikację.
Wybierz pozycję Synchronizuj stan urządzenia.
Jeśli przetestowano aplikację za pomocą turn on tv polecenia w poprzedniej sekcji, zobaczysz programy telewizyjne tak jak na.
Wybierz pozycję Włącz mikrofon.
Wybierz przycisk Porozmawiaj.
Powiedz .turn on the fan Stan wizualny wentylatora powinien ulec zmianie na włączony.

Następne kroki

Aktualizowanie polecenia z poziomu aplikacji klienckiej

Udostępnij za pośrednictwem