Lưu ý quan trọng: Content API for Shopping đã ngừng hoạt động từ ngày 18 tháng 8 năm 2026.

Kể từ ngày 1 tháng 9 năm 2026, các yêu cầu Content API for Shopping sẽ gặp phải lỗi tăng dần. Xem hướng dẫn về việc ngừng cung cấp Content API.

Nếu cần thêm thời gian để di chuyển sang Merchant API, hãy đăng ký gia hạn quyền truy cập vào Content API for Shopping.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Chọn giữa nguồn cấp dữ liệu dạng tệp và Merchant API

Bạn có thể tải dữ liệu sản phẩm lên Merchant Center bằng nguồn cấp dữ liệu dựa trên tệp, Merchant API hoặc kết hợp cả hai:

Nguồn cấp dữ liệu sản phẩm dựa trên tệp: Tải tệp CSV, TSV hoặc XML lên bằng SFTP, Google Cloud Storage, Google Trang tính hoặc tính năng tìm nạp theo lịch.
Merchant API: Gửi yêu cầu có lập trình ngay từ phần phụ trợ để cập nhật dần khi dữ liệu sản phẩm thay đổi, đồng thời đồng bộ hoá toàn bộ danh mục định kỳ.

Hướng dẫn này so sánh cả hai phương pháp, giải thích thời điểm nên sử dụng phương pháp này thay vì phương pháp kia (hoặc cả hai cùng nhau) và cung cấp cẩm nang di chuyển từng bước nếu bạn quyết định chuyển một số hoặc tất cả sản phẩm của mình từ nguồn cấp dữ liệu tệp sang API.

Chọn phương pháp cho nguồn dữ liệu

Đánh giá mức độ biến động của danh mục, cấu trúc phần phụ trợ và quy trình vận hành để quyết định nên sử dụng Merchant API, nguồn cấp dữ liệu tệp hay chế độ thiết lập kết hợp.

Trường hợp nên sử dụng Merchant API

Sử dụng nguồn dữ liệu chính API nếu:

Tích hợp có lập trình trực tiếp: Bạn muốn gọi API trực tiếp từ phần phụ trợ thay vì tạo tệp và quản lý quy trình chuyển tệp (chẳng hạn như SFTP hoặc Google Cloud Storage).
Giá và tình trạng còn hàng biến động mạnh: Giá sản phẩm hoặc mức tồn kho của bạn thay đổi thường xuyên trong ngày.
Cập nhật ngay khi dữ liệu thay đổi: Bạn muốn gửi thông tin về các thay đổi đối với sản phẩm cho Google ngay khi các thay đổi đó xảy ra trong hệ thống phụ trợ, thay vì đợi đến lần tạo và tải tệp lên theo lịch tiếp theo.
Nội dung cập nhật danh mục gia tăng: Bạn muốn chèn, cập nhật hoặc xoá từng sản phẩm khi có thay đổi mà không cần tải lên lại toàn bộ danh mục mỗi lần.
Cập nhật một phần thuộc tính: Bạn muốn cập nhật các trường cụ thể của một sản phẩm (chẳng hạn như price hoặc availability bằng productInputs.patch) mà không cần gửi lại toàn bộ tải trọng của sản phẩm.

Trường hợp sử dụng nguồn cấp dữ liệu tệp

Sử dụng nguồn dữ liệu chính dựa trên tệp nếu:

Danh mục tĩnh: Dữ liệu sản phẩm của bạn không thường xuyên thay đổi (ví dụ: một lần mỗi ngày hoặc ít hơn).
Phần phụ trợ chỉ có ảnh chụp nhanh mà không có tính năng theo dõi delta: Phần phụ trợ của bạn chỉ xuất ảnh chụp nhanh danh mục đầy đủ và không thể theo dõi các thay đổi ở cấp mặt hàng hoặc các thao tác xoá sản phẩm rõ ràng.
Quy trình làm việc dựa trên bảng tính: Các nhóm không thuộc bộ phận kỹ thuật chọn lọc hoặc ghi đè dữ liệu sản phẩm ngay trong Google Trang tính hoặc tệp CSV.
Hoạt động ít cần bảo trì: Bạn muốn xuất tệp theo lịch, trong đó Merchant Center xử lý việc tìm nạp và xử lý thông tin tổng quan nhanh, thay vì vận hành một quy trình tích hợp API với tốc độ yêu cầu, xử lý thử lại và đồng bộ hoá toàn bộ danh mục định kỳ.

