การจัดการผลิตภัณฑ์ของคุณ

  • บทความ

API เนื้อหาคือ RESTful API ที่ใช้ทรัพยากร ผลิตภัณฑ์ เพื่อจัดการข้อเสนอผลิตภัณฑ์ในที่เก็บ Microsoft Merchant Center (MMC) ของคุณ

ต่อไปนี้คือ URI พื้นฐานที่คุณใช้เพื่อเรียกใช้ API เนื้อหา

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/

คําขอ HTTP แต่ละรายการต้องมีโทเค็นการเข้าถึง OAuth ของผู้ใช้และโทเค็นนักพัฒนาของคุณ หากต้องการระบุโทเค็นการเข้าถึงของผู้ใช้ ให้ตั้งค่าส่วนหัว AuthenticationToken หากต้องการระบุโทเค็นนักพัฒนาของคุณ ให้ตั้งค่าส่วนหัว DeveloperToken

ถ้าคุณจัดการแค็ตตาล็อกในนามของลูกค้ารายอื่น คุณต้องตั้งค่า:

  • ส่วนหัว CustomerId ไปยัง ID ลูกค้าของลูกค้าที่ร้านค้าที่คุณกําลังจัดการอยู่
  • ส่วนหัว CustomerAccountId ไปยัง ID บัญชีของบัญชีของลูกค้าที่คุณจัดการ (ไม่สําคัญว่าบัญชีที่มีการจัดการใด)

ตามค่าเริ่มต้น API เนื้อหาใช้ออบเจ็กต์ JSON เพื่อแสดงข้อเสนอผลิตภัณฑ์ เมื่อต้องการใช้ XML ให้ตั้งค่าพารามิเตอร์คิวรี alt เป็น XML

สําหรับรายละเอียดเกี่ยวกับการใช้ทรัพยากรผลิตภัณฑ์ ให้ดูส่วนต่อไปนี้

การรับข้อเสนอผลิตภัณฑ์จากร้านค้า

หากต้องการรับข้อเสนอผลิตภัณฑ์เฉพาะจากร้านค้า ให้ผนวกเทมเพลตต่อไปนี้เข้ากับ URI พื้นฐาน

{mmcMerchantId}/products/{productUniqueId}

ตั้งค่า {mmcMerchantId} เป็น ID ร้านค้า MMC ของคุณและตั้งค่า {productUniqueId} เป็น ID ผลิตภัณฑ์ที่มีคุณสมบัติครบถ้วน (ตัวอย่างเช่น Online:en:US:Sku123) ไม่ใช่ offerId ของผลิตภัณฑ์ เนื่องจากรหัสผลิตภัณฑ์ต้องตรงตามตัวพิมพ์ใหญ่-เล็ก ให้ใช้ ID ที่ API ส่งกลับมาให้คุณเมื่อคุณเพิ่มผลิตภัณฑ์

ส่งคําขอ HTTP GET ไปยัง URL ผลลัพธ์ ถ้าพบผลิตภัณฑ์ การตอบสนองจะประกอบด้วยวัตถุ ผลิตภัณฑ์ ที่มีข้อเสนอ

ถ้าคุณแทรกผลิตภัณฑ์ที่มี ID เดียวกันในหลายแค็ตตาล็อก บริการจะส่งกลับเพียงหนึ่งรายการเท่านั้น ซึ่งผลิตภัณฑ์ใดและแค็ตตาล็อกใดที่ยังไม่ได้รับการกําหนด ด้วยเหตุนี้ คุณจึงไม่ควรแทรกผลิตภัณฑ์ที่มี ID ผลิตภัณฑ์เดียวกันลงในหลายแค็ตตาล็อก

สําหรับตัวอย่างโค้ดที่แสดงวิธีการรับข้อเสนอผลิตภัณฑ์ ให้ดู การจัดการรหัสผลิตภัณฑ์ ตัวอย่าง

การรับรายการข้อเสนอผลิตภัณฑ์จากร้านค้า

หากต้องการรับรายการข้อเสนอผลิตภัณฑ์ที่อยู่ในร้านค้า ให้ผนวกเทมเพลตต่อไปนี้เข้ากับ URI พื้นฐาน

{mmcMerchantId}/products

ตั้งค่า {mmcMerchantId} เป็น ID ร้านค้า MMC ของคุณ

