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 cho Shopping và API AdWords, đồng thời xây dựng một ứng dụng sử dụng cả hai API này. Cụ thể, bạn sẽ xây dựng một ứng dụng dòng lệnh để tạo và liên kết tài khoản AdWords và 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ừ tài khoản Merchant Center đến tài khoản AdWords.
• Cách chấp nhận liên kết 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 (bạn nên dùng một IDE có thể hiểu 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), chứa một dự án Maven cùng với tất cả tài nguyên bạn cần. Bạn cần đặc biệt lưu ý các thư mục con sau:

• 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 bắt buộc và xây dựng

Nếu đang sử dụng một IDE có thể 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, sau đó 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 quy trình 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 phù hợp cho API AdWords và Content API cho Shopping.

Thiết lập quy trình xác thực API AdWords

Lớp học lập trình này sử dụng cùng một quy trình 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 đến 3 để bắt đầu sử dụng Thư viện ứng dụng API Google Ads cho Java.

Thiết lập quy trình xác thực Content API

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

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

Bây giờ, hãy làm theo hướng dẫn để thiết lập quy trình xác thực cho các mẫu Shopping 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 đây trong thư mục chính: shopping-samples/content/service-account.json. Bạn không cần 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 hoàn thành lớp học lập trình này!

Dùng thử

Giờ đây, khi đã có mã thông báo xác thực ở đúng vị trí, hãy thử chạy các mẫu. Nếu đang sử dụng Maven ở 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 không thực hiện bất kỳ thay đổi nào về 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 các 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 không cung cấp đối tượng phiên, thì mã thông báo xác thực của bạn đã được đặt đúng vị trí và 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 sửa.

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. 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.

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

Giờ đây, khi đã 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 cách tạo các đối tượng phiên bằng mã thông báo xác thực. Trong 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ác đối tượng phiên này.

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

Để tạo phiên Content API, chúng ta sẽ tạo đối tượng ShoppingContent.Builder, sau đó sử dụng đối tượng này để tạo đối tượng ShoppingContent thích hợp. May mắn là tất cả những gì chúng ta cần để tạo đối tượng trước đó đều đã có trong khung mã. Vì vậy, chúng ta chỉ cần kết hợp 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ã mẫu này và các mã mẫu sau đây đã có trong khung mã. Hãy tìm các nhận xét đó để biết vị trí cần thêm các dòng này.

Chúng tôi cũng bỏ qua mọi câu lệnh nhập cần thiết 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 không sử dụng IDE có thể tự động thêm các dữ liệu nhập chính xác, vui lòng kiểm tra mã trong gói solution để biết các dữ liệu nhập cần thiết.

Việc đặt tên ứng dụng không thực sự cần thiết, nhưng việc này cho thấy cách đặt mọi lựa 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ó một lớp AdWordsSession.Builder để tạo các đối tượng AdWordsSession. Điểm khác biệt chính ở đây là thay vì đặt các lựa 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 lựa 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 cuối cùng để xây dựng lại và chạy dự án Maven, nếu bạn đang chạy dự án này 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 không nhận được dữ liệu đầu ra thú vị nào. Chúng ta sẽ thêm dữ liệu đó 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ẽ xem xét và tạo các tài khoản mà chúng ta muốn liên kết. Chúng ta sẽ bắt đầu với AdWords và tạo một tài khoản kiểm thử 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 đều được thêm vào cùng một vị trí trong mã khung theo thứ tự trình bày. Vì lý do đó, chúng ta sẽ chỉ hiển thị nhận xét (// TODO...) đánh dấu vị trí đặt các đoạn mã đó trong đoạn mã đầ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ó nhận xét giới thiệu, thì các đoạn mã đó sẽ xuất hiện ngay sau đoạn mã trước đó.

Truy cập vào ManagedCustomerService

Trong API AdWords, chúng ta truy cập vào nhiều dịch vụ có sẵn bằng cách truy xuất trước tiên một thực thể của lớp AdWordsServices bằng phương thức tĩnh getInstance(). Khi sử dụng thực thể 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(), 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);

Ở đây, chúng ta truy cập vào ManagedCustomerService, cho phép chúng ta 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 chế độ cài đặt tài khoản mới

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 kiểm thử cho lớp học lập trình này, đặt đơn vị tiền tệ là USD và múi giờ giống như bờ biển phía 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 ta cũng tạo một số ngẫu nhiên mà chúng ta đưa vào tên của tài khoản. Điều này chỉ để chúng ta có thể 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, để chúng ta có thể kiểm tra trực quan các tài khoản đó sau khi giải pháp hoàn tất và đảm bảo rằng giải pháp đã thực sự liên kết hai tài khoản đó.

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 thao tác ADD operation:

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 phương thức mutate() của đối tượng ManagedCustomerService. Phương thức này nhận một mảng các thao tác để thực hiện, nhưng ở đây, chúng ta chỉ muốn thực hiện một thao tác. Kết quả của phương thức mutate() là một giá trị chứa danh sách ManagedCustomers; ở đây, đó sẽ là danh sách chứa một khách hàng, tức là tài khoản mới mà chúng ta đã tạo. Chúng ta sẽ truy xuất mã của tài khoản mới đó để sử dụng trong tương lai và cũng sẽ in mã đó để chúng ta có thể xem mã đó như một phần của dữ liệu đầu ra 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);

