Membuat dan Menautkan Sub-akun AdWords dan Merchant Center

1. Pengantar

Dalam codelab ini, Anda akan mempelajari beberapa dasar cara menggunakan Content API for Shopping dan AdWords API serta membuat aplikasi yang menggunakan keduanya. Khususnya, Anda akan membuat 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 dengan akun multiklien.
  • Cara meminta penautan dari akun Merchant Center ke akun AdWords.
  • Cara menyetujui penautan Merchant Center yang tertunda di akun AdWords.

Yang Anda butuhkan

2. Mempersiapkan

Download contoh

Klik link berikut guna mendownload semua kode untuk codelab ini:

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:

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

Menginstal paket dan 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 belum diekstrak (shopping-account-linking-master):

mvn compile

3. Menyiapkan autentikasi

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

Menyiapkan autentikasi AdWords API

Codelab ini menggunakan pemuatan kredensial yang sama seperti library klien, jadi jika Anda sudah 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 dan pilih Content API dari menu tambahan: 89507d635c51a3dc.pngS
  2. Pilih Authentication, lalu klik tombol + berwarna biru: c465d8dc314ec158.png
  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 sampel Shopping dengan akun layanan. Artinya, salinan kunci akun layanan Anda harus berada di jalur berikut dari direktori utama 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 sampel. Jika Anda menggunakan Maven di command line, jalankan perintah berikut:

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

Jika Anda mendapatkan pesan error tentang objek sesi tidak disediakan, artinya token autentikasi Anda sudah diterapkan 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.

4. Menghubungkan ke API

Setelah Anda memiliki token autentikasi yang valid untuk kedua API yang akan kita gunakan, mari kita mulai mengisi kode yang sebenarnya. Kita akan mulai dengan membuat objek sesi menggunakan token otentikasi kita. 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, yang kita butuhkan untuk membangun yang pertama sudah tersedia dalam kerangka kode, jadi kita hanya perlu menyatukannya seperti berikut:

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

Menetapkan nama aplikasi tidak sepenuhnya diperlukan, tetapi tindakan ini 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 utama di sini adalah, alih-alih menetapkan opsi konfigurasi secara langsung di builder, kita akan menggunakan metode fromFile() untuk memuatnya 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 sebelumnya untuk membangun ulang dan menjalankan project Maven jika Anda menjalankannya dari command line:

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

Kali ini, Anda seharusnya tidak 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 yang baru

Setelah membuat objek sesi API, kita akan melanjutkan dan membuat akun yang ingin kita tautkan. Kita akan mulai dengan AdWords dan membuat akun percobaan di akun pengelola kami.

Mengakses ManagedCustomerService

Di AdWords API, kami mengakses berbagai layanan yang tersedia dengan terlebih dahulu mengambil instance class AdWordsServices menggunakan metode getInstance() statis. Dengan menggunakan instance ini, kita kemudian dapat membuat klien untuk layanan tersebut melalui metode get(), yang menggunakan 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" AdWords (akun) 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 menyetel mata uangnya ke USD dan zona waktunya sama seperti 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 angka acak yang kami sertakan dalam nama akun. Hal ini bertujuan agar kami dapat mencocokkan akun AdWords yang akan dibuat di sini dengan akun Merchant Center yang akan kita buat nanti, sehingga kami dapat memeriksanya secara visual setelah solusi selesai dan memastikan bahwa keduanya memang tertaut.

Membuat akun terkelola baru

Untuk benar-benar membuat akun baru, kita akan menggunakan ManagedCustomerOperation untuk menetapkan 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 mengambil array operasi untuk dilakukan, tetapi di sini kita hanya ingin melakukan satu operasi. Hasil metode mutate() adalah nilai yang berisi daftar ManagedCustomer; di sini, daftar yang berisi satu pelanggan, akun baru yang kita buat. Kita akan mengambil ID akun baru tersebut untuk penggunaan berikutnya, dan kita juga akan mencetaknya sehingga dapat dilihat 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 tetap tidak melihat error, dan kali ini kami akan melihat ID akun AdWords baru yang telah kita buat. Periksa situs AdWords untuk akun pengelola dan Anda juga akan melihat akun baru yang tercantum di sana.

6. Membuat sub-akun Merchant Center baru

Pada langkah ini, kita akan membuat sub-akun Merchant Center yang akan ditautkan ke akun AdWords yang telah kita buat di langkah terakhir. Alih-alih meminta penautan secara terpisah setelah membuat sub-akun, kami dapat meminta penautan selama pembuatan karena kami telah memiliki ID untuk akun AdWords yang sesuai.

Menentukan setelan untuk sub-akun baru

Tidak seperti AdWords API, penyetel untuk class model Account menampilkan objek, jadi kita dapat membuat rantai panggilan ke objek tersebut pada objek Account yang baru. Kami juga akan menggunakan angka acak yang kami buat selama pembuatan akun AdWords atas nama akun Merchant Center yang 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 pendahuluan untuk langkah ini, karena kita sudah memiliki ID AdWords untuk akun terkelola yang baru, kita dapat menambahkan ID tersebut ke daftar AdwordsLinks untuk sub-akun baru sekarang. Saat sub-akun baru dibuat, penautan ini akan diminta secara otomatis 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 yang digunakan untuk membuat sub-akun baru, 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 yang baru. Kami akan mencetaknya dalam output dari solusi kami, sehingga kami dapat menjalankan solusi kami, 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 tetap tidak melihat error, dan kali ini kami akan melihat ID untuk akun AdWords baru dan akun Merchant Center baru. Buka Merchant Center untuk akun multiklien Anda guna melihat sub-akun baru di sana.

7. Setujui penautan dari akun AdWords

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

Mengakses CustomerService

Seperti sebelumnya, kita akan menggunakan class AdWordsServices guna mendapatkan klien untuk CustomerService. Namun, sebelum membuat klien, kami mengubah terlebih dahulu objek sesi AdWords agar penggunaan di masa mendatang akan menggunakan akun terkelola yang baru, bukan akun pengelola. Lagi pula, akun Merchant Center meminta penautan ke akun yang dikelola, bukan ke 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);

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

Terakhir, kita akan memanggil metode mutateServiceLinks() objek CustomerService untuk melakukan operasi. Seperti sebelumnya, diperlukan array operasi link layanan. Kali ini, metode ini menampilkan daftar link layanan (yang mungkin berubah) secara langsung, jadi kita hanya akan mencetak hasil solusi kita dengan melakukan loop pada daftar tersebut. Tentu saja, karena kita hanya menentukan satu operasi, Anda hanya mengharapkan satu link yang akan 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 tetap tidak melihat error, dan kali ini kita juga akan melihat catatan bahwa link layanan diperbarui agar aktif. Periksa AdWords dan Merchant Center dan periksa kembali apakah akun tersebut sudah ditautkan.

8. Variasi pada tema

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

Dalam codelab, kami dengan cerdas membuat akun AdWords terlebih dahulu agar 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.

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, lalu lihat bahwa penautan tersebut benar-benar aktif.

Dunia adalah tirammu

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