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 đề của sản phẩm. Cấu trúc 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 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

Sau đâ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 quy trình 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 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ự 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 được 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á quy trình 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ẽ sửa đổi trực tiếp một dữ liệu đầ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ị các lượt tải nguồn cấp dữ liệu khác ghi đè một cách bất ngờ. Trong Merchant API, thông tin cập nhật sẽ được giữ nguyê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 cho 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 sạch hơn: Tất cả các thao tác productInputs ghi 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 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 dùng được 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.

Mẹo: Cải thiện công suất bằng nhóm kênh: Định cấu hình nhóm kênh để tối đa hoá công suất cho các thao tác hàng loạt. Cách này bỏ qua giới hạn 100 luồng thông thườ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 bài viết 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

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

Thuật ngữ chính: "Đánh cắp sản phẩm" xảy ra khi một sản phẩm được xác định bằng khoá duy nhất (language, feedlabel, offerID) được chèn vào một nguồn dữ liệu chính khác với nguồn dữ liệu mà sản phẩm đó thuộc về. Thao tác này sẽ xoá sản phẩm khỏi nguồn cũ và chuyển sản phẩm đó sang nguồn mới, nơi có thể áp dụng các quy tắc và chế độ cài đặt quyền sở hữu khác nhau cho nguồn dữ liệu. Mặc dù bạn có thể cố ý đánh cắp sản phẩm để sắp xếp lại sản phẩm, nhưng việc đánh cắp sản phẩm vô tình có thể xảy ra nếu bạn cung cấp dataSource không chính xác trong quá trình chè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 ngừa các vấn đề như đánh cắp sản phẩm, hãy làm theo những đề 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 với sản phẩm, bạn nên thực hiện thao tác điền lại cơ sở dữ liệu cục bộ một lần. Thêm trường tên dataSource vào từng bản ghi sản phẩm để bạn có thể cung cấp giá trị nhận dạng chính xác trực tiếp trong các yêu cầu.

• Hợp nhất và sử dụng nguồn dữ liệu cho mọi nhãn 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 và ngôn ngữ, do đó cho phép chèn sản phẩm bằng mọi nhãn và ngôn ngữ của nguồn dữ liệu. Hãy cân nhắc sử dụng một nguồn dữ liệu cho mọi nhãn và ngôn ngữ.

• Bảo vệ sản phẩm: Nếu bạn sử dụng quy tắc nguồn dữ liệu, hãy gọi products.get để tìm dataSource chính xác được 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ự định và ngăn việc đánh cắp sản phẩm vô tình.

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. Hãy xem cả 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 yêu cầu không đồng bộ hoặc tính năng phân lô HTTP

Giá trị nhận dạng

Định dạng của 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. Mã hoá: 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ự mà 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. Thay vào đó, 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 dữ liệu đầu vào của sản phẩm. Yêu cầu dataSource.
products.update	productInputs.patch	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 giữ nguyên.
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 yêu cầu không đồng bộ hoặc tính năng phân lô 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 yêu cầu 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 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. 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ự 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 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à 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 cửa hàng địa phương.	Trường channel không còn xuất hiện trong Merchant API. Thay vào đó, 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 mà bạn 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.