Di chuyển từ Content API for Shopping sang Merchant API

Hướng dẫn này giải thích quy trình di chuyển từ Content API for Shopping sang Merchant API để quản lý dữ liệu doanh nghiệp.

Bạn có thể sử dụng hướng dẫn này để di chuyển chế độ triển khai Content API for Shopping hiện có sang Merchant API. Để biết thêm thông tin về chi tiết của Merchant API và các API phụ của API này, hãy xem Thiết kế Merchant API.

Bắt đầu

Để bắt đầu sử dụng Merchant API, hãy thay đổi URL yêu cầu của bạn thành định dạng sau:

https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME}:{METHOD}…

Để sử dụng Merchant API, bạn phải liên kết tài khoản Merchant Center và dự án Google Cloud bằng phương thức Đăng ký nhà phát triển, như sau:

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

{
  developer_email:"example-email@example.com"
}

Để biết thêm thông tin, hãy xem hướng dẫn bắt đầu nhanh và tài liệu tham khảo về Merchant API.

Những điểm cải tiến so với Content API for Shopping

Merchant API giúp bạn tự động hoá và đơn giản hoá quy trình làm việc trong Merchant Center, đồng thời cung cấp các chức năng nâng cao so với Content API for Shopping.

Các trường hợp sử dụng chính:

  • Quản lý tài khoản tự động
  • Quản lý sản phẩm tự động
  • Quản lý kho hàng tự động
  • Báo cáo tuỳ chỉnh

Các lĩnh vực cần cải thiện chính:

Những điều đã thay đổi:

  • Số lượng pageSize tối đa đã tăng từ 250 lên 1.000 hàng cho mỗi lệnh gọi API.
  • Đã khắc phục tình trạng chậm trễ khi chèn sản phẩm, chương trình khuyến mãi, bài đánh giá sản phẩm và bài đánh giá người bán sau khi tạo DataSources.

Những điểm sắp ra mắt:

  • Ra mắt định nghĩa mới cho clickPotentialRank trong bảng productView trong API phụ Báo cáo: * Thứ hạng của sản phẩm dựa trên clickPotential được chuẩn hoá thành các giá trị từ 1 đến 1000.
    • Những sản phẩm có clickPotentialRank thấp vẫn có khả năng nhận được nhiều lượt nhấp nhất trong số những sản phẩm của người bán đáp ứng các điều kiện của cụm từ tìm kiếm. Đây là một thay đổi không làm gián đoạn và có thể được ra mắt vào ngày 1 tháng 7 năm 2025.
  • AccountIdAlias trong tài nguyên AccountRelationship giúp bạn quản lý cấu trúc tài khoản phức tạp hiệu quả hơn. Ví dụ: trang web thương mại sử dụng một biệt hiệu do người dùng xác định thay vì mã nhận dạng nội bộ của người bán, chẳng hạn như mã tài khoản.

Hỗ trợ gRPC

Merchant API hỗ trợ gRPC và REST. Bạn có thể sử dụng gRPC cho Merchant API và REST cho Content API for Shopping cùng một lúc.

Thư viện ứng dụng Merchant API yêu cầu gRPC.

Để biết thêm thông tin, hãy xem Tổng quan về gRPC.

Khả năng tương thích

Hướng dẫn này mô tả những thay đổi chung áp dụng cho toàn bộ Merchant API.

Merchant API được thiết kế để hoạt động cùng với các tính năng hiện có của Content API for Shopping.

Ví dụ: bạn có thể sử dụng Merchant Inventories API cùng với chế độ triển khai Content API for Shopping phiên bản 2.1 products hiện có. Bạn có thể sử dụng Content API for Shopping để tải một sản phẩm địa phương mới lên (sản phẩm mà bạn bán tại một cửa hàng địa phương), sau đó sử dụng tài nguyên Merchant Inventories API LocalInventory để quản lý thông tin tại cửa hàng cho sản phẩm đó.

Những điểm cải tiến so với Content API

Merchant API cải thiện Content API ở những điểm sau:

Hãy xem xét kỹ hơn những thay đổi này.

Phân phiên bản và API phụ