หากต้องการดูรายการข้อเสนอให้ใช้พารามิเตอร์คิวรีผลลัพธ์สูงสุดและโทเค็นเริ่มต้น ในการโทรครั้งแรกของคุณ ให้ตั้งค่า max-results เป็นจํานวนข้อเสนอสูงสุดที่คุณต้องการให้บริการส่งกลับ จํานวนสูงสุดของข้อเสนอที่บริการสามารถส่งกลับได้คือ 250 ค่าเริ่มต้นคือ 25 ส่งคําขอ HTTP GET ไปยัง URL ผลลัพธ์ ต่อไปนี้แสดงตัวอย่างของคําขอ

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250

ถ้าร้านค้ามีข้อเสนอ การตอบสนองจะประกอบด้วยวัตถุ ผลิตภัณฑ์ ที่มีจํานวนข้อเสนอที่ร้องขอ

ถ้ามีข้อเสนอเพิ่มเติม การตอบกลับจะรวมเขตข้อมูล nextPageToken (ดู ผลิตภัณฑ์) เขตข้อมูล nextPageToken ประกอบด้วยค่าโทเค็นที่คุณใช้เพื่อตั้งค่า start-token พารามิเตอร์ในการร้องขอรายการถัดไปของคุณ ต่อไปนี้แสดงตัวอย่างที่ใช้โทเค็น

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250&start-token=DFSos893j...

สําหรับตัวอย่างโค้ดที่แสดงวิธีการรับรายการผลิตภัณฑ์ที่นําเสนอ โปรดดู ตัวอย่างการจัดการรหัสผลิตภัณฑ์

การลบข้อเสนอออกจากร้านค้า

เมื่อต้องการลบข้อเสนอผลิตภัณฑ์เฉพาะจากร้านค้า ให้ผนวกเทมเพลตต่อไปนี้เข้ากับ URI พื้นฐาน

{mmcMerchantId}/products/{productUniqueId}

ตั้งค่า {mmcMerchantId} เป็น ID ร้านค้า MMC ของคุณและตั้งค่า {productUniqueId} เป็น ID ผลิตภัณฑ์ที่มีคุณสมบัติครบถ้วน (ตัวอย่างเช่น Online:en:US:Sku123) ไม่ใช่ offerId ของผลิตภัณฑ์ เนื่องจากรหัสผลิตภัณฑ์ต้องตรงตามตัวพิมพ์ใหญ่-เล็ก ให้ใช้ ID ที่ API ส่งกลับมาให้คุณเมื่อคุณเพิ่มผลิตภัณฑ์

ส่งคําขอ HTTP DELETE ไปยัง URL ผลลัพธ์ ถ้าพบผลิตภัณฑ์ ผลิตภัณฑ์จะถูกลบ

ถ้าคุณแทรกผลิตภัณฑ์ที่มี ID ผลิตภัณฑ์เดียวกันในหลายแค็ตตาล็อก บริการจะลบผลิตภัณฑ์ทั้งหมด คุณไม่ควรแทรกผลิตภัณฑ์ที่มี ID ผลิตภัณฑ์เดียวกันลงในหลายแค็ตตาล็อก

สําหรับตัวอย่างโค้ดที่แสดงวิธีการลบข้อเสนอผลิตภัณฑ์ ให้ดู การจัดการรหัสผลิตภัณฑ์

การเพิ่มและการอัปเดตข้อเสนอผลิตภัณฑ์

การเพิ่มหรือการอัปเดตข้อเสนอเป็นการดําเนินการแทรก เนื่องจากการอัปเดตเป็นการดําเนินการแทรก คุณต้องรวมเขตข้อมูลทั้งหมดของข้อเสนอในคําขอ คุณไม่สามารถอัปเดตเขตข้อมูลเดียวได้

เมื่อต้องการแทรกข้อเสนอผลิตภัณฑ์ ให้ผนวกเทมเพลตต่อไปนี้เข้ากับ URI พื้นฐาน

{mmcMerchantId}/products

ตั้งค่า {mmcMerchantId} เป็น ID ร้านค้า MMC ของคุณ

