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.

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 OpenAPISpecification (OAS), versi 3.0 API menggunakan Gemini Code Assist. Gemini Code Assist dapat menyertakan konteks perusahaan untuk bantuan AI generatif dalam proses pengembangan API. Konteks perusahaan menggunakan API hub API project sebagai konteks saat membuat API baru dan hanya tersedia dengan project yang menggunakan hub API.

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 perancangan API yang menggabungkan objek baru dengan objek yang sudah ada (jika konteks perusahaan diaktifkan). Solusi ini tidak mendukung skenario yang hanya memungkinkan menggunakan kembali objek tanpa membuat objek baru.

Untuk membuat API, ikuti langkah-langkah berikut:

1. Klik tongkat ajaib di navigasi sebelah kiri untuk menggunakan Gemini Code Assist guna membuat spesifikasi API baru. Pastikan Anda menggunakan metode ini untuk 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 ingin, pilih template perintah dari chip template yang ditampilkan. Template perintah memberikan framework bagi perintah Anda untuk 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 hub API, konteks perusahaan tersebut akan digunakan untuk menggunakan kembali objek dari API lain ke OAS ini dan disebutkan dalam 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 Save 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 menghasilkan paket proxy. Anda akan melihat proxy baru di daftar menu sebelah kiri proxy. Lihat panduan pembuatan proxy API yang terintegrasi dalam Cloud Code untuk mengetahui informasi tambahan tentang pembuatan 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.
• Terima 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 layanan 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 {i>topping<i} dan jenis patty. Sandwich memiliki jenis roti, jenis daging, sayuran, keju, dan petunjuk khusus.

Contoh ini menunjukkan perintah yang kurang efektif. Coba hindari dialog dengan struktur seperti berikut:

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

Mendaftarkan API dengan hub API

Setelah API ditinjau dan difinalisasi, Anda dapat menyediakannya untuk developer dengan mendaftarkannya ke hub API:

1. Klik Register to API hub.
2. Ikuti petunjuk untuk mendaftarkan API. Lihat Mendaftar API untuk mendapatkan informasi tentang cara mendaftar dengan hub API dan informasi yang perlu Anda berikan.

Mengupdate API hub API dari Cloud Code

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

Untuk menyimpan spesifikasi sebagai versi baru, klik tombol More options... di panel Swagger dan Publish to API hub. Berikan ID versi API baru. Anda akan melihat versi baru muncul di 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 ketersediaan Gemini Code Assist dan caranya, 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 guna menonaktifkan sementara semua fitur Gemini Code Assist:

"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 di organisasi Anda. Proses ini menemukan API serupa menggunakan nama dan deskripsi objek di katalog hub API Anda yang ada dalam katalog hub API yang diizinkan untuk Anda akses. 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 perubahan yang disertakan di panel Output:

Guna menonaktifkan konteks perusahaan untuk pembuatan spesifikasi baru, tambahkan baris berikut dalam file settings.json setelah "cloudcode.apigee.gemini.enable": true:

"cloudcode.apigee.gemini.options": {
        "enterpriseContext": {
          "enabled": false,
          "includeMetadata": false,
          "includeSchema": false,
          "includeSecurity": false
        }
    }

Dalam hal ini:

• enabled menentukan apakah konteks perusahaan diaktifkan secara keseluruhan. Tetapkan ke false untuk menonaktifkan konteks perusahaan.
• includeMetadata mengontrol apakah konteks metadata disertakan atau tidak. 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 atau tidak. 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 atau tidak. 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 sudah ada dan merupakan bagian dari katalog hub API Anda, ikuti petunjuk berikut. Perubahan yang Anda buat di Cloud Code dapat disimpan kembali ke hub API.

Petunjuk ini ditujukan bagi pengguna yang tidak menggunakan add-on Gemini Code Assist untuk Apigee. Untuk mengetahui 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 hub API harus disimpan sebagai versi baru.

Untuk mengedit spesifikasi API:

1. Pastikan project yang Anda pilih di Cloud Code adalah project dengan katalog hub API 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. Atau, uji API Anda menggunakan server tiruan.
6. Simpan perubahan sebagai versi baru dengan tombol More di panel Swagger, lalu Publish to API hub. Konfirmasi atau update versi saat diminta dan simpan perubahan kembali ke hub API. Anda akan melihat versi baru muncul di daftar versi untuk API tersebut dalam daftar API hub di Cloud Code.

Menguji API Anda 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 saat Anda harus menyiapkan dan mengelola server tiruan Google Cloud.

Menggunakan server tiruan lokal

Server tiruan lokal menerima permintaan ke API ini dan mengemulasikan respons. Kolom tersebut hanya dapat digunakan oleh pengguna saat ini selama sesi saat ini. Namun, tidak seperti server tiruan jarak jauh, ini tidak memerlukan penyiapan atau pengelolaan dan tidak dikenai 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, ID tersebut tidak akan tersedia di menu drop-down.

Untuk menggunakan server tiruan lokal:

1. Pilih server tiruan lokal (server pengembangan) di menu dropdown Servers.
   
2. Buka jalur dan klik Coba.
   
3. Isi semua parameter permintaan, lalu klik Execute.
   
4. Anda juga dapat mengirimkan permintaan menggunakan curl dari perintah. Gunakan alamat server dan port dari menu 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 dengan 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 hub API.

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

Men-deploy server tiruan jarak jauh Google Cloud akan menciptakan layanan Cloud Run baru. Cloud Build membangun image container untuk server tiruan menggunakan Cloud Build dan mengupload image container ke Cloud Artifact Registry di project Google. Anda bertanggung jawab atas biaya dan pemeliharaan yang ditimbulkan setelah dibuat. 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 timbul dari penggunaan, pengelolaan, dan penghapusannya setelah tidak diperlukan lagi. Lihat https://cloud.google.com/run/pricing untuk mengetahui informasi harga, termasuk informasi tentang semua 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 hub API, daftarkan API 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 buat beberapa server tiruan jarak jauh dengan nama yang sama, meskipun antarmuka pengguna tidak akan mencegah Anda melakukannya untuk 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 dalam daftar server panel Swagger dan panel OUTPUT.
6. Untuk menggunakan server tiruan, buka jalur dan klik Coba.
   
   
   Isi semua parameter permintaan, lalu klik Execute.
   
   
   Anda juga dapat mengirimkan permintaan menggunakan curl dari perintah. Gunakan alamat server dan port dari menu dropdown Servers.

Untuk membagikan akses ke server tiruan dengan pengguna lain:

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

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

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