Tạo và liên kết tài khoản phụ AdWords với tài khoản Merchant Center

1. Giới thiệu

Trong lớp học lập trình này, bạn sẽ tìm hiểu một số kiến thức cơ bản về cách làm việc với Content API for Shopping và API AdWords, cũng như tạo một ứng dụng sử dụng cả hai. Cụ thể, bạn sẽ tạo một ứng dụng dòng lệnh để tạo và liên kết tài khoản AdWords với tài khoản Merchant Center.

Kiến thức bạn sẽ học được

• Cách tạo tài khoản AdWords do tài khoản người quản lý quản lý.
• Cách tạo tài khoản Merchant Center do tài khoản nhiều khách hàng quản lý.
• Cách yêu cầu liên kết tài khoản Merchant Center với tài khoản AdWords.
• Cách chấp nhận đường liên kết đến Merchant Center đang chờ xử lý trong tài khoản AdWords.

Bạn cần có

• Tài khoản người quản lý AdWords
• Tài khoản nhiều khách hàng trong Merchant Center
• Java 7 trở lên
• Maven
• Mã mẫu
• Trình chỉnh sửa văn bản (nên dùng một IDE hiểu được các dự án Maven như Eclipse hoặc IntelliJ)

2. Thiết lập

Tải mã xuống

Nhấp vào đường liên kết sau đây để tải toàn bộ mã nguồn cho lớp học lập trình này:

Tải mã nguồn xuống

Giải nén tệp zip đã tải xuống. Thao tác này sẽ giải nén một thư mục gốc (shopping-account-linking-master), thư mục này chứa một dự án Maven cùng với tất cả tài nguyên bạn cần. Các thư mục con sau đây đặc biệt đáng chú ý:

• src/main/java là thư mục gốc của dự án Maven và chứa một khung mã để bạn làm việc.
• src/main/java/solution chứa giải pháp hoàn chỉnh.

Cài đặt các gói cần thiết và bản dựng

Nếu đang dùng một IDE nhận biết Maven như Eclipse hoặc IntelliJ, bạn có thể nhập thư mục đã trích xuất dưới dạng dự án Maven rồi biên dịch dự án như bình thường.

Nếu đang sử dụng Maven từ dòng lệnh, bạn có thể chạy lệnh sau để truy xuất các gói cần thiết và biên dịch dự án từ thư mục gốc của dự án đã giải nén (shopping-account-linking-master):

mvn compile

3. Thiết lập tính năng xác thực

Ở bước này, chúng ta sẽ không lập trình mà sẽ thiết lập các tệp chứa mã thông báo xác thực thích hợp cho AdWords API và Content API for Shopping.

Thiết lập tính năng xác thực API AdWords

Lớp học lập trình này sử dụng cùng một phương thức tải thông tin xác thực như thư viện ứng dụng, vì vậy, nếu đã sử dụng Thư viện ứng dụng API Google Ads cho Java bằng tài khoản người quản lý, thì bạn đã thiết lập xong. Nếu không, hãy làm theo các bước 1-3 để bắt đầu sử dụng Thư viện ứng dụng API Google Ads cho Java.

Thiết lập tính năng xác thực Content API

Nếu bạn chưa có khoá tài khoản dịch vụ:

1. Truy cập vào Merchant Center cho tài khoản nhiều khách hàng và chọn Content API trong trình đơn mục bổ sung:
2. Chọn Xác thực, rồi nhấp vào nút + màu xanh dương:
3. Sau khi chấp nhận Điều khoản dịch vụ của Google Cloud Platform và API của Google, trình duyệt của bạn sẽ tự động tải tệp JSON xuống có chứa khoá tài khoản dịch vụ mới.

Bây giờ, hãy làm theo hướng dẫn để thiết lập tính năng xác thực cho các mẫu Mua sắm bằng tài khoản dịch vụ. Tức là bản sao khoá tài khoản dịch vụ của bạn phải nằm ở đường dẫn sau từ thư mục gốc: shopping-samples/content/service-account.json. Bạn không cần phải thiết lập cấu hình mẫu, trừ phi bạn muốn dùng thử các mẫu sau khi kết thúc lớp học lập trình này!

Thử nghiệm

Giờ đây, khi bạn đã có mã thông báo xác thực ở đúng vị trí, hãy thử chạy các mẫu. Nếu bạn đang sử dụng Maven tại dòng lệnh, hãy chạy các lệnh sau:

