การสร้างและลิงก์บัญชีย่อย AdWords กับ Merchant Center

1. บทนำ

ใน Codelab นี้ คุณจะได้เรียนรู้พื้นฐานบางอย่างเกี่ยวกับการใช้งาน Content API for Shopping และ AdWords API รวมถึงสร้างแอปพลิเคชันที่มีการใช้ทั้ง 2 แบบ โดยเฉพาะอย่างยิ่ง คุณจะต้องสร้างแอปพลิเคชันบรรทัดคำสั่งที่จะสร้างและลิงก์บัญชี AdWords กับบัญชี Merchant Center

สิ่งที่คุณจะได้เรียนรู้

  • วิธีสร้างบัญชี AdWords ที่จัดการโดยบัญชีดูแลจัดการ
  • วิธีสร้างบัญชี Merchant Center ที่จัดการโดยบัญชีหลายลูกค้า
  • วิธีส่งคำขอลิงก์จากบัญชี Merchant Center ไปยังบัญชี AdWords
  • วิธียอมรับลิงก์ Merchant Center ที่รอดำเนินการในบัญชี AdWords

สิ่งที่คุณต้องมี

2. การตั้งค่า

ดาวน์โหลดรหัส

คลิกลิงก์ต่อไปนี้เพื่อดาวน์โหลดโค้ดทั้งหมดสำหรับ Codelab นี้:

