Membuat permintaan HTTP

Dalam Copilot Studio, Anda dapat memperluas kemampuan agen dengan memanggil REST API eksternal menggunakan simpul Permintaan HTTP . Panggilan ini dapat membantu ketika Anda perlu mengambil data dari sistem eksternal atau memanipulasi data pada sistem tersebut.

Prasyarat

Menggunakan simpul Permintaan HTTP

  1. Pilih ikon Tambahkan simpul di bawah simpul setelah itu Anda ingin memanggil API eksternal, arahkan ke Tingkat Lanjut, dan pilih Kirim permintaan HTTP.

  2. Di kotak URL , masukkan URL untuk endpoint API yang ingin Anda panggil.

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

    Tangkapan layar dari URL API yang telah selesai dan metode dropdown

  4. Di Header dan isi pada node, pilih tombol Edit, yang membuka panel properti Permintaan HTTP.

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

    Tangkapan layar daftar pasangan nilai kunci header untuk simpul HTTP.

    Anda dapat menggunakan bagian header untuk meneruskan token autentikasi, jenis konten, atau header lain yang diperlukan untuk API yang Anda panggil. Misalnya, Anda dapat menambahkan header seperti Authorization: Bearer <your_token> untuk mengautentikasi permintaan.

  6. Secara default, tidak ada konten yang dikirim dalam isi permintaan HTTP, tetapi Anda dapat menentukan konten di isi.

  7. Pada simpul, pilih Tipe data respons dari opsi yang tersedia.

    Anda dapat memberikan contoh respons JSON, yang biasanya dapat Anda temukan di dokumentasi untuk API yang Anda panggil. Ini menghasilkan variabel Power Fx, memungkinkan Anda untuk menggunakannya di tempat lain di kanvas penulisan Anda, dengan dukungan IntelliSense di editor Power Fx. Pilih Dari Data Sampel, lalu pilih Dapatkan skema dari JSON Sampel. Tempelkan contoh respons Anda ke editor dan pilih Konfirmasi.

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

Mengirim konten di isi permintaan HTTP

  1. Di Header dan isi pada node, pilih tombol Edit, yang membuka panel properti Permintaan HTTP.

  2. Di bawah Isi, pilih jenis konten yang sesuai. Secara default, Body diatur ke No Content, di mana tidak ada konten yang boleh ada dalam isi permintaan, yang paling sering digunakan dengan permintaan GET. Untuk menambahkan konten ke isi, pilih salah satu opsi yang tersedia.

    Cuplikan layar menu turun bawah opsi konten utama

    • Konten JSON: Konten JSON memungkinkan Anda menyediakan objek JSON di isi permintaan. Objek ini sering digunakan saat membuat permintaan POST atau PUT. Saat opsi ini dipilih, editor memungkinkan Anda memasukkan konten JSON Anda.

      Anda juga dapat menentukan konten JSON Anda menggunakan Power Fx, memungkinkan Anda menyertakan nilai dinamis dan variabel referensi. Pilih tombol Edit JSON , pilih Rumus, lalu masukkan Power Fx objek (JSON yang ada yang dimasukkan dikonversi menjadi Power Fx objek untuk Anda), yang dikonversi menjadi JSON saat permintaan HTTP dibuat.

      Tangkapan layar konten JSON yang 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 jenis string yang ditunjukkan dalam contoh berikut.

      Tangkapan layar konten RAW yang dipilih untuk jenis konten isi.

Penanganan kesalahan dan batas waktu

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

Secara default, fitur ini menimbulkan kesalahan. Ini berarti bahwa ketika permintaan HTTP mengembalikan kesalahan atau gagal dieksekusi, agen menghentikan operasinya dan memicu topik sistem On Error , menampilkan pesan kesalahan.

Namun, Anda dapat mengonfigurasi penanganan kesalahan agar tidak memicu topik sistem On Error . Sebagai gantinya, Anda dapat membuatnya menyimpan kode status HTTP dan isi respons kesalahan apa pun ke dalam variabel yang Anda tentukan. Anda dapat menginterogasi variabel ini sesuai kebutuhan, dan topik dapat terus berjalan. Konfigurasi ini berguna dalam skenario di mana Anda ingin agen melanjutkan operasi, bahkan jika permintaan HTTP tertentu gagal.

Untuk mengonfigurasi perilaku penanganan kesalahan simpul Permintaan HTTP :

  1. Di bawah Header dan isi, pilih Edit. Panel properti Permintaan HTTP muncul.

  2. Di bawah Penanganan kesalahan, pilih perilaku yang diinginkan: Memunculkan kesalahan, atau Lanjutkan meski terjadi kesalahan.

  3. Jika Anda memilih Lanjutkan pada kesalahan, konfigurasikan variabel untuk kode status dan isi respons kesalahan.

    Cuplikan layar panel 'Properti Permintaan HTTP' untuk simpul 'Permintaan HTTP' yang menunjukkan konfigurasi penanganan kesalahan, untuk meneruskan pelaksanaan meskipun terjadi kesalahan. Variabel untuk kode status dan bagian tubuh respons kesalahan telah dipilih.

Dalam contoh ini, jika permintaan HTTP gagal, agen menyimpan kode status HTTP dalam Topic.StatusCode variabel, dan isi respons dalam Topic.ErrorResponse variabel. Agen tersebut melanjutkan ke langkah berikutnya mengenai topik ini.

Respons kesalahan jenis variabel adalah Any. Anda dapat menggunakan node Parse value untuk mengonversi variabel ini menjadi catatan Power Fx.

Di panel properti Permintaan HTTP, Anda juga dapat mengatur properti Batas waktu permintaan , dalam milidetik. Nilai standarnya adalah 30 detik.

  • Last updated on