Menyiapkan titik akhir web

Artikel
01/18/2024

Penting

Perintah Kustom akan dihentikan pada 30 April 2026. Mulai 30 Oktober 2023 Anda tidak dapat membuat aplikasi Perintah Kustom baru di Speech Studio. Terkait perubahan ini, LUIS akan dihentikan pada 1 Oktober 2025. Mulai 1 April 2023 Anda tidak dapat membuat sumber daya LUIS baru.

Dalam artikel ini, Anda mempelajari cara menyiapkan titik akhir web dalam aplikasi Perintah Kustom yang memungkinkan Anda membuat permintaan HTTP dari aplikasi klien. Kemudian, selesaikan tugas-tugas berikut:

Menyiapkan titik akhir web di aplikasi Perintah Kustom
Memanggil titik akhir web di aplikasi Perintah Kustom
Menerima respons titik akhir web
Mengintegrasikan respons titik akhir web ke dalam payload JSON kustom, mengirim, dan memvisualisasikan dari aplikasi klien SDK Ucapan C# UWP

Prasyarat

Visual Studio 2019
Kunci dan wilayah sumber daya Azure AI Speech: Buat sumber daya Ucapan di portal Azure. Untuk informasi selengkapnya, lihat Membuat sumber daya multi-layanan.
Aplikasi Perintah Kustom (lihat Membuat asisten suara menggunakan Perintah Kustom)
Aplikasi klien yang mengaktifkan SDK Ucapan (lihat Mengintegrasikan dengan aplikasi klien menggunakan SDK Ucapan)

Menyebarkan titik akhir web eksternal menggunakan aplikasi Fungsi Azure

Untuk tutorial ini, Anda memerlukan titik akhir HTTP yang mempertahankan status semua perangkat yang disiapkan di perintah TurnOnOff aplikasi Perintah Kustom Anda.

Jika Anda sudah memiliki titik akhir web yang ingin dipanggil, lewati ke bagian berikutnya. Atau, bagian berikutnya memberikan detail tentang titik akhir web yang dihosting default yang dapat Anda gunakan jika ingin melewati bagian ini.

Format input fungsi Azure

Selanjutnya, Anda menyebarkan titik akhir menggunakan Azure Functions. Berikut ini adalah format peristiwa Perintah Kustom yang diteruskan ke fungsi Azure Anda. Gunakan informasi ini saat Anda menulis aplikasi Fungsi Azure.

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

Tabel berikut menjelaskan atribut kunci dari input ini:

Atribut	Penjelasan
conversationId	Pengidentifikasi unik percakapan. Perhatikan BAHWA ID ini dapat dihasilkan oleh aplikasi klien.
currentCommand	Perintah yang sedang aktif dalam percakapan.
nama	Nama perintah. Atribut `parameters` adalah peta dengan nilai parameter saat ini.
currentGlobalParameters	Peta seperti `parameters`, tetapi digunakan untuk parameter global.

Untuk DeviceState Azure Function, contoh peristiwa Perintah Kustom terlihat seperti berikut ini. Ini bertindak sebagai input ke aplikasi fungsi.

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

Output Fungsi Azure untuk aplikasi Perintah Kustom

Jika output dari Fungsi Azure Anda digunakan oleh aplikasi Perintah Kustom, hal ini akan muncul dalam format berikut. Lihat Memperbarui perintah dari titik akhir web untuk detailnya.

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

Output Fungsi Azure untuk aplikasi klien

Jika output dari Fungsi Azure Anda digunakan oleh aplikasi klien, output dapat mengambil bentuk apa pun yang dibutuhkan aplikasi klien.

Untuk titik akhir DeviceState kami, output fungsi Azure Anda digunakan oleh aplikasi klien, bukan aplikasi Perintah Kustom. Contoh output dari fungsi Azure akan terlihat seperti berikut:

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

Output ini harus ditulis ke penyimpanan eksternal, agar Anda dapat mempertahankan status perangkat. Status penyimpanan eksternal digunakan di bagian Integrasikan dengan aplikasi klien di bawah ini.

Menyebarkan fungsi Azure

