Mendesain dan mengedit API

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat dokumentasi Apigee Edge.

Ikuti petunjuk di halaman ini untuk menggunakan Cloud Code guna mendesain dan mengedit API.

Peran tambahan yang diperlukan untuk mendesain API

Anda memerlukan peran yang tercantum di bawah untuk melakukan beberapa langkah desain dan pengujian API yang dijelaskan di halaman ini.

Tugas	Peran yang Diperlukan
Mendesain API menggunakan Gemini Code Assist	Pengguna Gemini untuk Google Cloud Pengguna Penggunaan Layanan Lihat Memberikan peran IAM di project Google Cloud untuk Gemini Code Assist.
Menggunakan konteks perusahaan dari API yang ada di API Hub saat mendesain API	Cloud API Hub Viewer
Daftarkan API baru Anda ke API hub	Cloud API Hub Editor atau Admin
Mengedit API hub API di Cloud Code	Cloud API Hub Editor atau Admin
Menyiapkan dan mengelola server tiruan jarak jauh untuk menguji API	Administrator Artifact Registry Akun Layanan Cloud Build Admin Cloud Run Admin Penggunaan Layanan Lihat Referensi peran dasar dan standar IAM.

Mendesain API dengan Gemini Code Assist

Pratinjau — Gemini Code Assist

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dalam Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Anda dapat menggunakan Cloud Code untuk mendesain API spesifikasi OpenAPI (OAS), versi 3.0 menggunakan Gemini Code Assist. Gemini Code Assist dapat menyertakan konteks perusahaan untuk bantuan AI generatif dalam proses pengembangan API. Konteks perusahaan menggunakan API hub project untuk konteks saat membuat API baru dan hanya tersedia dengan project yang menggunakan API hub.

Lihat Menggunakan Gemini Code Assist untuk mengetahui informasi tentang langkah-langkah penyiapan untuk menggunakan fungsi di bagian ini.

Catatan: Saat ini, Gemini Code Assist mendukung desain API yang menggabungkan objek baru dengan objek yang ada (jika konteks perusahaan diaktifkan). API ini tidak mendukung skenario untuk hanya menggunakan kembali objek tanpa membuat objek baru.

Membuat API

Untuk membuat API, ikuti langkah-langkah berikut:

1. Klik tongkat sihir di navigasi sebelah kiri untuk menggunakan Gemini Code Assist guna membuat spesifikasi API baru. Pastikan untuk menggunakan metode ini guna membuat spesifikasi API, bukan chat Gemini Code Assist, yang tidak mendukung semua fitur dan fungsi saat membuat spesifikasi API.
   
2. Masukkan perintah yang menjelaskan API baru di jendela input Create an API spec.
   1. Jika diinginkan, pilih template perintah dari chip template yang ditampilkan. Template perintah menyediakan framework untuk perintah Anda guna membantu Anda memulai.
   2. Masukkan perintah. Lihat Cara menulis perintah spesifikasi API yang efektif.
      
      
3. Gemini Code Assist menghasilkan OAS yang menentukan API.
4. Tinjau spesifikasinya:
   1. Klik Lihat kode untuk meninjau spesifikasi di editor kode.
   2. Panel perender API menampilkan pratinjau API karena dapat dilihat oleh developer, termasuk deskripsi API dan dokumentasi lainnya.
   3. Jika Anda sudah memiliki API di API Hub, konteks perusahaan tersebut digunakan untuk menggunakan kembali objek dari API lain ke OAS ini dan dihitung di panel OUTPUT:
      
   4. Kami menghargai masukan Anda. Berikan masukan tentang spesifikasi yang dihasilkan dengan mengklik ikon suka atau tidak suka di panel Swagger.
      
   5. Jika Anda ingin mengedit perintah pratinjau dan membuat ulang spesifikasi, klik panah histori perintah di atas perintah untuk berpindah di antara perintah sebelumnya.
      
5. Uji spesifikasi. Setelah spesifikasi baru selesai, Anda dapat mengujinya menggunakan server tiruan. Lihat Menguji API menggunakan server tiruan.
6. Klik Simpan untuk menyimpan API baru dengan nama pilihan Anda.
7. Untuk membuat proxy API Apigee dari spesifikasi ini, klik Create API proxy dari menu More. Proses pembuatan akan membuat paket proxy. Anda akan melihat proxy baru di daftar menu kiri proxy. Lihat panduan pembuatan proxy API yang terintegrasi dalam Cloud Code untuk informasi tambahan tentang cara membuat proxy dari Cloud Code.
   

Cara menulis perintah spesifikasi API yang efektif

Akurasi dan kesesuaian spesifikasi API yang dihasilkan sangat bergantung pada perintah yang diberikan ke model.

Berikut adalah contoh perintah yang baik:

