מעבר מ-Content API for Shopping ל-Merchant API

במדריך הזה מוסבר תהליך המיגרציה מ-Content API for Shopping אל Merchant API לניהול נתונים עסקיים.

במדריך הזה מוסבר איך להעביר את ההטמעה הקיימת של Content API for Shopping אל Merchant API. מידע נוסף על הפרטים של Merchant API וממשקי המשנה שלו זמין במאמר Merchant API design.

שנתחיל?

כדי להתחיל להשתמש ב-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.

תרחישי שימוש עיקריים:

  • ניהול חשבונות אוטומטי
  • ניהול אוטומטי של מוצרים
  • ניהול מלאי שטחי פרסום אוטומטי
  • דוחות בהתאמה אישית

תחומי שיפור עיקריים:

מה השתנה:

  • המספר המקסימלי של pageSize עלה מ-250 ל-1,000 שורות לכל קריאה ל-API.
  • תוקן עיכוב שהיה בהוספת מוצרים, מבצעים, ביקורות על מוצרים וביקורות על מוכרים אחרי יצירת DataSources.

מה צפוי:

  • הוצאה משימוש והסרה עתידית של שדה הערוץ עבור DataSources ומוצרים.
  • השקנו הגדרה מעודכנת של clickPotentialRank בטבלה productView בקטע Reporting sub-API: * הדירוג של המוצרים על סמך clickPotential מנורמל לערכים בין 1 ל-1,000.
    • למוצרים עם ערך 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 לצד ההטמעה הקיימת של productsContent API for Shopping גרסה 2.1. אפשר להשתמש ב-Content API for Shopping כדי להעלות מוצר מקומי חדש (שנמכר בחנות מקומית), ואז להשתמש במשאב Merchant Inventories API‏ LocalInventory כדי לנהל את פרטי המוצר בחנות.

שיפורים לעומת Content API

‫Merchant API משפר את Content API בתחומים הבאים:

כדאי לעיין בשינויים האלה בפירוט.

ניהול גרסאות ו-sub-APIs

ב-Merchant API מוצגים המושגים ניהול גרסאות וממשקי API משניים. העיצוב המודולרי שלו משפר את קלות השימוש, כי הוא מאפשר לכם להתמקד בממשקי ה-API המשניים שאתם צריכים, ומקל על מעבר עתידי לגרסאות חדשות יותר. הוספת גרסאות תתבצע עם כתובות ה-URL של הבקשות.האסטרטגיה דומה לחוויית השימוש ב-Google Ads API.

בקשות חזקות יותר

כדי לשלוח קריאה ל-Merchant API באמצעות בקשות לכתובות URL של 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/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 יש שני הורים שכלולים במזהה השם (accounts/ ו-products/), כי החשבון הוא ההורה של מקור המידע product.

סוגי 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 כוללות

מחיר

אלה השינויים שבוצעו בחבילה Merchant Common עבור Price:

Content API for Shopping Merchant API
שדה הסכום value:string amountMicros:int64
שדה מטבע currency:string currencyCode:string

הסכום Price מתועד עכשיו במיקרו, כאשר מיליון מיקרו שווה ליחידה הסטנדרטית של המטבע שלכם.

ב-Content API for Shopping, הערך של Price היה מספר עשרוני בפורמט של מחרוזת.

השם של שדה הסכום השתנה מ-value ל-amountMicros

השם של שדה המטבע השתנה מ-currency ל-currencyCode. הפורמט נשאר ISO 4217.

העדכונים וההודעות האחרונים

לעדכונים מפורטים יותר, אפשר לעיין בהערות המוצר שספציפיות לכל API משני. כדי לקבל עדכונים קבועים יותר על Merchant API, אפשר לעיין בעדכונים האחרונים.

פרטים ספציפיים יותר ומידע נוסף על Merchant API זמינים בסקירה הכללית באתר למפתחים ובמדריך המיגרציה.

פרטים על Merchant API ועל ממשקי המשנה שלו זמינים במאמר Merchant API design.

הקודם
Quickstart
הבא
Migrate from accountstatuses to Account Issues