ایجاد و پیوند حساب های فرعی AdWords و Merchant Center

1. مقدمه

در این کد لبه، شما برخی از اصول کار با Content API for Shopping و AdWords API را یاد خواهید گرفت و اپلیکیشنی را می سازید که از هر دو استفاده کند. به طور خاص، شما یک برنامه خط فرمان خواهید ساخت که یک حساب AdWords و یک حساب Merchant Center را ایجاد و پیوند می دهد.

چیزی که یاد خواهید گرفت

• نحوه ایجاد حساب های AdWords مدیریت شده توسط یک حساب مدیر.
• نحوه ایجاد حساب‌های Merchant Center که توسط یک حساب چند مشتری مدیریت می‌شود.
• نحوه درخواست پیوند از حساب Merchant Center به حساب AdWords.
• نحوه پذیرش پیوند Merchant Center معلق در حساب AdWords.

آنچه شما نیاز دارید

• یک حساب مدیر AdWords
• یک حساب چند مشتری Merchant Center
• جاوا 7+
• ماون
• کد نمونه
• یک ویرایشگر متن (یک IDE که پروژه های Maven مانند Eclipse یا IntelliJ را درک می کند توصیه می شود)

2. راه اندازی

c ode را دانلود کنید

برای دانلود تمامی کدهای این کد لبه روی لینک زیر کلیک کنید:

دانلود کد منبع

