ย้ายข้อมูลจาก 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/v1beta/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

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

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

ดูข้อมูลอัปเดตล่าสุดใน Merchant API (เบต้า)

การปรับปรุง Content API for Shopping

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

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

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

ด้านการปรับปรุงที่สำคัญ

  • API ย่อยที่มีฟีเจอร์ใหม่ๆ ได้แก่
    • การติดตามคำสั่งซื้อ รองรับประวัติการติดตามคำสั่งซื้อของธุรกิจเพื่อระบุการนำส่งโดยประมาณที่แม่นยำและถูกต้อง ให้แก่ลูกค้า สัญญาณยังช่วยให้ข้อมูลได้รับการเพิ่มประสิทธิภาพด้วยการจัดส่งฟรีและรวดเร็ว
    • การแก้ปัญหา ให้สิทธิ์เข้าถึงเนื้อหาการวินิจฉัยและการดำเนินการสนับสนุนในลักษณะเดียวกับที่ มีให้บริการใน UI ของ Merchant Center
    • Product Studio (ALPHA) ใช้ GenAI เพื่อสร้างและเพิ่มประสิทธิภาพชื่อและคำอธิบายผลิตภัณฑ์ คุณต้องลงนามในแบบฟอร์มนี้เพื่อขอ สิทธิ์เข้าถึง
    • ทรัพยากรใหม่ใน Accounts sub-API
    • OmnichannelSettings จัดการการกำหนดค่าบัญชีสำหรับการแสดงผลแบบหลายช่องทาง เช่น ข้อมูลในร้านที่แสดงฟรี (FLL) และโฆษณาสินค้าคงคลังในร้าน (LIA)
    • LfpProviders เชื่อมต่อกับพาร์ทเนอร์โปรแกรมพาร์ทเนอร์ทางธุรกิจสำหรับฟีดในร้าน (LFP) เพื่อรับข้อมูลสินค้าคงคลัง
    • GbpAccounts เชื่อมต่อกับบัญชี Google Business Profile สำหรับข้อมูลร้านค้าในพื้นที่
    • OnlineReturnPolicy ช่วยให้คุณสร้าง ลบ และอัปเดตนโยบายออนไลน์ได้
  • วิธีการใหม่สำหรับสินค้าคงคลัง ข้อมูลผลิตภัณฑ์ และ API อื่นๆ ได้แก่
    • เมธอดใหม่ใน Products sub-API
    • ProductsUpdate ช่วยให้คุณอัปเดตผลิตภัณฑ์แต่ละรายการได้โดยไม่ต้องระบุฟิลด์ทั้งหมดที่จำเป็นสำหรับ ProductInput
  • ความสามารถในการสร้างไม่เพียงแต่แหล่งข้อมูลหลัก แต่ยังสร้างแหล่งข้อมูลหลายแหล่งได้ด้วย เช่น
  • เปิดตัวการอัปโหลดรีวิวผลิตภัณฑ์และรีวิวผู้ขาย
  • Merchant API ช่วยให้คุณเปิดใช้การแจ้งเตือนสำหรับการเปลี่ยนแปลงข้อมูลบัญชีได้

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

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

สิ่งที่จะเกิดขึ้น

  • การเลิกใช้งานและการนำฟิลด์ช่องออกในอนาคตสำหรับ DataSources และผลิตภัณฑ์
  • การเปิดตัวคำจำกัดความที่อัปเดตแล้วสำหรับ clickPotentialRank ในตาราง productView ภายใต้ Reporting sub-API: * การจัดอันดับผลิตภัณฑ์ตาม clickPotential จะได้รับการปรับให้เป็นค่า ระหว่าง 1 ถึง 1000
    • ผลิตภัณฑ์ที่มี clickPotentialRank ต่ำยังคงมีโอกาสคลิกสูงสุดในบรรดาผลิตภัณฑ์ของผู้ขายที่ตรงตามเงื่อนไขของคำค้นหา การเปลี่ยนแปลงนี้ไม่ใช่การเปลี่ยนแปลงที่ทำให้เกิดข้อขัดข้อง และอาจเปิดตัวในวันที่ 1 กรกฎาคม 2025
  • 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}identifier ประกอบด้วยตัวระบุทรัพยากรและตัวระบุหลัก (หรืออาจมีตัวระบุหลักหลายรายการ) เพื่อให้ {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/v1beta/{PARENT}/regionalInventories:insert

ตารางแสดงการเปลี่ยนแปลงคำขอ Content API for Shopping products.get ดังนี้

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

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

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

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

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

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

เช่น รหัสผลิตภัณฑ์ใน Content API for Shopping

channel:contentLanguage:feedLabel:offerId

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

channel~contentLanguage~feedLabel~offerId

ฟิลด์ระดับบนสุดสำหรับทรัพยากรระดับล่าง

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

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

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

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

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

ผู้ปกครองคือ 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.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.shopping.merchant.products.v1beta.Attributes;
import com.google.shopping.merchant.products.v1beta.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1beta.ProductInput;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1beta.Shipping;
import com.google.shopping.type.Channel.ChannelEnum;
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();

    Attributes attributes =
        Attributes.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("in stock")
            .setCondition("new")
            .setGoogleProductCategory("Media > Books")
            .addGtin("9780007350896")
            .addShipping(shipping)
            .addShipping(shipping2)
            .build();

    return ProductInput.newBuilder()
        .setChannel(ChannelEnum.ONLINE)
        .setContentLanguage("en")
        .setFeedLabel("CH")
        .setOfferId(generateRandomString())
        .setAttributes(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

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

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

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

ฟีเจอร์พิเศษสำหรับ Merchant API มีดังนี้

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

ราคา

สิ่งที่เปลี่ยนแปลงสำหรับ 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

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

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

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

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

ก่อนหน้า
Quickstart
ถัดไป
Migrate from accountstatuses to Account Issues