Membuat dan Menautkan Sub-akun AdWords dan Merchant Center

1. Pengantar

Dalam codelab ini, Anda akan mempelajari beberapa dasar-dasar penggunaan Content API for Shopping dan AdWords API serta mem-build aplikasi yang menggunakan keduanya. Secara khusus, Anda akan mem-build aplikasi command line yang akan membuat dan menautkan akun AdWords dan akun Merchant Center.

Yang akan Anda pelajari

• Cara membuat akun AdWords yang dikelola oleh akun pengelola.
• Cara membuat akun Merchant Center yang dikelola oleh akun multiklien.
• Cara meminta penautan dari akun Merchant Center ke akun AdWords.
• Cara menerima penautan Merchant Center yang tertunda di akun AdWords.

Yang Anda butuhkan

• Akun pengelola AdWords
• Akun multiklien Merchant Center
• Java 7+
• Maven
• Kode contoh
• Editor teks (IDE yang memahami project Maven seperti Eclipse atau IntelliJ direkomendasikan)

2. Mempersiapkan

Download kode

Klik link berikut guna mendownload semua kode untuk codelab ini:

Download kode sumber

Ekstrak file ZIP yang didownload. Tindakan ini akan mengekstrak folder root (shopping-account-linking-master), yang berisi project Maven beserta semua resource yang Anda perlukan. Subdirektori berikut perlu diperhatikan secara khusus:

• src/main/java adalah root sumber project Maven dan berisi kerangka kode untuk Anda gunakan.
• src/main/java/solution berisi solusi yang sudah selesai.

Menginstal paket dan mem-build yang diperlukan

Jika menggunakan IDE yang mendukung Maven seperti Eclipse atau IntelliJ, Anda dapat mengimpor folder yang diekstrak sebagai project Maven, lalu mengompilasi project secara normal.

Jika menggunakan Maven dari command line, Anda dapat menjalankan perintah berikut untuk mengambil paket yang diperlukan dan mengompilasi project dari folder root project yang diekstrak (shopping-account-linking-master):

mvn compile

3. Menyiapkan autentikasi

Untuk langkah ini, kita tidak akan melakukan coding apa pun, tetapi menyiapkan file yang berisi token autentikasi yang sesuai untuk AdWords API dan Content API untuk Shopping.

Menyiapkan autentikasi AdWords API

Codelab ini menggunakan pemuatan kredensial yang sama dengan library klien, jadi jika Anda telah menggunakan Library Klien Google Ads API untuk Java dengan akun pengelola, Anda seharusnya sudah siap. Jika tidak, ikuti langkah 1-3 untuk memulai Library Klien Google Ads API untuk Java.

Menyiapkan autentikasi Content API

Jika Anda belum memiliki kunci akun layanan:

1. Buka Merchant Center untuk akun multiklien Anda, lalu pilih Content API dari menu tambahan:
2. Pilih Authentication, lalu klik tombol + biru:
3. Setelah menyetujui Persyaratan Layanan Google Cloud Platform dan Google API, browser Anda akan otomatis mendownload file JSON yang berisi kunci akun layanan baru Anda.

Sekarang, ikuti petunjuk untuk menyiapkan autentikasi untuk contoh Shopping dengan akun layanan. Artinya, salinan kunci akun layanan Anda harus berada di jalur berikut dari direktori beranda Anda: shopping-samples/content/service-account.json. Anda tidak perlu menyiapkan konfigurasi contoh, kecuali jika Anda tertarik untuk mencoba contoh setelah menyelesaikan codelab ini.

Melakukan pengujian

Setelah Anda memiliki token autentikasi di tempat yang tepat, coba jalankan contoh. Jika Anda menggunakan Maven di command line, jalankan perintah berikut:

mvn compile

Catatan: Jika Anda mengubah salah satu file di src/main/resources, meskipun Anda tidak membuat perubahan kode apa pun (seperti pada langkah ini), kompilasi ulang sebelum menjalankan contoh untuk menyalin resource yang diubah ke target.

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

Jika Anda mendapatkan pesan error tentang objek sesi yang tidak diberikan, berarti token autentikasi Anda sudah ada dan berfungsi dengan benar. Jika tidak, pesan error yang Anda dapatkan akan memberi tahu Anda kredensial mana yang gagal berfungsi dan file mana yang harus diperbaiki.

Penting: Framework yang kami berikan mengasumsikan bahwa akun layanan Content API Anda hanya tercantum sebagai pengguna di akun multiklien Anda. Jika Anda mendapatkan error yang menyatakan bahwa akun layanan Anda memiliki akses ke lebih dari satu akun, ikuti langkah-langkah di atas untuk mendapatkan kunci akun layanan khusus untuk akun multiklien Anda.

