ย้ายข้อมูลจาก Content API for Shopping ไปยัง Merchant API

คู่มือนี้อธิบายกระบวนการย้ายข้อมูลจาก Content API for Shopping ไปยัง Merchant API เพื่อการจัดการข้อมูลธุรกิจ

คุณใช้คู่มือนี้เพื่อย้ายข้อมูลการติดตั้งใช้งาน Content API for Shopping ที่มีอยู่ไปยัง Merchant API ได้ ดูข้อมูลเพิ่มเติมเกี่ยวกับรายละเอียดของ Merchant API และ API ย่อยได้ที่การออกแบบ Merchant API

เริ่มต้นใช้งาน

หากต้องการเริ่มใช้ Merchant API ให้เปลี่ยน URL คำขอเป็นรูปแบบต่อไปนี้

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

หากต้องการใช้ Merchant API คุณต้องลิงก์บัญชี Merchant Center กับโปรเจ็กต์ Google Cloud โดยใช้วิธีการลงทะเบียนเป็นนักพัฒนาแอป ดังนี้

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

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

ดูข้อมูลเพิ่มเติมได้ที่คู่มือเริ่มใช้งานฉบับย่อและเอกสารอ้างอิง Merchant API

การปรับปรุงเมื่อเทียบกับ Content API for Shopping

Merchant API ช่วยให้คุณทำงานใน Merchant Center ได้โดยอัตโนมัติและมีประสิทธิภาพมากขึ้น รวมถึงมีฟีเจอร์ที่ปรับปรุงแล้วเมื่อเทียบกับ Content API for Shopping

กรณีการใช้งานหลัก

  • การจัดการบัญชีอัตโนมัติ
  • การจัดการผลิตภัณฑ์อัตโนมัติ
  • การจัดการพื้นที่โฆษณาอัตโนมัติ
  • การรายงานที่กำหนดเอง

ส่วนที่ปรับปรุงหลัก

การเปลี่ยนแปลงที่เกิดขึ้นมีดังนี้

  • pageSize สูงสุดเพิ่มขึ้นจาก 250 เป็น 1,000 แถวต่อการเรียก API
  • แก้ไขความล่าช้าที่เกิดขึ้นกับการแทรกผลิตภัณฑ์ โปรโมชัน รีวิวสินค้า และรีวิวผู้ขายหลังจาก DataSourcesสร้าง แก้ไขแล้ว
  • เปิดตัวคำจำกัดความที่อัปเดตสำหรับ clickPotentialRank ในตาราง productView ภายใต้ API ย่อยการรายงาน:
    • การจัดอันดับผลิตภัณฑ์ตาม clickPotential จะได้รับการปรับให้เป็นค่าระหว่าง 1 ถึง 1,000
  • AccountIdAlias ในแหล่งข้อมูล AccountRelationship ช่วยให้จัดการโครงสร้างบัญชีที่ซับซ้อนได้ดียิ่งขึ้น ตัวอย่างเช่น มาร์เก็ตเพลสใช้ชื่อแทนที่ผู้ใช้กำหนดแทนรหัสภายในของผู้ขาย เช่น รหัสบัญชี

การรองรับ gRPC

Merchant API รองรับ gRPC และ REST คุณสามารถใช้ gRPC สำหรับ Merchant API และ REST สำหรับ Content API for Shopping ได้พร้อมกัน

ไลบรารีของไคลเอ็นต์ Merchant API ต้องใช้ gRPC

ดูข้อมูลเพิ่มเติมได้ที่ ภาพรวมของ gRPC

ความเข้ากันได้

คู่มือนี้อธิบายการเปลี่ยนแปลงทั่วไปที่ใช้กับ Merchant API ทั้งหมด

Merchant API ได้รับการออกแบบมาให้ทำงานร่วมกับฟีเจอร์ Content API for Shopping ที่มีอยู่

