Di chuyển sản phẩm

Merchant API mang đến một cách mạnh mẽ và trực quan hơn để quản lý dữ liệu sản phẩm của bạn. Thay đổi chính là việc tách dữ liệu sản phẩm thành hai tài nguyên riêng biệt: ProductInput để gửi dữ liệu và Product để xem phiên bản cuối cùng đã xử lý, bao gồm cả trạng thái và vấn đề của sản phẩm. Cơ cấu mới này mang lại trải nghiệm dễ dự đoán và minh bạch hơn.

Hướng dẫn này sẽ trình bày những điểm khác biệt chính để giúp bạn di chuyển quy trình tích hợp từ Content API for Shopping. Để xem hướng dẫn chi tiết về cách sử dụng các tính năng mới, hãy xem bài viết Quản lý sản phẩm.

Những điểm khác biệt chính

Sau đây là những thay đổi quan trọng nhất đối với cách bạn quản lý sản phẩm trong Merchant API so với Content API for Shopping:

  • Tài nguyên chuyên biệt cho dữ liệu đầu vào và dữ liệu đã xử lý: Merchant API chia việc quản lý sản phẩm thành hai tài nguyên. Bạn có thể sử dụng tài nguyên ProductInput để chèn, cập nhật và xoá dữ liệu sản phẩm. Bạn có thể sử dụng tài nguyên Product chỉ có thể đọc để xem sản phẩm cuối cùng sau khi Google xử lý dữ liệu đầu vào, áp dụng quy tắc và kết hợp dữ liệu từ các nguồn bổ sung.

  • Mã hoá tên sản phẩm: Bạn có thể sử dụng phương thức mã hoá base64url không đệm (RFC 4648 Mục 5) cho cả hai trường ProductInput.name và Product.name. Trong trường hợp tên sản phẩm chứa các ký tự mà Merchant API sử dụng hoặc các ký tự dành riêng cho URL, bạn bắt buộc phải mã hoá. Ví dụ: bạn phải mã hoá tên sản phẩm nếu tên sản phẩm chứa bất kỳ ký tự nào sau đây:

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

  • Trạng thái sản phẩm tích hợp: Dịch vụ productstatuses đã bị xoá. Các vấn đề về việc xác thực sản phẩm và trạng thái của vị trí xuất hiện hiện được đưa trực tiếp vào tài nguyên Product trong trường productStatus, giúp đơn giản hoá việc truy xuất dữ liệu.

  • Thông tin cập nhật dễ đoán về sản phẩm: Phương thức productInputs.patch mới sửa đổi trực tiếp một thông tin đầu vào cụ thể của sản phẩm. Đây là một điểm cải tiến đáng kể so với Content API for Shopping, nơi các bản cập nhật có thể bị ghi đè ngoài dự kiến khi bạn tải các nguồn cấp dữ liệu khác lên. Trong Merchant API, nội dung cập nhật sẽ được giữ nguyên cho đến khi thông tin đầu vào của sản phẩm cụ thể đó được cập nhật lại hoặc bị xoá. Nội dung cập nhật sản phẩm được áp dụng cho tài nguyên ProductInput thay vì tài nguyên Product đã xử lý.

  • Chọn nguồn dữ liệu để quản lý dữ liệu rõ ràng hơn: Tất cả thao tác ghi productInputs hiện đều yêu cầu tham số truy vấn dataSource, giúp xác định rõ ràng nguồn dữ liệu mà bạn đang sửa đổi. Điều này đặc biệt hữu ích nếu bạn có nhiều nguồn cung cấp dữ liệu.

  • Giá trị nhận dạng tài nguyên mới: Sản phẩm hiện được xác định bằng tài nguyên RESTful name thay vì trường id. Định dạng là accounts/{account}/products/{product}.

  • Không có lô tuỳ chỉnh: Phương thức custombatch không còn hoạt động nữa. Bạn có thể sử dụng yêu cầu không đồng bộ hoặc tính năng phân lô HTTP để gửi nhiều yêu cầu trong một lệnh gọi HTTP.

Nguyên tắc về nguồn dữ liệu trong quá trình di chuyển

Trước khi di chuyển nguồn dữ liệu, bạn nên chọn chiến lược nguồn dữ liệu.

Để đảm bảo quá trình di chuyển diễn ra suôn sẻ và ngăn chặn các vấn đề như đánh cắp ưu đãi, hãy làm theo các đề xuất sau:

  • Điền lại cơ sở dữ liệu: Thay vì gọi dataSources.list trước mỗi thao tác sản phẩm, bạn nên thực hiện một lần điền lại cơ sở dữ liệu cục bộ. Thêm trường tên dataSource vào mỗi bản ghi sản phẩm để bạn có thể cung cấp trực tiếp giá trị nhận dạng chính xác trong các yêu cầu của mình.

  • Hợp nhất và sử dụng nguồn dữ liệu cho mọi nhãn nguồn dữ liệu và ngôn ngữ: Merchant API cho phép bạn tạo nguồn dữ liệu mà không cần chỉ định nhãn nguồn dữ liệu và ngôn ngữ, nhờ đó bạn có thể chèn sản phẩm bằng bất kỳ nhãn nguồn dữ liệu và ngôn ngữ nào của nguồn dữ liệu. Hãy cân nhắc sử dụng một nguồn dữ liệu duy nhất cho mọi nhãn và ngôn ngữ.

  • Bảo vệ sản phẩm của bạn: Nếu bạn sử dụng quy tắc nguồn dữ liệu, hãy gọi products.get để tìm chính xác dataSource liên kết với một sản phẩm trước khi cập nhật hoặc xoá sản phẩm đó. Điều này đảm bảo bạn đang sửa đổi nguồn dự kiến và ngăn chặn việc vô tình lấy cắp ưu đãi.