Kami menyediakan contoh yang dapat Anda konfigurasikan dan sebarkan sebagai aplikasi Azure Functions. Untuk membuat akun penyimpanan sampel kami, ikuti langkah-langkah ini.

Buat penyimpanan tabel untuk menyimpan status perangkat. Di portal Azure, buat sumber daya baru dengan jenis Akun penyimpanan dengan nama devicestate.
Salin nilai String koneksi dari devicestate -> Kunci akses. Anda perlu menambahkan rahasia string ini ke sampel kode Aplikasi Fungsi yang diunduh.
Unduh sampel Kode Aplikasi Fungsi.
Buka solusi yang diunduh di Visual Studio 2019. Di Connections.json, ganti STORAGE_ACCOUNT_SECRET_CONNECTION_STRING dengan rahasia dari Langkah 2.
Unduh kode DeviceStateAzureFunction.

Untuk menyebarkan aplikasi sampel ke Azure Functions, ikuti langkah-langkah berikut.

Sebarkan aplikasi Azure Functions.
Tunggu hingga penyebaran berhasil dan buka sumber daya yang disebarkan di portal Azure.
Pilih Fungsi di panel sebelah kiri, lalu pilih DeviceState.
Di jendela baru, pilih Kode + Uji lalu pilih Dapatkan URL fungsi.

Menyiapkan titik akhir web di Perintah Kustom

Mari kita kaitkan fungsi Azure dengan aplikasi Perintah Kustom yang ada. Di bagian ini, Anda menggunakan titik akhir DeviceState default yang sudah ada. Jika Anda membuat titik akhir web sendiri menggunakan Fungsi Azure atau yang lainnya, gunakan hal ini sebagai ganti default https://webendpointexample.azurewebsites.net/api/DeviceState.

Buka aplikasi Perintah Kustom yang telah Anda buat sebelumnya.

Buka Titik akhir web, pilih Titik akhir web baru.

New web endpoint

Pengaturan	Nilai yang disarankan	Deskripsi
Nama	UpdateDeviceState	Nama untuk titik akhir web.
URL	`https://webendpointexample.azurewebsites.net/api/DeviceState`	URL titik akhir yang Anda inginkan untuk diajak bicara oleh aplikasi perintah kustom Anda.
Metode	POST	Interaksi yang diizinkan (seperti GET, POST) dengan titik akhir Anda.
Header	Kunci: aplikasi, Nilai: ambil delapan digit pertama applicationId Anda	Parameter header yang akan disertakan dalam header permintaan.

Catatan

Contoh titik akhir web yang dibuat menggunakan Azure Functions, yang terhubung dengan database yang menyimpan status perangkat tv dan kipas angin.
Header yang disarankan hanya diperlukan untuk titik akhir contoh.
Untuk memastikan nilai header unik di titik akhir contoh kami, ambil 8 digit pertama applicationId Anda.
Di dunia nyata, titik akhir web dapat menjadi titik akhir ke IOT hub yang mengelola perangkat Anda.

Pilih Simpan.

Menghubungi titik akhir web

Buka perintah TurnOnOff, pilih ConfirmationResponse di bagian aturan penyelesaian, lalu pilih Tambahkan tindakan.
Di bagian Jenis Tindakan Baru, pilih Panggil titik akhir web
Di Edit Tindakan - Titik akhir, pilih UpdateDeviceState, yang merupakan titik akhir web yang kami buat.

Di Konfigurasi, masukkan nilai berikut:

Call web endpoints action parameters

Pengaturan	Nilai yang disarankan	Deskripsi
Titik akhir	UpdateDeviceState	Titik akhir web yang ingin Anda panggil dalam tindakan ini.
Parameter kueri	item={SubjectDevice}&&value={OnOff}	Parameter kueri yang akan ditambahkan ke URL titik akhir web.
Isi konten	T/A	Isi konten permintaan.

Catatan

Parameter kueri yang disarankan hanya diperlukan untuk titik akhir contoh

Di Saat berhasil - Tindakan yang akan dijalankan, pilih Kirim respons ucapan.

