إنشاء الحسابات الفرعية في 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
• نموذج الرمز البرمجي
• محرِّر نصوص (ننصح باستخدام بيئة تطوير متكاملة تتيح استخدام مشاريع 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 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. الصيغ المختلفة لموضوع معيّن

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

رصيد إضافي: تعديل حساب حالي على Merchant Center لطلب ربط حساب على AdWords

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

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

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

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

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

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

الوصول إلى مستخدمين من جميع أنحاء العالم

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