การส่งคําขอ HTTP POST ไปยัง URL ที่เป็นผลลัพธ์จะเขียนข้อเสนอไปยังแค็ตตาล็อกที่เก็บเริ่มต้น หากต้องการเขียนข้อเสนอไปยังแค็ตตาล็อกเฉพาะ ให้รวมพารามิเตอร์คิวรี bmc-catalog-id

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?bmc-catalog-id=123456

ถ้ามีการแทรกผลิตภัณฑ์ การตอบสนองจะประกอบด้วยวัตถุ Product ออบเจ็กต์ Product ประกอบด้วย รหัสผลิตภัณฑ์ที่คุณใช้เพื่อรับและลบข้อเสนอ

ข้อเสนอต้องมีเขตข้อมูลต่อไปนี้:

API ใช้ channel, contentLanguagetargetCountry, และ offerId เพื่อสร้างรหัสผลิตภัณฑ์ เนื่องจากฟิลด์เหล่านี้ถูกใช้เพื่อสร้าง ID คุณไม่สามารถอัปเดตได้ รหัสผลิตภัณฑ์ต้องตรงตามตัวพิมพ์ใหญ่-เล็ก ID ใช้ปลอกเดียวกันกับที่คุณใช้เพื่อระบุ channelcontentLanguage, targetCountry, และofferId

ข้อ ควร ระวัง

ตรวจสอบให้แน่ใจว่าได้ใช้ปลอกเดียวกันสําหรับ channel, contentLanguagetargetCountry, และofferIdเนื่องจากคุณสามารถเพิ่มผลิตภัณฑ์เดียวกันได้อย่างมีประสิทธิภาพหลายครั้งหากปลอกนั้นแตกต่างกัน

ฟิลด์ต่อไปนี้ยังจําเป็นหากผู้ผลิตกําหนดค่า

คุณต้องระบุค่าถ้าทราบ ถ้าคุณไม่ได้ระบุค่าใดๆ คุณต้องตั้งค่าเขตข้อมูล identifierExists เป็น false ค่าเริ่มต้นเป็นจริง

หากผลิตภัณฑ์มีตัวระบุเหล่านี้และคุณไม่ได้ระบุไว้ MMC จะยอมรับผลิตภัณฑ์ในตอนนี้ แต่ Product วัตถุในการตอบสนองจะ warnings รวมถึงเขตข้อมูล คุณควรตรวจสอบว่า warnings เขตข้อมูลนั้นมีอยู่หรือไม่และแก้ไขปัญหาที่ระบุทั้งหมด

นอกเหนือจากเขตข้อมูลที่จําเป็น คุณควรระบุวันที่และเวลาที่คุณต้องการให้ข้อเสนอหมดอายุด้วย (ดู expirationDate) ตามค่าเริ่มต้น ข้อเสนอจะหมดอายุ 30 วันนับจากวันที่และเวลาที่เขียนไปยังร้านค้าหรือแค็ตตาล็อก คุณควรติดตามผลิตภัณฑ์ที่ใกล้หมดอายุและก่อนที่ผลิตภัณฑ์จะหมดอายุให้อัปเดตวันหมดอายุหรืออัปเดตเพียงผลิตภัณฑ์ (คุณไม่จําเป็นต้องอัปเดตเขตข้อมูลของผลิตภัณฑ์) ซึ่งจะขยายวันหมดอายุโดยอัตโนมัติอีก 30 วัน ถ้าคุณกําหนดวันหมดอายุอย่างชัดเจน การอัปเดตผลิตภัณฑ์จะไม่ขยายวันหมดอายุโดยอัตโนมัติอีก 30 วันในกรณีนี้

เขตข้อมูลอื่น ๆ ทั้งหมดจะถือว่าเป็นตัวเลือก อย่างไรก็ตาม คุณควรระบุให้มากเท่าที่จําเป็นเพื่ออธิบายผลิตภัณฑ์อย่างถูกต้อง

หมายเหตุ

วัตถุ Product ต้องมีเฉพาะเขตข้อมูลที่ถูกตั้งค่าเป็นค่าเท่านั้น ไม่รวมเขตข้อมูล Null ใน Product วัตถุ ตัวอย่างเช่น ไม่รวม"adult":null