Yêu cầu

Phần này so sánh định dạng yêu cầu cho Content API for Shopping và Merchant API.

Nội dung mô tả yêu cầu Content API for Shopping Merchant API
Mua sản phẩm GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
Liệt kê sản phẩm GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
Chèn sản phẩm POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert
Cập nhật sản phẩm PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
Xoá sản phẩm DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
Xem trạng thái sản phẩm GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId} GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
Liệt kê trạng thái sản phẩm GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
Gom nhiều yêu cầu theo lô POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch Sử dụng tài nguyên không đồng bộ hoặc tính năng gom theo lô HTTP

Giá trị nhận dạng

Định dạng của mã nhận dạng sản phẩm trong Merchant API đã thay đổi thành tên tài nguyên REST chuẩn.

Nội dung mô tả về giá trị nhận dạng Content API for Shopping Merchant API
Mã sản phẩm Một chuỗi gồm các phân đoạn được phân tách bằng dấu hai chấm (:).
Định dạng: channel:contentLanguage:targetCountry:offerId hoặc channel:contentLanguage:feedLabel:offerId.
Ví dụ: online:en:US:sku123		 Chuỗi name tài nguyên REST.
Định dạng: accounts/{account}/products/{product}, trong đó {product} là contentLanguage~feedLabel~offerId.
Ví dụ: accounts/12345/products/en~US~sku123.
Mã hoá: Bạn nên sử dụng mã hoá base64url không có khoảng đệm và bắt buộc trong trường hợp mã sản phẩm chứa các ký tự mà Merchant API sử dụng hoặc các ký tự dành riêng cho URL.

Phương thức

Bảng này cho biết các phương thức của Content API for Shopping và các phương thức tương đương trong Merchant API.

Phương thức Content API for Shopping Phương thức Merchant API Phạm vi cung cấp và lưu ý
products.get products.get Truy xuất sản phẩm cuối cùng đã xử lý.
products.list products.list Liệt kê các sản phẩm cuối cùng đã được xử lý.
products.insert productInputs.insert Chèn một dữ liệu đầu vào của sản phẩm. Cần có dataSource.
products.update productInputs.patch Hành vi này khác biệt đáng kể. Nguồn cấp dữ liệu này cập nhật một dữ liệu đầu vào cụ thể của sản phẩm và có tính ổn định.
products.delete productInputs.delete Xoá một dữ liệu đầu vào cụ thể của sản phẩm. Cần có dataSource.
products.custombatch Không có Sử dụng tài nguyên không đồng bộ hoặc tính năng gom theo lô HTTP.
productstatuses.get products.get Dịch vụ productstatuses đã bị xoá. Thông tin về trạng thái hiện là một phần của tài nguyên Product.
productstatuses.list products.list Dịch vụ productstatuses đã bị xoá. Thông tin về trạng thái hiện là một phần của tài nguyên Product.
productstatuses.custombatch Không có Sử dụng tài nguyên không đồng bộ hoặc tính năng phân lô HTTP.

Thay đổi chi tiết về trường

Bảng này nêu bật những trường quan trọng đã được thay đổi, thêm hoặc xoá trong Merchant API.

Content API for Shopping Merchant API Mô tả
id name Giá trị nhận dạng chính cho một sản phẩm hiện là tài nguyên REST name. Bạn nên dùng mã hoá base64url không có khoảng đệm và bắt buộc trong trường hợp tên sản phẩm chứa các ký tự mà Merchant API sử dụng hoặc các ký tự dành riêng cho URL.
Các thuộc tính quy cách dữ liệu sản phẩm cấp cao nhất (ví dụ: title, price, link) Đối tượng productAttributes Các thuộc tính sản phẩm như title, price và link không còn là các trường cấp cao nhất. Các trường này hiện được nhóm trong đối tượng productAttributes ở cả tài nguyên Product và ProductInput. Điều này giúp cấu trúc tài nguyên gọn gàng và ngăn nắp hơn.
targetCountry feedLabel Tên tài nguyên hiện sử dụng feedLabel thay vì targetCountry để phù hợp với chức năng của Merchant Center.
feedId dataSource (tham số truy vấn) Tên dataSource hiện là tham số truy vấn bắt buộc cho tất cả phương thức ghi productInputs (insert, update, delete).
channel Không có. Sử dụng legacy_local cho các sản phẩm chỉ có tại cửa hàng địa phương. Trường channel không còn xuất hiện trong Merchant API nữa. Các sản phẩm có kênh LOCAL trong Content API for Shopping nên đặt trường legacy_local thành true.
Không có versionNumber Một trường tuỳ chọn mới trên ProductInput có thể dùng để ngăn việc chèn không theo thứ tự vào các nguồn dữ liệu chính.
Trường loại string có tập hợp giá trị được xác định Trường loại enum có tập hợp giá trị được xác định Các trường trong thuộc tính sản phẩm có tập hợp giá trị được xác định (ví dụ: excluded_destinations, availability) hiện thuộc loại enum.
gtin productAttributes.gtins Thay đổi từ một chuỗi đơn (gtin) thành một chuỗi lặp lại (gtins).
sizes productAttributes.size Thay đổi từ chuỗi lặp lại (sizes) thành chuỗi đơn (size).
sizeType, additionalSizeType productAttributes.sizeTypes Thay thế sizeType và additionalSizeType bằng enum SizeType lặp lại (sizeTypes) chấp nhận tối đa hai giá trị (ví dụ: ["PETITE", "MATERNITY"]).
Trước
Migrate online return policy management
Tiếp
Migrate reporting management