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ể là 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 được quản lý bằng tài khoản người 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 (nên dùng IDE hiểu được các dự án Maven như Eclipse hoặc IntelliJ)
2. Thiết lập
Tải thông báo xuống 90%
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:
Giải nén tệp zip đã tải xuống. Thao tác này sẽ giải nén thư mục gốc (shopping-account-linking-master
), thư mục này chứa 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ần lưu ý cụ thể:
src/main/java
là gốc nguồn của dự án Maven và chứa một bộ khung mã để bạn xử lý.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 một 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 dịch vụ uỷ quyền AdWords API
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 dành 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 giấy phép Content API
Nếu bạn chưa có khoá tài khoản dịch vụ:
- Chuyển đến Merchant Center của tài khoản nhiều khách hàng rồi chọn Content API trên trình đơn mục bổ sung:
- Chọn Xác thực, rồi nhấp vào nút + màu xanh dương:
- 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à một bản sao khoá tài khoản dịch vụ phải nằm tại đường dẫn sau đây từ thư mục gốc của bạn: 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!
Dùng thử
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
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ã 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.
4. Kết nối với các API
Bây giờ, 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 bằng cách đ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 này để 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();
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ì trực tiếp đặt các tuỳ chọn cấu hình trên trình tạo, chúng ta sẽ sử dụng phương thức fromFile()
để tải 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ù bạn 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
Bây giờ, chúng ta đã tạo đối tượng phiên API, chúng ta sẽ tìm hiểu và tạo những 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ý.
Truy cập vào ManagedCustomerService
Trong API AdWords, chúng ta truy cập vào các dịch vụ có sẵn khác nhau bằng cách truy xuất một phiên bản của lớp AdWordsServices trước tiên bằng cách sử dụng phương thức getInstance()
tĩnh. 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, dịch vụ này cho phép chúng tôi quản lý "khách hàng" AdWords (tài khoản) 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 có 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 sẽ tạo một số ngẫu nhiên và đư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 sẽ tạo ở đây với tài khoản Merchant Center mà chúng tôi sẽ tạo sau này, nhờ đó chúng ta có thể kiểm tra trực quan tài khoản khi giải pháp của chúng ta 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 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 cầ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 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 của tài khoản mới đó để sử dụng sau này, đồng thời cũng in mã này để có thể xem được 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);
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 từ dòng lệnh:
mvn compile
mvn exec:java -Dexec.mainClass="SolutionRunner"
Nếu mọi việc suôn sẻ, bạn sẽ vẫn không thấy lỗi và lần này chúng ta sẽ thấy ID của tài khoản AdWords mới mà chúng tôi đã tạo. Kiểm tra trang web AdWords để tìm tài khoản người quản lý của bạn và bạn cũng sẽ thấy tài khoản mới được liệt kê ở đó!
6. Tạo tài khoản phụ mới trong Merchant Center
Ở 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 đã tạo ở bước cuối cùng. Thay vì yêu cầu riêng một liên kết 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 tôi đã có ID cho tài khoản AdWords tương ứng.
Chỉ định các 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
sẽ trả về đối tượng, vì vậy, chúng ta có thể liên kết các lệnh gọi đến phương thức đó 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 cho bước này, vì chúng ta đã có ID AdWords cho tài khoản được quản lý mới, nên bây giờ chúng ta có thể thêm ID đó 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ó sẵn trong AdWords API.
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 hoạt động. 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 tôi sẽ ghi đè đối tượng Account
ban đầu vì phiên bản được trả về bao gồm một thông tin quan trọng: mã nhận dạng của tài khoản phụ mới. Chúng tôi in kết quả từ giải pháp của mình để có thể chạy giải pháp, sau đó xác minh tài khoản phụ mới có trong Merchant Center.
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 việc suôn sẻ, bạn sẽ vẫn không thấy lỗi và lần này chúng ta sẽ thấy ID cho cả tài khoản AdWords mới và tài khoản Merchant Center mới. Truy cập vào Merchant Center của tài khoản nhiều khách hàng để xem tài khoản phụ mới ở đó.
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 tôi sẽ hoàn tất quy trình bằng cách sử dụng AdWords API để chấp nhận liên kết đã yêu cầu.
Truy cập 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 khách hàng, trước tiên chúng tôi thay đổi đối tượng phiên AdWords để việc 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 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 tùy chọn 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ỉ xuất 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 sẽ chỉ thấy một đường liên kết duy nhất được in ra 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à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 việc suôn sẻ, bạn sẽ vẫn không thấy lỗi. Lần này, chúng ta cũng sẽ thấy một ghi chú cho biết đường liên kết đến dịch vụ đã được cập nhật thành đang 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ể trên 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.
Giá trị đóng góp bổ sung: 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 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.
Con số của bạn 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 các mẫu của Google Mua sắm và thư mục examples
trong nguồn thư viện ứng dụng Java của Google Ads.