ตัวอย่างเช่น คุณสามารถใช้ Merchant Inventories API ควบคู่ไปกับการติดตั้งใช้งาน Content API for Shopping v2.1 products ที่มีอยู่ คุณ อาจใช้ Content API for Shopping เพื่อ อัปโหลดผลิตภัณฑ์ใหม่ในร้าน (ที่คุณขาย ในร้านค้าจริง) จากนั้นใช้ LocalInventory แหล่งข้อมูลของ Merchant Inventories API เพื่อจัดการข้อมูลในร้านค้าสำหรับผลิตภัณฑ์ดังกล่าว

การปรับปรุงเมื่อเทียบกับ Content API

Merchant API ได้รับการปรับปรุงจาก Content API ในส่วนต่อไปนี้

พิจารณาการเปลี่ยนแปลงเหล่านี้ในรายละเอียดเพิ่มเติม

การกำหนดเวอร์ชันและ API ย่อย

Merchant API เปิดตัวแนวคิดเรื่อง การกำหนดเวอร์ชันและ API ย่อย การออกแบบแบบแยกส่วนช่วยให้ใช้งานได้ง่ายขึ้น โดยช่วยให้คุณมุ่งเน้นไปที่ API ย่อยที่ต้องการ และช่วยให้การย้ายข้อมูลในอนาคตไปยังเวอร์ชันใหม่ๆ ง่ายขึ้น ระบบจะใช้การกำหนดเวอร์ชันกับ URL คำขอ กลยุทธ์นี้ คล้ายกับประสบการณ์การใช้งาน Google Ads API

คำขอที่เสถียรมากขึ้น

คำขอ URL ของ Merchant API ต้องใช้พารามิเตอร์เพิ่มเติมในการเรียก Merchant API ซึ่งรวมถึงแหล่งข้อมูล เวอร์ชัน ชื่อ (ตัวระบุ) และเมธอด (เมธอดที่ไม่ใช่มาตรฐาน) ดูข้อมูลเพิ่มเติมเกี่ยวกับเรื่องนี้ได้ที่ตัวระบุ บัญชีและผลิตภัณฑ์และ ตัวอย่าง

หลักการ AIP สำหรับตัวระบุ

แม้ว่า Content API for Shopping จะใช้รหัสเพื่อระบุแหล่งข้อมูล (เช่น merchantId, productId) แต่ Merchant API ใช้ name ตัวระบุเพื่อให้สอดคล้องกับ AIP (ดู หลักการปรับปรุง API)

ตัวระบุ {name} ประกอบด้วยตัวระบุแหล่งข้อมูลและตัวระบุหลัก (หรืออาจมีหลายตัวระบุหลัก) โดยที่ {name} เท่ากับ accounts/{account}/products/{product}

การเรียกอ่านและเขียนทั้งหมดจะแสดงผลฟิลด์ name เป็นตัวระบุแหล่งข้อมูล

{name} ยังรวมถึงตัวระบุคอลเล็กชัน accounts/ และ products/ ด้วย

Merchant API ใช้ {account} เพื่ออ้างอิงรหัส Merchant Center และ {product} เพื่ออ้างอิงตัวระบุผลิตภัณฑ์

ตัวอย่างเช่น ใช้เมธอด getName() เพื่อดึงข้อมูล name จากแหล่งข้อมูล และจัดเก็บเอาต์พุตเป็นตัวแปรแทนการสร้าง name จากรหัสผู้ขายและรหัสแหล่งข้อมูลด้วยตนเอง

ตัวอย่างวิธีใช้ฟิลด์ name ในการเรียก

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

ตารางแสดงวิธีที่คำขอ products.get ของ Content API for Shopping เปลี่ยนไป

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}

ดูรายละเอียดเพิ่มเติมได้ที่การเปลี่ยนแปลง ตัวระบุ

อีกตัวอย่างหนึ่ง การดึงข้อมูลผลิตภัณฑ์ที่มีตัวระบุ en~US~1234 จากรหัส Merchant Center 4321 โดยใช้ Merchant API จะมีลักษณะดังนี้

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

