Bagikan melalui

Membuat permintaan HTTP

  • Artikel

Penting

Power Virtual Agents kemampuan dan fitur sekarang menjadi bagian dari Microsoft Copilot Studio mengikuti investasi signifikan dalam AI generatif dan integrasi yang ditingkatkan Microsoft Copilot.

Beberapa artikel dan tangkapan layar mungkin merujuk saat Power Virtual Agents kami memperbarui dokumentasi dan konten pelatihan.

Dalam Copilot Studio, Anda dapat memperluas kemampuan kopilot dengan memanggil REST API eksternal menggunakan node permintaan HTTP. Ini dapat membantu ketika Anda perlu mengambil data dari sistem eksternal atau memanipulasi data pada sistem itu.

Prasyarat

Menggunakan node permintaan HTTP

  1. Pilih Tambahkan node (+), buka submenu Tingkat Lanjut , lalu pilih Kirim permintaan HTTP.

    Cuplikan layar opsi kirim permintaan HTTP di menu lanjutan.

  2. Dalam kotak URL , masukkan URL untuk API titik akhir ingin Anda panggil.

  3. Pilih Metode permintaan yang sesuai dari dropdown. Metode GET, POST, PATCH, PUT, dan DELETE didukung.

    Cuplikan layar dropdown URL API dan metode yang telah selesai

  4. Di bawah Header dan isi pada node, klik tombol Edit . Ini akan membuka panel properti permintaan HTTP.

  5. Anda dapat secara opsional menambahkan satu atau beberapa header ke permintaan HTTP. Klik tombol Add untuk menambahkan kunci dan nilai setiap header.

    Cuplikan layar daftar pasangan nilai kunci header untuk node HTTP.

  6. Secara default, tidak ada konten yang dikirim dalam isi permintaan HTTP, tetapi Anda menentukan konten yang akan dikirim pada tubuh.

  7. Pada node, pilih tipe data Respons dari opsi yang tersedia.

    Anda dapat memberikan contoh respons JSON (yang biasanya dapat Anda temukan dalam dokumentasi untuk API yang Anda panggil), yang akan menghasilkan variabel Power FX yang sangat diketik, memungkinkan Anda menggunakannya di tempat lain di kanvas penulisan Anda dengan dukungan intellisense di editor Power FX. Untuk melakukannya, pilih Dari Data Sampel lalu klik Dapatkan skema dari sampel JSON, tempelkan respons sampel Anda ke editor yang ditampilkan dan pilih Konfirmasi.

    Cuplikan layar skema Dapatkan dari sampel editor JSON.

  8. Di bawah Simpan respons sebagai , pilih tempat Anda ingin menyimpan respons permintaan HTTP, baik membuat variabel baru atau memilih yang sudah ada.

Mengirim konten dalam isi permintaan HTTP

  1. Di bawah Header dan isi pada node, klik tombol Edit . Ini akan membuka panel properti permintaan HTTP.

  2. Di bawah Isi, pilih jenis konten yang sesuai. Secara default ini diatur ke Tidak Ada Konten, di mana tidak ada konten yang harus ada dalam badan permintaan, yang paling sering digunakan dengan permintaan GET. Untuk menambahkan konten ke isi, pilih dari salah satu opsi yang tersedia.

    Cuplikan layar tarik-turun opsi konten isi

    • Konten JSON: Konten JSON memungkinkan Anda menyediakan objek JSON di isi permintaan. Ini sering digunakan saat membuat permintaan POST atau PUT. Ketika opsi ini dipilih, Anda akan disajikan dengan editor tempat Anda dapat memasukkan konten JSON Anda.

      Anda juga dapat memasukkan menentukan konten JSON Anda menggunakan Power FX, memungkinkan Anda untuk menyertakan nilai dinamis dan variabel referensi. Untuk melakukan ini, pilih tombol Edit JSON , pilih Formula lalu masukkan objek Power FX (JSON yang ada yang telah dimasukkan akan dikonversi menjadi objek Power FX untuk Anda), yang akan dikonversi menjadi JSON saat permintaan HTTP dibuat.

      Cuplikan layar konten JSON dipilih untuk jenis konten isi.

    • Konten mentah: Konten mentah memungkinkan Anda menyisipkan string data ke dalam isi permintaan, dan string ini dapat berupa jenis konten apa pun yang Anda tentukan. Konten mentah dimasukkan menggunakan rumus Power FX, seperti konten string yang ditunjukkan dalam contoh di bawah ini.

      Cuplikan layar konten RAW dipilih untuk jenis konten isi.

Penanganan kesalahan dan batas waktu

Node permintaan HTTP memiliki beberapa opsi untuk menangani situasi di mana permintaan HTTP mungkin gagal atau mengembalikan kesalahan.

Secara default, fitur akan "Raise an error". Ini berarti bahwa ketika permintaan HTTP mengembalikan kesalahan atau gagal dijalankan, kopilot akan menghentikan operasinya dan memicu topik sistem Kesalahan , menampilkan pesan kesalahan.

Namun, Anda dapat mengonfigurasi penanganan kesalahan agar tidak memicu topik sistem Kesalahan dan, sebagai gantinya, mengisi kode status HTTP dan badan respons kesalahan apa pun ke dalam variabel yang Anda tentukan, memungkinkan Anda untuk menginterogasi variabel-variabel ini sesuai kebutuhan dan agar topik terus berjalan. Ini berguna dalam skenario di mana Anda ingin kopilot melanjutkan operasi bahkan jika permintaan HTTP tertentu gagal.

Untuk mengkonfigurasi perilaku penanganan kesalahan.

  1. Di bawah Header dan isi pada node, klik tombol Edit . Ini akan membuka panel properti permintaan HTTP.

  2. Pilih perilaku yang Anda inginkan dari menu dropdown Penanganan kesalahan.

  3. Jika Anda memilih Lanjutkan pada kesalahan, konfigurasikan kode Status dan variabel isi respons kesalahan, baik membuat variabel baru atau memilih variabel yang ada dari pemilih.

    Cuplikan layar penanganan kesalahan dikonfigurasi untuk melanjutkan kesalahan dengan variabel yang ditentukan untuk kode status dan isi respons kesalahan.

Dalam sampel kode ini, jika permintaan HTTP gagal, kopilot akan menyimpan kode status HTTP dalam variabel Topic.StatusCode dan badan respons dalam variabel Topic.ErrorResponse. Kopilot kemudian akan melanjutkan ke langkah selanjutnya dalam topik.

Jenis variabel respons kesalahan akan menjadi Apa saja. Anda dapat menggunakan simpul Nilai Parse untuk mengonversinya menjadi Power Fx rekaman.

Panel properti juga berisi properti Permintaan batas waktu , yang menerima nilai dalam milidetik. Nilai default adalah 30 detik, tetapi Anda dapat mengubah nilai ini jika diperlukan.