בדף הזה נסביר איך מעלים מוצרים ומנהלים אותם באופן פרוגרמטי. באמצעות Merchant Products API אפשר להוסיף או לעדכן מוצר במקור נתונים, לאחזר מוצר מהחשבון ולמחוק מוצר ממקור נתונים.
Merchant Products API מכיל שני משאבים.
productInputsrepresents the input parts of your products.productsמייצג את המוצרים שעברו עיבוד ונוצרו מחלקי הקלט.
השדה productInputs יכול להיות ראשי ומשלים, בהתאם לכך שהוא הועלה למקור נתונים ראשי או למקור נתונים משלים.
כל product מורכב מ-productInput ראשי אחד וממספר כלשהו של productInputs משניים.
אפשר להשתמש ב-Merchant Products API כדי ליצור קטלוגים של מוצרים בחנות מקומית או באינטרנט. אלה מוצרים שיכולים להופיע במספר יעדים של שופינג.
אפשר להשתמש במשאב productInputs אחרי שיוצרים חשבון Merchant Center, מגדירים את מקור הנתונים הראשון ומוכנים להעלות קבוצה ראשונית של מוצרים דרך ה-API.
למוכרים יש אפשרות להעלות מוצרים באמצעות קובץ שנקרא PrimaryProductDataSource, אבל יש כמה יתרונות ליצירה ולמחיקה של מוצרים באמצעות Merchant API. היתרונות האלה כוללים זמן תגובה מהיר יותר ויכולת לעדכן מוצרים בזמן אמת, בלי צורך לנהל קבצים גדולים. יכול להיות שיעברו כמה שעות עד ששינויים במוצרים שבוצעו באמצעות קריאות ל-API יופיעו במסד הנתונים של שופינג.
דרישות מוקדמות
אם אין לכם מקור נתונים, יוצרים מקור נתונים באמצעות Merchant Data Sources API או Merchant Center.
אם כבר יש לכם מקור נתונים שיצרתם באמצעות ממשק המשתמש של Merchant Center או באמצעות ה-API, תוכלו להשתמש ב-Merchant Products API כדי להוסיף את המוצרים שלכם. אם אתם משתמשים ב-Content API for Shopping כדי להוסיף מוצרים, תוכלו לעיין במדריך ההעברה כדי להבין איך מתחילים להשתמש ב-Merchant Products API.
באחריותכם לציית לכללי המדיניות של מודעות שופינג ושל כרטיסי מוצר חינמיים. מערכת מודעות השופינג שומרת לעצמה את הזכות לאכוף את כללי המדיניות האלה ולהגיב בהתאם אם נמצא תוכן או התנהגות שמפירים את כללי המדיניות האלה.
משאבים
המשאב products מאפשר לאחזר פרטי מוצרים ממסד הנתונים של Shopping.
המשאב productInput מייצג את נתוני הקלט ששולחים לגבי מוצר. בנוסף, יש שיטות שמאפשרות לעדכן או למחוק את פרטי המוצרים, אחד אחרי השני או כמה בו-זמנית במצב באצווה. למשאב productInput חייבים להיות השדות הבאים:
channel: הערוץ של המוצר.offerId: המזהה הייחודי של המוצר.contentLanguage: קוד השפה בן שתי האותיות של המוצר לפי תקן ISO 639-1.feedLabel: התווית שמאפשרת לכם לסווג את המוצרים ולזהות אותם. מספר התווים המרבי המותר הוא 20, והתווים הנתמכים הםA-Z,0-9, מקף וקו תחתון. אין לכלול רווחים בתווית הפיד. מידע נוסף זמין במאמר שימוש בתוויות של פידים.
העלאת קלט של מוצר לחשבון
כדי להעלות קלט של מוצר לחשבון, משתמשים בשיטה accounts.productInputs.insert. צריך להעביר את המזהה הייחודי של מקור הנתונים הראשי או המשלים.
בבקשה לדוגמה הבאה מוסבר איך משתמשים ב-method accounts.productInputs.insert כדי להעלות קלט של מוצר לחשבון המוכר. בבקשה מוגדרים מחיר המשלוח והאזור, וגם מאפיינים מותאמים אישית כמו תאריך הייצור והגודל.
POST https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID} /productInputs:insert?dataSource={DATASOURCE}
{
"name": "{PRODUCT_TITLE} ",
"versionNumber": {VERSION_NUMBER} ,
"contentLanguage": "{CONTENT_LANGUAGE} ",
"feedLabel": "{FEED_LABEL} ",
"offerId": "{OFFER_ID} ",
"channel": "ONLINE",
"attributes": {
"availability": "in stock",
"imageLink": "{IMAGE_LINK} ",
"link": "{PRODUCT_LINK} ",
"brand": "{BRAND_NAME} ",
"price": {
"currencyCode": "{CURRENCY_CODE} ",
"amountMicros": {PRICE}
},
"color": "red",
"productWeight": {
"value": 320,
"unit": "g"
},
"adult": false,
"shipping": [
{
"country": "GB",
"price": {
"amountMicros": {SHIPPING_COST} ,
"currencyCode": "{CURRENCY_CODE_SHIPPING} "
},
"postalCode": "{SHIPPING_POSTALCODE} ",
"service": "",
"region": "{SHIPPING_REGION} ",
"maxHandlingTime": "{MAX_HANDLING_TIME} ",
"minHandlingTime": "{MIN_HANDLING_TIME} ",
"maxTransitTime": "{MAX_TRANSIT_TIME} ",
"minTransitTime": "{MIN_TRANSIT_TIME} "
}
],
"gender": "Female"
},
"customAttributes": [
{
"name": "size",
"value": "Large"
},
{
"name": "Date of Manufacturing",
"value": "2024-05-05"
}
]
}
מחליפים את מה שכתוב בשדות הבאים:
- {ACCOUNT_ID}: המזהה הייחודי של חשבון Merchant Center.
- {DATASOURCE}: המזהה הייחודי של מקור הנתונים. הפורמט הנדרש הוא
accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}. - {PRODUCT_TITLE}: שם המוצר.
- {VERSION_NUMBER}: מספר הגרסה של המוצר. אופציונלי.
- {CONTENT_LANGUAGE}: קוד השפה בן שתי האותיות של המוצר לפי תקן ISO 639-1. חובה.
- {FEED_LABEL}: התווית שמאפשרת לסווג ולזהות את המוצרים. מספר התווים המקסימלי הוא 20, והתווים הנתמכים הם
A-Z,0-9, מקף וקו תחתון. אין לכלול רווחים בתווית הפיד. - {OFFER_ID}: המזהה הייחודי של המוצר. חובה.
- {IMAGE_LINK}: הקישור לתמונה של המוצר באתר שלכם. אופציונלי.
- {PRODUCT_LINK}: הקישור למוצר באתר שלכם. אופציונלי.
- {CURRENCY_CODE}: המטבע של המחיר, באמצעות ראשי תיבות של שלוש אותיות בהתאם לתקן ISO 4217. אופציונלי.
- {PRICE}: המחיר של המוצר, שמוצג כמספר ב-micros. אופציונלי.
- {SHIPPING_COST}: מחיר המשלוח הקבוע, שמוצג כמספר. אופציונלי.
- {SHIPPING_POSTALCODE}: טווח המיקוד שבו חל תעריף המשלוח. אופציונלי.
- {MAX_HANDLING_TIME}: זמן הטיפול המקסימלי בימי עסקים ממועד קבלת ההזמנה ועד למועד השליחה שלה. אופציונלי.
- {MIN_HANDLING_TIME}: זמן הטיפול המינימלי בימי עסקים ממועד קבלת ההזמנה ועד למועד השליחה שלה. הערך 0 מציין שההזמנה תימסר באותו יום שבו היא תתקבל. אופציונלי.
- {MAX_TRANSIT_TIME}: זמן האספקה המקסימלי בימי עסקים ממועד שליחת ההזמנה ועד למועד המסירה שלה. אופציונלי.
- {MIN_TRANSIT_TIME}: זמן האספקה המינימלי בימי עסקים ממועד שליחת ההזמנה ועד למועד המסירה שלה. הערך 0 מציין שההזמנה תימסר באותו יום שבו היא תישלח. אופציונלי.
אם הבקשה פועלת בהצלחה, תוצג התגובה הבאה:
{
"name": "{PRODUCT_NAME} ",
"product": "{PRODUCT_ID} ",
"channel": "ONLINE",
"offerId": "{OFFER_ID} ",
"contentLanguage": "{CONTENT_LANGUAGE} ",
"feedLabel": "{FEED_LABEL} ",
"versionNumber": "{VERSION_NUMBER} ",
"attributes": {
"link": "{PRODUCT_LINK} ",
"imageLink": "{IMAGE_LINK} ",
"adult": false,
"availability": "in stock",
"brand": "{BRAND_NAME} ",
"color": "red",
"gender": "Female",
"price": {
"amountMicros": "{PRICE} ",
"currencyCode": "{CURRENCY_CODE} "
},
"shipping": [
{
"price": {
"amountMicros": "{SHIPPING_COST} ",
"currencyCode": "{CURRENCY_CODE} "
},
"country": "{SHIPPING_COUNTRY} ",
"region": "{SHIPPING_REGION} ",
"postalCode": "{SHIPPING_POSTALCODE} ",
"minHandlingTime": "{MIN_HANDLING_TIME} ",
"maxHandlingTime": "{MAX_HANDLING_TIME} ",
"minTransitTime": "{MIN_TRANSIT_TIME} ",
"maxTransitTime": "{MAX_TRANSIT_TIME} "
}
],
"productWeight": {
"value": 320,
"unit": "g"
}
},
"customAttributes": [
{
"name": "Size",
"value": "Large"
},
{
"name": "Date of Manufacturing",
"value": "2024-05-05"
}
]
}
כדי להוסיף מוצר לחשבון Merchant Center, אפשר להשתמש ב-method google.shopping.merchant.accounts.v1beta.InsertProductInputSample, כפי שמתואר בדוגמה הבאה.
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
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 shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to insert a product input */
public class InsertProductInputSample {
private static String getParent(String accountId) {
return String.format("accounts/%s", accountId);
}
public static void insertProductInput(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)) {
// Price to be used for shipping ($33.45).
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")
.setGtin(0, "9780007350896")
.addShipping(shipping)
.addShipping(shipping2)
.build();
// The datasource can be either a primary or supplemental datasource.
InsertProductInputRequest request =
InsertProductInputRequest.newBuilder()
.setParent(parent)
// You can only insert products into datasource types of Input "API" and "FILE", 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(
ProductInput.newBuilder()
.setChannel(ChannelEnum.ONLINE)
.setContentLanguage("en")
.setFeedLabel("label")
.setOfferId("sku123")
.setAttributes(attributes)
.build())
.build();
System.out.println("Sending insert ProductInput request");
ProductInput response = productInputsServiceClient.insertProductInput(request);
System.out.println("Inserted ProductInput Name below");
// The last part of the product name will be the product ID assigned to a product by Google.
// Product ID has the format `channel~contentLanguage~feedLabel~offerId`
System.out.println(response.getName());
System.out.println("Inserted Product Name below");
System.out.println(response.getProduct());
} 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/{INSERT_DATASOURCE_ID}";
insertProductInput(config, dataSource);
}
}
אחזור מוצר מעובד מהחשבון
כדי לאחזר מוצר מעובד מהחשבון, משתמשים ב-method accounts.products.get. יכול להיות שיחלפו כמה דקות עד שהמוצר המעובד יופיע אחרי ההוספה.
GET https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID} /products/{PRODUCT_NAME}
מחליפים את {PRODUCT_NAME} בשם של משאב הקלט של המוצר שרוצים למחוק. לדוגמה, online~en~US~sku123.
אפשר לקבל את שם המשאב של המוצר המעובד מהשדה product בתגובה של accounts.productInputs.insert.
כדי לאחזר מוצר יחיד בחשבון Merchant Center נתון, אפשר להשתמש ב-method google.shopping.merchant.accounts.v1beta.GetProductRequest, כפי שמתואר בדוגמה הבאה.
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.products.v1beta.GetProductRequest;
import com.google.shopping.merchant.products.v1beta.Product;
import com.google.shopping.merchant.products.v1beta.ProductsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to get a single product for a given Merchant Center account */
public class GetProductSample {
public static void getProduct(Config config, String product) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductsServiceSettings productsServiceSettings =
ProductsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Calls the API and catches and prints any network failures/errors.
try (ProductsServiceClient productsServiceClient =
ProductsServiceClient.create(productsServiceSettings)) {
// The name has the format: accounts/{account}/products/{productId}
GetProductRequest request = GetProductRequest.newBuilder().setName(product).build();
System.out.println("Sending get product request:");
Product response = productsServiceClient.getProduct(request);
System.out.println("Retrieved Product below");
System.out.println(response);
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
// The name of the `product`, returned after a `Product.insert` request. We recommend
// having stored this value in your database to use for all future requests.
String product = "accounts/{datasource}/products/{productId}";
getProduct(config, product);
}
}
מחיקת קלט של מוצר מהחשבון
כדי למחוק קלט של מוצר מהחשבון, משתמשים ב-method accounts.productInputs.delete. כדי למחוק מוצר באמצעות Merchant Products API, צריך להעביר את המזהה הייחודי של מקור הנתונים הראשי או המשלים שאליו המוצר שייך.
הבקשה הבאה מראה איך משתמשים בשיטה accounts.productInputs.delete כדי למחוק קלט של מוצר:
DELETE https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID} /productInputs/{PRODUCT_NAME} ?dataSource=accounts/{ACCOUNT_ID} /dataSources/{DATASOURCE_ID}
מחליפים את {PRODUCT_NAME} בשם של משאב הקלט של המוצר שרוצים למחוק. לדוגמה, online~en~US~sku123.
כדי למחוק מוצר מחשבון Merchant Center ספציפי, אפשר להשתמש ב-method google.shopping.merchant.accounts.v1beta.DeleteProductInputRequest, כפי שמתואר בדוגמה הבאה.
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.products.v1beta.DeleteProductInputRequest;
import com.google.shopping.merchant.products.v1beta.ProductInputName;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to delete a product for a given Merchant Center account */
public class DeleteProductInputSample {
public static void deleteProductInput(Config config, String productId, 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 product name to identify product.
String name =
ProductInputName.newBuilder()
.setAccount(config.getAccountId().toString())
.setProductinput(productId)
.build()
.toString();
// Calls the API and catches and prints any network failures/errors.
try (ProductInputsServiceClient productInputsServiceClient =
ProductInputsServiceClient.create(productInputsServiceSettings)) {
DeleteProductInputRequest request =
DeleteProductInputRequest.newBuilder().setName(name).setDataSource(dataSource).build();
System.out.println("Sending deleteProductInput request");
productInputsServiceClient.deleteProductInput(request); // no response returned on success
System.out.println(
"Delete successful, note that it may take a few minutes for the delete to update in"
+ " the system. If you make a products.get or products.list request before a few"
+ " minutes have passed, the old product data may be returned.");
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
// An ID assigned to a product by Google. In the format
// channel~contentLanguage~feedLabel~offerId
String productId = "online~en~label~sku123";
// The name of the dataSource from which to delete the product. If it is a primary feed, this
// will delete the product completely. If it's a supplemental feed, it will only delete the
// product information from that feed, but the product will still be available from the primary
// feed.
String dataSource = "accounts/{account}/dataSources/{dataSource}";
deleteProductInput(config, productId, dataSource);
}
}
הצגת רשימה של מוצרים מהחשבון
כדי לקבל רשימה של המוצרים שעברו עיבוד בחשבון, משתמשים ב-method accounts.products.list, כפי שמתואר בבקשה הבאה.
GET https://merchantapi.googleapis.com/products/v1beta/accounts/{ACCOUNT_ID} /products
כדי להוסיף מוצר לחשבון Merchant Center ספציפי, אפשר להשתמש ב-method google.shopping.merchant.accounts.v1beta.ListProductsRequest, כפי שמתואר בדוגמה הבאה.
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.products.v1beta.ListProductsRequest;
import com.google.shopping.merchant.products.v1beta.Product;
import com.google.shopping.merchant.products.v1beta.ProductsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductsServiceClient.ListProductsPagedResponse;
import com.google.shopping.merchant.products.v1beta.ProductsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to list all the products for a given merchant center account */
public class ListProductsSample {
private static String getParent(String accountId) {
return String.format("accounts/%s", accountId);
}
public static void listProducts(Config config) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductsServiceSettings productsServiceSettings =
ProductsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates parent to identify the account from which to list all products.
String parent = getParent(config.getAccountId().toString());
// Calls the API and catches and prints any network failures/errors.
try (ProductsServiceClient productsServiceClient =
ProductsServiceClient.create(productsServiceSettings)) {
// The parent has the format: accounts/{account}
ListProductsRequest request = ListProductsRequest.newBuilder().setParent(parent).build();
System.out.println("Sending list products request:");
ListProductsPagedResponse response = productsServiceClient.listProducts(request);
int count = 0;
// Iterates over all rows in all pages and prints the datasource in each row.
// Automatically uses the `nextPageToken` if returned to fetch all pages of data.
for (Product product : response.iterateAll()) {
System.out.println(product); // The product includes the `productStatus` field
// That shows approval and disapproval information.
count++;
}
System.out.print("The following count of products were returned: ");
System.out.println(count);
} catch (Exception e) {
System.out.println("An error has occured: ");
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
listProducts(config);
}
}