Merchant API giới thiệu các khái niệm về phiên bản và API phụ. Thiết kế theo mô-đun giúp cải thiện tính dễ sử dụng bằng cách cho phép bạn tập trung vào các API phụ mà bạn cần và giúp việc di chuyển trong tương lai sang các phiên bản mới trở nên dễ dàng hơn. Tính năng lập phiên bản sẽ được áp dụng cho URL yêu cầu.Chiến lược này tương tự như trải nghiệm Google Ads API.

Yêu cầu mạnh mẽ hơn

Các yêu cầu về URL Merchant API cần thêm nhiều tham số để gọi Merchant API. Điều này bao gồm tài nguyên, phiên bản, tên (các giá trị nhận dạng) và phương thức (các phương thức không chuẩn). Để biết thêm thông tin về vấn đề này, hãy xem Mã nhận dạng tài khoản và sản phẩm và ví dụ.

Nguyên tắc AIP đối với mã nhận dạng

Trong khi Content API for Shopping sử dụng mã nhận dạng để xác định tài nguyên (ví dụ: merchantId, productId), Merchant API sử dụng mã nhận dạng name để phù hợp với AIP (xem các nguyên tắc cải thiện API).

Giá trị nhận dạng {name} bao gồm giá trị nhận dạng tài nguyên và giá trị nhận dạng mẹ (hoặc có thể là nhiều giá trị nhận dạng mẹ), sao cho {name} bằng accounts/{account}/products/{product}

Tất cả các lệnh gọi đọc và ghi đều trả về trường name dưới dạng giá trị nhận dạng tài nguyên.

{name} cũng bao gồm các mã nhận dạng bộ sưu tập accounts/ và products/.

Merchant API sử dụng {account} để chỉ mã nhận dạng Merchant Center và {product} để chỉ mã nhận dạng sản phẩm.

Ví dụ: hãy triển khai phương thức getName() để truy xuất name từ một tài nguyên và lưu trữ đầu ra dưới dạng một biến thay vì tự tạo name từ mã nhận dạng người bán và tài nguyên.

Sau đây là ví dụ về cách sử dụng trường name trong các lệnh gọi của bạn:

   POST https://merchantapi.googleapis.com/inventories/v1/{PARENT}/regionalInventories:insert

Bảng này cho biết cách yêu cầu products.get của Content API for Shopping thay đổi:

Content API for Shopping Merchant API
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} GET https://merchantapi.googleapis.com/products/v1/{name}

Để biết thêm thông tin, hãy xem bài viết Các thay đổi về giá trị nhận dạng.

Một ví dụ khác là việc truy xuất một sản phẩm có giá trị nhận dạng en~US~1234 từ mã truy cập Merchant Center 4321 bằng Merchant API sẽ có dạng như sau:

    GET
    https://merchantapi.googleapis.com/products/v1/accounts/4321/products/online~en~US~1234

trong đó {name} bằng accounts/4321/products/en~US~1234. Trường tên mới này được trả về dưới dạng mã nhận dạng tài nguyên cho tất cả các lệnh gọi đọc và ghi trong Merchant API.

Trong Content API for Shopping, dấu hai chấm (:) biểu thị dấu phân cách trong tên sản phẩm, trong khi trong Merchant API, dấu ngã (~) thực hiện chức năng này. Giá trị nhận dạng Merchant API không chứa phần channel.

Ví dụ: mã sản phẩm trong Content API for Shopping:

channel:contentLanguage:feedLabel:offerId.

trong Merchant API sẽ trở thành:

contentLanguage~feedLabel~offerId.

Các trường mẹ cho tài nguyên con

Trong Merchant API, tất cả tài nguyên con đều có trường parent. Bạn có thể sử dụng trường parent để chỉ định {name} của tài nguyên để chèn trẻ vào, thay vì truyền toàn bộ tài nguyên mẹ. Bạn cũng có thể sử dụng trường parent với list

Ví dụ: để liệt kê kho hàng tại địa phương cho một sản phẩm nhất định, hãy chỉ định name của sản phẩm trong trường parent cho phương thức list. Trong trường hợp này, product đã cho là parent của tài nguyên LocalInventory được trả về.

    GET
    https://merchantapi.googleapis.com/inventories/v1/{parent}/localInventories