โดยที่ {name} เท่ากับ accounts/4321/products/en~US~1234 ระบบจะแสดงผลฟิลด์ชื่อใหม่นี้เป็นตัวระบุแหล่งข้อมูลสำหรับการเรียกอ่านและเขียนทั้งหมดใน Merchant API

ใน Content API for Shopping เครื่องหมายโคลอน (:) หมายถึงตัวคั่นในชื่อสินค้า แต่ใน Merchant API เครื่องหมายทิลดา (~) จะทำหน้าที่นี้ ตัวระบุ Merchant API ไม่มีส่วน channel

ตัวอย่างเช่น รหัสสินค้าใน Content API for Shopping

channel:contentLanguage:feedLabel:offerId

ใน Merchant API จะกลายเป็นดังนี้

contentLanguage~feedLabel~offerId

ฟิลด์หลักสำหรับแหล่งข้อมูลย่อย

ใน Merchant API แหล่งข้อมูลย่อยทั้งหมดมี parent ฟิลด์ คุณสามารถใช้ฟิลด์ parent เพื่อระบุ {name} ของแหล่งข้อมูลที่จะแทรกแหล่งข้อมูลย่อยแทนการส่งแหล่งข้อมูลหลักทั้งหมด นอกจากนี้ คุณยังใช้ฟิลด์ parent กับ list ได้ด้วย

ตัวอย่างเช่น หากต้องการแสดงรายการสินค้าคงคลังในร้านสำหรับผลิตภัณฑ์ที่ระบุ ให้ระบุ ของผลิตภัณฑ์ name ในฟิลด์ parent สำหรับเมธอด list ในกรณีนี้ product ที่ระบุจะเป็น parent ของ LocalInventory ที่แสดงผล

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

หากต้องการดึงข้อมูลสินค้าคงคลังในร้านทั้งหมดสำหรับผลิตภัณฑ์ en~US~1234' และบัญชี 4321 คำขอจะมีลักษณะดังนี้

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

Parent คือ accounts/{account}/products/{product} โปรดทราบว่าในกรณีนี้ แหล่งข้อมูล localInventories มี Parent 2 รายการที่รวมอยู่ในตัวระบุชื่อ (accounts/ และ products/) เนื่องจากบัญชีเป็น Parent ของแหล่งข้อมูลผลิตภัณฑ์

Enum ทั่วไป

การใช้ Enum ทั่วไปช่วยให้มีความสอดคล้องกันมากขึ้น

ฟิลด์ Destination.DestinationEnum จะระบุแพลตฟอร์มที่จะแสดงแหล่งข้อมูล DestinationEnum แสดงรายการค่าทั้งหมดที่ใช้กำหนดเป้าหมายปลายทางได้ และเป็น ค่าเดียวกันใน API ย่อยต่างๆ เช่น สำหรับ แอตทริบิวต์ โปรโมชัน

The ReportingContext.ReportingContextEnum ฟิลด์แสดงถึงบริบทที่ใช้กับปัญหาเกี่ยวกับบัญชีและผลิตภัณฑ์ ฟิลด์นี้ใช้ในเมธอดการรายงาน (เช่น สำหรับ IssueSeverityPerReportingContext)

ความเข้ากันได้แบบย้อนหลัง

เมื่อคุณเริ่มใช้ Merchant API การผสานรวม Content API for Shopping ที่มีอยู่จะยังคงทำงานต่อไปโดยไม่มีการหยุดชะงัก ดูข้อมูลเพิ่มเติมได้ที่ ดู ความเข้ากันได้

เมื่อย้ายข้อมูล API ย่อยไปยัง Merchant API แล้ว เราขอแนะนำให้คุณใช้เฉพาะ Merchant API สำหรับ API ย่อยที่ย้ายข้อมูล

ความพร้อมใช้งานของการเรียกกระบวนการระยะไกล (gRPC)

gRPC เป็นวิธีใหม่ที่แนะนำให้ใช้ในการผสานรวม กับ Merchant API

ข้อดีของ gRPC ได้แก่

