Permintaan HTTP dari server Multiplay
Anda dapat melakukan permintaan HTTP dari server ZEPETO World Multiplay menggunakan modul ZEPETO.Multiplay.HttpService. Integrasikan layanan web eksternal ke dalam operasi logika bisnis Anda, penyimpanan data, analisis statistik, pelacakan kesalahan, dan lainnya.
- Harap pastikan bahwa hanya protokol HTTPS yang digunakan, sementara HTTP hanya didukung di lingkungan pengembangan.
- Permintaan hanya diizinkan pada port 80 dan 443.
- Ukuran maksimum untuk tubuh permintaan dan respons dibatasi hingga 16KB.
- Jaga jumlah permintaan per menit di bawah 500 untuk menghindari potensi pembatasan pada layanan dunia jika terjadi permintaan berlebihan.
- Permintaan akan gagal jika layanan web eksternal tidak merespons dalam waktu 5 detik.
- Pastikan bahwa content-type dalam header respons sesuai dengan nilai yang ditentukan dalam HttpContentType enum; jika tidak, permintaan akan gagal.
- Mengingat kemungkinan permintaan web gagal karena berbagai alasan, disarankan untuk melakukan pengkodean secara defensif.
📘 Silakan merujuk ke panduan berikut. [API ZEPETO.Multiplay.HttpService]
Metode | Deskripsi |
---|---|
HttpService.getAsync(url: string, headers?: HttpHeader): Promise | Melakukan permintaan HTTP GET secara asinkron. .[Parameter] - url : Alamat web untuk mengirim permintaan. - headers : Header permintaan HTTP. (Opsional) [Nilai Kembali] - Promise<HttpResponse> : Mengembalikan objek HttpResponse yang berisi informasi tentang respons sebagai Promise |
HttpService.postAsync(url: string, body: HttpBodyType, headers?: HttpHeader): Promise | Melakukan permintaan HTTP POST secara asinkron. .[Parameter] - url : Alamat web untuk mengirim permintaan. - body : Konten tubuh permintaan. - headers : Header permintaan HTTP. (Opsional) [Nilai Kembali] - Promise<HttpResponse> : Mengembalikan objek HttpResponse yang berisi informasi tentang respons sebagai Promise |
HttpService.postAsync(url: string, body: HttpBodyType, httpContentType: HttpContentType, headers?: HttpHeader): Promise | Melakukan permintaan HTTP POST secara asinkron. .[Parameter] - url : Alamat web untuk mengirim permintaan. - body : Konten tubuh permintaan. - httpContentType : Menentukan header Content-Type permintaan. - headers : Header permintaan HTTP. (Opsional) [Nilai Kembali] - Promise<HttpResponse> : Mengembalikan objek HttpResponse yang berisi informasi tentang respons sebagai Promise. Saat menggunakan tanda tangan ini, jika Anda menambahkan 'Content-Type' ke header, itu akan ditimpa oleh apa yang ditentukan dalam httpContentType |
Deklarasi | Deskripsi |
---|---|
HttpContentType | Enumerasi konstanta yang menentukan Content-Type untuk header HTTP. - ApplicationJson : 'application/json' - ApplicationXml : 'application/xml' - ApplicationUrlEncoded : 'application/x-www-form-urlencoded' - TextPlain : 'text/plain' - TextXml : 'text/xml' |
HttpBodyType | Tipe untuk konten tubuh permintaan HTTP, yang bisa berupa string atau objek dengan kunci string dan nilai apa pun. |
HttpHeader | Tipe untuk mendefinisikan header permintaan HTTP, di mana nilai properti bisa berupa string atau angka dalam objek. |
HttpResponse | Antarmuka yang mencakup informasi tentang hasil permintaan HTTP dan data respons. - statusCodeHTTP : Sebuah angka yang mewakili kode status dari respons. Biasanya, 200 menunjukkan permintaan yang berhasil. - statusTextHTTP : Sebuah string yang mewakili pesan status dari respons. Biasanya, "OK" menunjukkan permintaan yang berhasil. - response : Sebuah string yang berisi data tubuh respons HTTP. |
📘 Status HTTP https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
Mari kita buat contoh permintaan GET sederhana menggunakan HttpService.getAsync. Ketika klien baru terhubung ke Ruang Multiplay, kita akan mengirim permintaan HTTP ke layanan web eksternal dan mencatat hasilnya.
restcountries.com adalah API terbuka yang menyediakan informasi tentang berbagai negara. Kami akan menggunakan layanan ini untuk mengetahui ibu kota Jepang.
Siapkan Multiplay, lalu buka World.multiplay/index.ts dan tulis skrip server sebagai berikut.
📘 Silakan merujuk ke panduan berikut. [Bermain Ganda]
Deskripsi kode:
- Ketika seorang klien terhubung ke Ruang Multiplay, fungsi onJoin dipicu, dan itu memanggil findCapitalCity.
- Jika panggilan getAsync ke API restcountries berhasil, Anda dapat mengakses objek httpResponse di dalam then callback.
- Parse httpResponse.response untuk mengonversi respons API, yang dalam format JSON, menjadi sebuah objek.
- Dengan merujuk pada struktur respons API, Anda mengakses properti yang diinginkan dan kemudian mencetak nilainya.
Ketika Anda menjalankan server Multiplay di Editor Unity dan memainkan adegan, yang berikut akan ditampilkan di Console.
- Sementara itu, seperti yang disebutkan dalam langkah-langkah pencegahan pengantar, permintaan web dapat gagal karena berbagai alasan, termasuk perubahan alamat web atau format respons API.
- Kegagalan untuk menangani permintaan ini dengan benar dapat memiliki berbagai efek buruk pada permainan Dunia, jadi disarankan untuk mengkode secara defensif, terutama saat berurusan dengan permintaan HTTP.
- Berikut adalah contoh penerapan beberapa teknik pengkodean defensif pada kode di atas.
Teknik pengkodean defensif yang diterapkan di sini meliputi yang berikut:
- Menggunakan Accept Header: Accept header digunakan untuk menentukan Content-Type yang diharapkan untuk body respons. Tergantung pada server, Content-Type respons dapat disesuaikan berdasarkan Accept header.
- Memeriksa HttpResponse.statusCode: Properti HttpResponse.statusCode digunakan untuk memverifikasi keberhasilan permintaan.
- Memvalidasi Struktur Data JSON: Anda mengonfirmasi apakah struktur data dari objek yang diparsing dengan JSON.parse sesuai dengan struktur yang diharapkan.
- Memverifikasi Keberadaan Properti: Anda memastikan bahwa properti yang ingin Anda gunakan benar-benar ada dalam objek.
- Memanfaatkan catch Metode Promise: Metode catch dari Promise digunakan untuk menangani kesalahan yang mungkin terjadi selama permintaan API dan pemrosesan respons.
Teknik-teknik ini melindungi kode agar beroperasi dengan andal di tengah kesalahan yang tidak terduga, meningkatkan ketahanannya.
Permintaan HTTP hanya mungkin dilakukan dari server Multiplay.
Namun, dengan menggunakan Pesan Ruangan Multiplay, Anda dapat memicu server untuk mengirim permintaan HTTP ke layanan web eksternal dari klien dan memanfaatkan respons di dalam klien.
Contoh berikut menunjukkan integrasi klien-server. Dalam demonstrasi ini, ketika tombol pada UI klien ditekan, ibu kota negara yang sesuai dengan tombol ditampilkan.
📘 Silakan merujuk ke panduan berikut. [Proses koneksi ruangan]
Kode Klien
Deskripsi kode:
- Kami mendefinisikan pendengar yang mengiterasi melalui tombol yang menampilkan nama-nama negara. Ketika diklik, pendengar ini mengirim Pesan Ruangan ke server Multiplay.
- Pendengar ini mengirim nama negara yang ditampilkan pada tombol sebagai pesan tipe 'client-to-server'.
- Untuk menangani respons, kami juga mendefinisikan pendengar untuk memproses Pesan Ruangan yang diterima sebagai tipe 'server-to-client'.
- Pendengar ini menampilkan nama ibu kota yang diterima dari server di layar. Jika ada beberapa ibu kota, mereka ditampilkan di layar, dipisahkan oleh koma.
Kode Server
Deskripsi kode:
- Kami mendefinisikan pendengar yang, setelah menerima pesan Ruang Multiplay tipe 'client-to-server', memanggil findCapitalCity.
- Kami membangun alamat untuk Pesan Ruang Multiplay menggunakan nama negara dan melakukan panggilan getAsync .
- Jika panggilan getAsync berhasil, respons ditangani seperti pada contoh sebelumnya.
- Nama ibu kota yang diperoleh dari respons API restcountries dikirim ke klien sebagai Pesan Ruang tipe 'server-to-client'.
Terakhir, mari kita buat contoh permintaan POST menggunakan HttpService.postAsync.
postman-echo adalah layanan yang menyediakan respons terstruktur yang menunjukkan konten apa yang diterima dari permintaan web, menjadikannya efektif untuk memverifikasi apakah klien telah mengonfigurasi permintaan dengan benar.
Melalui contoh ini, kita akan mengatur permintaan POST dengan parameter kueri, badan permintaan, dan header serta memastikan bahwa permintaan dikonfigurasi dengan benar.
Siapkan Multiplay, lalu buka World.multiplay/index.ts dan tulis skrip server sebagai berikut.
Deskripsi kode:
- Ketika klien terhubung ke Ruang Multiplay, echoPost fungsi dipanggil dari onJoin pemicu.
- Saat membuat postAsync permintaan:
- Pada parameter pertama, kami membangun string URL dengan parameter kueri.
- Pada parameter kedua, kami mengatur konten tubuh permintaan.
- Pada parameter keempat, kami mengonfigurasi header permintaan.
- Untuk menentukan bahwa tubuh permintaan dalam format JSON, kami mengatur 'application/json' Content-Type di parameter ketiga.
- Jika postAsync panggilan berhasil, kami dapat mengakses httpResponse objek di then callback.
- Kami mengurai httpResponse.response untuk mengonversi respons API dalam format JSON menjadi objek.
- Merujuk pada struktur respons API, kami menggunakan output Console untuk memverifikasi apakah parameter kueri permintaan HTTP kami, tubuh permintaan, dan header permintaan telah dikonfigurasi dengan benar.
Ketika Anda menjalankan server Multiplay di Editor Unity dan memainkan adegan, yang berikut akan ditampilkan di Konsol.