۱. مقدمه
در این آزمایشگاه کد، شما اصول اولیه کار با API محتوا برای خرید و API ادوردز را یاد خواهید گرفت و برنامهای خواهید ساخت که از هر دو استفاده میکند. به طور خاص، شما یک برنامه خط فرمان خواهید ساخت که یک حساب ادوردز و یک حساب مرکز فروشندگان را ایجاد و به هم پیوند میدهد.
آنچه یاد خواهید گرفت
- نحوه ایجاد حسابهای ادوردز که توسط یک حساب مدیریتی مدیریت میشوند.
- نحوه ایجاد حسابهای مرکز فروش که توسط یک حساب چند کلاینتی مدیریت میشوند.
- نحوه درخواست لینک از حساب مرکز فروش به حساب ادوردز.
- نحوه پذیرش لینک در حال انتظار مرکز فروشندگان در حساب ادوردز.
آنچه نیاز دارید
- یک حساب کاربری مدیریت ادوردز
- یک حساب کاربری چند کلاینتی مرکز بازرگانان
- جاوا ۷+
- ماون
- کد نمونه
- یک ویرایشگر متن (یک IDE که پروژههای Maven مانند Eclipse یا IntelliJ را درک کند، توصیه میشود)
۲. راهاندازی
کد را دانلود کنید
برای دانلود تمام کدهای این codelab روی لینک زیر کلیک کنید:
فایل زیپ دانلود شده را از حالت فشرده خارج کنید. این کار پوشه ریشه ( 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
۳. احراز هویت را تنظیم کنید
برای این مرحله، ما هیچ کدنویسی انجام نخواهیم داد، اما فایلهایی را تنظیم میکنیم که حاوی توکنهای احراز هویت مناسب برای API ادوردز و API محتوا برای خرید باشند.
تنظیم احراز هویت API ادوردز
این آزمایشگاه کد از همان بارگذاری اعتبارنامه به عنوان کتابخانه کلاینت استفاده میکند، بنابراین اگر قبلاً از کتابخانه کلاینت APIهای گوگل ادز برای جاوا با حساب مدیر خود استفاده کردهاید، باید از قبل راهاندازی شده باشید. در غیر این صورت، مراحل ۱ تا ۳ را برای شروع کار با کتابخانه کلاینت APIهای گوگل ادز برای جاوا دنبال کنید.
تنظیم احراز هویت برای API محتوا
اگر از قبل کلید حساب سرویس ندارید:
- برای حساب چند کلاینتی خود به مرکز فروشندگان بروید و از منوی باز شده، Content API را انتخاب کنید:
- گزینه Authentication (احراز هویت) را انتخاب کنید، سپس روی دکمه آبی + کلیک کنید:
- پس از پذیرش شرایط خدمات پلتفرم ابری گوگل و APIهای گوگل، مرورگر شما بهطور خودکار یک فایل JSON حاوی کلید حساب سرویس جدید شما را دانلود میکند.
حالا دستورالعملهای مربوط به تنظیم احراز هویت برای نمونههای خرید با یک حساب کاربری سرویس را دنبال کنید. یعنی، یک کپی از کلید حساب کاربری سرویس شما باید در مسیر زیر از دایرکتوری خانگی شما قرار داشته باشد: shopping-samples/content/service-account.json . نیازی به تنظیم پیکربندی نمونهها ندارید، مگر اینکه پس از اتمام این آزمایشگاه کد، علاقهمند به امتحان کردن نمونهها باشید!
آن را آزمایش کنید
حالا که توکنهای احراز هویت را در جای درست قرار دادهاید، نمونهها را اجرا کنید. اگر از Maven استفاده میکنید، دستورات زیر را در خط فرمان اجرا کنید:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
اگر پیام خطایی در مورد عدم ارائه اشیاء جلسه دریافت کردید، پس توکنهای احراز هویت شما در جای خود قرار دارند و به درستی کار میکنند! در غیر این صورت، پیام خطایی که دریافت میکنید باید به شما اطلاع دهد که کدام اعتبارنامهها کار نکردهاند و کدام فایل را باید اصلاح کنید.
۴. به APIها متصل شوید
حالا که توکنهای احراز هویت معتبری برای دو API مورد استفاده دارید، بیایید شروع به پر کردن کد اصلی کنیم. ما با ایجاد اشیاء جلسه با استفاده از توکنهای احراز هویت خود شروع خواهیم کرد. در مراحل بعدی، با استفاده از این اشیاء جلسه به سرویسها و متدهای مختلفی که هر API ارائه میدهد دسترسی خواهیم داشت.
ایجاد یک شیء جلسه API محتوا
برای ایجاد یک جلسه 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() تنظیم کرد.
ایجاد یک شیء جلسه 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"
این بار، نباید هیچ خطایی دریافت کنید، هرچند خروجی جالبی هم دریافت نخواهید کرد. این را هنگام فراخوانی APIها برای ایجاد و پیوند حسابهای جدید اضافه خواهیم کرد.
۵. یک حساب کاربری مدیریتشدهی جدید در ادوردز ایجاد کنید
حالا که اشیاء جلسه API خود را ایجاد کردهایم، به سراغ ایجاد حسابهایی که میخواهیم به آنها لینک دهیم میرویم. با 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 دسترسی داریم که به ما امکان میدهد «مشتریان» (حسابهای) ادوردز را از یک حساب مدیریتی مشخص مدیریت کنیم.
تنظیمات حساب جدید را مشخص کنید
ابتدا، یک شیء 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 ها میشود؛ در اینجا، لیستی شامل یک مشتری، یعنی حساب جدیدی که ایجاد کردهایم، خواهد بود. ما شناسه آن حساب جدید را برای استفادههای بعدی بازیابی میکنیم و همچنین آن را چاپ میکنیم تا بتوانیم آن را به عنوان بخشی از خروجی راهحل خود ببینیم.
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"
اگر همه چیز خوب پیش برود، هنوز نباید هیچ خطایی ببینید و این بار شناسه حساب ادوردز جدیدی که ایجاد کردهایم را خواهیم دید. سایت ادوردز را برای حساب مدیریت خود بررسی کنید و باید حساب جدید را نیز در آنجا مشاهده کنید!
۶. یک حساب فرعی جدید در مرکز بازرگانان ایجاد کنید
در این مرحله، ما یک زیرحساب مرکز فروشندگان ایجاد خواهیم کرد که آن را به حساب ادوردزی که در مرحله قبل ایجاد کردیم، لینک خواهیم کرد. به جای اینکه بعد از ایجاد زیرحساب، درخواست جداگانهای برای لینک بدهیم، میتوانیم در حین ایجاد حساب، درخواست لینک را انجام دهیم، زیرا از قبل شناسه حساب ادوردز مربوطه را داریم.
تنظیمات مربوط به حساب فرعی جدید را مشخص کنید
برخلاف API ادوردز، تنظیمکنندههای کلاس مدل Account ، شیء را برمیگردانند، بنابراین میتوانیم فراخوانیهای خود را در شیء Account جدید به آنها زنجیره کنیم. ما از عدد تصادفی که در طول ایجاد حساب ادوردز ایجاد کردیم، در نام حساب جدید مرکز فروشندگان نیز استفاده خواهیم کرد.
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 در دسترس قرار میگیرد.
زیرحساب جدید را ایجاد کنید
در API محتوا، ما متد accounts() از شیء session را برای دسترسی به سرویس 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 اصلی خود را بازنویسی میکنیم زیرا نسخه برگردانده شده شامل یک بخش مهم از اطلاعات است: شناسه زیرحساب جدید. ما آن را در خروجی راهحل خود چاپ میکنیم، بنابراین میتوانیم راهحل خود را اجرا کنیم و سپس تأیید کنیم که زیرحساب جدید در مرکز فروشندگان وجود دارد.
آن را آزمایش کنید
مانند قبل، سعی کنید راهحل را اجرا کنید. اگر از Maven از خط فرمان استفاده میکنید:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
اگر همه چیز خوب پیش برود، هنوز نباید هیچ خطایی ببینید و این بار شناسههای هر دو حساب جدید AdWords و حساب جدید Merchant Center را خواهیم دید. برای مشاهده زیرحساب جدید، Merchant Center را برای حساب چند کلاینتی خود بررسی کنید.
۷. لینک را از حساب ادوردز خود بپذیرید
در مرحله آخر، ما یک زیرحساب مرکز فروشندگان جدید ایجاد کردیم و همزمان درخواست لینک به حساب ادوردز جدید خود را دادیم. در این مرحله، با استفاده از API ادوردز برای پذیرش لینک درخواستی، این فرآیند را به پایان خواهیم رساند.
دسترسی به خدمات مشتریان
مانند قبل، ما از کلاس AdWordsServices برای دریافت یک کلاینت برای CustomerService استفاده خواهیم کرد. با این حال، قبل از ایجاد کلاینت، ابتدا شیء جلسه AdWords خود را تغییر میدهیم تا استفادههای بعدی به جای حساب مدیر، روی حساب مدیریتشده جدید عمل کنند. از این گذشته، حساب مرکز فروشندگان درخواست پیوند به حساب مدیریتشده را داشت، نه حساب مدیر.
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 ، از شناسه حساب مرکز فروشندگان که تازه ایجاد کردهایم استفاده خواهیم کرد، زیرا این شناسه برای شناسه لینک سرویس در 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 و مرکز فروشندگان را بررسی کنید و دوباره بررسی کنید که حسابها واقعاً اکنون به هم متصل شدهاند.
۸. واریاسیونهایی روی یک تم
تبریک میگویم که از آزمایشگاه کد عبور کردید! حالا که یک راهحل کاملاً کاربردی دارید، بیایید به چند مثال از نحوهی اصلاح یا گسترش آن برای استفادهی بیشتر از APIهایی که در این آزمایشگاه کد دیدهاید، نگاهی بیندازیم.
اعتبار اضافی: برای درخواست لینک AdWords، حساب مرکز فروشندگان فعلی خود را بهروزرسانی کنید
در codelab، ما هوشمندانه ابتدا حساب AdWords را ایجاد کردیم تا بتوانیم از اطلاعات آن برای درخواست لینک هنگام ایجاد حساب مرکز فروشندگان استفاده کنیم. با این حال، اگر حساب مرکز فروشندگان از قبل وجود دارد، باید پیکربندی آن را بهروزرسانی کنید. سعی کنید کد خود را تغییر دهید تا ابتدا حساب مرکز فروشندگان ایجاد شود و سپس پس از ایجاد حساب AdWords برگردید و پیکربندی آن را برای درخواست لینک بهروزرسانی کنید.
اعتبار اضافی: با بازیابی اطلاعات حساب AdWords و Merchant Center، ایجاد لینک را تأیید کنید
در حال حاضر، برنامه فقط عدم وجود خطا در فراخوانیهای API را به عنوان نشانهای از موفقیت در نظر میگیرد. سعی کنید مثال را گسترش دهید تا اطلاعات لینک را برای حسابهای جدید مرکز فروشندگان و Adwords بررسی کنید و ببینید که آیا لینک واقعاً فعال است یا خیر.
دنیا مال توئه
اگر به تغییرات دیگری که میتوانید ایجاد کنید فکر میکنید، آنها را امتحان کنید! اگر برای ایدههای خود به کد مرجع نیاز دارید، نمونههای خرید گوگل و فهرست examples را در منبع کتابخانه کلاینت جاوای گوگل ادز بررسی کنید.