ย้ายข้อมูลจาก v1beta เป็น v1

คำแนะนำนี้จะช่วยคุณย้ายข้อมูลจาก Merchant API v1beta ไปยัง v1 ซึ่งเป็นเวอร์ชันแรก ที่พร้อมให้บริการแก่บุคคลทั่วไป เวอร์ชัน v1 มีการอัปเดตหลายอย่างและ การเปลี่ยนแปลงบางอย่างที่อาจต้องมีการอัปเดตโค้ด การเปลี่ยนแปลงเหล่านี้มีจุดประสงค์เพื่อ ลดความซับซ้อนของ API และปรับปรุงการจัดการบัญชี Merchant Center

ความแตกต่างที่สำคัญ

การเปลี่ยนแปลงที่สำคัญที่สุดซึ่งคุณควรทราบเมื่อย้ายข้อมูลจาก v1beta ไป v1 มีดังนี้

• ลงทะเบียนนักพัฒนา API อย่างน้อย 1 รายแบบครั้งเดียวเพื่อใช้ Merchant API: คุณจะต้องเรียกใช้เมธอด registerGcp (เพียงครั้งเดียวสำหรับแต่ละโปรเจ็กต์ Google Cloud ที่ใช้สำหรับการ ตรวจสอบสิทธิ์) เพื่อระบุรายละเอียดการติดต่อ ซึ่งจะช่วยให้คุณใช้ API และรับข้อมูลอัปเดตและประกาศที่เกี่ยวข้องกับ Merchant API ได้ คุณจะใช้ API ของ v1 หรือ v1alpha ไม่ได้จนกว่าจะทำขั้นตอนนี้เสร็จสมบูรณ์ ดูวิธีการได้ที่หัวข้อลงทะเบียนในฐานะนักพัฒนาแอป

• การเข้ารหัสชื่อผลิตภัณฑ์: ฟิลด์ ProductInput.name และ Product.name รองรับการเข้ารหัส base64url แบบไม่มีการเพิ่มแพด (RFC 4648 ส่วนที่ 5) ทำตามหลักเกณฑ์ต่อไปนี้

  • สตริงต้องเป็นไปตามcontentLanguage~feedLabel~offerIdรูปแบบก่อนการเข้ารหัส

  • การเข้ารหัสเป็นข้อกำหนดหากชื่อผลิตภัณฑ์มีอักขระที่ใช้โดย Merchant API หรืออักขระที่สงวนไว้สำหรับ URL เช่น

    % . + / : ~ , ( * ! ) & ? = @ # $
    

  • หากชื่อผลิตภัณฑ์เป็นไปตามcontentLanguage~feedLabel~offerId รูปแบบและไม่มีอักขระใดๆ ที่ใช้โดย Merchant API หรือ อักขระที่สงวนไว้สำหรับ URL คุณอาจใช้รูปแบบธรรมดาโดยไม่ต้องเข้ารหัส

  • เราขอแนะนำให้ใช้การเข้ารหัส base64url ที่ไม่มีการเพิ่ม Padding สำหรับชื่อผลิตภัณฑ์ทั้งหมดเพื่อให้การแยกวิเคราะห์สอดคล้องและถูกต้อง

• การนำข้อมูลภาษีระดับผลิตภัณฑ์ออก: taxes และ taxCategory

• Product.attributes เปลี่ยนชื่อแล้ว: เปลี่ยนชื่อฟิลด์ Product.attributes เป็น Product.productAttributes แล้ว

• การนำข้อมูลภาษีระดับผลิตภัณฑ์ออก: ระบบได้นำฟิลด์ taxes และ taxCategory ออกจากออบเจ็กต์ Product.productAttributes แล้ว ดูข้อมูลเพิ่มเติมได้ที่บทความช่วยเหลือของ Google Merchant Center เกี่ยวกับภาษี

• การเปลี่ยนแปลงฟิลด์ GTIN: ฟิลด์ gtin ในออบเจ็กต์ Product.productAttributes เปลี่ยนชื่อเป็น gtins เพื่อให้สะท้อนว่าฟิลด์นี้สามารถมีค่าได้หลายค่าได้ดียิ่งขึ้น ตอนนี้ฟิลด์ gtin ในออบเจ็กต์ OrderTrackingSignals.lineItemDetails เป็น array และมีการเปลี่ยนชื่อเป็น gtins ด้วย