فایل فشرده دانلود شده را باز کنید. این یک پوشه ریشه ( 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. احراز هویت را تنظیم کنید

برای این مرحله، ما هیچ کدنویسی انجام نمی‌دهیم، بلکه فایل‌هایی را تنظیم می‌کنیم که حاوی نشانه‌های احراز هویت مناسب برای API AdWords و Content API برای خرید هستند.

API AdWords را یک احراز هویت تنظیم کنید

این کد لبه از بارگیری اعتبارنامه مشابه کتابخانه سرویس گیرنده استفاده می کند، بنابراین اگر قبلاً از Google Ads APIs Client Library برای جاوا با حساب مدیر خود استفاده کرده اید، باید قبلاً راه اندازی شده باشید. در غیر این صورت، مراحل 1-3 را برای شروع با Google Ads APIs Client Library برای جاوا دنبال کنید.

Content API را یک احراز هویت تنظیم کنید

اگر از قبل کلید حساب سرویس ندارید:

1. برای حساب چند مشتری خود به Merchant Center بروید و Content API را از منوی سرریز انتخاب کنید:
2. Authentication را انتخاب کنید، سپس روی دکمه آبی + کلیک کنید:
3. پس از پذیرش شرایط سرویس Google Cloud Platform و Google APIs، مرورگر شما به طور خودکار یک فایل JSON حاوی کلید حساب سرویس جدید شما را دانلود می کند.

اکنون دستورالعمل‌های تنظیم احراز هویت را برای نمونه‌های خرید با یک حساب سرویس دنبال کنید. یعنی یک کپی از کلید حساب سرویس شما باید در مسیر زیر از فهرست اصلی شما قرار گیرد: shopping-samples/content/service-account.json . شما نیازی به تنظیم پیکربندی نمونه ها ندارید، مگر اینکه علاقه مند باشید نمونه ها را پس از اتمام این کد لبه امتحان کنید!

تستش کن

اکنون که نشانه های احراز هویت را در مکان های مناسب دارید، سعی کنید نمونه ها را اجرا کنید. اگر از Maven در خط فرمان استفاده می کنید، دستورات زیر را اجرا کنید:

mvn compile

توجه: اگر هر یک از فایل‌ها را در src/main/resources تغییر می‌دهید، حتی اگر هیچ تغییری در کد ایجاد نمی‌کنید (مانند این مرحله)، قبل از اجرای نمونه‌ها، دوباره کامپایل کنید تا منابع تغییر یافته خود را در هدف کپی کنید.

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

اگر پیام خطایی در مورد ارائه نشدن اشیاء جلسه دریافت کردید، نشانه‌های احراز هویت شما در جای خود هستند و به درستی کار می‌کنند! در غیر این صورت، پیام خطایی که دریافت می‌کنید باید به شما اطلاع دهد که کدام اعتبارنامه کار نمی‌کند و کدام فایل را باید اصلاح کنید.

مهم : چارچوبی که ما ارائه کرده‌ایم فرض می‌کند که حساب سرویس Content API شما فقط به عنوان کاربر در حساب چند مشتری شما فهرست شده است. اگر خطایی دریافت کردید که می‌گوید حساب سرویس شما به بیش از یک حساب دسترسی دارد، مراحل بالا را دنبال کنید تا یک کلید حساب سرویس مخصوص حساب چند مشتری خود را دریافت کنید.

4. به API ها متصل شوید

اکنون که توکن‌های معتبر احراز هویت برای دو API استفاده می‌کنیم، بیایید شروع به پر کردن کد واقعی کنیم. ما با ایجاد اشیاء جلسه با استفاده از توکن های احراز هویت خود شروع می کنیم. در مراحل بعدی، به سرویس‌ها و روش‌های مختلفی که هر API با استفاده از این اشیاء جلسه ارائه می‌کند، دسترسی خواهیم داشت.

یک شی جلسه 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();

توجه: نظرات اولیه در این و نمونه کد زیر از قبل در اسکلت کد وجود دارد. به دنبال آنها بگردید تا ببینید این خطوط باید کجا اضافه شوند.

ما همچنین هر گونه عبارت import مورد نیاز را برای کلاس‌های API AdWords و Content API که در این قطعه‌ها استفاده می‌کنیم حذف می‌کنیم. اگر از یک IDE استفاده نمی‌کنید که بتواند به‌طور خودکار واردات صحیح را اضافه کند، لطفاً کد موجود در بسته solution را برای واردات مورد نیاز بررسی کنید.

تنظیم نام برنامه کاملاً ضروری نیست، اما نشان می دهد که چگونه می توان هر گزینه دلخواه را از طریق شی ShoppingContent.Builder قبل از فراخوانی متد build() تنظیم کرد.

یک شی جلسه API AdWords ایجاد کنید

به طور مشابه، یک کلاس 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 را از طریق خط فرمان اجرا می کنید، از همان دستورات قسمت آخر برای بازسازی و اجرای پروژه Maven استفاده می کنیم:

mvn compile

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

این بار، به هیچ وجه نباید خطایی دریافت کنید، هرچند خروجی جالبی نیز دریافت نخواهید کرد. وقتی با API ها تماس می گیریم تا حساب های جدید را ایجاد و پیوند دهیم، آن را اضافه می کنیم.

5. یک حساب AdWords مدیریت شده جدید ایجاد کنید

اکنون که اشیاء جلسه API خود را ایجاد کرده‌ایم، حساب‌هایی را که می‌خواهیم پیوند بدهیم ایجاد می‌کنیم. ما با AdWords شروع می کنیم و یک حساب آزمایشی تحت حساب مدیر خود ایجاد می کنیم.

توجه: تمام کدهای این بخش به ترتیب ارائه شده به همان مکان در کد اسکلت اضافه می شوند. به همین دلیل، ما فقط نظر ( // TODO...) نشان می‌دهیم که محل قرار دادن آنها را در اولین مورد مشخص می‌کند. بنابراین در این مرحله و مراحل بعدی، اگر قطعه کد بدون نظر مقدماتی را مشاهده کردید، بلافاصله بعد از قطعه قبلی می روند.

به ManagedCustomerService دسترسی پیدا کنید

در API AdWords، ابتدا با بازیابی نمونه ای از کلاس AdWordsServices با استفاده از متد static 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 ایجاد می کنیم که حاوی تنظیمات حساب جدید ما است. ما یک حساب آزمایشی برای این Codelab ایجاد می‌کنیم و واحد پول آن را USD و منطقه زمانی آن را مشابه ساحل غربی ایالات متحده تنظیم می‌کنیم.

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 s است. در اینجا، فهرستی حاوی یک مشتری، حساب جدیدی است که ما ایجاد کردیم. شناسه آن حساب جدید را برای استفاده در آینده بازیابی می کنیم و همچنین آن را چاپ می کنیم تا بتوانیم آن را به عنوان بخشی از خروجی راه حل خود ببینیم.

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 model شی را برمی‌گردانند، بنابراین می‌توانیم تماس‌های خود را با آنها در شیء 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 برای حساب فرعی جدید اضافه کنیم. هنگامی که حساب فرعی جدید ایجاد شد، این پیوند به طور خودکار در API AdWords درخواست و در دسترس خواهد بود.

یک حساب فرعی جدید ایجاد کنید

در 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 را برای حساب چند مشتری خود بررسی کنید تا حساب فرعی جدید را در آنجا ببینید.

توجه: مانند AdWords، هر اجرا از راه حل اکنون حساب های Merchant Center جدیدی ایجاد می کند. پس از اتمام راه‌حل خود، می‌توانید حساب‌های فرعی ایجاد شده را از طریق Merchant Center حذف کنید.

7. پیوند را از حساب AdWords بپذیرید

در مرحله آخر، یک حساب فرعی Merchant Center جدید ایجاد کردیم و همزمان درخواست پیوند به حساب جدید AdWords خود را دادیم. در این مرحله، فرآیند را با استفاده از API AdWords برای پذیرش پیوند درخواستی به پایان خواهیم رساند.

دسترسی به خدمات مشتری

مانند قبل، از کلاس 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 ببریم و آن را روی ACTIVE SET . برای تنظیم 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. تغییرات در یک موضوع

به شما تبریک می‌گویم که توانستید آن را از طریق نرم‌افزار رمزگذاری کنید! اکنون که راه حلی کاملاً کارآمد دارید، بیایید به چند نمونه از نحوه تغییر یا گسترش آن برای استفاده بیشتر از APIهایی که در این کد لبه دیده‌اید نگاه کنیم.

اعتبار اضافی: برای درخواست پیوند AdWords، یک حساب Merchant Center موجود را به‌روزرسانی کنید

در Codelab ابتدا حساب AdWords را هوشمندانه ایجاد کردیم تا بتوانیم از اطلاعات آن برای درخواست پیوند هنگام ایجاد حساب Merchant Center استفاده کنیم. با این حال، اگر حساب Merchant Center از قبل وجود داشته باشد، به جای آن باید پیکربندی آن را به‌روزرسانی کنید. سعی کنید ابتدا کد خود را تغییر دهید تا حساب Merchant Center ایجاد شود و سپس پس از ایجاد حساب AdWords به عقب برگردید و پیکربندی آن را برای درخواست پیوند به روز کنید.

توجه: باید از روش Accounts.update یا Accounts.patch استفاده کنید. در واقع، یک نسخه را با هر کدام امتحان کنید تا تفاوت را درک کنید!

مهم : ممکن است یک حساب Merchant Center جدید بلافاصله پس از تماس با Accounts.insert در دسترس نباشد. تا زمانی که حساب جدید در دسترس باشد، در تلاش برای دسترسی یا تغییر آن، خطای HTTP 401 دریافت خواهید کرد. نمونه های خرید نمونه ای از استفاده از backoff نمایی برای امتحان مجدد روش ها در AccountWorkflow.java دارند که از روش retryFailures از BaseWorkflowSample.java استفاده می کند.

اعتبار اضافی: ایجاد پیوند را با بازیابی اطلاعات حساب AdWords و Merchant Center تأیید کنید

در حال حاضر، این برنامه تنها عدم وجود خطا از فراخوانی های API را به عنوان نشانه موفقیت در نظر می گیرد. سعی کنید مثال را گسترش دهید تا اطلاعات پیوند را برای حساب‌های Merchant Center و Adwords جدید بررسی کنید و ببینید که پیوند واقعاً فعال است.

توجه: در سمت Content API، باید به روش Accounts.get نگاه کنید. در سمت AdWords، باید از متد getServiceLinks شی CustomerServiceInterface استفاده کنید.

دنیا صدف توست

اگر به تغییرات دیگری فکر می کنید که می توانید ایجاد کنید، آنها را امتحان کنید! اگر برای ایده‌های خود به کد مرجع نیاز دارید، نمونه‌های خرید Google و فهرست examples را در منبع کتابخانه سرویس گیرنده Google Ads Java بررسی کنید.