แตกไฟล์ ZIP ที่ดาวน์โหลด การดำเนินการนี้จะคลายแพ็กโฟลเดอร์รูท (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. ตั้งค่าการตรวจสอบสิทธิ์

ในขั้นตอนนี้ เราจะไม่เขียนโค้ดใดๆ แต่จะตั้งค่าไฟล์ที่มีโทเค็นการตรวจสอบสิทธิ์ที่เหมาะสมสำหรับ AdWords API และ Content API for Shopping

ตั้งค่าวิธีการใช้งาน AdWords API

Codelab นี้ใช้การโหลดข้อมูลเข้าสู่ระบบเดียวกันกับไลบรารีของไคลเอ็นต์ ดังนั้นหากคุณใช้ไลบรารีของไคลเอ็นต์ Google Ads API สำหรับ Java กับบัญชีดูแลจัดการอยู่แล้ว ก็ควรจะมีการตั้งค่าเรียบร้อยแล้ว มิเช่นนั้น ให้ทำตามขั้นตอนที่ 1-3 เพื่อเริ่มต้นใช้งานไลบรารีของไคลเอ็นต์ Google Ads API สำหรับ Java

ตั้งค่า uthentication ของ Content API

หากยังไม่มีคีย์บัญชีบริการ ให้ทำดังนี้

  1. ไปที่ Merchant Center สำหรับบัญชีหลายลูกค้า แล้วเลือก Content API จากเมนูรายการเพิ่มเติม: 89507d635c51a3dc.png
  2. เลือกการตรวจสอบสิทธิ์ แล้วคลิกปุ่ม + สีน้ำเงิน ดังนี้ c465d8dc314ec158.png
  3. หลังจากยอมรับข้อกำหนดในการให้บริการของ Google Cloud Platform และ Google APIs แล้ว เบราว์เซอร์จะดาวน์โหลดไฟล์ JSON ที่มีคีย์บัญชีบริการใหม่โดยอัตโนมัติ

จากนั้นทำตามคำแนะนำในการตั้งค่าการตรวจสอบสิทธิ์สำหรับตัวอย่าง Shopping ด้วยบัญชีบริการ ซึ่งหมายความว่าสำเนาคีย์บัญชีบริการควรอยู่ในเส้นทางต่อไปนี้จากไดเรกทอรีหน้าแรก: shopping-samples/content/service-account.json คุณไม่จำเป็นต้องสร้างการกำหนดค่าตัวอย่าง เว้นแต่จะสนใจลองใช้ตัวอย่างหลังจากจบ Codelab นี้แล้ว

ทดสอบเลย

ตอนนี้คุณมีโทเค็นการตรวจสอบสิทธิ์ในที่ที่เหมาะสมแล้ว ให้ลองเรียกใช้ตัวอย่าง หากคุณใช้ Maven ที่บรรทัดคำสั่ง ให้เรียกใช้คำสั่งต่อไปนี้

mvn compile

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

หากคุณได้รับข้อความแสดงข้อผิดพลาดเกี่ยวกับออบเจ็กต์เซสชันที่ไม่แสดง แสดงว่าโทเค็นการตรวจสอบสิทธิ์ของคุณพร้อมใช้งานและทำงานได้อย่างถูกต้อง ไม่เช่นนั้น ข้อความแสดงข้อผิดพลาดที่คุณได้รับจะแจ้งให้ทราบว่าข้อมูลเข้าสู่ระบบใดใช้งานไม่ได้และไฟล์ใดที่ต้องแก้ไข

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

การตั้งชื่อแอปพลิเคชันไม่จำเป็นเสมอไป แต่จะแสดงวิธีการตั้งค่าตัวเลือกที่ต้องการผ่านออบเจ็กต์ 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"

ถึงคราวนี้ คุณไม่น่าจะได้รับข้อผิดพลาดใดๆ เลย แต่ก็จะไม่ได้รับผลลัพธ์ที่น่าสนใจด้วย เราจะเพิ่มข้อมูลดังกล่าวเมื่อเราเรียกใช้ API เพื่อสร้างและลิงก์บัญชีใหม่

5. สร้างบัญชี AdWords ที่จัดการใหม่

เมื่อเราสร้างออบเจ็กต์เซสชัน API แล้ว เราจะมาดูและสร้างบัญชีที่ต้องการลิงก์ เราจะเริ่มต้นด้วย AdWords และสร้างบัญชีทดสอบภายใต้บัญชีดูแลจัดการของเรา

เข้าถึง ManagedCustomerService

ใน AdWords API เราจะเข้าถึงบริการต่างๆ ที่มีอยู่ด้วยการเรียกอินสแตนซ์ของคลาส AdWordsServices ขึ้นมาก่อนโดยใช้เมธอด getInstance() แบบคงที่ จากนั้นเราจะสร้างไคลเอ็นต์สำหรับบริการเหล่านั้นโดยใช้เมธอด get() ซึ่งใช้ 2 อาร์กิวเมนต์ ได้แก่ เซสชันที่จะใช้สร้างไคลเอ็นต์และอินเทอร์เฟซสำหรับบริการที่ต้องการ

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 ที่จะสร้างขึ้นในภายหลัง เพื่อให้เราสามารถตรวจสอบด้วยสายตาเมื่อวิธีแก้ปัญหาของเราเสร็จสมบูรณ์ และดูว่าบัญชีดังกล่าวเชื่อมโยงทั้ง 2 อย่างแล้วจริง

สร้างบัญชีที่จัดการใหม่

หากต้องการสร้างบัญชีใหม่ เราจะใช้ ManagedCustomerOperation เพื่อระบุการดำเนินการ "ADD"

SolutionRunner.java

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

จากนั้นเราจะดำเนินการโดยใช้เมธอด mutate() ของออบเจ็กต์ ManagedCustomerService เมธอดนี้ใช้อาร์เรย์ของการดำเนินการเพื่อทำการดำเนินการ แต่ที่นี่เราต้องการทำเพียงการดำเนินการเดียวเท่านั้น ผลลัพธ์ของเมธอด mutate() คือค่าที่มีรายการ ManagedCustomer ก็จะเห็นรายชื่อที่มีลูกค้า 1 ราย คือบัญชีใหม่ที่เราสร้าง เราจะเรียกรหัสของบัญชีใหม่นั้นไว้ใช้ในอนาคต และเราจะพิมพ์รหัสนั้นด้วยเพื่อให้ดูเป็นส่วนหนึ่งของผลลัพธ์โซลูชันของเรา

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 ของบัญชีดูแลจัดการ คุณน่าจะเห็นบัญชีใหม่แสดงในหน้านั้นด้วย

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() โดยตรงแทนการตั้งค่าออบเจ็กต์การดำเนินการ วิธีการนี้ใช้อาร์กิวเมนต์ 2 อย่าง ได้แก่ รหัสบัญชีหลายลูกค้าที่ใช้สร้างบัญชีย่อยใหม่ และออบเจ็กต์ 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 สำหรับบัญชีหลายลูกค้าเพื่อดูบัญชีย่อยใหม่

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 สำเร็จ ตอนนี้คุณมีโซลูชันที่ทำงานได้อย่างสมบูรณ์แล้ว มาดูตัวอย่างบางส่วนของวิธีที่คุณสามารถแก้ไขหรือขยายโซลูชันเพื่อใช้ API มากขึ้นที่คุณเห็นใน Codelab นี้กัน

ใน Codelab เราจะสร้างบัญชี AdWords อย่างชาญฉลาดก่อน เพื่อให้เราใช้ข้อมูลในการขอลิงก์เมื่อสร้างบัญชี Merchant Center ได้ อย่างไรก็ตาม หากมีบัญชี Merchant Center อยู่แล้ว คุณจะต้องอัปเดตการกำหนดค่าของบัญชีดังกล่าวแทน ลองแก้ไขโค้ดเพื่อสร้างบัญชี Merchant Center ก่อน จากนั้นย้อนกลับหลังจากที่สร้างบัญชี AdWords และอัปเดตการกำหนดค่าเพื่อขอลิงก์แล้ว

ปัจจุบัน แอปพลิเคชันจะพิจารณาเฉพาะการไม่มีข้อผิดพลาดจากการเรียก API เท่านั้นว่าเป็นสัญญาณของความสำเร็จ ลองขยายตัวอย่างเพื่อตรวจสอบข้อมูลลิงก์ของบัญชี Merchant Center และ AdWords ใหม่ แล้วเห็นว่าลิงก์ใช้งานได้จริง

โลกของหอยนางรม

ลองพิจารณาการเปลี่ยนแปลงอื่นๆ ที่สามารถทำได้ หากคุณต้องการโค้ดอ้างอิงสำหรับแนวคิด โปรดดูตัวอย่าง Google Shopping และไดเรกทอรี examples ในแหล่งที่มาไลบรารีไคลเอ็นต์ Google Ads Java