Microsoft ไม่ได้ใช้เขตข้อมูล Product ทั้งหมด สําหรับรายการเขตข้อมูลที่ API ยอมรับ แต่ไม่ใช้ โปรดดู ฉันสามารถใช้แอตทริบิวต์ใดของ Google ได้บ้าง เขตข้อมูลอื่น ๆ ทั้งหมดที่ Microsoft ใช้จะถูกใช้เพื่อกรองผลิตภัณฑ์เมื่อแสดงโฆษณาผลิตภัณฑ์

ถ้าคุณระบุเขตข้อมูลที่ API เนื้อหาไม่รู้จัก บริการจะละเว้นเขตข้อมูล

เมื่อคุณแทรกข้อเสนอ บริการจะดําเนินการตรวจสอบเบื้องต้นเกี่ยวกับข้อเสนอและส่งกลับข้อผิดพลาดและคําเตือนตามความเหมาะสม ถ้ามีข้อผิดพลาดเกิดขึ้น การตอบสนองจะประกอบด้วย ErrorResponse วัตถุ ถ้ามีคําเตือนเกิดขึ้น การตอบสนองจะประกอบด้วย Product วัตถุและเขตข้อมูลจะแสดง warnings รายการคําเตือน

ถ้าข้อเสนอผ่านการตรวจสอบเบื้องต้น ข้อเสนอจะผ่านการตรวจสอบความถูกต้องและการตรวจสอบแบบออฟไลน์ เช่น บทวิจารณ์ของบรรณาธิการ ซึ่งอาจใช้เวลาถึง 36 ชั่วโมง ข้อเสนอจะไม่ให้บริการจนกว่าการตรวจสอบความถูกต้องและบทวิจารณ์ทั้งหมดจะเสร็จสมบูรณ์ เมื่อต้องการกําหนดสถานะของข้อเสนอ ให้ใช้ทรัพยากร สถานะ

โปรดทราบว่า API ไม่มีตัวควบคุมภาวะพร้อมกัน เช่น ETags ถ้าแอปสองแอปกําลังพยายามเพิ่มหรืออัปเดตผลิตภัณฑ์เดียวกัน แอปสุดท้ายชนะ

ข้อเสนอที่แสดงในโฆษณาผลิตภัณฑ์ประกอบด้วยราคา ชื่อร้านค้า (หรือ sellerName ถ้ามีการระบุ) ลิงก์ไปยังหน้าเว็บที่มีข้อมูลเพิ่มเติมเกี่ยวกับผลิตภัณฑ์ และรูปภาพของผลิตภัณฑ์

สําหรับผลิตภัณฑ์เครื่องแต่งกายที่พร้อมใช้งานในหลายสี รูปแบบ หรือวัสดุ ให้สร้างผลิตภัณฑ์สําหรับแต่ละตัวแปร และใช้เขตข้อมูล itemGroupId เพื่อจัดกลุ่มผลิตภัณฑ์ย่อยทั้งหมด

สําหรับตัวอย่างรหัสที่แสดงวิธีการแทรกข้อเสนอผลิตภัณฑ์ โปรดดู ตัวอย่างการจัดการรหัสผลิตภัณฑ์

การใช้การประมวลผลชุดงาน

หากคุณกําลังประมวลผลข้อเสนอผลิตภัณฑ์หลายรายการ คุณควรพิจารณาใช้คุณลักษณะการประมวลผลชุดงานของ API คุณลักษณะนี้ช่วยให้คุณสามารถประมวลผลการแทรก รับ และลบหลายรายการในคําขอเดียวได้ การประมวลผลข้อเสนอหลายรายการในคําขอเดียวกันมีประสิทธิภาพมากกว่าการส่งคําขอแยกต่างหากสําหรับแต่ละข้อเสนอ ค่าใช้จ่ายที่เกิดขึ้นกับการประมวลผลคําขอเดียวจะแพร่กระจายไปตามข้อเสนอหลายพันรายการในคําขอชุดแทนที่จะเกิดขึ้นซึ่งค่าใช้จ่ายสําหรับแต่ละคําขอ

อย่าแทรก รับ หรือลบผลิตภัณฑ์เดียวกันในคําขอเดียวกัน

หากต้องการส่งคําขอชุดงาน ให้ผนวกเทมเพลตต่อไปนี้เข้ากับ URI พื้นฐาน

{mmcMerchantId}/products/batch

ตั้งค่า {mmcMerchantId} เป็น ID ร้านค้า MMC ของคุณ