Để truy xuất tất cả kho hàng tại địa phương cho sản phẩm en~US~1234' và tài khoản 4321, yêu cầu sẽ có dạng như sau

    GET
    https://merchantapi.googleapis.com/inventories/v1/accounts/4321/products/online~en~US~1234/localInventories</code>

Phần tử mẹ là accounts/{account}/products/{product}. Xin lưu ý rằng trong trường hợp này, tài nguyên localInventories có 2 tài nguyên mẹ có trong mã nhận dạng tên (accounts/ và products/), vì tài khoản này là tài khoản mẹ của tài nguyên sản phẩm.

Các enum phổ biến

Việc sử dụng các enum phổ biến giúp tăng tính nhất quán.

Trường Destination.DestinationEnum chỉ định các nền tảng để hiển thị tài nguyên của bạn. DestinationEnum liệt kê tất cả các giá trị có sẵn cho tiêu chí nhắm mục tiêu theo vị trí xuất hiện và được hợp nhất trên các API phụ, ví dụ: đối với thuộc tính khuyến mãi.

Trường ReportingContext.ReportingContextEnum đại diện cho bối cảnh mà vấn đề về tài khoản và sản phẩm của bạn áp dụng. Trường này được dùng trong các phương thức báo cáo (ví dụ: cho IssueSeverityPerReportingContext).

Khả năng tương thích ngược

Khi bạn bắt đầu sử dụng Merchant API, chế độ tích hợp Content API for Shopping hiện tại của bạn sẽ tiếp tục hoạt động mà không bị gián đoạn. Để biết thêm thông tin, hãy xem bài viết Khả năng tương thích.

Sau khi di chuyển các API phụ sang Merchant API, bạn chỉ nên sử dụng Merchant API cho các API phụ đã di chuyển.

Khả năng hỗ trợ lệnh gọi quy trình từ xa (gRPC)

gRPC là cách mới mà bạn nên dùng để tích hợp với Merchant API.

Các ưu điểm của phương pháp này bao gồm:

Tính năng kết hợp tuỳ chỉnh sẽ trở thành tính năng kết hợp tích hợp

Việc xử lý hàng loạt sẽ hiệu quả hơn khi bạn sử dụng các lệnh gọi không đồng bộ. Tìm hiểu thêm về cách sử dụng các lệnh gọi song song để đạt được việc xử lý hàng loạt trong Merchant API và cách Tái cấu trúc mã cho các yêu cầu đồng thời.

Để giúp đẩy nhanh quá trình di chuyển, bạn nên sử dụng thư viện ứng dụng.

Merchant API không hỗ trợ phương thức customBatch có trong Content API for Shopping. Thay vào đó, hãy xem phần Gửi nhiều yêu cầu cùng một lúc hoặc thực thi các lệnh gọi của bạn một cách không đồng bộ.

Mẫu Java sau đây minh hoạ cách chèn một dữ liệu đầu vào của sản phẩm.

   import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.shopping.merchant.products.v1.Availability;
import com.google.shopping.merchant.products.v1.Condition;
import com.google.shopping.merchant.products.v1.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1.ProductAttributes;
import com.google.shopping.merchant.products.v1.ProductInput;
import com.google.shopping.merchant.products.v1.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1.Shipping;
import com.google.shopping.type.Price;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert a product input */
public class InsertProductInputAsyncSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static ProductInput createRandomProduct() {
    Price price = Price.newBuilder().setAmountMicros(33_450_000).setCurrencyCode("USD").build();

    Shipping shipping =
        Shipping.newBuilder().setPrice(price).setCountry("GB").setService("1st class post").build();

    Shipping shipping2 =
        Shipping.newBuilder().setPrice(price).setCountry("FR").setService("1st class post").build();

    ProductAttributes attributes =
        ProductAttributes.newBuilder()
            .setTitle("A Tale of Two Cities")
            .setDescription("A classic novel about the French Revolution")
            .setLink("https://exampleWebsite.com/tale-of-two-cities.html")
            .setImageLink("https://exampleWebsite.com/tale-of-two-cities.jpg")
            .setAvailability(Availability.IN_STOCK)
            .setCondition(Condition.NEW)
            .setGoogleProductCategory("Media > Books")
            .addGtins("9780007350896")
            .addShipping(shipping)
            .addShipping(shipping2)
            .build();

