Lập phiên bản

Một số API Trang doanh nghiệp có nhiều phiên bản và kênh phát hành. Phiên bản là phân đoạn của URL yêu cầu theo sau tên máy chủ, chẳng hạn như v1 hoặc v1alpha. Trang này giải thích cách đánh số phiên bản, mức độ ổn định của từng kênh phát hành và cách gọi kênh alpha.

Đánh số phiên bản

Mỗi phiên bản API đều có một số phiên bản lớn và một hậu tố kênh không bắt buộc:

  • Phiên bản chính (v1, v2, ...): Phiên bản ổn định, được cung cấp rộng rãi. Phiên bản lớn chỉ nhận được các thay đổi tương thích ngược, chẳng hạn như các phương thức mới, trường mới hoặc giá trị enum mới. Những thay đổi không có khả năng tương thích ngược sẽ được phát hành trong một phiên bản lớn mới.
  • Kênh Alpha (v1alpha, v2alpha, ...): Kênh phát hành trước của một phiên bản chính. Kênh này bao gồm mọi tính năng trong phiên bản lớn đó, cộng với các tính năng chưa đạt đến giai đoạn phát hành rộng rãi.

Kênh phát hành

Kênh Độ ổn định Nội dung
Giai đoạn phát hành rộng rãi (v1) Ổn định. Các thay đổi trong một phiên bản lớn đều có khả năng tương thích ngược. Khi một phiên bản lớn không còn được dùng nữa, phiên bản đó vẫn được cung cấp trong ít nhất 12 tháng sau thông báo ngừng sử dụng. Ngày ngừng sử dụng và ngày ngừng cung cấp được công bố trên trang Lịch ngừng sử dụng. Các tính năng được phát hành rộng rãi.
Alpha (v1alpha) Bản phát hành trước, không có cam kết về độ ổn định và không có thời hạn sử dụng xác định. Các tính năng alpha có thể thay đổi hoặc ngừng cung cấp sau khi chúng tôi thông báo trước ít nhất 30 ngày. Đừng sử dụng các tính năng ở giai đoạn alpha trong quá trình tích hợp chính thức. Mọi tính năng trong v1, cộng với các tính năng chưa được phát hành rộng rãi.

Cách các tính năng di chuyển giữa các kênh

Khi một tính năng chuyển từ v1alpha sang v1, tính năng đó vẫn có trong v1alpha.

Hướng dẫn và trang tham khảo cho các tính năng chỉ có trong v1alpha được đánh dấu là alpha. Các tính năng mới ở giai đoạn alpha và giai đoạn phát hành rộng rãi, cũng như các thay đổi hoặc việc xoá tính năng ở giai đoạn alpha, sẽ được thông báo trong phần Thông tin cập nhật mới nhất và trong nhật ký thay đổi của từng API.

Sử dụng kênh alpha

Để gọi kênh alpha, hãy thay thế v1 bằng v1alpha trong URL yêu cầu. Ví dụ:

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

Cả hai kênh đều thuộc cùng một API, vì vậy, chúng có chung những điểm sau:

  • Bật API trong Google Cloud Console.
  • Phạm vi OAuth 2.0 và các yêu cầu về quyền truy cập.
  • Tên tài nguyên, chẳng hạn như locations/{locationId}.
  • Hạn mức. Các yêu cầu gửi đến v1 và v1alpha đều được tính vào cùng một hạn mức cho mỗi dự án. Để biết thông tin chi tiết, hãy xem phần Giới hạn về hạn mức.
  • Dữ liệu doanh nghiệp cơ bản. Những thay đổi mà bạn thực hiện thông qua v1alpha sẽ xuất hiện trong v1 và ngược lại.

Thư viện ứng dụng và thư mục API công khai chỉ bao gồm v1. Để gọi v1alpha, hãy gửi trực tiếp các yêu cầu REST.

Các phương pháp hay nhất

  • Sử dụng phiên bản ổn định, chẳng hạn như v1, cho các hoạt động tích hợp chính thức.
  • Sử dụng kênh alpha, chẳng hạn như v1alpha, để áp dụng các tính năng mới trước khi chúng đạt giai đoạn phát hành rộng rãi. Để chia sẻ ý kiến phản hồi, hãy xem phần Hỗ trợ.
  • Hãy đảm bảo ứng dụng của bạn chấp nhận các trường và giá trị enum mà ứng dụng không nhận dạng được.
  • Trước khi xây dựng dựa trên một tính năng ở giai đoạn alpha, hãy xem hướng dẫn và nhật ký thay đổi của tính năng đó để biết các hạn chế đã biết.