Pembuatan Versi

Beberapa API Profil Bisnis tersedia dalam lebih dari satu versi dan saluran rilis. Versi adalah segmen URL permintaan yang mengikuti nama host, seperti v1 atau v1alpha. Halaman ini menjelaskan cara penomoran versi, tingkat stabilitas setiap saluran rilis, dan cara memanggil saluran alfa.

Penomoran versi

Setiap versi API memiliki nomor versi utama dan akhiran saluran opsional:

  • Versi utama (v1, v2, ...): Versi stabil yang tersedia secara umum. Versi utama hanya menerima perubahan yang kompatibel dengan versi lama, seperti metode baru, kolom baru, atau nilai enum baru. Perubahan yang tidak kompatibel dengan versi lama akan dirilis dalam versi utama baru.
  • Saluran alfa (v1alpha, v2alpha, ...): Saluran pra-rilis dari versi utama. Versi ini mencakup semua fitur dalam versi utama tersebut, ditambah fitur yang belum mencapai ketersediaan umum.

Saluran rilis

Saluran Stabilitas Daftar Isi
Ketersediaan umum (v1) Stabil. Perubahan dalam versi utama kompatibel dengan versi lama. Jika versi utama tidak digunakan lagi, versi tersebut akan tetap tersedia setidaknya selama 12 bulan setelah pengumuman penghentian penggunaan. Tanggal penghentian penggunaan dan penghentian dipublikasikan di halaman Jadwal penghentian penggunaan. Fitur yang tersedia secara umum.
Alfa (v1alpha) Pra-rilis, tanpa komitmen stabilitas dan tanpa masa aktif yang ditentukan. Fitur alfa dapat berubah atau dihentikan dengan pemberitahuan minimal 30 hari. Jangan gunakan fitur alfa dalam integrasi produksi. Semua yang ada di v1, ditambah fitur yang belum mencapai ketersediaan umum.

Cara fitur berpindah antar-saluran

Saat fitur lulus dari v1alpha ke v1, fitur tersebut tetap tersedia di v1alpha.

Panduan dan halaman referensi untuk fitur yang hanya tersedia di v1alpha ditandai sebagai alfa. Fitur alfa dan fitur yang tersedia secara umum yang baru, serta perubahan atau penghapusan fitur alfa, diumumkan di Update terbaru dan di log perubahan untuk setiap API.

Menggunakan saluran alfa

Untuk memanggil saluran alfa, ganti v1 dengan v1alpha di URL permintaan. Contoh:

GET https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}?readMask={readMask}

Kedua saluran tersebut termasuk dalam API yang sama, sehingga memiliki kesamaan berikut:

  • Pengaktifan API di Konsol Google Cloud.
  • Cakupan OAuth 2.0 dan persyaratan akses.
  • Nama resource, seperti locations/{locationId}.
  • Kuota. Permintaan ke v1 dan v1alpha mengurangi kuota per project yang sama. Untuk mengetahui detailnya, lihat Batas kuota.
  • Data bisnis pokok. Perubahan yang Anda buat melalui v1alpha akan terlihat melalui v1, dan sebaliknya.

Library klien dan direktori API publik hanya menyertakan v1. Untuk memanggil v1alpha, kirim permintaan REST secara langsung.

Praktik terbaik

  • Gunakan versi stabil, seperti v1, untuk integrasi produksi.
  • Gunakan saluran alfa, seperti v1alpha, untuk mengadopsi fitur baru sebelum fitur tersebut mencapai ketersediaan umum. Untuk memberikan masukan, lihat Dukungan.
  • Buat klien Anda menoleransi kolom dan nilai enum yang tidak dikenali.
  • Sebelum Anda membangun fitur alfa, periksa panduan dan log perubahannya untuk mengetahui batasan yang diketahui.