מעבר מ-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 ב-Reporting sub-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 גרסה 2.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, צריך להוסיף עוד פרמטרים. המידע הזה כולל את המשאב, הגרסה, השם (מזהים) והשיטה (שיטות לא סטנדרטיות). מידע נוסף זמין במאמר מזהי חשבונות ומוצרים ובדוגמאות.

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

רשימות נפוצות

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

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

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

תאימות לדורות קודמים

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

אחרי שתעבירו את ממשקי ה-API המשניים ל-Merchant API, מומלץ להשתמש רק ב-Merchant API בשביל ממשקי ה-API המשניים שהועברו.

זמינות של קריאה לשירות מרוחק (gRPC)

‫gRPC היא הדרך החדשה והמומלצת לשילוב עם Merchant API.

היתרונות של המודל הזה:

התכונה "התאמה אישית של מקבצים" הופכת ל"מקבצים מובנים"

האצווה פועלת בצורה יעילה יותר כשמשתמשים בקריאות אסינכרוניות. מידע נוסף על שימוש בקריאות מקבילות כדי לבצע איסוף קריאות ל-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 מתועד עכשיו במיקרו-יחידות, כאשר מיליון מיקרו-יחידות שוות ליחידה סטנדרטית במטבע שלכם.

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

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

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

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

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

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

במאמר עיצוב Merchant API מפורט מידע על Merchant API ועל ממשקי ה-API המשניים שלו.

הקודם
Manage and transition Google Cloud projects
הבא
Start your migration