يشرح هذا الدليل عملية نقل البيانات من Content API for Shopping إلى Merchant API لإدارة بيانات النشاط الإعلاني.
يمكنك استخدام هذا الدليل لنقل بيانات عملية التنفيذ الحالية في Content API for Shopping إلى Merchant API. لمزيد من المعلومات حول تفاصيل Merchant 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.
أبرز حالات الاستخدام:
- الإدارة التلقائية للحساب
- الإدارة التلقائية للمنتجات
- نظام إدارة المخزون التلقائي
- إعداد التقارير المخصّصة
أبرز مجالات التحسين:
- واجهات برمجة تطبيقات فرعية تتضمّن ميزات جديدة، بما في ذلك:
- تتتبّع ميزة "تتبُّع الطلبات" سجلّ تتبُّع طلبات المؤسسة لتزويد العملاء بتقديرات دقيقة ومحدّدة للشحن. تتيح إشاراتها أيضًا عرض بيانات محسّنة تتضمّن شحنًا سريعًا ومجانيًا.
- توفر ميزة "حل المشاكل" إمكانية الوصول إلى محتوى التشخيص وإجراءات الدعم بالطريقة نفسها المتوفرة في واجهة مستخدم Merchant Center.
- يستفيد Product Studio (إصدار ألفا) من الذكاء الاصطناعي التوليدي لإنشاء عناوين وأوصاف المنتجات وتحسينها. عليك توقيع هذا النموذج لـ طلب الوصول.
- مراجع جديدة في واجهة برمجة التطبيقات الفرعية "الحسابات ".
OmnichannelSettingsتُدير إعدادات الحساب للعرض على قنوات متعدّدة، مثل البيانات المحلية المجانية وإعلانات المنتجات داخل المتجر.LfpProvidersتتصل بشركاء "برنامج الشراكة في الخلاصات المحلية" للحصول على بيانات المخزون.GbpAccountsتتصل بحساب على "الملف التجاري على Google" للحصول على بيانات المتجر المحلي.OnlineReturnPolicyتوفّر إمكانية إنشاء سياساتك على الإنترنت وحذفها وتعديلها.
- طُرق جديدة للمخزون وبيانات المنتجات وواجهات برمجة التطبيقات الأخرى، بما في ذلك:
- طريقة جديدة في واجهة برمجة التطبيقات الفرعية "المنتجات ".
ProductsUpdateتتيح لك تعديل المنتجات الفردية بدون الحاجة إلى تقديم جميع الحقول المطلوبة لـProductInput.
- إمكانية إنشاء مصادر بيانات متعدّدة، بالإضافة إلى مصادر البيانات الأساسية، مثل:
- إمكانية تحميل مراجعات المنتجات ومراجعات التجّار
- باستخدام Merchant API، يمكنك تفعيل الإشعارات بشأن التغييرات في بيانات الحساب
التغييرات التي أُجريت
- تمت زيادة الحد الأقصى لـ
pageSizeمن 250 إلى 1000 صف لكل طلب بيانات من واجهة برمجة التطبيقات. - تم إصلاح التأخير الذي كان يحدث عند إدراج المنتجات والعروض الترويجية ومراجعات المنتجات و
مراجعات التجّار بعد
DataSourcesالإنشاء - تم إطلاق تعريف معدَّل لـ
clickPotentialRankفي جدولproductViewضمن واجهة برمجة التطبيقات الفرعية إعداد التقارير:- يتم ضبط ترتيب المنتجات استنادًا إلى
clickPotentialعلى قيم تتراوح بين 1 و1000.
- يتم ضبط ترتيب المنتجات استنادًا إلى
- يتيح
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 لإدارة معلومات هذا المنتج داخل المتجر.LocalInventory
التحسينات الهيكلية مقارنةً بـ Content API
تتفوّق Merchant API على Content API في المجالات التالية:
- واجهات برمجة تطبيقات فرعية تتضمّن ميزات جديدة لعملية الدمج الفريدة
- طُرق جديدة للمخزون وبيانات المنتجات وواجهات برمجة التطبيقات الأخرى
- إمكانية إنشاء مصادر بيانات متعدّدة، بالإضافة إلى مصادر البيانات الأساسية، مثل:
- إمكانية تحميل مراجعات المنتجات ومراجعات التجّار
- باستخدام Merchant API، يمكنك تفعيل الإشعارات بشأن التغييرات في بيانات الحساب.
- إمكانية الفلترة في مرجع "الحسابات"
لنلقِ نظرة على هذه التغييرات بمزيد من التفصيل.
تحديد الإصدارات وواجهات برمجة التطبيقات الفرعية
تطرح Merchant API مفهومَي تحديد الإصدارات و واجهات برمجة التطبيقات الفرعية. يُسهّل تصميمها المعياري عملية الاستخدام، ما يسمح لك بالتركيز على واجهات برمجة التطبيقات الفرعية التي تحتاج إليها ويسهّل عمليات النقل المستقبلية إلى الإصدارات الأحدث. سيتم تطبيق تحديد الإصدارات على عناوين URL للطلبات. والاستراتيجية مشابهة لتجربة Google Ads API.
طلبات أكثر فعالية
تتطلّب طلبات عناوين URL في Merchant API المزيد من المَعلمات لاستدعاء Merchant API. ويشمل ذلك المرجع والإصدار والاسم (المعرّفات) والطريقة (الطرق غير العادية). لمزيد من المعلومات حول ذلك، يُرجى الاطّلاع على معرّفات الحسابات والمنتجات و أمثلة.
مبادئ AIP للمعرّفات
بينما تستخدم Content API for Shopping أرقام تعريف لتحديد المراجع (مثل
merchantId وproductId)، تستخدم Merchant API معرّف
name
للتوافق مع AIP (يُرجى الاطّلاع على
مبادئ تحسين واجهة برمجة التطبيقات).
يتضمّن المعرّف {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
يوضّح الجدول كيفية تغيير طلب products.get في Content API for Shopping:
| 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/)، لأنّ الحساب هو السمة الرئيسية لمرجع المنتج.
القيم الثابتة الشائعة
يوفّر استخدام القيم الثابتة الشائعة مزيدًا من الاتساق.
يحدّد الحقل
Destination.DestinationEnum
المنصات التي سيتم عرض مراجعك عليها.
DestinationEnum تسرد جميع القيم المتاحة للاستهداف حسب الوجهة وهي
موحّدة على مستوى واجهات برمجة التطبيقات الفرعية، مثلاً لـ سمات
العروض الترويجية.
يمثّل الحقل
ReportingContext.ReportingContextEnum
السياق الذي تنطبق عليه مشاكل حسابك ومنتجاتك.
يُستخدَم هذا الحقل في طرق إعداد التقارير (مثلاً، لـ
IssueSeverityPerReportingContext).
التوافق مع الإصدارات السابقة
عند بدء استخدام Merchant API، ستستمر عملية الدمج الحالية في Content API for Shopping في العمل بدون انقطاع. لمزيد من المعلومات، يُرجى الاطّلاع على التوافق.
بعد نقل بيانات واجهات برمجة التطبيقات الفرعية إلى Merchant API، ننصحك باستخدام Merchant API فقط لواجهات برمجة التطبيقات الفرعية التي تم نقل بياناتها.
مدى توفّر استدعاء الإجراء عن بُعد (gRPC)
gRPC هي الطريقة الجديدة المقترَحة للتكامل مع Merchant API.
تشمل مزاياه ما يلي:
- لا يعتمد على لغة معيّنة
- يعتمد على آليات سَلسلة البيانات المنظّمة
يستخدم HTTP/2 لتوفير حلول قابلة للتوسّع وعالية الأداء (مرجع RPC)
إذا كنت تستخدم مكتبات العملاء أو عيّنات التعليمات البرمجية، يكون gRPC آلية النقل التلقائية.
لمزيد من المعلومات حول gRPC، يُرجى الاطّلاع على ما يلي:
تصبح عملية تجميع الطلبات المخصّصة عملية تجميع مدمَجة
تكون عملية تجميع الطلبات أكثر كفاءة عند استخدام طلبات غير متزامنة. مزيد من المعلومات حول استخدام الطلبات المتوازية لتحقيق عملية تجميع الطلبات في Merchant API وكيفية إعادة تصميم التعليمات البرمجية للطلبات المتزامنة requests.
للمساعدة في تسريع عملية نقل البيانات، ننصحك باستخدام مكتبات العملاء.
لا تتوافق 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.
آخر الأخبار والإعلانات المهمة
للاطّلاع على آخر الأخبار الأكثر تفصيلاً، يُرجى مراجعة ملاحظات الإصدار الخاصة بكل واجهة برمجة تطبيقات فرعية. للاطّلاع على آخر الأخبار المجمّعة المنتظمة في Merchant API، يُرجى مراجعة آخر الأخبار.
لمزيد من التفاصيل المحدّدة ولمعرفة المزيد عن Merchant API، يُرجى الاطّلاع على موقع المطوّرين نظرة عامة ودليل نقل البيانات العام لمزيد من التفاصيل.
يُرجى الاطّلاع على تصميم Merchant API للحصول على تفاصيل حول Merchant API وواجهات برمجة التطبيقات الفرعية.