• Buat API yang memungkinkan pelanggan membayar pesanan menggunakan berbagai metode pembayaran seperti kartu kredit dan kartu debit.
• Menerima pesanan pembelian untuk pembelian biji kopi khusus melalui API.
• Kami adalah perusahaan pizza dan ingin membuat solusi pengiriman pizza kustom secara online. Buat API untuk menerima pesanan pizza.
• API untuk bisnis pesan-antar makanan. Pelanggan dapat memesan kombinasi pizza, burger, atau sandwich dalam satu pesanan. Setiap jenis makanan tersebut memiliki skema sendiri. Pizza memiliki topping dan ukuran. Burger memiliki topping dan jenis patty. Sandwich memiliki jenis roti, jenis daging, sayuran, keju, dan petunjuk kustom.

Contoh ini menunjukkan perintah yang kurang efektif. Cobalah untuk menghindari perintah yang disusun seperti ini:

• Membuat API untuk toko saya. Perintah ini berisi terlalu sedikit informasi bagi model untuk menghasilkan spesifikasi yang lengkap dan akurat.
• Buat API pengembalian dana baru yang menggunakan kembali objek pesanan. Anda tidak perlu menentukan objek mana yang akan digunakan kembali oleh Gemini Code Assist saat membuat API baru; Gemini Code Assist secara otomatis mendeteksi objek yang paling sesuai untuk digunakan kembali.

Mendaftarkan API ke API hub

Setelah API ditinjau dan selesai, Anda dapat menyediakannya kepada developer dengan mendaftarkannya ke API hub:

1. Klik Register to API hub.
2. Ikuti petunjuk untuk mendaftarkan API. Lihat Mendaftarkan API untuk mengetahui informasi tentang pendaftaran ke API hub dan informasi yang perlu Anda berikan.

Memperbarui API hub API dari Cloud Code

Anda dapat menyimpan versi baru spesifikasi API hub saat mengeditnya dari Cloud Code.

Untuk menyimpan spesifikasi sebagai versi baru, klik tombol Opsi lainnya... di panel Swagger dan Publikasikan ke API hub. Berikan ID versi API baru. Anda akan melihat versi baru muncul dalam daftar versi untuk API tersebut dalam daftar API hub di Cloud Code.

Menggunakan file setelan untuk mengontrol perilaku Gemini Code Assist

Bagian ini menjelaskan cara mengelola apakah dan bagaimana Gemini Code Assist tersedia, dari file setelan.

Menonaktifkan atau mengaktifkan Gemini Code Assist

Setelah menyiapkan Apigee di Cloud Code (lihat Menyiapkan Apigee di Cloud Code), Anda dapat menambahkan baris ini ke file setelan untuk menonaktifkan semua fitur Gemini Code Assist untuk sementara:

"cloudcode.apigee.gemini.enable": false

Hapus baris atau tetapkan ke true (default) untuk mengaktifkan kembali Gemini Code Assist.

Mengontrol konteks perusahaan dalam pembuatan spesifikasi

Pembuatan OAS dapat mencakup skema, metadata, dan definisi keamanan dari API lain organisasi Anda. Proses ini menemukan API serupa menggunakan nama dan deskripsi objek di katalog API hub yang Anda miliki otorisasi untuk mengaksesnya. Status deployment API hub API tidak dipertimbangkan.

Konteks perusahaan diaktifkan secara default.

Anda dapat:

• Lihat jumlah modifikasi yang disertakan dari konteks perusahaan, jika ada, di panel Swagger:
• Lihat modifikasi yang disertakan di panel Output:

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
        }
    }

Lokasi:

• enabled menentukan apakah konteks perusahaan diaktifkan secara keseluruhan. Tetapkan ke false 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 jika enabled ditetapkan ke true.
• includeSchema mengontrol apakah konteks skema disertakan. Setelan ini menyertakan atau mengecualikan informasi skema dari API lain di hub API. includeSchema hanya berlaku jika enabled ditetapkan ke true.
• includeSecurity mengontrol apakah konteks terkait keamanan disertakan. Setelan ini menyertakan atau mengecualikan informasi keamanan dari API lain di hub API. includeSecurity hanya berlaku jika enabled ditetapkan ke true.

Edit API

Untuk menggunakan Cloud Code guna mengedit API yang ada dan merupakan bagian dari katalog API hub Anda, ikuti petunjuk berikut. Perubahan yang Anda buat di Cloud Code dapat disimpan kembali ke API Hub.

Petunjuk ini ditujukan untuk pengguna yang tidak menggunakan add-on Gemini Code Assist untuk Apigee. Untuk informasi tentang fungsi tambahan yang tersedia dengan Gemini Code Assist saat mendesain dan mengedit API, lihat Mendesain API dengan Gemini Code Assist.

Catatan: Saat ini, setiap perubahan pada API yang disimpan kembali ke API hub harus disimpan sebagai versi baru.

Untuk mengedit spesifikasi API:

