إنشاء الحسابات الفرعية في AdWords وMerchant Center وربطها

1. مقدمة

في هذا الدرس التطبيقي حول الترميز، ستتعرّف على بعض أساسيات العمل مع Content API for Shopping وAdWords API، وستنشئ تطبيقًا يستخدم كلتيهما. على وجه الخصوص، ستنشئ تطبيق سطر أوامر لإنشاء حساب على "إعلانات Google" وحساب على 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 على الحلّ النهائي.

تثبيت الحِزم المطلوبة وإنشاء التطبيق

إذا كنت تستخدم بيئة تطوير متكاملة (IDE) متوافقة مع 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 API للغة Java.

إعداد مصادقة Content API

إذا لم يكن لديك مفتاح حساب خدمة، اتّبِع الخطوات التالية:

1. انتقِل إلى Merchant Center لحسابك المتعدّد العملاء، وانقر على Content API من القائمة الكاملة:
2. اختَر المصادقة، ثم انقر على الزر الأزرق +:
3. بعد قبول بنود خدمة Google Cloud Platform وGoogle APIs، سينزّل المتصفّح تلقائيًا ملف JSON يحتوي على مفتاح حساب الخدمة الجديد.

اتّبِع الآن التعليمات لإعداد المصادقة لعينات Shopping باستخدام حساب خدمة. أي يجب أن تكون نسخة من مفتاح حساب الخدمة متوفرة في المسار التالي من الدليل الرئيسي: shopping-samples/content/service-account.json. لست بحاجة إلى إعداد إعدادات العيّنات، إلا إذا كنت مهتمًا بتجربة العيّنات بعد الانتهاء من هذا الدرس التطبيقي حول الترميز.

تجربة الميزة

بعد وضع رموز المصادقة المميزة في الأماكن الصحيحة، جرِّب تشغيل النماذج. إذا كنت تستخدم Maven في سطر الأوامر، نفِّذ الأوامر التالية:

mvn compile

ملاحظة: إذا غيّرت أيًا من الملفات في src/main/resources، حتى إذا لم تُجرِ أي تغييرات على الرمز (كما في هذه الخطوة)، أعِد تجميع الملفات قبل تشغيل النماذج لنسخ الموارد التي تم تغييرها إلى الهدف.

mvn exec:java -Dexec.mainClass="SolutionRunner"

إذا تلقّيت رسالة خطأ بشأن عدم توفير عناصر الجلسة، يعني ذلك أنّ رموز المصادقة متوفّرة وتعمل بشكل صحيح. في ما عدا ذلك، ستُعلمك رسالة الخطأ التي تظهر لك ببيانات الاعتماد التي لم تعمل والملف الذي يجب إصلاحه.

ملاحظة مهمة: يفترض إطار العمل الذي قدّمناه أنّ حساب الخدمة على Content API مُدرَج كمستخدم في حسابك المتعدّد العملاء فقط. إذا تلقّيت رسالة خطأ تفيد بأنّ حساب الخدمة لديه إذن الوصول إلى أكثر من حساب واحد، اتّبِع الخطوات أعلاه للحصول على مفتاح حساب خدمة خاص بحسابك المتعدّد العملاء.

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();

ملاحظة: تتوفّر التعليقات الأولية في عينة الرمز البرمجي هذه وعينات الرموز البرمجية التالية في البنية الأساسية للرمز البرمجي. ابحث عن هذه الأقسام لمعرفة المكان الذي يجب إضافة هذه الأسطر فيه.

نحذف أيضًا أي عبارات استيراد مطلوبة لفئات AdWords API وContent API التي نستخدمها في هذه المقتطفات. إذا كنت لا تستخدم بيئة تطوير متكاملة يمكنها إضافة عمليات الاستيراد الصحيحة تلقائيًا، يُرجى مراجعة الرمز في حزمة solution لمعرفة عمليات الاستيراد المطلوبة.

ليس من الضروري تمامًا ضبط اسم التطبيق، ولكنّه يوضّح كيفية ضبط أي خيارات مطلوبة من خلال العنصر 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 وننشئ حسابًا تجريبيًا ضمن حسابنا الإداري.

