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 Spesifikasi OpenAPI (OAS), versi 3.0 API yang menggunakan Gemini Code Assist. Gemini Code Assist dapat mencakup konteks perusahaan untuk AI generatif bantuan dalam proses pengembangan API. Konteks perusahaan menggunakan API hub API project untuk 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 penggunaan fungsi tersebut di bagian ini.

Catatan: Saat ini Gemini Code Assist mendukung perancangan API yang menggabungkan objek baru dengan (jika konteks perusahaan diaktifkan). Tidak mendukung skenario yang hanya untuk penggunaan ulang 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. Merek pastikan menggunakan metode ini untuk membuat spesifikasi API, bukan percakapan 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 kerangka kerja untuk {i>prompt<i} 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 spesifikasi:
   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 prompt untuk berpindah di antara prompt sebelumnya.
      
5. Uji spesifikasi. Setelah spesifikasi baru selesai, Anda dapat mengujinya menggunakan server tiruan. Lihat Uji API Anda menggunakan server tiruan.
6. Klik Save untuk menyimpan API baru dengan nama pilihan Anda.
7. Untuk membuat proxy Apigee API dari spesifikasi ini, klik Buat proxy API dari menu Lainnya. Proses pembuatan menciptakan paket proxy. Anda akan melihat proxy baru di daftar menu sebelah kiri proxy. Melihat proxy API panduan pembuatan konten yang terintegrasi dalam Cloud Code untuk informasi tambahan tentang membuat proxy dari Cloud Code.
   

Cara menulis perintah spesifikasi API yang efektif

Keakuratan dan kesesuaian spesifikasi API yang dihasilkan sangat bergantung pada perintah yang yang disediakan 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 layanan pesan-antar pizza online khusus solusi. Buat api untuk menerima pesanan pizza.
• API untuk bisnis layanan pesan-antar makanan. Pelanggan dapat memesan kombinasi pizza, burger, atau {i>sandwich <i}dalam satu pesanan. Setiap jenis makanan tersebut memiliki skema sendiri. Piza memiliki {i>topping<i} dan ukuran. Burger memiliki {i>topping<i} dan jenis patty. Sandwich memiliki jenis roti, daging jenis makanan, 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; Bantuan Kode Gemini secara otomatis mendeteksi objek yang paling cocok untuk digunakan kembali.

Mendaftarkan API dengan hub API

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

1. Klik Register to API hub.
2. Ikuti petunjuk untuk mendaftarkan API. Lihat Daftarkan API untuk informasi tentang pendaftaran dengan hub API dan informasi yang harus Anda berikan.

Mengupdate API hub API dari Cloud Code

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

Untuk menyimpan spesifikasi sebagai versi baru, klik tombol More options... di panel Swagger dan Publish to API hub. Sediakan ID versi API baru. Anda akan melihat versi baru muncul di bagian daftar untuk API tersebut di daftar Hub API di Cloud Code.

Menggunakan file setelan untuk mengontrol perilaku Gemini Code Assist

Bagian ini menjelaskan cara mengelola ketersediaan Gemini Code Assist dan caranya, dari 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 sementara semua Gemini Code Assist fitur:

"cloudcode.apigee.gemini.enable": false

Hapus baris atau setel 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 lainnya. Proses menemukan API yang serupa menggunakan nama dan deskripsi objek di hub API Anda katalog yang ada di katalog hub API yang boleh Anda akses. Status deployment API hub API tidak dipertimbangkan.

Konteks perusahaan diaktifkan secara default.

Anda dapat:

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

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

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

Di mana:

• 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 sama dengan hanya berlaku jika enabled ditetapkan ke true.
• includeSecurity mengontrol apakah konteks terkait keamanan disertakan atau tidak. 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 yang merupakan bagian dari Katalog hub API, 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 informasi 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 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 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 bisa melihat operasi API di Swagger .
5. Atau, uji API Anda menggunakan server tiruan.
6. Simpan perubahan sebagai version dengan Tombol More di panel Swagger, lalu Publikasikan ke hub API. Konfirmasi atau update versi saat diminta dan simpan perubahan kembali ke hub API. Anda akan melihat versi baru muncul di bagian daftar untuk API tersebut di daftar Hub API di Cloud Code.

Menguji API Anda menggunakan server tiruan

Anda dapat menguji API menggunakan server tiruan lokal atau tiruan jarak jauh berbasis Google Cloud server tertentu. Server tiruan lokal diinstal dan tersedia secara {i> default<i} 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. Data hanya dapat digunakan selama sesi saat ini oleh pengguna saat ini. Namun, tidak seperti server tiruan jarak jauh, layanan ini tidak memerlukan penyiapan atau pengelolaan dan tidak dikenai biaya.

Catatan: Server tiruan lokal mungkin tidak berfungsi dengan benar saat digunakan VS {i>Remote Explorer<i}. Selain itu, terkadang server tiruan lokal tidak dapat dimulai. Di sana kasus ini, keterangan 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. Menggunakan server alamat 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 di dalam organisasi Anda untuk menguji API baru sebelum diluncurkan produksi. 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. Kebijakan Privasi Server tiruan jarak jauh cloud tidak otomatis diperbarui untuk perubahan apa pun yang Anda buat ke API setelah men-deploy server tiruan, jadi tunggu untuk menambahkan server tiruan sampai Anda telah membuat API sepenuhnya.

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

Penting: Setelah Anda membuat server tiruan jarak jauh Google Cloud Anda bertanggung jawab atas biaya apa pun yang timbul dari penggunaan, pengelolaan, dan penghapusannya setelah tidak lagi diperlukan. Lihat https://cloud.google.com/run/pricing untuk 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, Nama Server, 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 saat ini.
4. Pembuatan server tiruan jarak jauh memerlukan waktu beberapa menit. Anda dapat melihat kemajuan 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 semua parameter permintaan, lalu klik Execute.
   
   
   Anda juga dapat mengirimkan permintaan menggunakan curl dari perintah. Menggunakan server alamat 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 Autentikasi developer.
2. Saat membuat permintaan ke server tiruan, pengguna mengikuti petunjuk di Uji layanan pribadi Anda.

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

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