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 cách triển khai Content API for Shopping hiện tại sang Merchant API. Để biết thêm thông tin về Merchant API và các API phụ, hãy xem bài viết 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ới dự án trên đám mây 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 tính 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ảng không quảng cáo tự động
  • Báo cáo tuỳ chỉnh

Các khía cạnh chính cần cải thiện:

Những điểm thay đổi

  • 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á của người bán sau khi tạo DataSources.
  • Ra mắt định nghĩa mới cho clickPotentialRank trong bảng productView thuộc 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.
  • AccountIdAlias trong tài nguyên AccountRelationship giúp bạn quản lý các 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 bí danh 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 phần 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 API Kho hàng cùng với phiên bản 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 mới tại cửa hàng địa phương lên (sản phẩm bạn bán tại 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 đó.

Cải tiến về cấu trúc so với Content API

Merchant API cải thiện Content API ở những khía cạnh sau:

Hãy xem xét những thay đổi này một cách chi tiết hơn.

Tạo phiên bản và API phụ

Merchant API giới thiệu các khái niệm về tạo phiên bản và API phụ. Thiết kế mô-đun của API này giúp bạn dễ dàng sử dụng hơn bằng cách cho phép bạn tập trung vào các API phụ mà bạn cần, đồng thời giúp bạn dễ dàng di chuyển sang các phiên bản mới hơn trong tương lai. Tính năng tạo phiên bản sẽ được áp dụng cho URL yêu cầu của bạn. 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

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

Nguyên tắc AIP cho giá trị 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 giá trị nhận dạng name để phù hợp với AIP (xem 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à tài nguyên mẹ (hoặc có thể là nhiều tài nguyên mẹ), sao cho {name} bằng accounts/{account}/products/{product}

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

{name} cũng bao gồm giá trị nhận dạng tập hợp accounts/ và products/.

Merchant API sử dụng {account} để tham chiếu đến mã truy cập Merchant Center và {product} để tham chiếu đến mã nhận dạng sản phẩm.

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

Dưới đây là ví dụ về cách sử dụng trường name trong lệnh gọi:

   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 Thay đổi về giá trị nhận dạng.

Một ví dụ khác, 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/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 giá trị nhận dạng tài nguyên cho tất 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, còn 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 như sau:

contentLanguage~feedLabel~offerId.

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 tài nguyên con 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/en~US~1234/localInventories

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

Enum phổ biến

Việc sử dụng 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 nơi tài nguyên của bạn sẽ xuất hiệ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ụ: cho thuộc tính khuyến mãi.

Trường ReportingContext.ReportingContextEnum thể hiện bối cảnh áp dụng các vấn đề về tài khoản và sản phẩm của bạn. 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, quá trình tích hợp Content API for Shopping hiện tại của bạn vẫn 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 phần 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.

Phạm vi cung cấp lệnh gọi quy trình từ xa (gRPC)

gRPC là cách mới được đề xuất để tích hợp với Merchant API.

Những lợi thế khi sử dụng phương pháp này gồm:

Tính năng gom theo lô tuỳ chỉnh trở thành tính năng gom theo lô tích hợp sẵn

Tính năng gom theo lô hoạt động hiệu quả hơn khi bạn sử dụng lệnh gọi không đồng bộ. Tìm hiểu thêm về cách sử dụng lệnh gọi song song để gom theo lô trong Merchant API và cách cải tiến mã cho các yêu cầu đồng thời.

Để đẩ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 lúc hoặc thực thi các lệnh gọi không đồng bộ.

Mẫu Java sau đây minh hoạ cách chèn 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.api.gax.grpc.ChannelPoolSettings;
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
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 a channel provider. This provider manages a pool of gRPC channels
    // to enhance throughput for bulk operations. Each individual channel in the pool
    // can handle up to approximately 100 concurrent requests.
    //
    // Channel: A single connection pathway to the service.
    // Pool: A collection of multiple channels managed by this provider.
    //   Requests are distributed across the channels in the pool.
    //
    // We recommend estimating the number of concurrent requests you'll make, divide by 50 (50%
    // utilization of channel capacity), and set the pool size to that number.
    InstantiatingGrpcChannelProvider channelProvider =
        InstantiatingGrpcChannelProvider.newBuilder()
            .setChannelPoolSettings(ChannelPoolSettings.staticallySized(30))
            .build();

    // Creates service settings using the credentials retrieved above.
    ProductInputsServiceSettings productInputsServiceSettings =
        ProductInputsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .setTransportChannelProvider(channelProvider)
            .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);
  }
}

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 vài 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 chỉ có trong Merchant API bao gồm:

  • Reviews API. Sử dụng tính năng Bài đá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 Bài đánh giá của người bán và Bài đánh giá sản phẩm.
  • Thông báo: Đăng ký nhận thông báo đẩy về những thay đổi đối với dữ liệu tài khoản và sản phẩm.

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

Số tiền Price hiện được ghi lại bằng đơ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ền tệ chuẩn của bạn.

Trong Content API for Shopping, Price là một số thập phân ở 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 vẫn là ISO 4217.

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

Để biết thêm thông tin cập nhật chi tiết, 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 tổng hợp 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 tổng quan trên trang web dành cho nhà phát triển và hướng dẫn di chuyển tổng thể để biết thêm thông tin chi tiết.

Hãy xem bài viết 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
Manage and transition Google Cloud projects
Tiếp
Start your migration