Halaman ini berlaku untuk Apigee dan Apigee Hybrid.
Lihat dokumentasi
Apigee Edge.
Halaman ini memberikan petunjuk tentang cara mendesain dan mengedit API di Apigee di Cloud Code, dengan memanfaatkan Gemini Code Assist untuk mempercepat pembuatan, pengeditan, dan pengelolaan spesifikasi API.
Sebelum memulai
Sebelum menggunakan fungsi dalam panduan ini:
- Pastikan Anda telah menyelesaikan langkah-langkah penyiapan untuk Menyiapkan Pengelolaan API Apigee di Cloud Code untuk VS Code, termasuk Menggunakan Gemini Code Assist dengan Apigee.
- Pastikan akun pengguna Anda memiliki peran yang diperlukan yang tercantum dalam Peran yang diperlukan untuk menggunakan Gemini Code Assist di Apigee untuk setiap tugas.
Menulis perintah spesifikasi API yang efektif
Anda akan meminta Gemini Code Assist di Apigee saat membuat dan mengedit spesifikasi API. Akurasi dan kesesuaian spesifikasi API yang dihasilkan sebagian besar bergantung pada perintah yang diberikan ke model.
Untuk menulis perintah pembuatan dan pengeditan spesifikasi API yang efektif:
- Dengan Gemini Code Assist Chat, selalu gunakan nama sebutan Apigee (
@Apigee
) di awal perintah Anda untuk membuat atau mengedit spesifikasi API. Dengan handle Apigee, Anda dapat mengakses alat Apigee yang mencakup fitur pengembangan spesifikasi API yang tangguh dan kaya fitur yang dijelaskan dalam panduan ini. - Gunakan bahasa alami: Susun perintah Anda seolah-olah Anda sedang berbicara dengan orang yang akan membuat spesifikasi.
- Bersikaplah spesifik: Berikan persyaratan yang tepat jika memungkinkan, seperti bahwa API penjadwalan klinik gigi Anda harus menyertakan beberapa jenis janji temu dan beberapa lokasi klinik gigi.
- Memanfaatkan konteks perusahaan tanpa menentukan nama objek:
Gemini Code Assist secara cerdas mendeteksi dan menggunakan kembali skema, metadata, dan
definisi keamanan yang ada dari katalog hub API Anda. Meskipun Anda tidak perlu menentukan
nama objek yang tepat, Anda dapat mengisyaratkan kemampuan ini dengan menyertakan frasa seperti
Use API Hub
atauLeverage Enterprise Context
dalam perintah Anda. - Gunakan perintah lanjutan untuk melakukan iterasi pada API Anda: Anda dapat menggunakan perintah seperti "Hapus entitas lokasi dari API ini" untuk membuat perubahan pada API.
Berikut adalah contoh perintah yang kurang dan lebih efektif untuk membuat dan mengedit spesifikasi API:
Perintah yang kurang efektif | Penjelasan perintah | Perintah yang lebih baik |
---|---|---|
"Buat API untuk toko saya." | Perintah ini berisi terlalu sedikit informasi sehingga model tidak dapat menghasilkan spesifikasi yang lengkap dan akurat. | "Buat API untuk toko saya agar pelanggan dapat memeriksa ketersediaan produk dan menambahkan item ke keranjang belanja mereka." "Buat API yang memungkinkan pelanggan membayar pesanan menggunakan berbagai metode pembayaran seperti kartu kredit dan kartu debit." |
"Buat API pengembalian dana baru yang menggunakan kembali objek pesanan." | Jangan tentukan objek mana yang harus digunakan kembali oleh Gemini Code Assist saat membuat API; Gemini Code Assist akan otomatis mendeteksi objek yang paling cocok untuk digunakan kembali. | "Buat API pengembalian dana baru yang memungkinkan pelanggan meminta pengembalian dana untuk pesanan sebelumnya." |
"Buat API untuk layanan pengiriman." | API yang dihasilkan akan terlalu umum. | "Kami adalah restoran pizza dan menginginkan solusi pengiriman pizza yang disesuaikan secara online. Buat API untuk menerima pesanan pizza dengan ukuran dan topping pizza." "API untuk bisnis pesan antar makanan. Pelanggan dapat memesan kombinasi pizza, burger, atau roti isi dalam satu pesanan. Setiap jenis makanan tersebut memiliki skemanya sendiri. Pizza memiliki topping dan ukuran. Burger memiliki topping dan jenis daging giling. Sandwich memiliki jenis roti, jenis daging, sayuran, keju, dan petunjuk khusus." |
Mendesain API dengan Gemini Code Assist
Anda dapat menggunakan Gemini Code Assist di Cloud Code untuk mendesain API spesifikasi OpenAPI (OAS), versi 3.0. API yang dirancang dapat menyertakan konteks perusahaan Anda saat membuat API baru dan hanya tersedia dengan project yang menggunakan hub API.
Lihat Sebelum memulai untuk mengetahui informasi tentang langkah-langkah penyiapan untuk menggunakan fungsi di bagian ini.
Untuk membuat API baru dengan Gemini Code Assist, ikuti langkah-langkah berikut:
- Gunakan salah satu metode berikut untuk mengakses perintah pembuatan spesifikasi API:
- Dari Gemini Code Assist: Chat: Di jendela chat, masukkan nama sebutan Apigee,
@Apigee
, lalu pilih alat Apigee.
-
Dari Apigee di Cloud Code: Klik tongkat ajaib di baris untuk Apigee.
Tindakan ini akan memuat Gemini Code Assist: Chat. Panggil alat Apigee dengan
@Apigee
untuk memulai pembuatan spesifikasi.
- Dari Gemini Code Assist: Chat: Di jendela chat, masukkan nama sebutan Apigee,
- Pilih Create API specification dari opsi alat Apigee.
- Lengkapi perintah dengan deskripsi API baru Anda. Lihat
Menulis perintah spesifikasi API yang efektif.
(Jangan salin dan tempel di atas tuas
@Apigee
. Sebagai gantinya, selesaikan perintah dengan mengetik atau menempelkan teks setelah nama sebutan channel.) - Kirimkan perintah.
- Gemini Code Assist menghasilkan OAS yang menentukan API. (Proses ini dapat memerlukan waktu hingga satu menit.) Jika hub API Anda menyertakan API lain, OAS baru dapat menggabungkan objek dan konteks dari katalog Anda. Ringkasan chat kontekstual memberikan informasi tentang API yang dihasilkan dan sumber yang digunakan.
- Tinjau spesifikasi yang dihasilkan. Spesifikasi kode YAML dan panel Swagger untuk API baru akan ditampilkan secara otomatis di tab.
- Setelah spesifikasi baru selesai, Anda dapat mengujinya menggunakan server tiruan. Lihat Menguji API menggunakan server tiruan.
- Untuk menyimpan API baru ke katalog hub API Anda, lihat Memublikasikan API ke hub API.
- Untuk membuat paket proxy API Apigee dari spesifikasi ini, lihat Menyimpan API sebagai paket proxy API.
Edit API
Anda dapat mengedit API yang telah disimpan secara lokal atau dari katalog hub API. Perubahan yang Anda buat di Cloud Code dapat disimpan ke hub API atau disimpan sebagai paket proxy API Apigee.
Mengedit spesifikasi API dari hub API
Untuk mengedit spesifikasi API yang disimpan di katalog hub API Anda:
- Pastikan project yang Anda pilih di Cloud Code adalah project dengan katalog hub API yang berisi API yang ingin Anda edit.
- Di menu kiri, luaskan hierarki API Hub di bagian Apigee.
- Pilih API dan versi yang akan diedit dari daftar.
- Lihat operasi API di panel Swagger. Klik Lihat kode di panel Swagger untuk membuka file YAML di tab pengeditan.
Mengedit spesifikasi API yang disimpan secara lokal
Untuk mengedit spesifikasi API yang disimpan secara lokal, buka file spesifikasi API di Cloud Code. Anda dapat memperbarui spesifikasi secara manual, atau menggunakan Gemini Code Assist Chat untuk melakukan iterasi pada spesifikasi.
Melakukan iterasi pada spesifikasi API menggunakan Gemini Code Assist Chat
Anda dapat membuat perubahan pada spesifikasi API yang ada menggunakan Gemini Code Assist Chat:
- Muat file spesifikasi ke dalam Cloud Code dengan mengikuti petunjuk untuk spesifikasi API dari hub API atau file spesifikasi API lokal.
- Pastikan file YAML yang berisi spesifikasi adalah tab yang aktif saat ini di editor Anda.
- Di jendela chat Gemini Code Assist, masukkan nama sebutan Apigee,
@Apigee
, lalu pilih alat Apigee. - Masukkan perintah pembaruan spesifikasi. Lihat Menulis perintah spesifikasi API yang efektif untuk mendapatkan panduan.
- Jika ingin, Anda dapat menguji API menggunakan server tiruan.
- Untuk menyimpan API baru ke katalog hub API Anda, lihat Memublikasikan API ke hub API.
- Untuk membuat paket proxy API Apigee dari spesifikasi ini, lihat Menyimpan API sebagai paket proxy API.
Memublikasikan API ke hub API
Jika menggunakan hub API, Anda dapat membuat API tersedia bagi developer lain dengan mendaftarkannya ke hub API:
- Di panel Swagger untuk spesifikasi API baru atau yang diedit, klik Publikasikan ke hub API.
- Dalam formulir, berikan metadata untuk API guna meningkatkan penemuan dan pengorganisasian API dalam katalog hub API Anda. Sebagian besar kolom diisi otomatis dari
spesifikasi API, tetapi Anda dapat mengubah nilainya. Lihat
Mendaftarkan API untuk
informasi tentang cara mendaftar ke hub API dan informasi yang perlu Anda berikan.
- Nama Tampilan API (Wajib): Nama API, yang dapat dilihat oleh developer lain.
- Deskripsi API (Opsional): Deskripsi API untuk referensi internal/developer.
- Nama Pemilik API (Opsional): Nama pemilik API.
- Email Pemilik API (Opsional): Alamat email pemilik.
- Versi API (Wajib): Versi API.
- Tahap Siklus Proses (Opsional): Pilih tahap dari daftar.
- Klik Publish untuk memublikasikan API ke hub API.
- Setelah penundaan singkat, perubahan Anda akan terlihat di struktur API Hub di bagian Apigee pada Cloud Code.
Menguji API menggunakan server tiruan
Anda dapat menguji API menggunakan server tiruan lokal atau server tiruan jarak jauh berbasis Google Cloud. Server tiruan lokal diinstal dan tersedia secara default, sedangkan Anda harus menyiapkan dan mengelola server tiruan. Google Cloud
Menggunakan server tiruan lokal
Server tiruan lokal menerima permintaan ke API ini dan meniru respons. Dapat digunakan hanya selama sesi saat ini oleh pengguna saat ini. Namun, tidak seperti server tiruan jarak jauh, server ini tidak memerlukan penyiapan atau pengelolaan dan tidak menimbulkan biaya.
Selain itu, server tiruan lokal:
- Tidak berfungsi saat menggunakan Cloud Shell Editor atau Cloud Workstations.
- Mungkin tidak berfungsi dengan benar saat menggunakan VS Code Remote Explorer.
Untuk menggunakan server tiruan lokal:
- Pilih server tiruan lokal di dropdown Servers (jika belum dipilih):
- Buka jalur di panel Swagger, lalu klik Try it out.
- Isi parameter permintaan, lalu klik Jalankan.
Menggunakan server tiruan jarak jauh
Server tiruan jarak jauh memberikan kemampuan untuk membuat instance server tiruan persisten yang, tidak seperti server tiruan lokal, dapat dibagikan dan digunakan oleh orang lain dalam organisasi Anda untuk menguji API baru. Server tiruan jarak jauh hanya dapat digunakan dengan API yang terdaftar di hub API.
Server tiruan jarak jauh tidak otomatis diperbarui untuk setiap perubahan yang Anda lakukan pada API setelah men-deploy server tiruan, jadi tunggu hingga Anda telah sepenuhnya membuat API sebelum menambahkan server tiruan.
Men-deploy server tiruan jarak jauh akan membuat layanan Cloud Run baru. Google Cloud Skrip ini membangun image container untuk server tiruan menggunakan Cloud Build dan mengupload image container ke Cloud Artifact Registry di project Google Anda. Lihat Apa itu Cloud Run?, Mengelola Layanan, dan dokumentasi Artifact Registry.
Anda dapat menggunakan akun layanan default atau memberikan akun layanan yang lebih terbatas untuk men-deploy aplikasi Cloud Run. Lihat Mengelola Cloud API dan Library Klien Cloud di Cloud Code untuk VS Code untuk mendapatkan informasi.
Untuk men-deploy server tiruan jarak jauh:
- Pilih Deploy mock server dari panel Swagger.
- Jika API Anda belum terdaftar di hub API, daftarkan saat diminta.
- Tentukan detail untuk server tiruan jarak jauh: Nama Server, Server Aman, Akun Layanan (biarkan kosong untuk menggunakan akun layanan default), dan apakah akan menambahkan URL server ke spesifikasi API. Klik Buat untuk membuat server tiruan jarak jauh.
- Pembuatan server tiruan jarak jauh memerlukan waktu beberapa menit. Anda dapat memantau progres di panel OUTPUT Cloud Code dan melalui pop-up notifikasi di pojok kanan bawah VS Code.
- Setelah proses pembuatan server tiruan jarak jauh selesai, Anda akan melihat URL server jarak jauh di daftar server panel Swagger dan panel OUTPUT.
- Untuk menggunakan server tiruan, buka jalur, lalu klik Coba.
Isi parameter permintaan, lalu klik Jalankan.
Anda juga dapat mengirimkan permintaan menggunakancurl
dari perintah. Gunakan alamat dan port server dari dropdown Server.
Untuk membagikan akses ke server tiruan dengan pengguna lain:
- Beri pengguna lain peran pemanggil untuk layanan yang di-deploy. Lihat Mengautentikasi developer.
- Saat membuat permintaan ke server tiruan, pengguna mengikuti petunjuk di Menguji layanan pribadi Anda.
Untuk mengelola server tiruan jarak jauh yang di-deploy:
- Buka Apigee API hub.
- Temukan API untuk melihat semua deployment API, yang mencakup server tiruan jarak jauh.
- Gunakan URL Resource untuk membuka deployment dan mengelolanya dengan menghentikan, menghapus, dan melakukan tindakan lain di server tiruan.
Menyimpan API sebagai paket proxy API
Anda dapat menyimpan API sebagai paket proxy API Apigee sehingga Anda dapat mengerjakannya dalam lingkungan pengembangan lokal Apigee. Untuk mengetahui informasi tentang cara menggunakan proxy API di Cloud Code, lihat Mengembangkan proxy API.
- Klik Create API proxy bundle di panel Swagger.
- Di kolom perintah, beri nama proxy API Anda dan lanjutkan.
- Proxy API Anda akan muncul di menu kiri Apigee di ruang kerja lokal Anda, di bagian apiproxies.
Mengontrol konteks perusahaan dalam pembuatan spesifikasi
Pembuatan OAS dapat mencakup skema, metadata, dan definisi keamanan dari API lain organisasi Anda. Proses menemukan API serupa menggunakan nama dan deskripsi objek. Status deployment API hub API tidak dipertimbangkan.
Konteks perusahaan diaktifkan secara default.
Untuk menonaktifkan konteks perusahaan untuk pembuatan spesifikasi baru, tambahkan baris ini di file
settings.json
setelah
"cloudcode.apigee.gemini.enable": true
:
"cloudcode.apigee.gemini.options": { "enterpriseContext": { "enabled": false, "includeMetadata": false, "includeSchema": false, "includeSecurity": false } }
enabled
menentukan apakah konteks perusahaan diaktifkan secara keseluruhan. Setel kefalse
untuk menonaktifkan konteks perusahaan.includeMetadata
mengontrol apakah konteks metadata disertakan. Setelan ini menyertakan atau mengecualikan metadata dari API lain di hub API.includeMetadata
hanya berlaku jikaenabled
ditetapkan ketrue
.includeSchema
mengontrol apakah konteks skema disertakan. Setelan ini mencakup atau mengecualikan informasi skema dari API lain di hub API.includeSchema
hanya berlaku jikaenabled
ditetapkan ketrue
.includeSecurity
mengontrol apakah konteks terkait keamanan disertakan. Setelan ini menyertakan atau mengecualikan informasi keamanan dari API lain di hub API.includeSecurity
hanya berlaku jikaenabled
ditetapkan ketrue
.