1. Pastikan project yang Anda pilih di Cloud Code adalah project dengan katalog API hub yang berisi API yang ingin Anda edit.
2. Di navigasi sebelah kiri, luaskan hierarki API Hub.
3. Pilih API dan versi yang akan diedit dari daftar.
4. Edit spesifikasi di panel pengeditan. Anda juga dapat melihat operasi API di panel Swagger.
5. Jika ingin, uji API Anda menggunakan server tiruan.
6. Simpan perubahan sebagai versi baru dengan tombol Lainnya di panel Swagger, lalu Publikasikan ke API Hub. Konfirmasi atau perbarui versi saat diminta dan simpan perubahan kembali ke API hub. Anda akan melihat versi baru muncul dalam daftar versi untuk API tersebut dalam daftar API hub di 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 mengemulasi respons. Fitur ini hanya dapat digunakan 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.

Catatan: Server tiruan lokal mungkin tidak berfungsi dengan benar saat menggunakan VS Code Remote Explorer. Selain itu, terkadang server tiruan lokal tidak dapat dimulai. Dalam hal ini, atribut tersebut tidak akan tersedia di menu drop-down.

Untuk menggunakan server tiruan lokal:

1. Pilih server tiruan lokal (server pengembangan) di dropdown Servers.
   
2. Buka jalur, lalu klik Coba.
   
3. Isi parameter permintaan, lalu klik Jalankan.
   
4. Anda juga dapat mengirimkan permintaan menggunakan curl dari perintah. Gunakan alamat dan port server dari dropdown Servers.

Menggunakan server tiruan jarak jauh

Server tiruan jarak jauh memberi Anda 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 sebelum diproduksi. Server tiruan jarak jauh hanya dapat digunakan dengan API yang terdaftar di API Hub.

Saat ini, server tiruan jarak jauh dapat dibuat di Google Cloud. Server tiruan jarak jauh Google Cloud tidak otomatis diperbarui untuk setiap perubahan yang Anda lakukan pada API setelah men-deploy server tiruan, jadi tunggu hingga Anda membuat API sepenuhnya sebelum menambahkan server tiruan.

Men-deploy server tiruan jarak jauh Google Cloud akan membuat layanan Cloud Run baru. Alat ini mem-build image container untuk server tiruan menggunakan Cloud Build dan mengupload image container ke Cloud Artifact Registry di project Google Anda; Anda bertanggung jawab atas biaya dan pemeliharaan yang dihasilkan setelah pembuatan. Anda juga bertanggung jawab untuk menghapusnya setelah tidak diperlukan lagi. Lihat Apa itu Cloud Run?, Mengelola Layanan, dan dokumentasi Artifact Registry.

Penting: Setelah membuat server tiruan jarak jauh Google Cloud, Anda bertanggung jawab atas biaya yang dihasilkan dari penggunaannya, pengelolaannya, dan penghapusannya setelah tidak diperlukan lagi. Lihat https://cloud.google.com/run/pricing untuk mengetahui informasi harga, termasuk informasi tentang opsi paket gratis.

Untuk men-deploy server tiruan jarak jauh:

1. Pilih Deploy mock server (Google Cloud) dari menu More.
2. Jika API Anda belum terdaftar di API Hub, daftarkan saat diminta.
3. Tentukan detail untuk server tiruan jarak jauh: Project ID, Server Name, dan Region, lalu klik Create untuk membuat server tiruan jarak jauh.
   Penting: Jangan membuat beberapa server tiruan jarak jauh dengan nama yang sama, meskipun antarmuka pengguna tidak akan mencegah Anda melakukannya saat ini.
4. Pembuatan server tiruan jarak jauh memerlukan waktu beberapa menit. Anda dapat melihat progresnya di panel OUTPUT Google Cloud.
5. Setelah pembuatan server tiruan jarak jauh selesai, Anda akan melihat URL server jarak jauh di daftar server panel Swagger dan panel OUTPUT.
6. Untuk menggunakan server tiruan, buka jalur dan klik Coba.
   
   
   Isi parameter permintaan, lalu klik Execute.
   
   
   Anda juga dapat mengirimkan permintaan menggunakan curl dari perintah. Gunakan alamat dan port server dari dropdown Servers.

Untuk membagikan akses ke server tiruan kepada pengguna lain:

1. Berikan peran pemanggil kepada pengguna lain untuk layanan yang di-deploy. Lihat Mengautentikasi developer.
2. Saat membuat permintaan ke server tiruan, pengguna mengikuti petunjuk di Menguji layanan pribadi Anda.

Gunakan langkah-langkah berikut untuk mengelola server tiruan jarak jauh yang di-deploy:

1. Buka API Hub dan temukan API untuk melihat semua deployment API, yang mencakup server tiruan jarak jauh.
2. Gunakan URL Resource untuk membuka deployment dan mengelolanya dengan menghentikan, menghapus, dan melakukan tindakan lainnya di server tiruan.