Dùng thử

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

mvn compile

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

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

Lưu ý: Tại thời điểm này, mỗi lần chạy giải pháp sẽ tạo tài khoản mới. Bạn có thể huỷ bất kỳ tài khoản AdWords nào đã tạo thông qua trang web AdWords sau khi chạy xong giải pháp. Sau cùng, quy tắ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 do mã của chúng ta tạo!

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

Trong bước này, chúng ta sẽ tạo tài khoản phụ Merchant Center mà chúng ta sẽ liên kết với tài khoản AdWords mà chúng ta đã 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ã 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, các 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ể xâu chuỗi các lệnh gọi đến các phương thức này trên đối tượng Account mới. Chúng ta cũng sẽ sử dụng số ngẫu nhiên mà chúng ta đã tạo trong quá trình tạo tài khoản AdWords trong 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 cho bước này, vì chúng ta đã có mã AdWords cho tài khoản được quản lý mới, nên giờ đây, 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, 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 nhận hai đối số: mã của tài khoản nhiều khách hàng mà theo đó sẽ 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 các 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ề bao gồm một phần thông tin quan trọng: mã của tài khoản phụ mới. Chúng ta in thông tin đó trong dữ liệu đầu ra từ giải pháp của mình, để chúng ta có thể chạy giải pháp rồi xác minh rằng tài khoản phụ mới tồn tại trong Merchant Center.

Dùng thử

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

mvn compile

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

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

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

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

Ở bước cuối cùng, chúng ta đã tạo một tài khoản phụ Merchant Center mới, đồng thời yêu cầu liên kết đến tài khoản AdWords mớ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 liên kết được yêu cầu.

Truy cập vào CustomerService

Như trước đây, chúng ta sẽ sử dụng lớp AdWordsServices để lấy ứ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ý. Sau cùng, tài khoản Merchant Center đã yêu cầu liên kết đến tài khoản được quản lý, 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 liên kết được yêu cầu

Giống như khi chúng ta tạo tài khoản AdWords mới, chúng ta sẽ tạo một đối tượng ServiceLink chứa các chế độ cài đặt liên kết, sau đó là một đối tượng ServiceLinkOperation mô tả thao tác mong muốn. Ở đây, chúng ta muốn lấy liên kết dịch vụ đang chờ xử lý đến tài khoản MERCHANT_CENTER và SET liên kết đó thành ACTIVE. Đối với chế độ cài đặt serviceLinkId, chúng ta sẽ sử dụng mã của tài khoản Merchant Center mà chúng ta vừa tạo, vì mã đó được dùng cho mã 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 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, phương thức này nhận một mảng các thao tác liên kết dịch vụ. Lần này, phương thức này trả về trực tiếp danh sách các liên kết dịch vụ (có thể đã thay đổi), vì vậy, chúng ta chỉ cần 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 liên kết duy nhất được in trong dữ liệu đầu ra.

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ếu đang sử dụng Maven từ dòng lệnh:

mvn compile

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

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

8. Các biến thể của một chủ đề

Xin chúc mừng bạn đã hoàn thành lớp học lập trình này! Giờ đây, khi đã có một giải pháp hoạt động đầy đủ, 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 thêm các API mà bạn đã thấy trong lớp học lập trình này.

Thưởng thêm: Cập nhật tài khoản Merchant Center hiện có để yêu cầu liên kết AdWords

Trong lớp học lập trình này, chúng ta đã khéo léo tạo tài khoản AdWords trước để có thể sử dụng thông tin của tài khoản đó để 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, thì bạn cần cập nhật cấu hình của tài khoản đó. Hãy thử thay đổi mã để tạo tài khoản Merchant Center trước, 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 nê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 từng phương thức để hiểu rõ sự khác biệt!

Quan trọng: Tài khoản Merchant Center mới có thể không có ngay sau khi gọi Accounts.insert. Cho đến khi tài khoản mới có sẵn, 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 đó. Các mẫu Shopping có một ví dụ về cách sử dụng thuật toán thời gian chờ luỹ thừa để thử lại các phương thức trong AccountWorkflow.java, sử dụng phương thức retryFailures từ BaseWorkflowSample.java.

Thưởng thêm: Xác minh việc tạo 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 từ các lệnh gọi API là dấu hiệu thành công. Hãy thử mở rộng ví dụ để kiểm tra thông tin liên kết cho tài khoản Merchant Center và tài khoản AdWords mới, đồng thời 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ĩ đến những thay đổi khác mà bạn có thể thực hiện, hãy thử! Nếu bạn cần mã tham chiếu cho ý tưởng của mình, hãy xem các 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.