Di Editor sederhana, masukkan {SubjectDevice} is {OnOff}.

Pengaturan Nilai yang disarankan Deskripsi

Tindakan yang akan dijalankan Kirim respons ucapan Tindakan yang akan dijalankan jika permintaan ke titik akhir web berhasil
Catatan
- Anda juga dapat langsung mengakses bidang dalam respons http dengan menggunakan {YourWebEndpointName.FieldName}. Misalnya: {UpdateDeviceState.TV}
Di Saat Gagal - Tindakan yang akan dijalankan, pilih Kirim respons ucapan

Di Editor sederhana, masukkan Sorry, {WebEndpointErrorMessage}.

Pengaturan Nilai yang disarankan Deskripsi

Tindakan yang akan dijalankan Kirim respons ucapan Tindakan yang akan dijalankan jika permintaan ke titik akhir web gagal
Catatan
- {WebEndpointErrorMessage} bersifat opsional. Anda dapat menghapusnya jika tidak ingin menampilkan pesan kesalahan apa pun.
- Dalam contoh titik akhir, kami mengirim kembali respons http dengan pesan kesalahan terperinci untuk kesalahan umum seperti parameter header yang hilang.

Pengaturan	Nilai yang disarankan	Deskripsi
Tindakan yang akan dijalankan	Kirim respons ucapan	Tindakan yang akan dijalankan jika permintaan ke titik akhir web berhasil

Pengaturan	Nilai yang disarankan	Deskripsi
Tindakan yang akan dijalankan	Kirim respons ucapan	Tindakan yang akan dijalankan jika permintaan ke titik akhir web gagal

Coba di portal uji

Pada respons Berhasil, simpan, latih dan uji.
Pada respons Gagal, hapus salah satu parameter kueri, simpan, latih ulang, dan uji.

Mengintegrasikan dengan aplikasi klien

Di Kirim aktivitas Perintah Kustom ke aplikasi klien, Anda menambahkan tindakan Kirim aktivitas ke klien. Aktivitas dikirim ke aplikasi klien, baik saat tindakan Panggil titik akhir web berhasil atau tidak. Namun, biasanya Anda hanya ingin mengirim aktivitas ke aplikasi klien saat panggilan ke titik akhir web berhasil. Dalam contoh ini, ini adalah saat status perangkat berhasil diperbarui.

Hapus tindakan Kirim aktivitas ke klien yang sebelumnya Anda tambahkan.
Edit titik akhir web panggilan:
1. Dalam Konfigurasi, pastikan Parameter Kueri adalah item={SubjectDevice}&&value={OnOff}
2. Di Saat Berhasil, ubah Tindakan yang akan dijalankan menjadi Kirim aktivitas ke klien
3. Salin JSON di bawah ini ke Konten Aktivitas
```
{
   "type": "event",
   "name": "UpdateDeviceState",
   "value": {
     "state": "{OnOff}",
     "device": "{SubjectDevice}"
   }
 }
```

Sekarang Anda hanya mengirim aktivitas ke klien ketika permintaan ke titik akhir web berhasil.

Membuat visual untuk menyinkronkan status perangkat

Tambahkan XML berikut ke MainPage.xaml di atas blok EnableMicrophoneButton.

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

Sinkronkan status perangkat

Di MainPage.xaml.cs, tambahkan referensi using Windows.Web.Http;. Tambahkan kode berikut ke kelas MainPage. Metode ini mengirim permintaan GET ke titik akhir contoh, dan mengekstrak status perangkat saat ini untuk aplikasi Anda. Pastikan untuk mengubah <your_app_name> menjadi apa yang Anda gunakan di header di titik akhir web Perintah Kustom.

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

Cobalah

Mulai aplikasi.
Pilih Sinkronkan Status Perangkat.
Jika Anda menguji aplikasi dengan turn on tv di bagian sebelumnya, Anda akan melihat TV ditampilkan sebagai aktif.
Pilih Aktifkan mikrofon.
Pilih tombol Bicara.
Katakan turn on the fan. Status visual kipas akan berubah menjadi aktif.

Langkah berikutnya

Memperbarui perintah dari aplikasi klien