ملاحظة: تتم إضافة جميع مقتطفات الرموز البرمجية في هذا القسم إلى المكان نفسه في الرمز الأساسي بالترتيب المعروض. لهذا السبب، لن نعرض سوى التعليق (// TODO...) الذي يحدّد مكان وضعها في التعليق الأول. لذلك، في هذه الخطوة والخطوات المستقبلية، إذا رأيت مقتطفات رمز بدون تعليق تمهيدي، ستظهر مباشرةً بعد المقتطف السابق.

الوصول إلى 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 الذي سننشئه لاحقًا، وبالتالي يمكننا فحص الحسابَين بصريًا بعد اكتمال الحلّ والتأكّد من أنّه ربط الحسابَين بالفعل.

إنشاء حساب مُدار جديد

لإنشاء الحساب الجديد فعليًا، سنستخدم 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 الإلكتروني بحثًا عن حسابك الإداري، وسيظهر لك الحساب الجديد مُدرَجًا هناك أيضًا.

ملاحظة: في هذه المرحلة، سيؤدي كل تشغيل للحلّ إلى إنشاء حسابات جديدة. يمكنك إلغاء أي حسابات AdWords تم إنشاؤها من خلال موقع AdWords بعد الانتهاء من تشغيل الحلّ. ففي النهاية، يسهّل نظام التسمية الذي نستخدمه لهذه الحسابات معرفة الحسابات التي أنشأها الرمز.

6. إنشاء حساب فرعي جديد على Merchant Center

في هذه الخطوة، سننشئ حسابًا فرعيًا على Merchant Center سنربطه بحساب AdWords الذي أنشأناه في الخطوة السابقة. بدلاً من طلب الربط بشكل منفصل بعد إنشاء الحساب الفرعي، يمكننا طلب الربط أثناء الإنشاء لأنّنا نملك الرقم التعريفي لحساب AdWords المقابل.

تحديد إعدادات الحساب الفرعي الجديد

على عكس 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 لحسابك المتعدّد العملاء للاطّلاع على الحساب الفرعي الجديد.

ملاحظة: كما هو الحال مع 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 وعدِّل إعداداته لطلب الربط.

ملاحظة: عليك استخدام إحدى الطريقتين Accounts.update أو Accounts.patch. في الواقع، جرِّب إصدارًا يتضمّن كليهما لفهم الفرق بينهما.

ملاحظة مهمة: قد لا يتوفّر حساب جديد على Merchant Center فورًا بعد إجراء طلب إلى Accounts.insert. إلى أن يصبح الحساب الجديد متاحًا، ستتلقّى رسالة خطأ 401 HTTP عند محاولة الوصول إليه أو تعديله. تتضمّن عيّنات Shopping مثالاً على استخدام أسلوب التراجع الدليلي لإعادة محاولة تنفيذ الطرق في AccountWorkflow.java، والذي يستخدم طريقة retryFailures من BaseWorkflowSample.java.

مكافأة إضافية: تأكَّد من إنشاء الرابط من خلال استرداد معلومات حساب AdWords وحساب Merchant Center

في الوقت الحالي، لا يتعامل التطبيق مع عدم ظهور أخطاء في طلبات البيانات من واجهة برمجة التطبيقات إلا كإشارة إلى النجاح. جرِّب توسيع المثال للتحقّق من معلومات الربط الخاصة بحسابَي Merchant Center وAdWords الجديدَين والتأكّد من أنّ الربط نشط بالفعل.

ملاحظة: من جهة Content API، عليك الاطّلاع على طريقة Accounts.get. من جهة AdWords، عليك استخدام طريقة getServiceLinks الخاصة بالعنصر CustomerServiceInterface.

العالم بين يديك

إذا فكّرت في تغييرات أخرى يمكنك إجراؤها، جرِّبها. إذا كنت بحاجة إلى رمز مرجعي لأفكارك، يمكنك الاطّلاع على أمثلة Google Shopping ودليل examples في مصدر مكتبة برامج Java للعملاء في "إعلانات Google".