mvn compile

Lưu ý: Nếu bạn thay đổi bất kỳ tệp nào trong src/main/resources, ngay cả khi bạn không thực hiện thay đổi nào đối với mã (như trong bước này), hãy biên dịch lại trước khi chạy các mẫu để sao chép tài nguyên đã thay đổi vào mục tiêu.

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

Nếu bạn nhận được thông báo lỗi về việc đối tượng phiên không được cung cấp, thì mã thông báo xác thực của bạn đang được sử dụng và đang hoạt động chính xác! Nếu không, thông báo lỗi bạn nhận được sẽ cho bạn biết thông tin xác thực nào không hoạt động và tệp nào cần khắc phục.

Lưu ý quan trọng: Khung mà chúng tôi cung cấp giả định rằng tài khoản dịch vụ Content API của bạn chỉ được liệt kê là người dùng trên tài khoản nhiều khách hàng của bạn. Nếu bạn nhận được thông báo lỗi cho biết tài khoản dịch vụ của bạn có quyền truy cập vào nhiều tài khoản, hãy làm theo các bước ở trên để lấy khoá tài khoản dịch vụ dành riêng cho tài khoản nhiều khách hàng của bạn.

4. Kết nối với các API

Giờ đây, bạn đã có mã thông báo xác thực hợp lệ cho hai API mà chúng ta sẽ sử dụng. Hãy bắt đầu điền mã thực tế. Chúng ta sẽ bắt đầu bằng việc tạo đối tượng phiên bằng mã thông báo xác thực. Ở các bước sau, chúng ta sẽ truy cập vào nhiều dịch vụ và phương thức mà mỗi API cung cấp bằng cách sử dụng các đối tượng phiên này.

Tạo đối tượng phiên Content API

Để tạo một phiên Content API, chúng ta sẽ tạo một đối tượng ShoppingContent.Builder, sau đó sử dụng đối tượng đó để tạo đối tượng ShoppingContent thích hợp. May mắn thay, tất cả những gì chúng ta cần để xây dựng cấu trúc đã có sẵn trong bộ khung mã, vì vậy chúng ta chỉ cần kéo chúng lại với nhau như sau:

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

Lưu ý: Các nhận xét ban đầu trong mẫu mã này và các mẫu mã sau đã có trong khung mã. Hãy tìm các dòng này để biết vị trí cần thêm.

Chúng tôi cũng bỏ qua bất kỳ câu lệnh nhập cần thiết nào cho các lớp API AdWords và Content API mà chúng tôi sử dụng trong các đoạn mã này. Nếu bạn hiện không sử dụng IDE có thể tự động thêm chính xác lệnh nhập, vui lòng kiểm tra mã trong gói solution để biết các lệnh nhập cần thiết.

Bạn không thực sự cần thiết đặt tên ứng dụng, nhưng sẽ hướng dẫn cách đặt các tuỳ chọn mong muốn thông qua đối tượng ShoppingContent.Builder trước khi gọi phương thức build().

Tạo đối tượng phiên API AdWords

Tương tự, cũng có một lớp AdWordsSession.Builder để tạo đối tượng AdWordsSession. Điểm khác biệt chính ở đây là thay vì đặt các tuỳ chọn cấu hình trực tiếp trên trình tạo, chúng ta sẽ sử dụng phương thức fromFile() để tải các tuỳ chọn đó từ tệp ads.properties mà chúng ta đã thiết lập ở bước trước.

SolutionRunner.java

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

Dùng thử

Chúng ta sẽ sử dụng các lệnh tương tự như trong phần trước để tạo lại và chạy dự án Maven, nếu bạn đang chạy dự án từ dòng lệnh:

mvn compile

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

Lần này, bạn sẽ không gặp lỗi nào, mặc dù cũng sẽ không nhận được kết quả thú vị nào. Chúng ta sẽ thêm mã đó khi gọi các API để tạo và liên kết các tài khoản mới.

5. Tạo tài khoản AdWords được quản lý mới

Giờ đây, khi đã tạo các đối tượng phiên API, chúng ta sẽ tạo các tài khoản mà chúng ta muốn liên kết. Chúng tôi sẽ bắt đầu với AdWords và tạo một tài khoản thử nghiệm trong tài khoản người quản lý.

