Panduan penerapan versi Compute Engine: API, library klien, dan alat

Panduan ini menjelaskan cara Compute Engine mengelola versi di seluruh REST API, library klien, dan alat command line gcloud. Dokumen ini menjelaskan perbedaan antara pembuatan versi berbasis saluran (CBV) dan pembuatan versi berbasis antarmuka (IBV), dengan berfokus terutama pada IBV.

Sebelum memulai

  • Siapkan autentikasi jika Anda belum melakukannya. Autentikasi memverifikasi identitas Anda untuk mengakses layanan Google Cloud dan API. Untuk menjalankan kode atau sampel dari lingkungan pengembangan lokal, Anda dapat melakukan autentikasi ke Compute Engine dengan memilih salah satu opsi berikut:

    Pilih tab untuk melihat bagaimana Anda berencana menggunakan contoh di halaman ini:

    Konsol

    Saat menggunakan konsol Google Cloud untuk mengakses layanan Google Cloud dan API, Anda tidak perlu menyiapkan autentikasi.

    gcloud

    1. Instal Google Cloud CLI. Setelah penginstalan, inisialisasi Google Cloud CLI dengan menjalankan perintah berikut: 

      gcloud init

      Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  • Tetapkan region dan zona default.

    • REST

    Untuk menggunakan contoh REST API di halaman ini dalam lingkungan pengembangan lokal, gunakan kredensial yang Anda berikan ke gcloud CLI.

      Instal Google Cloud CLI.

      Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

    Untuk mengetahui informasi selengkapnya, lihat Melakukan autentikasi untuk menggunakan REST dalam dokumentasi autentikasi Google Cloud .

Pembuatan versi berbasis saluran dan pembuatan versi berbasis antarmuka

Compute Engine API mendukung dua skema pembuatan versi: pembuatan versi berbasis saluran (CBV) dan pembuatan versi berbasis antarmuka (IBV).

  • Dalam pembuatan versi berbasis saluran, rilis bersifat jangka panjang dan menerima update di tempat. Compute Engine mendukung saluran v1, beta, dan alfa.

  • Dalam pembuatan versi berbasis antarmuka, setiap antarmuka, metode, dan resource dibuat versinya, dan dapat berkembang secara inkremental dan independen.

IBV menggantikan CBV. Namun, penerapan CBV yang ada tidak terpengaruh oleh pengenalan IBV dan oleh versi baru. Anda dapat terus menggunakan CBV jika lebih memilih untuk tetap menggunakan rilis API yang ada.

IBV membantu Anda memercayai bahwa perilaku API, serta payload permintaan dan responsnya, sesuai dengan versi API yang dimaksud. Anda menggunakan IBV dengan menentukan versi API dalam permintaan, menggunakan parameter kueri atau header. Untuk mengetahui informasi selengkapnya, lihat Membuat permintaan API.

Menggunakan IBV memberikan manfaat berikut:

  • Peningkatan stabilitas: IBV melindungi aplikasi yang sedang berjalan dari perubahan dengan memungkinkan Anda menunjukkan versi API yang harus digunakan layanan untuk merespons.
  • Kontrol atas penerapan perubahan: dengan IBV, Anda memilih versi yang melayani permintaan Anda. Dengan demikian, Anda dapat mengupgrade ke fitur layanan baru sesuai jadwal Anda sendiri.

Untuk mengetahui informasi selengkapnya tentang strategi penetapan versi, lihat Proposal peningkatan API 185.

Kebijakan pembuatan versi berbasis antarmuka

Setiap rilis Compute Engine IBV API adalah kumpulan perubahan antarmuka yang menggunakan versi layanan yang sama, meskipun antarmuka dapat mengubah versi secara independen.

API IBV Compute Engine mendukung versi stabil dan pratinjau.

Versi stabil

Sebagian besar rilis API adalah versi stabil. Versi stabil mempertahankan kompatibilitas yang ketat seperti yang ditentukan dalam AIP-180, yang berarti rilis stabil yang lebih baru dari versi yang sama tidak merusak fungsi yang ada atau memerlukan penulisan ulang kode.

Compute Engine mengidentifikasi versi API stabil menggunakan tanggal standar dalam format YYYY-MM-DD (seperti 2026-09-01). Tanggal yang lebih baru menunjukkan rilis yang lebih baru.

Compute Engine mendukung versi stabil dalam jangka waktu yang lama sehingga sistem produksi Anda tetap andal dan tidak terganggu. Untuk sebagian besar aplikasi, Anda hanya perlu menggunakan satu versi stabil untuk melakukan tugas harian.