4. Menghubungkan ke API

Setelah Anda memiliki token autentikasi yang valid untuk dua API yang akan kita gunakan, mari kita mulai mengisi kode yang sebenarnya. Kita akan mulai dengan membuat objek sesi menggunakan token autentikasi. Pada langkah berikutnya, kita akan mengakses berbagai layanan dan metode yang disediakan setiap API menggunakan objek sesi ini.

Membuat objek sesi Content API

Untuk membuat sesi Content API, kita akan membuat objek ShoppingContent.Builder, lalu menggunakannya untuk membuat objek ShoppingContent yang sesuai. Untungnya, semua yang kita perlukan untuk membuat yang pertama sudah tersedia dalam kerangka kode, jadi kita hanya perlu menggabungkannya seperti ini:

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

Catatan: Komentar awal dalam contoh kode ini dan berikutnya sudah ada dalam kerangka kode. Cari untuk melihat tempat baris ini harus ditambahkan.

Kami juga menghilangkan pernyataan impor yang diperlukan untuk class AdWords API dan Content API yang kami gunakan dalam cuplikan ini. Jika Anda tidak menggunakan IDE yang dapat otomatis menambahkan impor yang benar, periksa kode dalam paket solution untuk impor yang diperlukan.

Menetapkan nama aplikasi tidak mutlak diperlukan, tetapi menunjukkan cara menetapkan opsi yang diinginkan melalui objek ShoppingContent.Builder sebelum memanggil metode build().

Membuat objek sesi AdWords API

Demikian pula, ada class AdWordsSession.Builder untuk membuat objek AdWordsSession. Perbedaan utamanya di sini adalah, bukan menetapkan opsi konfigurasi langsung di builder, kita akan menggunakan metode fromFile() untuk memuat opsi tersebut dari file ads.properties yang kita siapkan di langkah sebelumnya.

SolutionRunner.java

// TODO(sessions): Create a AdWordsSession object using AdWordsSession.Builder.
adWordsSession =
    new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(adwordsOAuth2Credential)
        .build();

Melakukan pengujian

Kita akan menggunakan perintah yang sama seperti di bagian terakhir untuk mem-build ulang dan menjalankan project Maven, jika Anda menjalankannya dari command line:

mvn compile

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

Kali ini, Anda tidak akan mendapatkan error sama sekali, meskipun Anda juga tidak akan mendapatkan output yang menarik. Kita akan menambahkannya saat memanggil API untuk membuat dan menautkan akun baru.

5. Membuat akun AdWords terkelola baru

Setelah membuat objek sesi API, kita akan membuat akun yang ingin ditautkan. Kita akan memulai dengan AdWords dan membuat akun pengujian di akun pengelola.