การจัดกลุ่มคำขอที่กำหนดเองจะกลายเป็นการจัดกลุ่มคำขอในตัว

การจัดกลุ่มคำขอจะทำงานได้อย่างมีประสิทธิภาพมากขึ้นเมื่อคุณใช้การเรียกแบบไม่พร้อมกัน ดูข้อมูลเพิ่มเติม เกี่ยวกับการใช้การเรียกแบบขนานเพื่อจัดกลุ่ม คำขอใน Merchant API และวิธี ปรับโครงสร้างโค้ดสำหรับคำขอ พร้อมกัน

เราขอแนะนำให้ใช้ ไลบรารีของไคลเอ็นต์ เพื่อช่วยเร่งการย้ายข้อมูล

Merchant API ไม่รองรับเมธอด customBatch ที่มีใน Content API for Shopping แต่ให้ดูที่ส่งคำขอหลายรายการ พร้อมกัน หรือเรียกใช้คำขอ แบบไม่พร้อมกัน

ตัวอย่าง Java ต่อไปนี้แสดงวิธีแทรกข้อมูลผลิตภัณฑ์

   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.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().setPoolSize(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);
  }
}
InsertProductInputAsyncSample.java

หากคุณใช้ customBatch ใน Content API และต้องการฟีเจอร์นี้สำหรับ Merchant API โปรดแจ้งให้เราทราบเหตุผลใน ความคิดเห็น

ฟีเจอร์สุดพิเศษ

ฟีเจอร์ในอนาคตจะปรากฏใน Merchant API เท่านั้น (จะมีข้อยกเว้นบางประการ เช่น ข้อกำหนดเฉพาะของฟีดประจำปี 2025)

ฟีเจอร์สุดพิเศษของ Merchant API ได้แก่

  • Reviews API ใช้รีวิวเพื่อติดตั้งใช้งานและจัดการคะแนนผลิตภัณฑ์และคะแนนร้านค้า ดูข้อมูลเพิ่มเติมได้ที่รีวิวผู้ขายและรีวิวผลิตภัณฑ์
  • การแจ้งเตือน: ลงชื่อสมัครรับ การแจ้งเตือนแบบพุชสำหรับการเปลี่ยนแปลงข้อมูลสินค้าของบัญชี

ราคา

สิ่งที่เปลี่ยนแปลงสำหรับ Price ในแพ็กเกจ Merchant Common มีดังนี้

Content API for Shopping Merchant API
ช่องจำนวนเงิน value:string amountMicros:int64
ช่องสกุลเงิน currency:string currencyCode:string

ตอนนี้ระบบจะบันทึกจำนวนเงิน Price เป็นหน่วยไมโคร โดย 1 ล้านหน่วยไมโครเทียบเท่ากับหน่วยมาตรฐานของสกุลเงิน

ใน Content API for Shopping Price เป็นเลขทศนิยมในรูปแบบสตริง

ชื่อฟิลด์จำนวนเงินเปลี่ยนจาก value เป็น amountMicros

ชื่อฟิลด์สกุลเงินเปลี่ยนจาก currency เป็น currencyCode รูปแบบยังคงเป็น ISO 4217

ข้อมูลอัปเดตและการประกาศล่าสุด

ดูข้อมูลอัปเดตที่ละเอียดยิ่งขึ้นได้ในบันทึกประจำรุ่นของ API ย่อยแต่ละรายการ หากต้องการดูข้อมูลอัปเดต Merchant API ที่รวบรวมเป็นประจำ โปรดดูข้อมูลอัปเดตล่าสุด

ดูรายละเอียดเพิ่มเติมและเรียนรู้เพิ่มเติมเกี่ยวกับ Merchant API ได้ที่ ภาพรวมเว็บไซต์สำหรับนักพัฒนาแอป และคู่มือการย้ายข้อมูลโดยรวม

ดูรายละเอียดเกี่ยวกับ Merchant API และ API ย่อยได้ที่การออกแบบ Merchant API

ถัดไป
Start your migration