การส่งการร้องขอ HTTP POST ไปยัง URL ที่เป็นผลลัพธ์จะนําการดําเนินการแทรกไปใช้กับแค็ตตาล็อกที่เก็บเริ่มต้น หากต้องการนําข้อเสนอไปใช้กับแค็ตตาล็อกเฉพาะ ให้รวมพารามิเตอร์คิวรี bmc-catalog-id

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products/batch?bmc-catalog-id=123456

เนื้อความของ POST เป็นออบเจ็กต์ชุดงานที่มีอาร์เรย์ของออบเจ็กต์รายการ สําหรับการดําเนินการทั้งหมด ให้batchIdตั้งค่าเขตข้อมูล และ merchantIdmethod batchIdเป็น ID ที่ผู้ใช้กําหนดซึ่งคุณใช้เพื่อระบุสินค้าของชุดงานในการตอบสนอง merchantId รหัสร้านค้าของคุณ และ method เป็นการดําเนินการที่จะดําเนินการ (ตัวอย่างเช่น แทรก ลบ หรือรับ)

ถ้า method ถูกแทรก ให้ product ตั้งค่าเขตข้อมูลเป็นวัตถุ Product ที่มีข้อเสนอเพื่อเพิ่มหรืออัปเดต มิฉะนั้น หาก method เป็นรับหรือลบ ให้ตั้งค่า productId เป็น ID ที่มีคุณสมบัติครบถ้วนของข้อเสนอที่คุณต้องการรับหรือลบ

ขนาดของเนื้อความของการร้องขอชุดงานต้องไม่เกิน 4 เมกะไบต์ ถ้าเนื้อความเกิน 4 MB การตอบสนองจะส่งกลับรหัสสถานะ HTTP 413 คุณสามารถส่งได้ระหว่างข้อเสนอ 2,000 ถึง 6,000 ทั้งนี้ขึ้นอยู่กับขนาดของแต่ละข้อเสนอ (จํานวนของเขตข้อมูลที่คุณระบุ) ถ้าคุณบีบอัดเนื้อความ คุณสามารถส่งจํานวนข้อเสนอสูงสุด ซึ่งเป็น 12,000 (ขึ้นอยู่กับขนาดของข้อเสนอ)

เมื่อต้องการบีบอัดเนื้อความ ให้ใช้การบีบอัด GZip เท่านั้น และตั้งค่าส่วนหัวการเข้ารหัสเนื้อหาของคําขอเป็น gzip

การบริการประมวลผลสินค้าแต่ละรายการในชุดงาน การตอบกลับมี Batch วัตถุที่ประกอบด้วยแต่ละ Item วัตถุที่อยู่ในการร้องขอ โปรดทราบว่าไม่มีการรับประกันว่าลําดับของรายการในการตอบสนองจะอยู่ในลําดับเดียวกับรายการในคําขอ

สําหรับการแทรกการดําเนินการ รายการจะมีเฉพาะเขตข้อมูล และ product เท่านั้นbatchId ฟิลด์ product ประกอบด้วยข้อเสนอเดียวกันกับที่คุณส่งในคําขอ แต่ยังรวมถึง ID ผลิตภัณฑ์ที่มีคุณสมบัติครบถ้วนด้วย ถ้ามีข้อผิดพลาดหรือคําเตือนเกิดขึ้น รายการจะมีbatchIdเขตข้อมูล , methodและerror ฟิลด์ error ประกอบด้วยสาเหตุที่การแทรกล้มเหลว หรือคําเตือนเกี่ยวกับปัญหาเกี่ยวกับข้อเสนอที่คุณต้องการแก้ไข

สําหรับการรับการดําเนินการ รายการจะbatchIdประกอบด้วยเขตข้อมูล และproduct ฟิลด์ product มีข้อเสนอที่คุณร้องขอ ถ้าไม่พบผลิตภัณฑ์ วัตถุจะไม่รวมเขตข้อมูลproduct

สําหรับการดําเนินการลบ สินค้าจะมีเฉพาะฟิลด์ เท่านั้น batchId ไม่มีข้อบ่งชี้ว่ามีข้อเสนออยู่และถูกลบออกหรือไม่

สําหรับตัวอย่างรหัสที่แสดงวิธีการใช้การประมวลผลชุดงาน ดูการสร้างคําขอชุดงาน