Pengelolaan siklus proses API

Halaman ini menjelaskan fitur pembuatan versi Cloud Endpoints API dan memberikan praktik terbaik untuk membuat versi dan melakukan penahapan 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 Anda mengikuti prinsip dasar yang sama yang digunakan Google untuk pembuatan versi API dan penyiapan layanan:

  • Sertakan kode berikut dalam file konfigurasi OpenAPI sebelum Anda men-deploy versi awal:

    • Tetapkan nomor versi di kolom info.version. Sebaiknya gunakan string versi yang mencakup versi utama dan versi minor, misalnya, 1.0.
    • Tetapkan kolom basePath untuk menyertakan nomor versi utama. Sebaiknya gunakan jalur dasar yang diformat sebagai huruf v diikuti dengan nomor versi utama, misalnya, /v1.

  • Saat Anda perlu membuat perubahan yang kompatibel dengan versi sebelumnya, seperti menambahkan metode baru, naikkan nomor versi minor (1.2, 1.3, dll.) di kolom info.version dan deploy ulang. Lihat Membuat Versi API untuk mengetahui detailnya.

  • Saat Anda perlu membuat perubahan pada metode yang ada yang merusak kode klien, buat salinan file konfigurasi OpenAPI Anda, lalu buat perubahan berikut:

    • Tingkatkan nomor versi utama (2.0, 3.0, dll.) di kolom info.version.
    • Tingkatkan 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.

  • 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 yang sama untuk semua versi utama API, dan Anda men-deploy semua versi API secara bersamaan. Google Cloud
    • Menjaga biaya Anda tetap rendah dengan menghindari menjalankan backend yang tidak diperlukan.

  • Lakukan penyiapan API di project Google Cloud terpisah sebelum men-deploy ke project Google Cloud produksi. Lihat Layanan penyiapan untuk mengetahui detailnya.

Penggunaan nomor versi utama dan versi minor di Endpoint sesuai dengan definisi dalam Pembuatan versi semantik. Meskipun Endpoints tidak mengharuskan Anda menaikkan 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 API Cloud Endpoints

Extensible Service Proxy (ESP) dapat mengelola beberapa versi utama API Anda secara bersamaan dalam satu Google Cloud project dan backend 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

Dengan demikian, pelanggan Anda dapat memilih versi yang ingin mereka gunakan dan mengontrol waktu 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 jumlah traffic yang didapatkan 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 memberi Anda histori berlabel dari deployment Anda.

  • 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 Anda meminta fitur baru, jadi Anda menambahkan metode baru. Dalam file konfigurasi OpenAPI, Anda menambahkan metode baru dan menaikkan kolom info.version menjadi 1.1. Anda menaikkan nomor versi minor karena perubahan ini tidak merusak 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 Anda tidak perlu mengubah dan men-deploy ulang klien mereka; klien dapat terus mengirim permintaan ke metode lama seperti sebelumnya.

Di Endpoints > Services, traffic yang disalurkan kini berada di versi 1.1. Jika Anda memilih rentang waktu yang lebih awal 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 membuat perubahan yang tidak kompatibel dengan versi lama pada metode yang ada. Karena penting agar Anda tidak merusak kode klien pelanggan, Anda memutuskan untuk mempertahankan dua versi API. Anda membiarkan metode lama seperti apa adanya, dan menerapkan metode versi baru. Anda membuat file konfigurasi OpenAPI lain untuk versi 2.0, dan mengonfigurasi versi baru agar ditayangkan 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.

Anda men-deploy file konfigurasi OpenAPI versi 1 dan versi 2 secara bersamaan, lalu men-deploy ulang backend, yang kini berisi kedua versi metode tersebut. (Lihat Membuat Versi API untuk mengetahui detailnya.)

Setelah men-deploy, Endpoints > Services akan menunjukkan bahwa Anda menayangkan dua versi API, dan Anda dapat melihat jumlah traffic yang didapatkan setiap versi. Klien v1 Anda dapat terus memanggil /v1, tetapi mereka juga dapat memanggil /v2 untuk menggunakan versi baru metode ini. 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 Anda melakukan migrasi 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 Anda dengan aman. Endpoints > Services menyimpan data historis dari versi 1.x.

Layanan penataan

Sebagai praktik terbaik, sebaiknya Anda melakukan penahapan update pada layanan Endpoint agar Anda dapat menguji layanan sebelum layanan tersebut menjangkau pelanggan Anda. Sebaiknya buat jugaGoogle Cloud project terpisah untuk melakukan staging layanan Anda, sehingga layanan tersebut 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, misalnya, loop for yang salah dapat menyebabkan gangguan pada layanan produksi Anda.

Sebaiknya buat Google Cloud nama project yang dengan jelas menunjukkan bahwa project tersebut ditujukan untuk staging. Strategi penamaan umum adalah menggunakan nama yang sama dengan nama project produksi Anda, tetapi dengan -staging di akhir. Google Cloud Anda juga dapat menambahkan -prod pada project produksi untuk memperjelas bahwa project tersebut menyimpan 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 set file konfigurasi API dan menyusun proses di mana Anda mengubah nama layanan agar cocok dengan nama project yang Anda deploy.

Langkah berikutnya