ย้ายข้อมูลจาก 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 โดยใช้วิธีการลงทะเบียนนักพัฒนาแอป ดังนี้

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 เพื่ออัปโหลดผลิตภัณฑ์ในร้าน (ที่คุณขายในร้านค้า) จากนั้นใช้แหล่งข้อมูล Merchant Inventories API LocalInventory เพื่อจัดการข้อมูลในร้านค้าสำหรับผลิตภัณฑ์นั้น

การปรับปรุงโครงสร้างผ่าน 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/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/en~US~1234/localInventories

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

Enum ทั่วไป

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

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

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

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

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

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

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

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

ข้อดี ได้แก่

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

การจัดกลุ่มจะมีประสิทธิภาพมากขึ้นเมื่อคุณใช้การเรียกแบบอะซิงโครนัส ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้การเรียกพร้อมกันเพื่อให้ได้การรวมกลุ่มใน 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.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);
  }
}

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

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

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

ฟีเจอร์ที่มีเฉพาะใน Merchant 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