Lưu ý: Tất cả các đoạn mã trong phần này được thêm vào cùng một vị trí trong mã khung theo thứ tự được trình bày. Vì lý do đó, chúng ta sẽ chỉ hiển thị bình luận (// TODO...) đánh dấu vị trí đặt bình luận trong phần đầu tiên. Vì vậy, trong bước này và các bước sau, nếu bạn thấy các đoạn mã không có chú thích giới thiệu, thì các đoạn mã đó sẽ nằm ngay sau đoạn mã trước.

Truy cập vào ManagedCustomerService

Trong API AdWords, trước tiên, chúng ta truy xuất một thực thể của lớp AdWordsServices bằng phương thức getInstance() tĩnh để truy cập vào nhiều dịch vụ có sẵn. Bằng cách sử dụng phiên bản này, chúng ta có thể tạo ứng dụng cho các dịch vụ đó thông qua phương thức get(). Phương thức này nhận hai đối số: phiên để tạo ứng dụng và giao diện cho dịch vụ mong muốn.

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

Tại đây, chúng ta truy cập vào ManagedCustomerService để quản lý "khách hàng" (tài khoản) AdWords từ một tài khoản người quản lý nhất định.

Chỉ định các chế độ cài đặt mới của tài khoản

Trước tiên, chúng ta sẽ tạo một đối tượng ManagedCustomer chứa các chế độ cài đặt cho tài khoản mới. Chúng ta sẽ tạo một tài khoản thử nghiệm cho lớp học lập trình này, đặt đơn vị tiền tệ thành USD và múi giờ giống với bờ tây Hoa Kỳ.

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

Chúng tôi cũng tạo một số ngẫu nhiên để đưa vào tên tài khoản. Việc này chỉ để chúng ta có thể so khớp tài khoản AdWords mà chúng ta sẽ tạo ở đây với tài khoản Merchant Center mà chúng ta sẽ tạo sau này. Nhờ đó, chúng ta có thể kiểm tra trực quan các tài khoản này sau khi hoàn tất giải pháp và đảm bảo rằng giải pháp đó thực sự đã liên kết hai tài khoản này.

Tạo tài khoản được quản lý mới

Để thực sự tạo tài khoản mới, chúng ta sẽ sử dụng ManagedCustomerOperation để chỉ định một hoạt động ADD:

SolutionRunner.java

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

Sau đó, chúng ta sẽ thực hiện thao tác bằng cách sử dụng phương thức mutate() của đối tượng ManagedCustomerService. Phương thức này thực hiện một loạt các thao tác, nhưng ở đây chúng ta chỉ muốn thực hiện một thao tác duy nhất. Kết quả của phương thức mutate() là một giá trị chứa danh sách các ManagedCustomer; tại đây, đó sẽ là một danh sách chứa một khách hàng, tài khoản mới mà chúng tôi đã tạo. Chúng ta sẽ truy xuất mã nhận dạng cho tài khoản mới đó để sử dụng sau này và cũng sẽ in mã nhận dạng đó để có thể xem mã nhận dạng đó trong kết quả của giải pháp.

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

Thử nghiệm

Như trước đây, hãy thử chạy giải pháp này. Nếu bạn đang sử dụng Maven qua dòng lệnh:

mvn compile

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

Nếu mọi thứ diễn ra suôn sẻ, bạn sẽ không thấy lỗi nào. Lần này, chúng ta sẽ thấy mã nhận dạng của tài khoản AdWords mới mà chúng ta đã tạo. Hãy kiểm tra trang web AdWords để xem tài khoản người quản lý của bạn. Bạn cũng sẽ thấy tài khoản mới được liệt kê ở đó!

Lưu ý: Tại thời điểm này, mỗi lần chạy giải pháp này sẽ tạo ra các tài khoản mới. Bạn có thể hủy bất kỳ tài khoản AdWords nào được tạo qua trang web AdWords sau khi chạy xong giải pháp. Xét cho cùng, lược đồ đặt tên cho các tài khoản này giúp bạn dễ dàng biết được tài khoản nào được tạo bằng mã của chúng ta!

6. Tạo tài khoản phụ Merchant Center mới

Ở bước này, chúng ta sẽ tạo tài khoản phụ Merchant Center để liên kết với tài khoản AdWords đã tạo ở bước cuối cùng. Thay vì yêu cầu liên kết riêng sau khi tạo tài khoản phụ, chúng ta có thể yêu cầu liên kết trong quá trình tạo vì chúng ta đã có mã nhận dạng cho tài khoản AdWords tương ứng.

Chỉ định chế độ cài đặt cho tài khoản phụ mới

Không giống như API AdWords, phương thức setter cho lớp mô hình Account trả về đối tượng, vì vậy, chúng ta có thể tạo chuỗi lệnh gọi đến các phương thức setter đó trên đối tượng Account mới. Chúng tôi cũng sẽ sử dụng số ngẫu nhiên mà chúng tôi đã tạo trong quá trình tạo tài khoản AdWords dưới tên của tài khoản Merchant Center mới.

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

Như đã đề cập trong phần giới thiệu về bước này, vì đã có mã AdWords cho tài khoản được quản lý mới, nên chúng ta có thể thêm mã đó vào danh sách AdwordsLinks cho tài khoản phụ mới. Khi tài khoản phụ mới được tạo, mối liên kết này sẽ tự động được yêu cầu và có trong API AdWords.

Tạo tài khoản phụ mới

Trong Content API, chúng ta gọi phương thức accounts() của đối tượng phiên để truy cập vào dịch vụ Accounts, sau đó gọi trực tiếp phương thức insert() thay vì thiết lập đối tượng thao tác. Phương thức này sẽ nhận hai đối số: mã của tài khoản nhiều khách hàng dùng để tạo tài khoản phụ mới và đối tượng Account chứa các chế độ cài đặt mong muốn:

SolutionRunner.java

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

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

Phương thức insert() trả về một đối tượng Account chứa chế độ cài đặt cho tài khoản phụ mới. Chúng ta ghi đè đối tượng Account ban đầu vì phiên bản được trả về có một thông tin quan trọng: mã nhận dạng của tài khoản phụ mới. Chúng ta in thông tin đó trong kết quả của giải pháp để có thể chạy giải pháp và xác minh tài khoản phụ mới có trong Merchant Center hay không.

Thử nghiệm

Như trước đây, hãy thử chạy giải pháp này. Nếu bạn đang sử dụng Maven từ dòng lệnh:

mvn compile

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

Nếu mọi thứ diễn ra suôn sẻ, bạn sẽ không thấy lỗi nào. Lần này, chúng ta sẽ thấy mã nhận dạng cho cả tài khoản AdWords mới và tài khoản Merchant Center mới. Kiểm tra Merchant Center của tài khoản nhiều khách hàng để xem tài khoản phụ mới trong đó.

Lưu ý: Giống như với AdWords, mỗi lần chạy giải pháp này sẽ tạo ra các tài khoản Merchant Center mới. Bạn có thể xoá mọi tài khoản phụ đã tạo qua Merchant Center sau khi chạy giải pháp xong.

7. Chấp nhận liên kết từ tài khoản AdWords

Trong bước cuối cùng, chúng tôi đã tạo một tài khoản phụ Merchant Center mới, đồng thời yêu cầu liên kết với tài khoản AdWords mới của chúng tôi. Trong bước này, chúng ta sẽ hoàn tất quy trình bằng cách sử dụng API AdWords để chấp nhận đường liên kết được yêu cầu.

Truy cập vào CustomerService

Giống như trước đây, chúng ta sẽ sử dụng lớp AdWordsServices để tải ứng dụng cho CustomerService. Tuy nhiên, trước khi tạo ứng dụng, trước tiên, chúng ta sẽ thay đổi đối tượng phiên AdWords để các lần sử dụng trong tương lai sẽ hoạt động trên tài khoản được quản lý mới thay vì tài khoản người quản lý. Xét cho cùng, tài khoản Merchant Center đã yêu cầu liên kết với tài khoản được quản lý, chứ không phải tài khoản người quản lý.

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

Chỉ định đường liên kết được yêu cầu

Giống như khi tạo tài khoản AdWords mới, chúng ta sẽ tạo đối tượng ServiceLink chứa các tùy chọn cài đặt liên kết, sau đó tạo đối tượng ServiceLinkOperation mô tả hoạt động mong muốn. Ở đây, chúng ta muốn chuyển đường liên kết đến dịch vụ đang chờ xử lý đến một tài khoản MERCHANT_CENTER và SET đường liên kết đó đến ACTIVE. Đối với cài đặt serviceLinkId, chúng tôi sẽ sử dụng ID của tài khoản Merchant Center mà chúng tôi vừa tạo, vì ID được sử dụng cho ID của liên kết dịch vụ trong 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);