Trường hợp sử dụng cả hai

Bạn có thể kết hợp nguồn cấp dữ liệu dạng tệp và Merchant API trong cùng một tài khoản Merchant Center trong các trường hợp sau:

Danh mục sản phẩm được phân vùng: Bạn sử dụng Merchant API cho các sản phẩm thay đổi nhanh (chẳng hạn như ưu đãi chớp nhoáng hoặc hàng tồn kho có doanh thu cao) và nguồn cấp dữ liệu tệp cho các phân khúc danh mục tĩnh hoặc dòng sản phẩm riêng biệt. Đảm bảo rằng mỗi sản phẩm chỉ được tải lên bằng một nguồn dữ liệu chính (xem phần Sử dụng song song và quyền sở hữu nguồn dữ liệu chính).
Dữ liệu chính của API có nguồn cấp dữ liệu bổ sung dựa trên tệp: Bạn quản lý dữ liệu sản phẩm cốt lõi thông qua nguồn dữ liệu chính của API, trong khi các nhóm không thuộc bộ phận kỹ thuật hoặc đối tác bên thứ ba cung cấp các thuộc tính bổ sung thông qua nguồn cấp dữ liệu bổ sung dựa trên tệp (chẳng hạn như tệp Google Trang tính hoặc tệp CSV) được kết hợp với các quy tắc thuộc tính hoặc ngược lại.
Di chuyển một phần hoặc theo giai đoạn: Bạn chuyển các thị trường, danh mục hoặc tài khoản phụ cụ thể sang API trong khi vẫn giữ phần còn lại của danh mục trên nguồn cấp dữ liệu tệp.

Nếu bạn quyết định di chuyển một số hoặc tất cả sản phẩm từ nguồn cấp dữ liệu dạng tệp sang Merchant API, hãy làm theo Sổ tay hướng dẫn di chuyển từng bước.

Những điểm khác biệt chính về cấu trúc

Nguồn cấp dữ liệu dạng tệp và Merchant API dựa trên phương thức đẩy khác nhau về cách Google xử lý và quản lý dữ liệu sản phẩm:

Khái niệm	Nguồn cấp dữ liệu tệp	Merchant API
Mô hình tích hợp	Kết xuất tệp ngoại tuyến: Bạn xuất danh mục của mình sang một tệp và chuyển tệp đó bằng SFTP, Google Cloud Storage, Google Trang tính hoặc tìm nạp theo lịch.	Tích hợp trực tiếp theo phương thức lập trình: Phần phụ trợ của bạn gửi yêu cầu trực tiếp đến điểm cuối API.
Độ chi tiết của đột biến	Xử lý hàng loạt: Việc sửa đổi một mục thường yêu cầu xử lý lại toàn bộ tệp.	Giao dịch chi tiết: Bạn chỉ có thể chèn, vá hoặc xoá những sản phẩm đã thay đổi.
Thời gian đồng bộ hoá	Đồng bộ hoá hàng loạt: Các thay đổi sẽ chờ trong phần phụ trợ của bạn cho đến chu kỳ xuất và chuyển tệp theo lịch tiếp theo.	Cuộc gọi ngay lập tức hoặc theo lịch: Bạn có thể gửi ngay các thay đổi gia tăng khi chúng xảy ra, cùng với các lần đồng bộ hoá toàn bộ định kỳ.
Hành vi xoá	Ngầm định (Ảnh chụp nhanh): Mỗi tệp là một ảnh chụp nhanh hoàn chỉnh; việc xoá một hàng khỏi tệp chính sẽ xoá sản phẩm.	Rõ ràng: Không có khái niệm ảnh chụp nhanh; hãy gọi `productInputs.delete` để xoá một sản phẩm đã ngừng cung cấp.
Biểu diễn tài nguyên	Trạng thái đơn: Các hàng trong tệp của bạn đại diện cho dữ liệu đầu vào thô.	Tách riêng dữ liệu thô và dữ liệu đã xử lý: API chia dữ liệu thành `ProductInput` (dữ liệu đầu vào thô) và `Product` (trạng thái đã xử lý cuối cùng).
Quy tắc thuộc tính (nguồn cấp dữ liệu)	Được áp dụng cho các cột tệp thô trong giao diện người dùng Merchant Center.	Được hỗ trợ trong giao diện người dùng của Merchant Center. Bắt buộc khi hợp nhất dữ liệu API với tệp bổ sung của bên thứ ba; không bắt buộc đối với các phép biến đổi một nguồn nếu được xử lý trong phần phụ trợ của bạn.

