Halaman ini menjelaskan fitur pembuatan versi Cloud Endpoints API dan memberikan praktik terbaik untuk pembuatan versi dan 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 seperti yang digunakan Google untuk pembuatan versi API dan staging layanan:
Sertakan baris berikut dalam file konfigurasi OpenAPI Anda sebelum 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 perlu mengubah metode yang ada yang merusak kode klien, buat salinan file konfigurasi OpenAPI, dan 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 sekarang memiliki kedua versi metode tersebut. Lihat Membuat Versi API untuk mengetahui detailnya.
- Tambahkan nomor versi utama (2.0, 3.0, dll.) di kolom
Menerapkan semua versi API utama dalam satu backend. Rekomendasi ini:
- Menyederhanakan pemilihan rute karena permintaan ke versi tertentu didasarkan pada jalur, seperti dalam contoh sebelumnya.
- Menyederhanakan konfigurasi dan deployment. Anda menggunakan project dan backend Google Cloud yang sama untuk semua versi utama API, dan men-deploy semua versi API secara bersamaan.
- Menekan biaya Anda dengan menghindari backend yang berlebihan.
Stage API Anda dalam project Google Cloud yang 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 Endpoint tidak mengharuskan Anda menambah nomor versi patch di file konfigurasi OpenAPI dan men-deploy konfigurasi saat men-deploy perbaikan bug di kode backend, Anda dapat 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 tersebut 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
Dengan begitu, pelanggan dapat memilih versi mana yang ingin digunakan dan mengontrol kapan mereka bermigrasi ke versi baru. ESP memberi tag pada setiap permintaan dengan nomor versi sebelum mengarahkan permintaan ke metode yang berlaku di backend. Karena setiap permintaan diberi tag dengan nomor versi:
Grafik dan log di Endpoint > Layanan menampilkan permintaan dari setiap versi API utama dan total gabungan di semua versi. Anda dapat memfilter tampilan ke versi tertentu. Ini memberi Anda gambaran yang jelas tentang berapa banyak traffic yang didapatkan setiap versi. Log bahkan dapat memberi tahu Anda klien mana yang menggunakan versi tertentu.
Saat Anda men-deploy ulang API dengan pembaruan nomor versi minor, aktivitas berikutnya akan diberi label dengan nomor versi baru di grafik dan log. Halaman ini menyediakan histori deployment yang diberi label.
Saat Anda menghapus versi API, grafik dan log akan terus menampilkan data dalam rentang waktu API aktif.
Contoh siklus proses API
Bagian ini menjelaskan evolusi standar dari suatu layanan.
Versi 1
Awalnya, Anda men-deploy layanan My Awesome Echo API versi 1. API ini disalurkan
dari my-api.endpoints.my‐awesomeproject.cloud.goog/v1/echo. Dalam grafik dan log di Endpoint > Layanan, Anda akan melihat semua traffic di 1.0.
Versi 1.1
Pelanggan Anda meminta fitur baru, jadi Anda menambahkan metode baru. Di file konfigurasi OpenAPI, Anda menambahkan metode baru dan menambahkan kolom info.version ke 1.1. Anda menambahkan nomor versi minor karena perubahan ini tidak merusak kode klien. Anda men-deploy dan menguji perubahan di lingkungan staging untuk memastikannya berfungsi.
Selanjutnya, Anda akan men-deploy konfigurasi OpenAPI dan backend API ke lingkungan produksi. API masih disalurkan 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 Anda tidak perlu mengubah dan men-deploy ulang klien mereka. Klien dapat terus mengirim permintaan ke metode lama dengan cara yang sama seperti sebelumnya.
Di Endpoint > Layanan, traffic yang dilayani kini berada pada versi 1.1. Jika Anda memilih rentang waktu sebelumnya untuk ditampilkan, versi sebelumnya akan ditampilkan dalam grafik dan log, yang menyediakan histori deployment Anda yang diberi label.
Versi 2.0
Seiring waktu, Anda menyadari bahwa Anda perlu membuat perubahan yang tidak kompatibel dengan versi lama pada
metode yang ada. Karena penting untuk tidak merusak kode klien pelanggan, Anda memutuskan untuk mempertahankan dua versi API. Anda membiarkan metode lama
apa adanya, dan menerapkan versi baru metode tersebut. Anda membuat file konfigurasi OpenAPI lain untuk versi 2.0, dan mengonfigurasi versi baru yang akan disalurkan dari my-api.endpoints.my‐awesomeproject.cloud.goog/v2/echo. File konfigurasi OpenAPI asli Anda masih mengarah ke versi lama metode, sedangkan file konfigurasi OpenAPI baru mengarah ke versi baru metode tersebut.
Anda men-deploy file konfigurasi OpenAPI versi 1 dan versi 2 secara bersamaan, dan men-deploy ulang backend, yang sekarang berisi kedua versi metode. (Lihat Membuat Versi API untuk detailnya.)
Setelah melakukan deployment, Endpoint > Layanan akan menunjukkan bahwa Anda menyalurkan dua versi API, dan dapat melihat jumlah traffic yang didapatkan setiap versi. Klien v1 Anda dapat terus memanggil /v1, tetapi juga dapat memanggil /v2 untuk menggunakan versi baru metode. Cara Anda menangani pembuatan versi di
kode backend bergantung pada framework API yang Anda gunakan. Untuk contoh penggunaan
servlet, lihat
Endpoint & Java dengan contoh beberapa versi.
Menonaktifkan versi 1
Pada waktunya, saat klien bermigrasi dan Anda melihat semua traffic ke v1 telah berhenti, Anda dapat berhenti menayangkannya. Untuk menghapus versi 1 API Anda, hanya deploy file konfigurasi OpenAPI versi 2 dan deploy ulang backend. Sekarang Anda dapat dengan aman menghapus kode yang menerapkan versi 1 dari backend Anda. Endpoint > Layanan menyimpan data historis dari versi 1.x.
Layanan Staging
Sebagai praktik terbaik, sebaiknya Anda melakukan update bertahap pada layanan Endpoint sehingga Anda dapat menguji layanan sebelum menjangkau pelanggan. Sebaiknya Anda juga membuat project Google Cloud yang terpisah untuk staging layanan Anda, sehingga terisolasi dari produksi. Misalnya, kuota Google umumnya digunakan bersama oleh resource dalam suatu project. Oleh karena itu, jika Anda menempatkan layanan staging dalam project yang sama dengan layanan produksi, errant for loop dapat menyebabkan pemadaman layanan produksi Anda.
Sebaiknya buat nama project Google Cloud yang dengan jelas menunjukkan nama tersebut untuk staging. Strategi penamaan yang umum adalah menggunakan nama yang sama dengan nama project Google Cloud produksi, tetapi dengan -staging di bagian akhir.
Anda mungkin juga ingin menempatkan -prod pada project produksi untuk memperjelas bahwa project tersebut memegang layanan produksi.
Nama layanan di Google Cloud harus unik. Karena Anda menetapkan nama layanan di file konfigurasi OpenAPI, Anda perlu mengelola file konfigurasi API terpisah untuk project staging dan produksi, atau menggunakan satu set file konfigurasi API dan membuat proses untuk mengubah nama layanan agar cocok dengan nama project yang menjadi tujuan deployment.