Chấp nhận đường liên kết

Cuối cùng, chúng ta sẽ gọi phương thức mutateServiceLinks() của đối tượng CustomerService để thực hiện thao tác. Như trước đây, hàm này sẽ thực hiện một mảng các hoạt động liên kết dịch vụ. Lần này, phương thức này trực tiếp trả về danh sách các đường liên kết dịch vụ (có thể đã thay đổi). Vì vậy, chúng ta sẽ chỉ in kết quả của giải pháp bằng cách lặp lại danh sách đó. Tất nhiên, vì chúng ta chỉ chỉ định một thao tác duy nhất, nên bạn chỉ mong đợi một đường liên kết được in ra trong kết quả.

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

Dùng thử

Như trước đây, hãy thử chạy giải pháp này. Nếu bạn đang sử dụng Maven qua dòng lệnh:

mvn compile

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

Nếu mọi thứ diễn ra suôn sẻ, bạn sẽ không thấy lỗi nào. Lần này, chúng ta cũng sẽ thấy một ghi chú cho biết đường liên kết dịch vụ đã được cập nhật để hoạt động. Kiểm tra AdWords và Merchant Center, đồng thời kiểm tra kỹ để đảm bảo các tài khoản hiện đã thực sự được liên kết.

8. Biến thể của một chủ đề

