API ของ Business Profile บางรายการมีให้บริการมากกว่า 1 เวอร์ชันและเวอร์ชันการเผยแพร่ เวอร์ชันคือส่วนของ URL คำขอที่ตามหลังชื่อโฮสต์ เช่น v1 หรือ v1alpha หน้านี้จะอธิบายวิธีระบุหมายเลขเวอร์ชัน ความเสถียรของเวอร์ชันการเผยแพร่แต่ละเวอร์ชัน และวิธีเรียกใช้เวอร์ชันอัลฟ่า
การกำหนดหมายเลขเวอร์ชัน
API แต่ละเวอร์ชันจะมีหมายเลขเวอร์ชันหลักและคำต่อท้ายช่องทาง (ไม่บังคับ) ดังนี้
- เวอร์ชันหลัก (
v1,v2, ...): เวอร์ชันที่เสถียรและพร้อมใช้งานโดยทั่วไป เวอร์ชันหลักจะได้รับการเปลี่ยนแปลงที่เข้ากันได้แบบย้อนหลังเท่านั้น เช่น เมธอดใหม่ ฟิลด์ใหม่ หรือค่า enum ใหม่ การเปลี่ยนแปลงที่เข้ากันไม่ได้แบบย้อนหลังจะเผยแพร่ในเวอร์ชันหลักใหม่ - เวอร์ชันอัลฟ่า (
v1alpha,v2alpha, ...): เวอร์ชันก่อนเผยแพร่ของเวอร์ชันหลัก ซึ่งรวมถึงทุกอย่างในเวอร์ชันหลักนั้น พร้อมด้วยฟีเจอร์ที่ยังไม่พร้อมให้บริการในเวอร์ชันสำหรับผู้ใช้ทั่วไป
เวอร์ชันการเผยแพร่
| ช่อง | ความเสถียร | เนื้อหา |
|---|---|---|
เวอร์ชันสำหรับผู้ใช้ทั่วไป (v1) |
เสถียร การเปลี่ยนแปลงภายในเวอร์ชันหลักจะเข้ากันได้แบบย้อนหลัง เมื่อเลิกใช้งานเวอร์ชันหลักแล้ว เวอร์ชันดังกล่าวจะยังคงใช้งานได้เป็นเวลาอย่างน้อย 12 เดือนหลังจากประกาศการเลิกใช้งาน วันที่เลิกใช้งานและวันที่สิ้นสุดจะเผยแพร่ในหน้ากำหนดการเลิกใช้งาน | ฟีเจอร์สำหรับผู้ใช้ทั่วไป |
อัลฟ่า (v1alpha) |
รุ่นทดลอง โดยไม่มีความมุ่งมั่นด้านความเสถียรและไม่มีอายุการใช้งานที่กำหนดไว้ ฟีเจอร์เวอร์ชันอัลฟ่าอาจมีการเปลี่ยนแปลงหรือปิดให้บริการโดยมีการแจ้งให้ทราบล่วงหน้าอย่างน้อย 30 วัน อย่าใช้ฟีเจอร์เวอร์ชันอัลฟ่าในการผสานรวมเวอร์ชันที่ใช้งานจริง | ทุกอย่างใน v1 รวมถึงฟีเจอร์ที่ยังไม่พร้อมให้บริการแก่ผู้ใช้ทั่วไป |
การย้ายฟีเจอร์ระหว่างช่องทางต่างๆ
เมื่อฟีเจอร์เปลี่ยนสถานะจาก v1alpha เป็น v1 ฟีเจอร์ดังกล่าวจะยังคงพร้อมใช้งานใน v1alpha
คู่มือและหน้าข้อมูลอ้างอิงสำหรับฟีเจอร์ที่พร้อมใช้งานใน v1alpha เท่านั้นจะทำเครื่องหมายเป็นอัลฟ่า เราจะประกาศฟีเจอร์เวอร์ชันอัลฟ่าและฟีเจอร์เวอร์ชันสำหรับผู้ใช้ทั่วไปใหม่ รวมถึงการเปลี่ยนแปลงหรือการนำฟีเจอร์เวอร์ชันอัลฟ่าออกในข้อมูลอัปเดตล่าสุดและในบันทึกการเปลี่ยนแปลงของ API แต่ละรายการ
ใช้ช่องอัลฟ่า
หากต้องการเรียกช่องทางอัลฟ่า ให้แทนที่ v1 ด้วย v1alpha ใน URL คำขอ เช่น
GET https://mybusinessbusinessinformation.googleapis.com/v1alpha/locations/{locationId}?readMask={readMask}
ทั้ง 2 ช่องทางเป็นของ API เดียวกัน จึงใช้ข้อมูลต่อไปนี้ร่วมกัน
- การเปิดใช้ API ในคอนโซล Google Cloud
- ขอบเขต OAuth 2.0 และข้อกำหนดในการเข้าถึง
- ชื่อทรัพยากร เช่น
locations/{locationId} - โควต้า คำขอไปยัง
v1และv1alphaจะนับรวมในโควต้าต่อโปรเจ็กต์เดียวกัน โปรดดูรายละเอียดที่หัวข้อขีดจำกัดโควต้า - ข้อมูลธุรกิจที่สำคัญ การเปลี่ยนแปลงที่คุณทำผ่าน
v1alphaจะปรากฏในv1และในทางกลับกัน
ไลบรารีของไคลเอ็นต์และไดเรกทอรี API สาธารณะจะมีเฉพาะ v1 เท่านั้น หากต้องการเรียกใช้ v1alpha ให้ส่งคำขอ REST โดยตรง
แนวทางปฏิบัติแนะนำ
- ใช้เวอร์ชันเสถียร เช่น
v1สำหรับการผสานรวมเวอร์ชันที่ใช้งานจริง - ใช้ช่องทางอัลฟ่า เช่น
v1alphaเพื่อใช้ฟีเจอร์ใหม่ก่อนที่จะเปิดให้ใช้งานในเวอร์ชันสำหรับผู้ใช้ทั่วไป หากต้องการแชร์ความคิดเห็น โปรดดูที่การสนับสนุน - ทำให้ไคลเอ็นต์ยอมรับฟิลด์และค่า enum ที่ไม่รู้จัก
- ก่อนที่จะสร้างฟีเจอร์เวอร์ชันอัลฟ่า โปรดดูคำแนะนำและบันทึกการเปลี่ยนแปลงเพื่อดูข้อจำกัดที่ทราบ