• การนำช่องทางออก: ระบบได้นำช่อง channel ออกจาก ผลิตภัณฑ์ ข้อมูลผลิตภัณฑ์ และแหล่งข้อมูล เราได้เพิ่มฟิลด์บูลีนใหม่ legacyLocal เพื่อระบุผลิตภัณฑ์ที่ขายเฉพาะในร้านค้าจริงอย่างชัดเจน หมายเหตุ: ฟิลด์ legacyLocal เป็นฟิลด์เสริมที่จะช่วยในการ ย้ายข้อมูล และจะเลิกใช้งานในที่สุดเมื่อกำหนดเป้าหมายวิธีการทางการตลาดออนไลน์และในร้าน ได้อย่างเต็มที่ด้วยแหล่งที่มาของผลิตภัณฑ์เดียว ดูข้อมูลเพิ่มเติมได้ในตาราง ในส่วนต่อไปนี้

• ฟิลด์ใหม่สำหรับแอตทริบิวต์สินค้าคงคลังระดับภูมิภาคและระดับท้องถิ่น:

  • ฟิลด์ RegionalInventory ทั้งหมดยกเว้น name, account และ region จะรวมอยู่ภายใต้ออบเจ็กต์ใหม่ที่ชื่อ regionalInventoryAttributes เช่น ตอนนี้แอตทริบิวต์ RegionalInventory.price อยู่ในส่วน RegionalInventory.regionalInventoryAttributes.price
  • ฟิลด์ LocalInventory ทั้งหมดยกเว้น name, account และ storeCode จะรวมอยู่ภายใต้ออบเจ็กต์ใหม่ที่ชื่อ localInventoryAttributes เช่น ตอนนี้แอตทริบิวต์ LocalInventory.price อยู่ในส่วน LocalInventory.localInventoryAttributes.price

• การนำ customAttributes ออกจากสินค้าคงคลังระดับภูมิภาคและระดับท้องถิ่น: ระบบได้นำฟิลด์ customAttributes ออกจากทั้งทรัพยากร RegionalInventory และ LocalInventory แล้ว

• การสร้างบัญชีที่ปรับปรุงแล้ว: เราได้นำฟิลด์ users ที่ซ้ำซ้อนออก จาก CreateAndConfigureAccountRequest แล้ว ใช้ฟิลด์ user รายการเดียว เพื่อเชื่อมโยงผู้ใช้เริ่มต้นกับบัญชีใหม่

• มีการเปลี่ยนแอตทริบิวต์บางประเภทจากสตริงเป็น Enum: ฟิลด์บางรายการ ภายในทรัพยากร Product และ Inventory ที่มีรายการค่าแบบย่อที่กำหนดไว้ได้เปลี่ยนจากประเภท string เป็นประเภท enum เพื่อการตรวจสอบข้อมูลที่ดีขึ้น (เช่น ฟิลด์ Product.ProductAttributes.condition ตอนนี้เป็น enum แล้ว)

• การนำวิธีการอัปเดตนโยบายคืนสินค้าออนไลน์ออก: เราได้นำวิธีการ onlineReturnPolicy.update ออกในv1 สร้างนโยบายการคืนสินค้าออนไลน์โดยใช้วิธีonlineReturnPolicy.create แทน

วิธีย้ายข้อมูล

เรามีกำหนดการที่จะหยุดให้บริการ Merchant API เวอร์ชัน v1beta ในวันที่ 28 กุมภาพันธ์ 2026 ดูข้อมูลเพิ่มเติมเกี่ยวกับกำหนดการเลิกใช้งานได้ที่คู่มือการควบคุมเวอร์ชัน Merchant API

• ขั้นตอนแรกในการย้ายข้อมูลคือการลงทะเบียนนักพัฒนาแอปแบบครั้งเดียว (ดูลงทะเบียนเป็นนักพัฒนาแอป) คุณต้องเรียกใช้เมธอด registerGcp สำหรับโปรเจ็กต์ Google Cloud แต่ละโปรเจ็กต์ที่คุณใช้ สำหรับการตรวจสอบสิทธิ์ก่อนที่เมธอด v1 จะทำงาน

• ไม่ว่าคุณจะเรียกใช้ API ด้วยวิธีใด (ด้วย REST, gRPC หรือโดยใช้ไลบรารี ไคลเอ็นต์) คุณก็สามารถย้ายข้อมูลเป็นระยะๆ ได้ ซึ่งหมายความว่าคุณสามารถอัปเดตและย้ายข้อมูลโค้ดทีละ API ได้ (เช่น ย้าย Products API ไปยัง v1 ขณะที่ยังคงใช้ Accounts API ใน v1beta) โดยไม่ต้องอัปเดตการผสานรวมทั้งหมดพร้อมกัน

การเปลี่ยนแปลงฟิลด์โดยละเอียด

ตารางนี้แสดงการเปรียบเทียบโดยละเอียดของฟิลด์ที่มีการเปลี่ยนแปลง ระหว่างเวอร์ชัน v1beta และ v1

