Halaman ini menjelaskan fitur pembuatan versi Cloud Endpoints API dan menyediakan praktik terbaik untuk membuat versi dan melakukan staging Endpoints API Anda. Informasi di halaman ini berlaku untuk API yang menggunakan spesifikasi OpenAPI. Untuk API yang menggunakan Framework Cloud Endpoints untuk lingkungan standar App Engine, lihat Menangani pembuatan versi API: Java atau Menangani pembuatan versi API: Python.
Sebaiknya ikuti prinsip dasar yang sama dengan yang digunakan Google untuk pembuatan versi API dan staging layanan:
Sertakan hal berikut dalam file konfigurasi OpenAPI sebelum Anda men-deploy versi awal:
- Tetapkan nomor versi di kolom
info.version. Sebaiknya gunakan string versi yang menyertakan versi utama dan versi minor, misalnya,1.0. - Tetapkan kolom
basePathuntuk menyertakan nomor versi utama. Sebaiknya gunakan jalur dasar yang diformat sebagai hurufvdiikuti dengan nomor versi utama, misalnya,/v1.
- Tetapkan nomor versi di kolom
Jika Anda perlu membuat perubahan yang kompatibel dengan versi lama, seperti menambahkan metode baru, tambahkan nomor versi minor (1.2, 1.3, dll.) di kolom
info.versiondan deploy ulang. Lihat Membuat versi API untuk mengetahui detailnya.Jika Anda perlu membuat perubahan pada metode yang ada yang merusak kode klien, buat salinan file konfigurasi OpenAPI, lalu buat perubahan berikut:
- Tambahkan nomor versi utama (2.0, 3.0, dll.) di kolom
info.version. - Tambahkan nomor versi utama (/v2, /v3, dll.) di kolom
basePath.
Deploy kedua versi file konfigurasi OpenAPI Anda dan deploy ulang backend, yang kini memiliki kedua versi metode. Lihat Membuat versi API untuk mengetahui detailnya.
- Tambahkan nomor versi utama (2.0, 3.0, dll.) di kolom
Terapkan semua versi API utama dalam satu backend. Rekomendasi ini:
- Menyederhanakan pemilihan rute karena permintaan ke versi tertentu didasarkan pada jalur, seperti pada contoh sebelumnya.
- Menyederhanakan konfigurasi dan deployment. Anda menggunakan project dan backend Google Cloud yang sama untuk semua versi utama API, dan Anda men-deploy semua versi API secara bersamaan.
- Menjaga biaya tetap rendah dengan menghindari menjalankan backend yang tidak perlu.
Lakukan staging API di project Google Cloud terpisah sebelum men-deploy ke project Google Cloud produksi. Lihat Layanan staging untuk mengetahui detailnya.
Penggunaan nomor versi utama dan minor di Endpoint sesuai dengan definisi dalam Pembuatan versi semantik. Meskipun Endpoints tidak mengharuskan Anda menambahkan nomor versi patch dalam file konfigurasi OpenAPI dan men-deploy konfigurasi saat men-deploy perbaikan bug dalam kode backend, Anda dapat memilih untuk melakukannya jika mau.
Fitur pembuatan versi Cloud Endpoints API
Extensible Service Proxy (ESP) memiliki kemampuan untuk mengelola beberapa versi utama API Anda secara serentak dalam satu project dan backend Google Cloud selama API tidak memiliki jalur yang tumpang-tindih. Contoh:
http://echo-api.endpoints.my-project.cloud.goog/v1/echo
http://echo-api.endpoints.my-project.cloud.goog/v2/echo
Hal ini memungkinkan pelanggan Anda memilih versi yang ingin mereka gunakan dan mengontrol saat mereka bermigrasi ke versi baru. ESP memberi tag pada setiap permintaan dengan nomor versi sebelum merutekan permintaan ke metode yang berlaku di backend. Karena setiap permintaan diberi tag dengan nomor versi:
Grafik dan log di Endpoints > Services menampilkan permintaan dari setiap versi API utama dan total gabungan di semua versi. Anda dapat memfilter tampilan ke versi tertentu. Hal ini memberi Anda gambaran yang jelas tentang berapa banyak traffic yang diperoleh setiap versi. Log bahkan dapat memberi tahu Anda klien mana yang menggunakan versi mana.
Saat Anda men-deploy ulang API dengan update nomor versi minor, aktivitas berikutnya akan diberi label dengan nomor versi baru dalam grafik dan log. Tindakan ini akan memberi Anda histori deployment yang diberi label.
Saat Anda menghapus versi API, grafik dan log akan terus menampilkan data dalam rentang waktu saat API aktif.
Contoh siklus proses API
Bagian ini menjelaskan evolusi umum layanan.
Versi 1
Anda awalnya men-deploy layanan My Awesome Echo API versi 1. API ditayangkan
dari my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. Dalam grafik dan log di Endpoints > Services, Anda akan melihat semua traffic di 1.0.
Versi 1.1
Pelanggan meminta fitur baru, jadi Anda menambahkan metode baru. Dalam file konfigurasi
OpenAPI, Anda menambahkan metode baru dan menambahkan kolom info.version
ke 1.1. Anda menambahkan nomor versi minor karena perubahan ini tidak
mengganggu kode klien. Anda men-deploy dan menguji perubahan di lingkungan staging untuk
memastikan perubahan tersebut berfungsi.
Selanjutnya, Anda men-deploy konfigurasi OpenAPI dan backend API ke lingkungan produksi. API masih ditayangkan dari
my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo, tetapi sekarang pemanggil dapat membuat
permintaan ke metode baru. Karena Anda tidak mengubah antarmuka ke metode lama, pelanggan tidak perlu mengubah dan
men-deploy ulang klien mereka; klien dapat terus mengirim permintaan ke metode lama
seperti sebelumnya.
Di Endpoints > Services, traffic yang ditayangkan kini berada di versi 1.1. Jika Anda memilih rentang waktu sebelumnya untuk ditampilkan, versi sebelumnya akan ditampilkan dalam grafik dan log, yang memberikan histori berlabel dari deployment Anda.
Versi 2.0
Seiring waktu, Anda menyadari bahwa Anda perlu melakukan perubahan yang tidak kompatibel dengan versi sebelumnya pada
metode yang ada. Karena Anda tidak boleh merusak kode klien
pelanggan, Anda memutuskan untuk mempertahankan dua versi API. Anda membiarkan metode lama
seperti apa adanya, dan menerapkan versi baru metode tersebut. Anda membuat file konfigurasi OpenAPI lain untuk versi 2.0, dan mengonfigurasi versi baru untuk ditayangkan dari my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. File konfigurasi OpenAPI asli Anda masih mengarah ke metode versi lama, sedangkan file konfigurasi OpenAPI baru mengarah ke metode versi baru.
Anda men-deploy file konfigurasi OpenAPI versi 1 dan versi 2 secara bersamaan, dan men-deploy ulang backend, yang kini berisi kedua versi metode tersebut. (Lihat Pembuatan versi API untuk mengetahui detailnya.)
Setelah Anda men-deploy, Endpoints > Services akan menunjukkan bahwa Anda menayangkan dua versi API, dan Anda dapat melihat jumlah traffic yang diperoleh setiap versi. Klien v1 Anda dapat terus memanggil /v1, tetapi juga dapat memanggil
/v2 untuk menggunakan metode versi baru. Cara Anda menangani pembuatan versi dalam
kode backend bergantung pada framework API yang Anda gunakan. Untuk contoh penggunaan
servlet, lihat
Contoh Endpoint & Java dengan beberapa versi.
Menonaktifkan versi 1
Seiring waktu, saat klien bermigrasi dan Anda melihat bahwa semua traffic ke v1 telah berhenti, Anda dapat berhenti menayangkannya. Untuk menghapus API versi 1, deploy hanya file konfigurasi OpenAPI versi 2 dan deploy ulang backend. Sekarang Anda dapat menghapus kode yang menerapkan versi 1 dari backend dengan aman. Endpoints > Services mempertahankan data historis dari versi 1.x.
Layanan staging
Sebagai praktik terbaik, sebaiknya Anda melakukan staging update ke layanan Endpoints agar dapat menguji layanan sebelum menjangkau pelanggan. Sebaiknya buat projectGoogle Cloud terpisah untuk melakukan staging layanan, sehingga terisolasi dari produksi. Misalnya, kuota Google umumnya dibagikan oleh resource dalam project. Dengan demikian, jika Anda menempatkan layanan staging dalam project yang sama dengan layanan produksi, loop for yang salah, misalnya, dapat menyebabkan pemadaman layanan produksi.
Sebaiknya Anda membuat Google Cloud nama project yang secara jelas
menunjukkan bahwa project tersebut untuk staging. Strategi penamaan yang umum adalah menggunakan nama yang sama dengan
nama project Google Cloud produksi Anda, tetapi dengan -staging di bagian akhir.
Anda juga dapat menempatkan -prod pada project produksi untuk memperjelas bahwa project tersebut memiliki layanan produksi.
Nama layanan di Google Cloud harus unik. Karena Anda menentukan nama layanan dalam file konfigurasi OpenAPI, Anda harus mempertahankan file konfigurasi API terpisah untuk project staging dan produksi, atau menggunakan satu kumpulan file konfigurasi API dan membuat proses untuk mengubah nama layanan agar cocok dengan nama project yang Anda deploy.