Catatan: Semua cuplikan kode di bagian ini ditambahkan ke tempat yang sama dalam kode kerangka dalam urutan yang ditampilkan. Oleh karena itu, kami hanya akan menampilkan komentar (// TODO...) yang menandai tempat untuk menempatkannya di komentar pertama. Jadi, dalam langkah ini dan langkah-langkah selanjutnya, jika Anda melihat cuplikan kode tanpa komentar pengantar, cuplikan tersebut akan langsung muncul setelah cuplikan sebelumnya.

Mengakses ManagedCustomerService

Di AdWords API, kita mengakses berbagai layanan yang tersedia dengan terlebih dahulu mengambil instance class AdWordsServices menggunakan metode getInstance() statis. Dengan menggunakan instance ini, kita dapat membuat klien untuk layanan tersebut melalui metode get(), yang memerlukan dua argumen: sesi untuk membuat klien dan antarmuka untuk layanan yang diinginkan.

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

Di sini, kita mengakses ManagedCustomerService, yang memungkinkan kita mengelola "pelanggan" (akun) AdWords dari akun pengelola tertentu.

Menentukan setelan akun baru

Pertama, kita akan membuat objek ManagedCustomer yang berisi setelan untuk akun baru kita. Kita akan membuat akun pengujian untuk codelab ini, dengan menetapkan mata uangnya ke USD dan zona waktunya sama dengan pantai barat AS.

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

Kami juga membuat nomor acak yang disertakan dalam nama akun. Hal ini hanya agar kita dapat mencocokkan akun AdWords yang akan kita buat di sini dengan akun Merchant Center yang akan kita buat nanti, sehingga kita dapat memeriksanya secara visual setelah solusi selesai dan memastikan bahwa solusi tersebut memang menautkan keduanya.

Membuat akun terkelola baru

Untuk benar-benar membuat akun baru, kita akan menggunakan ManagedCustomerOperation untuk menentukan operasi ADD:

SolutionRunner.java

ManagedCustomerOperation operation = new ManagedCustomerOperation();
operation.setOperand(newAdWordsAccount);
operation.setOperator(Operator.ADD);

Kemudian, kita akan melakukan operasi menggunakan metode mutate() dari objek ManagedCustomerService. Metode ini menggunakan array operasi yang akan dilakukan, tetapi di sini kita hanya ingin melakukan satu operasi. Hasil metode mutate() adalah nilai yang berisi daftar ManagedCustomer; di sini, nilai tersebut akan berupa daftar yang berisi satu pelanggan, yaitu akun baru yang kita buat. Kita akan mengambil ID untuk akun baru tersebut untuk digunakan di masa mendatang, dan kita juga akan mencetaknya agar dapat melihatnya sebagai bagian dari output solusi kita.

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

Melakukan pengujian

Seperti sebelumnya, coba jalankan solusi. Jika Anda menggunakan Maven dari command line:

mvn compile

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

Jika semuanya berjalan lancar, Anda seharusnya masih tidak melihat error, dan kali ini kita akan melihat ID akun AdWords baru yang kita buat. Periksa situs AdWords untuk akun pengelola Anda dan Anda akan melihat akun baru tersebut tercantum di sana juga.

Catatan: Pada tahap ini, setiap pengoperasian solusi kini akan menghasilkan akun baru. Anda dapat membatalkan akun AdWords yang dibuat melalui situs AdWords setelah selesai menjalankan solusi. Lagi pula, skema penamaan kami untuk akun ini memudahkan untuk melihat akun mana yang dibuat oleh kode kami.

6. Membuat sub-akun Merchant Center baru

Pada langkah ini, kita akan membuat sub-akun Merchant Center yang akan ditautkan ke akun AdWords yang dibuat pada langkah terakhir. Daripada meminta penautan secara terpisah setelah membuat sub-akun, kita dapat meminta penautan selama pembuatan karena kita sudah memiliki ID untuk akun AdWords yang sesuai.

Menentukan setelan untuk sub-akun baru

Tidak seperti AdWords API, penyetel untuk class model Account menampilkan objek, sehingga kita dapat merantai panggilan ke objek tersebut di objek Account baru. Kami juga akan menggunakan angka acak yang dibuat selama pembuatan akun AdWords di nama akun Merchant Center baru.

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

Seperti yang disebutkan dalam pengantar untuk langkah ini, karena sudah memiliki ID AdWords untuk akun terkelola baru, kita dapat menambahkan ID tersebut ke daftar AdwordsLinks untuk sub-akun baru sekarang. Saat sub-akun baru dibuat, penautan ini akan otomatis diminta dan tersedia di AdWords API.

Buat sub-akun baru

Di Content API, kita memanggil metode accounts() dari objek sesi untuk mengakses layanan Accounts, lalu memanggil metode insert() secara langsung, bukan menyiapkan objek operasi. Metode ini menggunakan dua argumen: ID akun multiklien tempat sub-akun baru akan dibuat, dan objek Account yang berisi setelan yang diinginkan:

SolutionRunner.java

newMcAccount = contentApiSession.accounts().insert(mcaId, newMcAccount).execute();

System.out.printf("Created new Merchant Center account %s%n", newMcAccount.getId());

Metode insert() menampilkan objek Account yang berisi setelan untuk sub-akun baru. Kami menimpa objek Account asli karena versi yang ditampilkan menyertakan informasi penting: ID sub-akun baru. Kita mencetaknya dalam output dari solusi, sehingga kita dapat menjalankan solusi, lalu memverifikasi bahwa sub-akun baru ada di Merchant Center.

Melakukan pengujian

Seperti sebelumnya, coba jalankan solusi. Jika Anda menggunakan Maven dari command line:

mvn compile

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

Jika semuanya berjalan lancar, Anda seharusnya masih tidak melihat error, dan kali ini kita akan melihat ID untuk akun AdWords baru dan akun Merchant Center baru. Periksa Merchant Center untuk akun multiklien Anda guna melihat sub-akun baru di sana.

Catatan: Seperti halnya AdWords, setiap pengoperasian solusi kini akan membuat akun Merchant Center baru. Anda dapat menghapus sub-akun yang dibuat melalui Merchant Center setelah selesai menjalankan solusi.

7. Menyetujui penautan dari akun AdWords

Pada langkah terakhir, kita membuat sub-akun Merchant Center baru, yang meminta penautan ke akun AdWords baru kita secara bersamaan. Pada langkah ini, kita akan menyelesaikan prosesnya dengan menggunakan AdWords API untuk menyetujui penautan yang diminta.

Mengakses CustomerService

Seperti sebelumnya, kita akan menggunakan class AdWordsServices untuk mendapatkan klien untuk CustomerService. Namun, sebelum membuat klien, kita harus mengubah objek sesi AdWords terlebih dahulu agar penggunaan di masa mendatang akan beroperasi di akun terkelola baru, bukan akun pengelola. Bagaimanapun, akun Merchant Center meminta penautan ke akun yang dikelola, bukan akun pengelola.

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

Menentukan link yang diminta

Seperti saat membuat akun AdWords baru, kita akan membuat objek ServiceLink yang berisi setelan penautan, lalu objek ServiceLinkOperation yang menjelaskan operasi yang diinginkan. Di sini, kita ingin mengambil penautan layanan yang tertunda ke akun MERCHANT_CENTER dan SET ke ACTIVE. Untuk setelan serviceLinkId, kita akan menggunakan ID akun Merchant Center yang baru saja dibuat, karena ID tersebut digunakan untuk ID penautan layanan di 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);