v1beta	v1	คำอธิบาย
ProductInput.name	ProductInput.name	Unpadded base64url encoding รองรับและต้องระบุสำหรับ ชื่อผลิตภัณฑ์ที่มีอักขระที่ใช้โดย Merchant API หรืออักขระที่สงวนไว้สำหรับ URL
Product.name	Product.name	Unpadded base64url encoding รองรับและต้องระบุสำหรับ ชื่อผลิตภัณฑ์ที่มีอักขระที่ใช้โดย Merchant API หรืออักขระที่สงวนไว้สำหรับ URL
Product.gtin	Product.gtins	มีการเปลี่ยนชื่อฟิลด์สำหรับ GTIN
Product.taxes	นำออกแล้ว	ระบบได้นำช่อง taxes ออกแล้ว
Product.taxCategory	นำออกแล้ว	ระบบได้นำช่อง taxCategory ออกแล้ว
Product.channel	นำออกแล้ว	นำช่อง channel ออกแล้ว ใช้ฟิลด์ legacyLocal สำหรับกรณีการใช้งานในพื้นที่
Product.attributes	Product.productAttributes	เปลี่ยนชื่อฟิลด์ attributes เป็น productAttributes แล้ว
availability, condition, gender, includedDestinations และ excludedDestinations ในช่อง Product จะแสดงเป็น strings (หรือ array ของ strings)	ตอนนี้ฟิลด์เหล่านี้เป็น enums (หรือ array ของ enums)	เปลี่ยนฟิลด์ที่มีรายการค่าแบบย่อที่กำหนดจากประเภท string เป็น enum
price, salePrice, salePriceEffectiveDate และ availability ใน RegionalInventory	ย้ายไปยัง RegionalInventory.regionalInventoryAttributes แล้ว	ระบบได้ย้ายช่องเหล่านี้ไปไว้ในส่วนregionalInventoryAttributesแล้ว
ฟิลด์ RegionalInventory.availability คือ string	ตอนนี้ RegionalInventory.regionalInventoryAttributes.availability เป็น enums แล้ว	เปลี่ยนประเภทความพร้อมให้บริการจาก string เป็น enum แล้ว
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla และ instoreProductLocation ใน LocalInventory	ย้ายไปยัง LocalInventory.localInventoryAttributes แล้ว	ระบบได้ย้ายช่องเหล่านี้ไปไว้ในส่วนlocalInventoryAttributesแล้ว
ฟิลด์ LocalInventory.availability คือ string	ตอนนี้ LocalInventory.localInventoryAttributes.availability เป็น enums แล้ว	เปลี่ยนประเภทความพร้อมให้บริการจาก string เป็น enum แล้ว
LocalInventory.customAttributes	นำออกแล้ว	ระบบไม่รองรับแอตทริบิวต์ที่กำหนดเองสำหรับสินค้าคงคลังในร้านอีกต่อไป
RegionalInventory.customAttributes	นำออกแล้ว	ระบบไม่รองรับแอตทริบิวต์ที่กำหนดเองสำหรับสินค้าคงคลังระดับภูมิภาคอีกต่อไป
ProductInput.channel	นำออกแล้ว	นำช่อง channel ออกแล้ว ใช้ฟิลด์ legacyLocal สำหรับกรณีการใช้งานในพื้นที่
DataSource.channel	นำออกแล้ว	นำช่อง channel ออกแล้ว ใช้ฟิลด์ legacyLocal สำหรับกรณีการใช้งานในพื้นที่
ไม่พร้อมใช้งาน	ProductInput.legacyLocal	ฟิลด์บูลีนใหม่เพื่อระบุว่าผลิตภัณฑ์กำหนดเป้าหมายได้เฉพาะวิธีทางการตลาดในพื้นที่ เท่านั้น รหัสทรัพยากรผลิตภัณฑ์จะมีคำนำหน้า "local~"
ไม่พร้อมใช้งาน	Product.legacyLocal	ฟิลด์บูลีนใหม่เพื่อระบุว่าผลิตภัณฑ์ขายเฉพาะในร้านค้าในพื้นที่และไม่พร้อมจำหน่ายทางออนไลน์
ไม่พร้อมใช้งาน	DataSource.legacyLocal	ฟิลด์บูลีนใหม่เพื่อระบุว่าแหล่งข้อมูลมีผลิตภัณฑ์ ที่ขายในร้านค้าในพื้นที่เท่านั้น
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	เปลี่ยนชื่อฟิลด์ gtin เป็น gtins และ ตอนนี้เป็นอาร์เรย์ของสตริง (แทนที่จะเป็นสตริง)
CreateAndConfigureAccountRequest.users	นำออกแล้ว	นำช่อง users ออกแล้ว ใช้ช่อง user เพื่อเพิ่มผู้ดูแลระบบเริ่มต้นลงในบัญชี