Trong Google Ads API, chế độ lỗi một phần giúp bạn thực hiện các thao tác hiệu quả hơn bằng cách cho phép những thao tác hợp lệ được xử lý và các thao tác gặp lỗi được phản hồi riêng. Đây là tính năng hữu ích khi bạn cần thêm hoặc chỉnh sửa nhiều đối tượng quảng cáo mà không làm gián đoạn toàn bộ quy trình do một vài lỗi nhỏ. Trong bài viết này, chúng ta sẽ tìm hiểu chi tiết cách áp dụng chế độ lỗi một phần, cách xử lý lỗi và tối ưu hóa quy trình sử dụng Google Ads API.
Trong API Google Ads, bạn có thể yêu cầu thực hiện các thao tác hợp lệ, trong khi các thao tác không thành công sẽ trả về lỗi. Tính năng này, gọi là “lỗi một phần” (partial failure), cho phép xử lý riêng các thao tác không thành công sau khi hoàn tất các thao tác hợp lệ. Chế độ lỗi một phần có sẵn trong các phương thức không phải phương thức get của nhiều dịch vụ API Google Ads.
Lưu ý quan trọng: Không phải tất cả các dịch vụ đều hỗ trợ chế độ lỗi một phần. Để xác định một phương thức cụ thể có hỗ trợ chế độ này hay không, bạn cần kiểm tra xem phương thức đó có chứa trường partial_failure
trong yêu cầu hay không. Ví dụ, phương thức MutateAdGroups
của dịch vụ AdGroupService
sử dụng đối tượng yêu cầu MutateAdGroupsRequest
, trong đó có trường partial_failure
, nghĩa là phương thức này hỗ trợ chế độ lỗi một phần.
Chi tiết kỹ thuật
Để kích hoạt tính năng lỗi một phần, hãy đặt tham số partialFailure
thành true
khi sử dụng phương thức tương ứng. Cách thực hiện có thể thay đổi đôi chút tùy thuộc vào thư viện ứng dụng bạn sử dụng. Dưới đây là một ví dụ bật tính năng này khi gửi yêu cầu với phương thức MutateAdGroups
:
Ngôn ngữ Java:
mutateAdGroups(String.valueOf(customerId), operations, true);
Cách sử dụng chế độ lỗi một phần trong Google Ads API
Giả sử bạn cần thêm một nhóm quảng cáo mới vào tài khoản Google Ads, nhưng có khả năng một số nhóm quảng cáo sẽ gặp lỗi. Trong trường hợp này, bạn muốn các nhóm quảng cáo hợp lệ được tạo thành công, còn các nhóm quảng cáo gặp lỗi sẽ được trả về cùng với thông báo lỗi để xử lý.
Tạo thao tác và thực hiện lệnh gọi API
Bạn cần thực hiện các thao tác thay đổi và gọi API như bình thường, nhưng sử dụng chế độ lỗi một phần để xử lý các thao tác không thành công. Dưới đây là cách triển khai bằng các ngôn ngữ lập trình phổ biến:
private MutateAdGroupsResponse createAdGroups(
GoogleAdsClient googleAdsClient, long customerId, long campaignId) {
// Tạo nhóm quảng cáo hợp lệAdGroup group1 = AdGroup.newBuilder()
.setCampaign(ResourceNames.campaign(customerId, campaignId))
.setName(“Valid AdGroup: “ + getPrintableDateTime())
.build();
// Tạo nhóm quảng cáo không hợp lệ (ID chiến dịch không tồn tại)
AdGroup group2 = AdGroup.newBuilder()
.setCampaign(ResourceNames.campaign(customerId, 0L))
.setName(“Broken AdGroup: “ + getPrintableDateTime())
.build();
// Tạo nhóm quảng cáo không hợp lệ (trùng tên nhóm quảng cáo)
AdGroup group3 = AdGroup.newBuilder()
.setCampaign(ResourceNames.campaign(customerId, campaignId))
.setName(group1.getName())
.build();
// Định nghĩa các thao tác
AdGroupOperation op1 = AdGroupOperation.newBuilder().setCreate(group1).build();
AdGroupOperation op2 = AdGroupOperation.newBuilder().setCreate(group2).build();
AdGroupOperation op3 = AdGroupOperation.newBuilder().setCreate(group3).build();
// Thực hiện lệnh gọi API
try (AdGroupServiceClient service =
googleAdsClient.getLatestVersion().createAdGroupServiceClient()) {
return service.mutateAdGroups(
MutateAdGroupsRequest.newBuilder()
.setCustomerId(String.valueOf(customerId))
.addAllOperations(Arrays.asList(op1, op2, op3))
.setPartialFailure(true) // Kích hoạt chế độ lỗi một phần
.build());
}
}
Kiểm tra lỗi trong phản hồi
Để xác định phản hồi có chứa lỗi một phần hay không, bạn có thể kiểm tra thuộc tính partialFailureError
trong phản hồi:
private boolean checkIfPartialFailureErrorExists(MutateAdGroupsResponse response) {
return response.hasPartialFailureError();
}
Xử lý các thao tác thành công và không thành công trong Google Ads
Nếu thao tác được thực thi thành công, phản hồi sẽ chứa thông tin tài nguyên liên quan. Trong trường hợp này, bạn có thể in thông tin tài nguyên hoặc sử dụng dữ liệu đó cho các mục đích khác mà bạn mong muốn.
Ngược lại, nếu phản hồi không chứa thông tin nào, thao tác đã thực hiện có khả năng thất bại. Để xác định nguyên nhân lỗi, bạn có thể trích xuất chi tiết lỗi từ thuộc tính partial_failure_error
trong phản hồi:
- Trường
partial_failure_error
là một đối tượngStatus
, chứa danh sách các thông tin chi tiết về lỗi. - Mỗi chi tiết trong danh sách tương ứng với một thao tác đã thực hiện. Chi tiết này được biểu thị dưới dạng thực thể
GoogleAdsFailure
. GoogleAdsFailure
bao gồm danh sách các đối tượngGoogleAdsError
, đại diện cho từng lỗi cụ thể trong thao tác.GoogleAdsError
cung cấp thông tin về thông báo lỗi, mã lỗi và các thông tin chi tiết liên quan khác.
Hầu hết các thư viện Google Ads API đều cung cấp các hàm hỗ trợ để trích xuất thông tin chi tiết về lỗi, giúp bạn không phải tự xử lý các bước này từ đầu. Dưới đây là một ví dụ minh họa bằng mã:
private void printResults(MutateAdGroupsResponse response) {
int operationIndex = 0;
for (MutateAdGroupResult result : response.getResultsList()) {
if (ErrorUtils.getInstance().isPartialFailureResult(result)) {
// Xử lý lỗi partial failure
GoogleAdsFailure googleAdsFailure = ErrorUtils.getInstance()
.getGoogleAdsFailure(response.getPartialFailureError());
for (GoogleAdsError error :ErrorUtils.getInstance()
.getGoogleAdsErrors(operationIndex, googleAdsFailure)) {
System.out.printf(“Operation %d failed with error: %s%n”, operationIndex, error);
}
} else {
System.out.printf(“Operation %d succeeded.%n”, operationIndex);
}
++operationIndex;
}
}
Ví dụ về mã xử lý lỗi trong Google Ads API
Thư mục ErrorHandling
trong mỗi thư viện của Google Ads API chứa các ví dụ minh họa cách sử dụng cơ chế xử lý lỗi. Dưới đây là đoạn mã Java chi tiết minh họa cách xử lý các lỗi partial failure, trong đó một số thao tác có thể thành công và một số khác thất bại:
public class HandlePartialFailure {
public static void main(String[] args) {
// Thiết lập thông tin khách hàng và chiến dịch
long customerId = Long.parseLong(“INSERT_CUSTOMER_ID”);
long campaignId = Long.parseLong(“INSERT_CAMPAIGN_ID”);
try {
GoogleAdsClient googleAdsClient = GoogleAdsClient.newBuilder()
.fromPropertiesFile().build();
new HandlePartialFailure().runExample(googleAdsClient, customerId, campaignId);
} catch (Exception e) {
System.err.println(“An error occurred: “ + e.getMessage());
e.printStackTrace();
}
}
public void runExample(GoogleAdsClient googleAdsClient, long customerId, long campaignId) {
MutateAdGroupsResponse response = createAdGroups(googleAdsClient, customerId, campaignId);
if (response.hasPartialFailureError()) {
System.out.println(“Partial failures occurred. Analyzing errors…”);
printResults(response);
} else {
System.out.println(“All operations completed successfully.”);
}
}
private MutateAdGroupsResponse createAdGroups(GoogleAdsClient googleAdsClient, long customerId, long campaignId) {
AdGroup validAdGroup = AdGroup.newBuilder()
.setCampaign(ResourceNames.campaign(customerId, campaignId))
.setName(“Valid AdGroup”)
.build();
AdGroup invalidAdGroup = AdGroup.newBuilder()
.setCampaign(ResourceNames.campaign(customerId, 0L))
.setName(“Invalid AdGroup”)
.build();
AdGroup duplicateAdGroup = AdGroup.newBuilder()
.setCampaign(ResourceNames.campaign(customerId, campaignId))
.setName(“Valid AdGroup”)
.build();
AdGroupOperation op1 = AdGroupOperation.newBuilder().setCreate(validAdGroup).build();
AdGroupOperation op2 = AdGroupOperation.newBuilder().setCreate(invalidAdGroup).build();
AdGroupOperation op3 = AdGroupOperation.newBuilder().setCreate(duplicateAdGroup).build();
try (AdGroupServiceClient service = googleAdsClient.getLatestVersion().createAdGroupServiceClient()) {
return service.mutateAdGroups(
MutateAdGroupsRequest.newBuilder()
.setCustomerId(String.valueOf(customerId))
.addAllOperations(Arrays.asList(op1, op2, op3))
.setPartialFailure(true)
.build()
);
}
}
private void printResults(MutateAdGroupsResponse response) {
int operationIndex = 0;
for (MutateAdGroupResult result : response.getResultsList()) {
if (result.hasPartialFailureError()) {
GoogleAdsFailure failure = result.getPartialFailureError();
for (GoogleAdsError error : failure.getErrorsList()) {
System.out.printf(“Error in operation %d: %s%n”, operationIndex, error.getMessage());
}
} else {
System.out.printf(“Operation %d succeeded.%n”, operationIndex);
}
operationIndex++;
}
}
}
Chế độ lỗi một phần trong Google Ads API mang lại sự linh hoạt và hiệu quả cao khi xử lý các thao tác quảng cáo. Bằng cách hiểu và áp dụng đúng cách tính năng này, bạn có thể giảm thiểu rủi ro, tiết kiệm thời gian và tối ưu hóa chiến dịch quảng cáo của mình. Hãy áp dụng ngay hôm nay để trải nghiệm lợi ích mà tính năng này mang lại!