Sử dụng song song và quyền sở hữu nguồn dữ liệu chính ("ưu tiên bản cập nhật gần đây nhất")

Mặc dù bạn có thể sử dụng cả nguồn cấp dữ liệu tệp và API trong cùng một tài khoản Merchant Center, nhưng bạn chỉ nên sử dụng một phương thức để chèn một sản phẩm nhất định.

Merchant Center hoạt động theo mô hình "bản cập nhật gần đây nhất sẽ được ưu tiên". Nguồn dữ liệu chính (API hoặc nguồn cấp dữ liệu tệp) đã đẩy nội dung chèn sản phẩm gần đây nhất sẽ có quyền sở hữu chính đối với dữ liệu của sản phẩm đó:

Khi nguồn dữ liệu tệp sở hữu sản phẩm: Việc bỏ qua sản phẩm trong lần tải tệp lên tiếp theo sẽ kích hoạt thao tác xoá ngầm, xoá sản phẩm khỏi Merchant Center.
Khi nguồn dữ liệu API sở hữu sản phẩm: Việc bỏ qua sản phẩm trong một tệp tải lên sẽ không có hiệu lực vì nguồn cấp dữ liệu tệp không còn sở hữu sản phẩm đó nữa. Bạn phải gọi accounts.productInputs.delete để xoá.
Nguy cơ vô tình lấy lại quyền sở hữu: Nếu nguồn cấp dữ liệu tệp đã cập nhật chạy sau khi API đẩy dữ liệu và chứa sản phẩm, thì nguồn dữ liệu tệp sẽ lấy lại quyền sở hữu. Sau đó, việc bỏ sót sản phẩm trong tệp sẽ vô tình xoá sản phẩm đó.

Để tránh bị xoá ngoài ý muốn hoặc mất thông tin cập nhật qua API, đừng cập nhật đồng thời cùng một sản phẩm bằng cả API và nguồn dữ liệu chính dạng tệp.

Những điểm chính cần cân nhắc về API

Hãy tìm hiểu các hành vi quan trọng sau đây của Merchant API trước khi bắt đầu triển khai:

Nguồn dữ liệu linh hoạt (không có ngôn ngữ hoặc nhãn)

Không giống như nguồn cấp dữ liệu dạng tệp yêu cầu bạn xác định trước một nhãn và ngôn ngữ cụ thể cho nguồn cấp dữ liệu mục tiêu, Merchant API cho phép bạn tạo nguồn dữ liệu chính mà không cần chỉ định feedLabel hoặc contentLanguage.

Tải lên linh hoạt: Tính năng này cho phép bạn tải sản phẩm lên bằng bất kỳ ngôn ngữ nào hoặc tổ hợp nhãn nguồn cấp dữ liệu nào vào một nguồn dữ liệu duy nhất.
Quản lý đơn giản: Bạn không cần tạo và quản lý các nguồn dữ liệu riêng biệt cho từng thị trường mục tiêu. Lưu ý: Để biết thêm thông tin về cách chọn chiến lược nguồn dữ liệu, hãy xem bài viết Chọn chiến lược nguồn dữ liệu.

Chiến lược và hạn mức đồng bộ hoá

Không giống như nguồn cấp dữ liệu tệp nơi bạn tải toàn bộ danh mục lên trong một lô, hãy thiết kế quy trình tích hợp Merchant API xoay quanh cả nội dung cập nhật gia tăng và đồng bộ hoá toàn bộ theo nhịp độ:

Kết hợp nội dung cập nhật gia tăng với việc đồng bộ hoá toàn bộ định kỳ: Gửi yêu cầu productInputs.insert hoặc productInputs.patch khi thuộc tính sản phẩm thay đổi trong phần phụ trợ. Vì việc chỉ dựa vào các bản cập nhật gia tăng có thể khiến dữ liệu của bạn không đồng bộ theo thời gian, nên bạn cũng cần chạy các bản đồng bộ hoá đầy đủ định kỳ để đối chiếu danh mục với nguồn đáng tin cậy (đồng thời làm mới thời hạn 30 ngày của sản phẩm). Tần suất bạn chạy quy trình đồng bộ hoá đầy đủ phụ thuộc vào kích thước danh mục và hạn mức API hiện có.
Điều chỉnh tốc độ gửi yêu cầu để tuân thủ hạn mức API: Đừng gọi API cho tất cả sản phẩm cùng một lúc. Mặc dù bạn có thể gửi các thay đổi gia tăng khi chúng xảy ra, nhưng hãy phân bổ đều các yêu cầu đồng bộ hoá đầy đủ trong ngày để duy trì trong hạn mức lệnh gọi phương thức hằng ngày và mỗi phút. Để biết thông tin chi tiết, hãy xem bài viết Hạn mức và giới hạn và Thường xuyên cập nhật sản phẩm.

Kiểm thử quá trình tích hợp

Xác thực logic tích hợp trong một môi trường an toàn trước khi chuyển sang môi trường thực tế.

Sử dụng tài khoản thử nghiệm

Trước khi thực hiện thay đổi trong phiên bản chính thức, bạn nên thực hiện các bước ban đầu của quá trình di chuyển trong tài khoản thử nghiệm hộp cát:

Tạo tài khoản thử nghiệm: Thiết lập một tài khoản thử nghiệm riêng biệt để thử nghiệm một cách an toàn mà không ảnh hưởng đến quảng cáo hoặc trang thông tin miễn phí đang hoạt động.
Tạo nguồn dữ liệu API: Thực hành tạo nguồn dữ liệu chính của API.
Kiểm tra quy tắc thuộc tính: Xác minh các phép biến đổi dữ liệu và việc kết hợp nguồn cấp dữ liệu bổ sung.
Xác thực tải trọng và khoá sản phẩm: Đẩy sản phẩm mẫu để xác minh cách viết hoa, mã hoá và xử lý lỗi của SKU.

Để biết thông tin chi tiết, hãy xem Bước 1: Tạo tài khoản thử nghiệm và hướng dẫn về Tài khoản thử nghiệm.

Xác thực việc căn chỉnh khoá sản phẩm

Đảm bảo khoá sản phẩm trong tải trọng có lập trình khớp chính xác với SKU trong nguồn cấp dữ liệu tệp của bạn. Google nhận dạng sản phẩm bằng cách kết hợp:

offerId (được gọi là id trong nguồn cấp dữ liệu tệp, phân biệt chữ hoa chữ thường)
contentLanguage (ví dụ: en)
feedLabel (ví dụ: US)

Ký tự đặc biệt và mã hoá

Nếu mã nhận dạng sản phẩm của bạn chứa các ký tự như /, % hoặc ~, hãy sử dụng Định dạng được mã hoá (mã hoá base64url không có khoảng đệm) trong các lệnh gọi API. Để biết thêm thông tin, hãy xem ProductInput.name

Kiểm soát đồng thời

Trong quá trình tích hợp theo thời gian thực, các bản cập nhật có thể đến không theo thứ tự do độ trễ mạng. Để ngăn các bản cập nhật cũ ghi đè dữ liệu mới hơn, hãy sử dụng trường versionNumber trong tài nguyên ProductInput.

Cẩm nang di chuyển từng bước

Nếu bạn quyết định chuyển một số hoặc tất cả sản phẩm từ nguồn cấp dữ liệu dạng tệp sang Merchant API, hãy làm theo cẩm nang này để chuyển đổi sản phẩm mà không làm mất số lượt hiển thị hoặc nhật ký phân phát.

1. Thử nghiệm việc di chuyển trong tài khoản thử nghiệm

Trước khi thực hiện thay đổi trong môi trường thực tế, hãy tạo một tài khoản thử nghiệm trong hộp cát bằng phương thức accounts.createTestAccount (xem hướng dẫn về Tài khoản thử nghiệm). Tài khoản thử nghiệm cung cấp một môi trường tách biệt, nơi các ưu đãi được phê duyệt theo mặc định, không cần xác minh miền và dữ liệu không bao giờ được phân phát công khai.