Menerima penautan

Terakhir, kita akan memanggil metode mutateServiceLinks() dari objek CustomerService untuk melakukan operasi. Seperti sebelumnya, operasi ini memerlukan array operasi penautan layanan. Kali ini, metode akan menampilkan daftar link layanan (mungkin diubah) secara langsung, jadi kita hanya akan mencetak hasil solusi dengan melakukan loop pada daftar tersebut. Tentu saja, karena kita hanya menentukan satu operasi, Anda hanya mengharapkan satu link yang dicetak dalam output.

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

Melakukan pengujian

Seperti sebelumnya, coba jalankan solusi. Jika Anda menggunakan Maven dari command line:

mvn compile

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

Jika semuanya berjalan lancar, Anda seharusnya masih tidak melihat error, dan kali ini kita juga akan melihat catatan bahwa penautan layanan telah diperbarui agar aktif. Periksa AdWords dan Merchant Center, lalu periksa kembali apakah akun tersebut memang sudah ditautkan.

8. Variasi pada tema

Selamat, Anda telah menyelesaikan codelab ini. Setelah Anda memiliki solusi yang berfungsi sepenuhnya, mari kita lihat beberapa contoh cara memodifikasi atau memperluasnya untuk menggunakan lebih banyak API yang telah Anda lihat di codelab ini.

Kredit tambahan: Memperbarui akun Merchant Center yang ada untuk meminta penautan AdWords

Dalam codelab, kita membuat akun AdWords terlebih dahulu dengan cerdik sehingga kita dapat menggunakan informasinya untuk meminta penautan saat membuat akun Merchant Center. Namun, jika akun Merchant Center sudah ada, Anda harus memperbarui konfigurasinya. Coba ubah kode Anda untuk membuat akun Merchant Center terlebih dahulu, lalu kembali setelah membuat akun AdWords dan perbarui konfigurasinya untuk meminta penautan.

Catatan: Sebaiknya gunakan metode Accounts.update atau Accounts.patch. Bahkan, coba versi dengan setiap opsi untuk memahami perbedaannya.

Penting: Akun Merchant Center baru mungkin tidak langsung tersedia setelah panggilan ke Accounts.insert. Hingga akun baru tersedia, Anda akan mendapatkan error HTTP 401 saat mencoba mengakses atau mengubahnya. Contoh Shopping memiliki contoh penggunaan backoff eksponensial untuk mencoba ulang metode di AccountWorkflow.java, yang menggunakan metode retryFailures dari BaseWorkflowSample.java.

Kredit tambahan: Verifikasi pembuatan penautan dengan mengambil informasi akun AdWords dan Merchant Center

Saat ini, aplikasi hanya memperlakukan tidak adanya error dari panggilan API sebagai tanda keberhasilan. Coba perluas contoh untuk memeriksa informasi penautan untuk akun Merchant Center dan AdWords baru dan lihat apakah penautan tersebut memang aktif.

Catatan: Di sisi Content API, Anda dapat melihat metode Accounts.get. Di sisi AdWords, Anda dapat menggunakan metode getServiceLinks dari objek CustomerServiceInterface.

Dunia adalah tiram Anda

Jika Anda memikirkan perubahan lain yang dapat dilakukan, coba lakukan. Jika Anda memerlukan kode referensi untuk ide Anda, lihat contoh Google Shopping dan direktori examples di sumber library klien Java Google Ads.