    return ProductInput.newBuilder()
        .setContentLanguage("en")
        .setFeedLabel("CH")
        .setOfferId(generateRandomString())
        .setProductAttributes(attributes)
        .build();
  }

  public static void asyncInsertProductInput(Config config, String dataSource) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    ProductInputsServiceSettings productInputsServiceSettings =
        ProductInputsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to insert the product.
    String parent = getParent(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (ProductInputsServiceClient productInputsServiceClient =
        ProductInputsServiceClient.create(productInputsServiceSettings)) {

      // Creates five insert product input requests with random product IDs.
      List<InsertProductInputRequest> requests = new ArrayList<>(5);
      for (int i = 0; i < 5; i++) {
        InsertProductInputRequest request =
            InsertProductInputRequest.newBuilder()
                .setParent(parent)
                // You can only insert products into datasource types of Input "API", and of Type
                // "Primary" or "Supplemental."
                // This field takes the `name` field of the datasource.
                .setDataSource(dataSource)
                // If this product is already owned by another datasource, when re-inserting, the
                // new datasource will take ownership of the product.
                .setProductInput(createRandomProduct())
                .build();

        requests.add(request);
      }

      System.out.println("Sending insert product input requests");
      List<ApiFuture<ProductInput>> futures =
          requests.stream()
              .map(
                  request ->
                      productInputsServiceClient.insertProductInputCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<ProductInput>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<ProductInput>>() {
            @Override
            public void onSuccess(List<ProductInput> results) {
              System.out.println("Inserted products below");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // Identifies the data source that will own the product input.
    String dataSource = "accounts/" + config.getAccountId() + "/dataSources/{datasourceId}";

    asyncInsertProductInput(config, dataSource);
  }
}
InsertProductInputAsyncSample.java

Nếu bạn sử dụng customBatch trong Content API và cần tính năng này cho Merchant API, hãy cho chúng tôi biết lý do trong ý kiến phản hồi của bạn.

Các tính năng độc quyền

Các tính năng trong tương lai sẽ chỉ xuất hiện trong Merchant API. (Sẽ có một số trường hợp ngoại lệ, chẳng hạn như quy cách nguồn cấp dữ liệu hằng năm năm 2025.)

Các tính năng dành riêng cho Merchant API bao gồm

  • Reviews API. Sử dụng phần Đánh giá để triển khai và quản lý điểm xếp hạng sản phẩm và cửa hàng. Để biết thêm thông tin, hãy xem bài viết Đánh giá người bán và Đánh giá sản phẩm.
  • Thông báo: Đăng ký nhận thông báo đẩy về các thay đổi đối với dữ liệu sản phẩm của một tài khoản.

Giá

Sau đây là những thay đổi đối với Price trong gói Merchant Common:

Content API for Shopping Merchant API
Trường số tiền value:string amountMicros:int64
Trường đơn vị tiền tệ currency:string currencyCode:string

Giờ đây, số tiền Price được ghi lại theo đơn vị một phần triệu, trong đó 1 triệu đơn vị một phần triệu tương đương với đơn vị tiêu chuẩn của đơn vị tiền tệ.

Trong Content API for Shopping, Price là một số thập phân dưới dạng chuỗi.

Tên trường số tiền đã thay đổi từ value thành amountMicros

Tên trường đơn vị tiền tệ đã thay đổi từ currency thành currencyCode. Định dạng này vẫn là ISO 4217.

Thông tin cập nhật và thông báo mới nhất

Để biết thông tin cập nhật chi tiết hơn, hãy xem ghi chú phát hành dành riêng cho từng API phụ. Để biết thêm thông tin cập nhật thường xuyên về Merchant API, hãy xem thông tin cập nhật mới nhất của chúng tôi.

Để biết thêm thông tin cụ thể và tìm hiểu thêm về Merchant API, hãy xem thông tin tổng quan về trang web dành cho nhà phát triển và hướng dẫn tổng thể về việc di chuyển để biết thêm thông tin chi tiết.

Hãy xem thiết kế Merchant API để biết thông tin chi tiết về Merchant API và các API phụ của API này.

Trước
Quickstart
Tiếp
Migrate accountstatuses to Account Issues