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

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

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

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

  • ลงทะเบียนนักพัฒนา API อย่างน้อย 1 รายแบบครั้งเดียวเพื่อใช้ Merchant API: คุณจะต้องเรียกใช้เมธอด registerGcp (เพียงครั้งเดียวสำหรับแต่ละโปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google ที่ใช้สำหรับการ ตรวจสอบสิทธิ์) เพื่อระบุข้อมูลติดต่อ ซึ่งจะช่วยให้คุณใช้ 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 เพื่อเพิ่มผู้ดูแลระบบเริ่มต้นลงในบัญชี