Versi pratinjau

Compute Engine dapat merilis versi pratinjau untuk mengumpulkan masukan awal pengguna tentang fitur baru. Rilis pratinjau menambahkan tag -preview ke tanggal (seperti 2026-10-01-preview).

Versi pratinjau mencakup semua kemampuan dari rilis stabil terbaru, ditambah fitur eksperimental yang baru ditambahkan. Perhatikan hal-hal berikut saat menggunakan versi pratinjau:

  • Fitur pratinjau tidak menjamin kompatibilitas dengan rilis sebelumnya atau mendatang.
  • Sebaiknya jangan gunakan versi pratinjau untuk lingkungan produksi yang sangat penting.
  • Kami dapat mengubah, menyempurnakan, atau menghapus fitur pratinjau saat mempromosikannya ke rilis stabil.

Gunakan versi pratinjau saat Anda ingin bereksperimen dengan kemampuan baru, dan berencana untuk mengupdate kode saat versi stabil diluncurkan.

Menentukan versi API dalam permintaan

Untuk membuat panggilan API menggunakan IBV, permintaan Anda menentukan versi target menggunakan parameter kueri atau header. Untuk contoh cara membuat permintaan API, lihat Membuat permintaan API.

Library Klien Cloud

Library Klien Cloud menghilangkan beban membangun dan mengurai panggilan REST mentah. Setiap rilis library terhubung langsung ke versi API berbasis tanggal tertentu.

Untuk mengakses fitur baru, update paket Library Klien Cloud Anda ke rilis terbaru. Kami memublikasikan Library Klien Cloud yang diupdate bersama dengan rilis API baru yang stabil dan pratinjau.

Sebaiknya jalankan aplikasi produksi di Library Klien Cloud yang stabil, sambil mengisolasi library pratinjau ke lingkungan pengujian.

Google Cloud CLI (gcloud)

Dengan CLI gcloud, Anda dapat mengelola resource Compute Engine tanpa harus melacak setiap endpoint REST secara manual.

CLI gcloud membagi perintah menjadi dua kategori:

  • Perintah stabil: perintah standar (seperti gcloud compute instances create) menargetkan versi API stabil. Perintah ini didukung sepenuhnya, dapat diprediksi, dan direkomendasikan untuk skrip produksi.
  • Perintah pratinjau: fitur akses awal menggunakan grup gcloud preview (seperti gcloud preview compute ...). Perintah ini menampilkan peringatan singkat karena kontrak dapat berubah sebelum rilis final.

Terraform

Penyedia Terraform Google Cloud mengabstraksi pembuatan versi API dan mengelola interaksi API yang mendasarinya. Konfigurasi Terraform tidak mengekspos atau memerlukan setelan header versi manual.

Untuk mengakses fitur baru, update Penyedia Terraform Google Cloud Anda ke rilis terbaru. Untuk fitur pratinjau, gunakan penyedia google-beta.

Pertanyaan umum (FAQ)

Bagian ini menjawab pertanyaan umum (FAQ) tentang pemberian versi API Compute Engine.

  • Apakah saya harus bermigrasi dari v1 (CBV) ke IBV?

    Tidak, permintaan CBV v1 API yang ada akan terus berfungsi seperti sebelumnya. Namun, Anda tidak akan dapat mengakses fitur baru yang tersedia di IBV API.

  • Berapa lama versi IBV API akan didukung?

    Versi stabil dipertahankan selamanya berdasarkan kebijakan penghentian layanan standar Google Cloud.

  • Seberapa sering versi IBV API baru dirilis?

    Versi IBV API baru direncanakan dengan rilis per kuartal. Versi pratinjau dapat dirilis kapan saja.

  • Apakah saya perlu mengaktifkan sesuatu di konsol Google Cloud ?

    Tidak, IBV API diaktifkan secara default dengan Compute Engine API.

  • Apa yang terjadi jika saya tidak menentukan versi dalam permintaan saya?

    Permintaan Anda secara default menggunakan endpoint CBV v1.

  • Di mana saya dapat menemukan versi API dalam entri Cloud Audit Logs?

    Versi API dicatat dalam log di protoPayload.requestMetadata.callerSuppliedUserAgent dan di header permintaan atau parameter kueri.

Langkah berikutnya

Untuk mempelajari lebih lanjut Compute Engine API, baca dokumen berikut: