Bagikan melalui

Membuat permintaan HTTP

  • Artikel

Dalam itu 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 Tambahkan node (),+ buka sub menu Tingkat Lanjut , lalu pilih Kirim permintaan HTTP.

    Tangkapan layar opsi kirim permintaan HTTP di menu lanjutan.

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

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

    Tangkapan layar URL API yang telah selesai dan dropdown metode

  4. Di bawah Header dan isi pada simpul, pilih tombol Edit , yang membuka panel properti permintaan HTTP.

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

    Cuplikan layar daftar pasangan nilai kunci header untuk simpul HTTP.

  6. Secara default, tidak ada konten yang dikirim dalam isi permintaan HTTP, tetapi Anda dapat menentukan konten dalam 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 Power Fx editor. Pilih Dari Data Sampel lalu pilih Dapatkan skema dari JSON sampel. Tempelkan respons sampel Anda ke editor dan pilih Konfirmasi.

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

Kirim konten di isi permintaan HTTP

  1. Di bawah Header dan isi pada simpul, pilih tombol Edit , yang membuka panel properti permintaan HTTP.

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

    Cuplikan layar dropdown opsi konten isi

    • Konten JSON: Konten JSON memungkinkan Anda menyediakan objek JSON dalam 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 untuk 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.

      Cuplikan 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 dari jenis konten apa pun yang Anda tentukan. Konten mentah dimasukkan menggunakan Power Fx rumus, seperti konten string yang ditunjukkan dalam contoh berikut.

      Tangkapan layar konten RAW yang dipilih untuk jenis konten isi.

Penanganan kesalahan dan waktu habis

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

Secara default, fitur ini memunculkan kesalahan. Ini berarti bahwa ketika permintaan HTTP mengembalikan kesalahan atau gagal dijalankan, 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, ini mengisi kode status HTTP dan isi respons kesalahan apa pun ke dalam variabel yang Anda tentukan, memungkinkan Anda untuk menginterogasi variabel ini sesuai kebutuhan, dan agar topik 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.

  1. Di bawah Header dan isi pada simpul, pilih tombol Edit , yang membuka panel properti permintaan HTTP.

  2. Pilih perilaku yang Anda inginkan dari 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 yang dikonfigurasi untuk melanjutkan kesalahan dengan variabel yang ditentukan untuk kode status dan isi respons kesalahan.

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

Jenis variabel respons Kesalahan adalah Any. Anda dapat menggunakan simpul Nilai Parse untuk mengonversi variabel ini menjadi rekaman Power Fx .

Panel properti juga berisi properti Batas waktu permintaan , yang menerima nilai dalam milidetik. Nilai defaultnya adalah 30 detik, tetapi Anda dapat mengubah nilai ini jika diperlukan.