Chúc mừng bạn đã vượt qua lớp học lập trình này! Bây giờ, bạn đã có một giải pháp hoàn toàn hoạt động, hãy xem một số ví dụ về cách bạn có thể sửa đổi hoặc mở rộng giải pháp đó để sử dụng các API khác mà bạn đã thấy trong lớp học lập trình này.

Tín dụng bổ sung: Cập nhật tài khoản Merchant Center hiện có để yêu cầu liên kết với AdWords

Trong lớp học lập trình này, trước tiên, chúng ta đã tạo tài khoản AdWords một cách khéo léo để có thể sử dụng thông tin của tài khoản đó nhằm yêu cầu liên kết khi tạo tài khoản Merchant Center. Tuy nhiên, nếu tài khoản Merchant Center đã tồn tại, bạn sẽ phải cập nhật cấu hình của tài khoản đó. Trước tiên, hãy thử thay đổi mã của bạn để tạo tài khoản Merchant Center, sau đó quay lại sau khi tạo tài khoản AdWords và cập nhật cấu hình của tài khoản để yêu cầu liên kết.

Lưu ý: Bạn cần sử dụng phương thức Accounts.update hoặc Accounts.patch. Trên thực tế, hãy thử một phiên bản với mỗi loại để hiểu sự khác biệt!

Lưu ý quan trọng: Tài khoản Merchant Center mới có thể không hoạt động ngay sau lệnh gọi đến Accounts.insert. Cho đến khi tài khoản mới hoạt động, bạn sẽ gặp lỗi HTTP 401 khi cố gắng truy cập hoặc sửa đổi tài khoản. Một ví dụ về quảng cáo Mua sắm là sử dụng thuật toán thời gian đợi luỹ thừa để thử lại các phương thức trong AccountWorkflow.java, trong đó sử dụng phương thức retryFailures trong BaseWorkflowSample.java.

Điểm thưởng: Xác minh việc tạo mối liên kết bằng cách truy xuất thông tin tài khoản AdWords và Merchant Center

Hiện tại, ứng dụng chỉ coi việc không có lỗi trong lệnh gọi API là dấu hiệu thành công. Hãy thử mở rộng ví dụ này để kiểm tra thông tin liên kết cho các tài khoản Merchant Center và AdWords mới và xem liên kết có thực sự đang hoạt động hay không.

Lưu ý: Về phía Content API, bạn nên xem phương thức Accounts.get. Về phía AdWords, bạn nên sử dụng phương thức getServiceLinks của đối tượng CustomerServiceInterface.

Thế giới trong tầm tay

Nếu bạn nghĩ về những thay đổi khác mà mình có thể thực hiện, hãy thử xem! Nếu bạn cần mã tham chiếu cho ý tưởng của mình, hãy xem mẫu Google Mua sắm và thư mục examples trong nguồn thư viện ứng dụng Java của Google Ads.