Sử dụng tài khoản thử nghiệm để phản ánh chế độ thiết lập chính thức và diễn tập quy trình di chuyển từ đầu đến cuối:

Sao chép chế độ thiết lập nguồn cấp dữ liệu dạng tệp: Tạo một nguồn dữ liệu chính dạng tệp (và mọi nguồn dữ liệu bổ sung) trong tài khoản thử nghiệm rồi tải một mẫu tệp nguồn cấp dữ liệu chính thức lên.
Tạo nguồn dữ liệu API thử nghiệm và các quy tắc: Tạo một nguồn dữ liệu chính API và định cấu hình mọi quy tắc thuộc tính bắt buộc hoặc các mối liên kết nguồn cấp dữ liệu bổ sung.
Kiểm tra việc tiếp quản quyền sở hữu và điều chỉnh khoá: Gửi yêu cầu productInputs.insert cho các sản phẩm mẫu và xác minh rằng nguồn dữ liệu API tiếp quản quyền sở hữu các mặt hàng hiện có mà không tạo ra sản phẩm trùng lặp.
Xác minh nội dung cập nhật và xoá: Kiểm tra nội dung cập nhật một phần bằng productInputs.patch và nội dung xoá bằng productInputs.delete, đồng thời kiểm tra tài nguyên thu được bằng products.get.

2. Tạo nguồn dữ liệu API Sản phẩm

Trước khi đẩy dữ liệu, hãy tạo một nguồn dữ liệu chính thuộc loại API trong tài khoản của bạn.

Tạo nguồn dữ liệu chính qua API

Để tạo một nguồn dữ liệu chấp nhận lệnh đẩy API, hãy gửi yêu cầu POST đến điểm cuối dataSources. Để biết thêm thông tin, hãy xem bài viết Tạo nguồn dữ liệu sản phẩm chính.

3. Chuyển đổi quy tắc thuộc tính tùy chỉnh

Quy tắc thuộc tính tuỳ chỉnh liên kết với các nguồn dữ liệu cụ thể và không tự động chuyển từ nguồn dữ liệu tệp sang nguồn dữ liệu API mới.

Cách bạn chuyển đổi quy tắc thuộc tính phụ thuộc vào mục đích của quy tắc:

Hợp nhất nhiều nguồn và nguồn cấp dữ liệu bổ sung của bên thứ ba: Nếu bạn kết hợp dữ liệu API chính với các nguồn dữ liệu bổ sung bên ngoài (chẳng hạn như tệp của nhà cung cấp bên thứ ba, bảng tính kho hàng hoặc nguồn cấp dữ liệu khuyến mãi), bạn phải tạo lại các quy tắc thuộc tính trong giao diện người dùng của Merchant Center và đính kèm các quy tắc đó vào nguồn dữ liệu API mới. Quá trình xử lý trước phía máy khách không thể thay thế các quy tắc kết hợp dữ liệu trên nhiều nguồn độc lập.
Biến đổi dữ liệu từ một nguồn: Để dọn dẹp, đặt giá trị mặc định hoặc định dạng chuỗi cho dữ liệu danh mục chính từ một nguồn, hãy chọn một trong các cách sau:
- Biến đổi phần phụ trợ (Nên dùng): Áp dụng các phép biến đổi trong hệ thống của riêng bạn trước khi gọi API. Điều này giúp bạn kiểm soát theo chương trình hiệu quả hơn, thử nghiệm dễ dàng hơn và gỡ lỗi đơn giản hơn.
- Quy tắc thuộc tính của Merchant Center: Tạo lại các quy tắc biến đổi cho nguồn dữ liệu API mới trong giao diện người dùng của Merchant Center nếu bạn muốn Merchant Center tiếp tục tự động quản lý các quy tắc đó.

4. Bật tính năng tích hợp API

Bật chế độ tích hợp API chính thức để bắt đầu chèn, cập nhật và xoá sản phẩm trong nguồn dữ liệu chính mới của API Sản phẩm:

Chèn và cập nhật sản phẩm (tiếp quản quyền sở hữu): Gửi yêu cầu productInputs.insert và productInputs.patch từ quy trình tích hợp của bạn. Khi bạn chèn một sản phẩm bằng API có cùng khoá (offerId, contentLanguage, feedLabel) với một sản phẩm hiện có trong nguồn cấp dữ liệu dạng tệp, nguồn dữ liệu API sẽ nắm quyền sở hữu sản phẩm đó và giữ nguyên nhật ký phân phát của sản phẩm. Để biết thêm hướng dẫn, hãy xem bài viết Chèn sản phẩm và Thêm và quản lý sản phẩm.

Quan trọng: Bạn chỉ có thể sử dụng productInputs.patch để cập nhật một sản phẩm đã được chèn vào nguồn dữ liệu chính của API. Trước khi cập nhật sản phẩm, hãy đảm bảo rằng bạn đã chèn sản phẩm vào nguồn dữ liệu chính của API (và do đó, nguồn dữ liệu chính của API sẽ sở hữu sản phẩm).
Xoá sản phẩm đã ngừng cung cấp: Định cấu hình chế độ tích hợp để gọi rõ ràng productInputs.delete bất cứ khi nào một sản phẩm bị xoá khỏi danh mục của bạn.
Triển khai dần dần: Đối với danh mục lớn, hãy bật tính năng tích hợp cho từng tài khoản phụ Merchant Center hoặc từng nguồn dữ liệu.
Định cấu hình tính năng xử lý đồng thời: Nếu bạn gửi nhiều yêu cầu, hãy định cấu hình ứng dụng để xử lý các yêu cầu đồng thời và quản lý nhiều kết nối. Hãy xem hướng dẫn Cải tiến mã cho các yêu cầu đồng thời.

5. Tạm dừng cập nhật nguồn dữ liệu dạng tệp

Sau khi tích hợp API, hãy dừng cập nhật tệp trước lần chạy tệp theo lịch tiếp theo để nguồn dữ liệu tệp không ghi đè lên nội dung cập nhật API:

Ngừng tải tệp mới lên vị trí SFTP/FTP, Google Cloud Storage hoặc Google Trang tính.
Trong giao diện người dùng của Merchant Center, hãy chuyển đến nguồn dữ liệu tệp của bạn và tạm dừng lịch tìm nạp.
Các sản phẩm hiện có thuộc nguồn dữ liệu tệp vẫn hoạt động trong tối đa 30 ngày cho đến khi chế độ tích hợp API chèn các sản phẩm đó.

6. Chờ quá trình di chuyển hoàn tất và xác minh

Chờ cho đến khi tất cả sản phẩm đang hoạt động di chuyển từ nguồn dữ liệu tệp sang nguồn dữ liệu API. Mặc dù các bản cập nhật gia tăng sẽ di chuyển sản phẩm khi sản phẩm thay đổi, nhưng việc chạy đồng bộ hoá toàn bộ danh mục theo tốc độ thông qua quá trình tích hợp thông thường sẽ giúp tăng tốc độ di chuyển toàn bộ danh mục (xem Chiến lược và hạn mức đồng bộ hoá).

Trong giai đoạn này:

Trong giao diện người dùng của Merchant Center, hãy theo dõi số lượng mặt hàng. Hãy đợi cho đến khi số lượng nguồn dữ liệu tệp giảm xuống còn 0 và số lượng nguồn dữ liệu API khớp với danh mục đang hoạt động của bạn.
Sử dụng products.get để xác minh rằng các thuộc tính và quy tắc thuộc tính tùy chỉnh hợp nhất như mong đợi.
Theo dõi công cụ Chẩn đoán API trong giao diện người dùng Merchant Center để theo dõi tỷ lệ lỗi và hiệu suất API.

7. Ngừng sử dụng nguồn dữ liệu tệp

Sau khi quá trình chuyển đổi hoàn tất và số lượng mục trong nguồn cấp dữ liệu tệp là 0:

Xác nhận rằng thông tin cập nhật được phản ánh theo thời gian thực.
Xoá nguồn dữ liệu tệp cũ trong giao diện người dùng của Merchant Center để tránh việc vô tình cập nhật dựa trên tệp và ghi đè dữ liệu API.

Migrate Local Inventory Ads settings