Di chuyển sản phẩm

Merchant API giới thiệu một cách thức mạnh mẽ và trực quan hơn để quản lý dữ liệu sản phẩm. 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 đề về sản phẩm. Cấu trúc mới này mang đến 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 quá trình tích hợp từ Content API for Shopping. Để biết 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

Dưới đây là những thay đổi quan trọng nhất về 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 riêng 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 chỉ đọc Product để 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 có phần đệm (RFC 4648 Mục 5) cho cả ProductInput.name và Product.name trường. Trong trường hợp tên sản phẩm chứa các ký tự do 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ề xác thực sản phẩm và trạng thái đích đến hiện được đưa trực tiếp vào trong Product tài nguyên 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 sản phẩm có thể dự đoán: Phương thức mới productInputs.patch 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 cải tiến đáng kể so với Content API for Shopping, trong đó, các thông tin cập nhật có thể bị ghi đè ngoài dự kiến bằng các lượt tải nguồn cấp dữ liệu khác lên. Trong Merchant API, thông tin cập nhật vẫn còn cho đến khi dữ liệu đầu vào cụ thể của sản phẩm đó được cập nhật lại hoặc bị xoá. Thông tin cập nhật sản phẩm được áp dụng trên ProductInput tài nguyên 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ả các thao tác ghi productInputs hiện đều yêu cầu tham số truy vấn dataSource, cho biết rõ 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: Các sản phẩm hiện được xác định bằng một 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 các yêu cầu không đồng bộ hoặc tính năng xử lý hàng loạt HTTP để gửi nhiều yêu cầu trong một lệnh gọi HTTP.

Mẹo: Cải thiện thông lượng bằng nhóm kênh: Thiết lập một nhóm kênh để tối đa hoá thông lượng cho các thao tác hàng loạt. Cách này bỏ qua giới hạn thông thường là 100 luồng của một kênh gRPC bằng cách quản lý nhiều kết nối cơ bản. Để biết thêm thông tin, hãy xem Tái cấu trúc mã cho các yêu cầu đồng thời: Cải thiện công suất bằng nhóm kênh

• Nguồn dữ liệu cho mọi nhãn nguồn cấp dữ liệu và ngôn ngữ: Merchant API cho phép tạo nguồn dữ liệu mà không cần chỉ định nhãn nguồn cấp dữ liệu và ngôn ngữ và do đó, cho phép chèn sản phẩm bằng mọi nhãn nguồn cấp dữ liệu và ngôn ngữ.

Lưu ý: Hãy nhớ sử dụng cùng một offerId cho cùng một sản phẩm khi gọi Merchant API như khi bạn sử dụng Content API for Shopping để tránh mất nhật ký sản phẩm. Bạn cũng có thể kiểm tra phần Giá trị nhận dạng trên trang này.

Yêu cầu

Phần này so sánh các đị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
Lấy một 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}
Lấy 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
Xử lý hàng loạt nhiều yêu cầu	POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch	Sử dụng các yêu cầu không đồng bộ hoặc tính năng xử lý hàng loạt HTTP

Giá trị nhận dạng

Định dạng cho giá trị nhận dạng sản phẩm đã thay đổi trong Merchant API thành tên tài nguyên REST tiêu chuẩn.

Nội dung mô tả giá trị nhận dạng	Content API for Shopping	Merchant API
Mã sản phẩm	Một chuỗi bao 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	Một chuỗi tài nguyên REST name. Định dạng: accounts/{account}/products/{product} trong đó {product} là contentLanguage~feedLabel~offerId. Ví dụ: accounts/12345/products/en~US~sku123. Phương thức mã hoá: Phương thức mã hoá base64url không có phần đệm được đề xuất và bắt buộc trong trường hợp mã sản phẩm chứa các ký tự do Merchant API sử dụng hoặc các ký tự dành riêng cho URL.

Lưu ý: Trường channel không còn xuất hiện trong Merchant API. 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.

Phương thức

Bảng này cho thấy các phương thức 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à ghi chú
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 đã xử lý.
products.insert	productInputs.insert	Chèn một dữ liệu đầu vào của sản phẩm. Yêu cầu dataSource.
products.update	productInputs.update	Hành vi này khác biệt đáng kể. Phương thức 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 liên tục.
products.delete	productInputs.delete	Xoá một dữ liệu đầu vào cụ thể của sản phẩm. Yêu cầu dataSource.
products.custombatch	Không có	Sử dụng các yêu cầu không đồng bộ hoặc tính năng xử lý hàng loạt HTTP.
productstatuses.get	products.get	Dịch vụ productstatuses đã bị xoá. Thông tin 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 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 các yêu cầu không đồng bộ hoặc tính năng xử lý hàng loạt HTTP.

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

Bảng này nêu bật các 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à name tài nguyên REST. Phương thức mã hoá base64url không có phần đệm được đề xuất và bắt buộc trong trường hợp tên sản phẩm chứa các ký tự do 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 thuộc tính 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 rõ ràng và có tổ chức 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à một tham số truy vấn bắt buộc cho tất cả cá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ỉ tại địa phương.	Trường channel không còn xuất hiện trong Merchant API. 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 không bắt buộc 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.
Các trường thuộc loại string có tập hợp giá trị được xác định	Các trường thuộc 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.