1. مقدمة
في هذا الدرس التطبيقي، ستتعرَّف على بعض أساسيات العمل باستخدام Content API for Shopping وAdWords API وإنشاء تطبيق يستخدم كليهما. وعلى وجه التحديد، ستُنشئ تطبيق سطر أوامر ينشئ حسابًا في AdWords ويربطه بحساب في Merchant Center.
المعلومات التي ستطّلع عليها
- كيفية إنشاء حسابات في AdWords مُدارة بواسطة حساب إداري.
- كيفية إنشاء حسابات على Merchant Center يُديرها حساب متعدّد العملاء
- كيفية طلب ربط حساب على Merchant Center بحساب في AdWords.
- كيفية قبول رابط Merchant Center في انتظار المراجعة في حساب AdWords.
المتطلبات
- حساب إداري في AdWords
- حساب متعدّد العملاء على Merchant Center
- Java 7+
- Maven
- نموذج الرمز
- محرِّر نصوص (يُنصح باستخدام بيئة تطوير متكاملة (IDE) تتعرّف على مشاريع Maven، مثل Eclipse أو IntelliJ (يُنصح باستخدامها)
2. بدء الإعداد
تنزيل العرض التقديمي
انقر على الرابط التالي لتنزيل جميع الرموز الخاصة بهذا الدرس التطبيقي حول الترميز:
فك ضغط ملف ZIP الذي تم تنزيله. سيؤدي هذا الإجراء إلى فك ضغط المجلد الجذر (shopping-account-linking-master
) الذي يحتوي على مشروع Maven بالإضافة إلى كل الموارد التي ستحتاج إليها. تُعد الأدلة الفرعية التالية ذات أهمية خاصة:
src/main/java
هو الجذر المصدر لمشروع Maven ويتضمّن بنية رمزية يمكنك استخدامها.- تحتوي السمة
src/main/java/solution
على الحل النهائي.
تثبيت الحِزم المطلوبة وتصميمها
إذا كنت تستخدم بيئة تطوير مدمجة تستند إلى Maven، مثل Eclipse أو IntelliJ، يمكنك استيراد المجلد المستخرَج كمشروع Maven ثم تجميع المشروع بشكل طبيعي.
في حال استخدام Maven من سطر الأوامر، يمكنك تشغيل الأمر التالي لاسترداد الحِزم اللازمة وتجميع المشروع من المجلد الجذر للمشروع غير المضغوط (shopping-account-linking-master
):
mvn compile
3- ضبط إعدادات المصادقة
لن نجري أي عمليات ترميز في هذه الخطوة، بل نعمل على إعداد ملفات تحتوي على رموز مصادقة مناسبة لواجهة AdWords API وContent API for Shopping.
إعداد تفعيل AdWords API
يستخدم هذا الدرس التطبيقي بيانات الاعتماد نفسها التي يتم تحميلها في مكتبة العملاء، لذا إذا سبق لك استخدام مكتبة برامج Google Ads API للغة Java مع حسابك الإداري، من المفترض أن تكون قد سبق لك إعدادها. وإذا لم تكن كذلك، يمكنك اتّباع الخطوات من 1 إلى 3 للبدء في استخدام مكتبة برامج Google Ads APIs للغة Java.
إعداد تفعيل Content API
إذا لم يكن لديك مفتاح حساب خدمة:
- انتقِل إلى Merchant Center لحسابك المتعدّد العملاء واختَر Content API من القائمة الكاملة:
.
- اختَر المصادقة، ثم انقر على زر + الأزرق:
- بعد قبول بنود خدمة Google Cloud Platform وGoogle APIs، سينزِّل متصفحك تلقائيًا ملف JSON يحتوي على مفتاح حساب الخدمة الجديد.
اتّبِع الآن التوجيهات بشأن إعداد المصادقة لنماذج Shopping باستخدام حساب خدمة. وهذا يعني أنّه يجب وضع نسخة من مفتاح حساب الخدمة في المسار التالي من الدليل الرئيسي: shopping-samples/content/service-account.json
. ولا تحتاج إلى ضبط إعدادات النماذج، إلّا إذا كنت مهتمًا بتجربة النماذج بعد الانتهاء من هذا الدرس التطبيقي حول الترميز.
تجربة الميزة
الآن بعد أن أصبح لديك رموز المصادقة في الأماكن الصحيحة، حاول تشغيل النماذج. إذا كنت تستخدم Maven في سطر الأوامر، شغِّل الأوامر التالية:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
إذا تلقّيت رسالة خطأ بشأن عدم توفير كائنات الجلسة، يعني ذلك أنّ الرموز المميّزة للمصادقة متوفّرة في مكانها وتعمل بشكلٍ صحيح. بخلاف ذلك، من المفترض أن توضّح لك رسالة الخطأ التي تظهر لك بيانات الاعتماد التي تعذّر عملها والملف الذي يجب إصلاحه.
4. الاتصال بواجهات برمجة التطبيقات
الآن وبعد أن أصبح لديك رموز مصادقة صالحة لواجهات برمجة التطبيقات اللتين سنستخدمهما، لنبدأ بملء الرمز الفعلي. سنبدأ بإنشاء كائنات الجلسة باستخدام الرموز المميزة للمصادقة. في الخطوات اللاحقة، سنصل إلى الخدمات والطرق المتنوعة التي توفّرها كل واجهة برمجة تطبيقات باستخدام كائنات الجلسات هذه.
إنشاء عنصر جلسة Content API
لإنشاء جلسة في Content API، سننشئ كائن ShoppingContent.Builder
، ثم نستخدمه لإنشاء عنصر ShoppingContent
المناسب. لحسن الحظ، كل ما نحتاج إليه لإنشاء السابق متاح بالفعل في الهيكل العظمي للتعليمة البرمجية، لذلك نحتاج فقط إلى جمعها معًا مثل:
SolutionRunner.java
// TODO(sessions): Create a ShoppingContent object using ShoppingContent.Builder.
contentApiSession =
new ShoppingContent.Builder(httpTransport, jsonFactory, contentApiCredential)
.setApplicationName("Linking AdWords and Merchant Center Accounts Codelab")
.build();
إنّ ضبط اسم تطبيق ليس ضروريًا للغاية، ولكنّه يوضّح كيفية ضبط أي خيارات مطلوبة باستخدام عنصر ShoppingContent.Builder
قبل استدعاء الطريقة build()
.
إنشاء كائن جلسة AdWords API
وبالمثل، هناك فئة AdWordsSession.Builder
لإنشاء عناصر AdWordsSession
. يتمثل الاختلاف الرئيسي هنا في أنه بدلاً من ضبط خيارات الضبط مباشرةً في أداة الإنشاء، سنستخدم طريقة fromFile()
لتحميلها من ملف ads.properties
الذي تم إعداده في الخطوة السابقة.
SolutionRunner.java
// TODO(sessions): Create a AdWordsSession object using AdWordsSession.Builder.
adWordsSession =
new AdWordsSession.Builder()
.fromFile()
.withOAuth2Credential(adwordsOAuth2Credential)
.build();
تجربة الميزة
سنستخدم الأوامر نفسها المستخدَمة في القسم الأخير لإعادة إنشاء مشروع Maven وتشغيله، إذا كنت تشغِّله من سطر الأوامر:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
وهذه المرّة، من المفترَض ألا تظهر أي أخطاء على الإطلاق، ولكن لن تظهر لك أيضًا أي نتائج مثيرة للاهتمام. سنضيف ذلك عندما نستدعي واجهات برمجة التطبيقات لإنشاء الحسابات الجديدة وربطها.
5- إنشاء حساب مُدار جديد في AdWords
الآن وبعد أن أنشأنا كائنات جلسة واجهة برمجة التطبيقات، سننتقل إلى الحسابات التي نريد ربطها وننشئها. سنبدأ باستخدام AdWords وننشئ حسابًا تجريبيًا ضمن حساب المدير.
الوصول إلى ManagedCustomerService
في AdWords API، يمكننا الوصول إلى الخدمات المختلفة المتاحة من خلال استرداد مثيل لفئة AdWordsServices أولاً باستخدام طريقة getInstance()
الثابتة. باستخدام هذا المثيل، يمكننا إنشاء عملاء لتلك الخدمات باستخدام الطريقة get()
، التي تستخدم وسيطتين: الجلسة التي يتم إنشاء العميل لها والواجهة للخدمة المطلوبة.
SolutionRunner.java
// TODO(newAWaccount): Using the ManagedCustomerService, create a new testing AdWords account
// under the given manager account.
AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();
ManagedCustomerServiceInterface managedCustomerService =
adWordsServices.get(adWordsSession, ManagedCustomerServiceInterface.class);
يمكننا هنا الوصول إلى ManagedCustomerService، الذي يسمح لنا بإدارة "عملاء" AdWords (الحسابات) من حساب إداري معيّن.
تحديد إعدادات الحساب الجديدة
أولاً، سننشئ عنصر ManagedCustomer يحتوي على إعدادات حسابنا الجديد. سننشئ حسابًا تجريبيًا لهذا الدرس التطبيقي حول الترميز، مع ضبط عملته على الدولار الأمريكي ومنطقته الزمنية لتكون هي الساحل الغربي للولايات المتحدة.
SolutionRunner.java
Random rand = new Random();
long run = rand.nextLong();
ManagedCustomer newAdWordsAccount = new ManagedCustomer();
newAdWordsAccount.setName(String.format("AdWords Account Created by Run %d", run));
newAdWordsAccount.setTestAccount(true);
newAdWordsAccount.setCurrencyCode("USD");
newAdWordsAccount.setDateTimeZone("America/Los_Angeles");
كما ننشئ رقمًا عشوائيًا نضمِّنه في اسم الحساب. الهدف من ذلك هو مطابقة حساب AdWords الذي سننشئه هنا مع حساب Merchant Center الذي سننشئه لاحقًا، لنتمكّن من فحصه بصريًا عند اكتمال الحل والتأكّد من أنّه تم ربطه بحسابَي Merchant Center.
إنشاء الحساب المُدار الجديد
لإنشاء الحساب الجديد، سنستخدم ManagedCustomerOperation لتحديد عملية ADD
:
SolutionRunner.java
ManagedCustomerOperation operation = new ManagedCustomerOperation();
operation.setOperand(newAdWordsAccount);
operation.setOperator(Operator.ADD);
بعد ذلك، سنُنفذ العملية باستخدام طريقة mutate()
للكائن ManagedCustomerService
. تستخدم هذه الطريقة مجموعة من العمليات، لكننا هنا نريد إجراء عملية واحدة فقط. نتيجة الطريقة mutate()
هي قيمة تحتوي على قائمة ManagedCustomer
، ستظهر هنا قائمة تحتوي على عميل واحد، وهو الحساب الجديد الذي أنشأناه. كما سنسترجع المعرّف لهذا الحساب الجديد لاستخدامه في المستقبل، كما سنطبعه أيضًا حتى نتمكن من رؤيته كجزء من ناتج الحل الذي نقدمه.
SolutionRunner.java
ManagedCustomerReturnValue result =
managedCustomerService.mutate(new ManagedCustomerOperation[] {operation});
Long adWordsId = result.getValue()[0].getCustomerId();
System.out.printf("Created new AdWords account %d%n", adWordsId);
تجربة الميزة
كما في السابق، جرِّب تشغيل الحلّ. في حال استخدام Maven من سطر الأوامر:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
إذا سارت الأمور على ما يرام، من المفترض ألا تظهر أي أخطاء، وسنشاهد هذه المرة رقم تعريف حساب AdWords الجديد الذي أنشأناه. اطّلع على موقع AdWords الإلكتروني الذي يخصّ حسابك الإداري، ومن المفترض أن يظهر لك الحساب الجديد مُدرجًا هناك أيضًا.
6- إنشاء حساب فرعي جديد على Merchant Center
في هذه الخطوة، سيتم إنشاء حساب فرعي على Merchant Center الذي سنربطه بحساب AdWords الذي أنشأناه في الخطوة الأخيرة. وبدلاً من طلب رابط بشكل منفصل بعد إنشاء الحساب الفرعي، يمكننا طلب الربط أثناء عملية الإنشاء لأنّ لدينا رقم التعريف لحساب "إعلانات Google" المقابل.
تحديد إعدادات الحساب الفرعي الجديد
على عكس AdWords API، تعرض كائنات ضبط فئة النموذج Account
الكائن، حتى نتمكن من ربط طلباتنا بالعنصر في كائن Account
الجديد. وسنستخدم الرقم العشوائي الذي أنشأناه أثناء إنشاء حساب AdWords باسم حساب Merchant Center الجديد أيضًا.
SolutionRunner.java
Account newMcAccount = new Account()
.setName(String.format("Merchant Center Account Created by Run %d", run))
.setAdwordsLinks(
ImmutableList.of(
new AccountAdwordsLink()
.setAdwordsId(BigInteger.valueOf(adWordsId))
.setStatus("active")));
كما ذكرنا في مقدمة هذه الخطوة، بما أن لدينا من قبل رقم تعريف AdWords للحساب المُدار الجديد، يمكننا إضافة هذا الرقم التعريفي إلى قائمة AdwordsLinks
للحساب الفرعي الجديد الآن. عند إنشاء الحساب الفرعي الجديد، سيتم طلب هذا الرابط تلقائيًا وسيكون متاحًا في AdWords API.
إنشاء الحساب الفرعي الجديد
في Content API، نستدعي الطريقة accounts()
لكائن الجلسة للوصول إلى خدمة Accounts
، ثم نستدعي الطريقة insert()
مباشرةً بدلاً من إعداد كائن عملية. تستخدم هذه الطريقة وسيطتين: رقم تعريف الحساب المتعدّد العملاء الذي سيتم إنشاء الحساب الفرعي الجديد من خلاله، وعنصر Account
الذي يحتوي على الإعدادات المطلوبة:
SolutionRunner.java
newMcAccount = contentApiSession.accounts().insert(mcaId, newMcAccount).execute();
System.out.printf("Created new Merchant Center account %s%n", newMcAccount.getId());
تعرض الطريقة insert()
عنصر Account
يحتوي على إعدادات الحساب الفرعي الجديد. نستبدل عنصر Account
الأصلي لأنّ النسخة المعروضة تحتوي على معلومة مهمة، وهي: رقم تعريف الحساب الفرعي الجديد. ونطبع ذلك في الناتج من الحل الذي نقدّمه لكي نتمكّن من تشغيل الحلّ، ثم التأكّد من توفّر الحساب الفرعي الجديد في Merchant Center.
تجربة الميزة
كما في السابق، جرِّب تشغيل الحلّ. في حال استخدام Maven من سطر الأوامر:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
إذا سارت الأمور على ما يرام، من المفترض ألا تظهر أي أخطاء، وسنعرض هذه المرة أرقام تعريف كلّ من حساب AdWords الجديد وMerchant Center الجديد. تحقَّق من حسابك المتعدّد العملاء على Merchant Center للاطّلاع على الحساب الفرعي الجديد فيه.
7. قبول الربط من حساب AdWords
في الخطوة الأخيرة، أنشأنا حسابًا فرعيًا جديدًا على Merchant Center، نطلب فيه في الوقت نفسه الربط بحسابنا الجديد في AdWords. في هذه الخطوة، سنكمل العملية باستخدام AdWords API لقبول الرابط المطلوب.
الوصول إلى CustomerService
كما في السابق، سنستخدم الفئة AdWordsServices
للحصول على برنامج لـ CustomerService
. ومع ذلك، قبل إنشاء العميل، نغير أولاً كائن جلسة AdWords حتى تعمل الاستخدامات المستقبلية على الحساب المُدار الجديد بدلاً من الحساب الإداري. بعد كل شيء، طلب حساب Merchant Center رابطًا للحساب المدار، وليس الحساب الإداري.
SolutionRunner.java
// TODO(acceptLink): Using the mutateServiceLinks method in CustomerService, accept the
// proposed link between the new AdWords account and the new Merchant Center account.
adWordsSession.setClientCustomerId(adWordsId.toString());
CustomerServiceInterface customerService =
adWordsServices.get(adWordsSession, CustomerServiceInterface.class);
تحديد الرابط المطلوب
كما هو الحال عند إنشاء حساب جديد على AdWords، سننشئ عنصر ServiceLink
يحتوي على إعدادات الربط، ثم عنصر ServiceLinkOperation
يصف العملية المطلوبة. في هذه الحالة، نريد نقل رابط الخدمة المعلّق إلى حساب MERCHANT_CENTER
وSET
إلى ACTIVE
. بالنسبة إلى الإعداد serviceLinkId
، سنستخدم رقم تعريف حساب Merchant Center الذي أنشأناه للتوّ، لأنّه يُستخدم لرقم تعريف رابط الخدمة في AdWords.
SolutionRunner.java
ServiceLink serviceLink = new ServiceLink();
serviceLink.setServiceLinkId(newMcAccount.getId().longValue());
serviceLink.setLinkStatus(ServiceLinkLinkStatus.ACTIVE);
serviceLink.setServiceType(ServiceType.MERCHANT_CENTER);
ServiceLinkOperation op = new ServiceLinkOperation();
op.setOperator(Operator.SET);
op.setOperand(serviceLink);
قبول الربط
وأخيرًا، سنستدعي الطريقة mutateServiceLinks()
لعنصر CustomerService لتنفيذ العملية. وكما في السابق، تتطلب هذه العملية مجموعة من عمليات ربط الخدمة. هذه المرة، تُرجع الطريقة قائمة بروابط الخدمة (ربما تم تغييرها) مباشرةً، ولذلك سنطبع نتيجة الحل الذي نقدمه من خلال التكرار فوق تلك القائمة. وبما أنّنا حدّدنا عملية واحدة فقط، لا تتوقّع أن تتم طباعة سوى رابط واحد في الناتج.
SolutionRunner.java
ServiceLink[] mutatedServiceLinks =
customerService.mutateServiceLinks(new ServiceLinkOperation[] {op});
for (ServiceLink mutatedServiceLink : mutatedServiceLinks) {
System.out.printf(
"Service link with service link ID %d, type '%s' updated to status: %s.%n",
mutatedServiceLink.getServiceLinkId(),
mutatedServiceLink.getServiceType(),
mutatedServiceLink.getLinkStatus());
}
تجربة الميزة
كما في السابق، جرِّب تشغيل الحلّ. في حال استخدام Maven من سطر الأوامر:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
وإذا سارت الأمور على ما يرام، من المفترض ألا تظهر أي أخطاء، وستظهر أيضًا ملاحظة تفيد بأنّه تم تعديل رابط الخدمة وأصبح نشطًا. اطّلِع على AdWords وMerchant Center وتأكَّد من أنّ الحسابات قد تم ربطها الآن.
8. الاختلافات في مظهر ما
تهانينا على اجتياز الدرس التطبيقي حول الترميز. والآن بعد أن أصبح لديك حل يعمل بشكل كامل، دعنا نلقي نظرة على بعض الأمثلة حول كيفية تعديله أو توسيعه لاستخدام المزيد من واجهات برمجة التطبيقات التي تعرفت عليها في هذا الدرس التطبيقي حول الترميز.
رصيد إضافي: تعديل حساب حالي في Merchant Center لطلب ربط حساب AdWords
في الدرس التطبيقي حول الترميز، أنشأنا حساب AdWords بمهارة أولاً لنتمكّن من استخدام معلوماته لطلب الربط عند إنشاء حساب Merchant Center. في المقابل، إذا كان حساب Merchant Center متوفّرًا حاليًا، عليك تعديل إعداداته بدلاً من ذلك. جرِّب تغيير الرمز لإنشاء حساب Merchant Center أولاً، ثم ارجع بعد ذلك بعد إنشاء حساب AdWords وعدِّل إعداداته لطلب الربط.
رصيد إضافي: تحقَّق من إنشاء الرابط من خلال استرداد معلومات حساب AdWords وMerchant Center
في الوقت الحالي، لا يتعامل التطبيق إلا مع غياب الأخطاء في طلبات البيانات من واجهة برمجة التطبيقات باعتبارها مؤشرًا على النجاح. جرِّب توسيع المثال للاطّلاع على معلومات الرابط لحسابَي Merchant Center وAdWords الجديدَين ومعرفة أنّ الرابط نشط.
العالم هو محارك
إذا كنت تفكر في تغييرات أخرى يمكنك إجراؤها، فجرّبها! إذا كنت بحاجة إلى رمز مرجعي لأفكارك، يمكنك الاطّلاع على نماذج Google Shopping والدليل examples
في مصدر مكتبة عملاء Java في "إعلانات Google".