מעבר מ-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/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 בקטע 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/v1/{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/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>

ההורה הוא accounts/{account}/products/{product}. שימו לב שבמקרה הזה, למקור המידע localInventories יש שני הורים שכלולים במזהה השם (accounts/ ו-products/), כי החשבון הוא ההורה של מקור המידע product.

סוגי enum נפוצים

השימוש בסוגי enum נפוצים מספק עקביות רבה יותר.

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

השדה ReportingContext.ReportingContextEnum מייצג את ההקשר שבו הבעיות בחשבון ובמוצרים רלוונטיות. השדה הזה משמש בכל שיטות הדיווח (לדוגמה, ב-IssueSeverityPerReportingContext).

תאימות לאחור

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

אחרי שתעבירו את ממשקי המשנה אל Merchant API, מומלץ להשתמש רק ב-Merchant 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.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 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 accountstatuses to Account Issues