Khi bạn gửi yêu cầu đến Google Ads API, yêu cầu đó có thể không thành công vì nhiều lý do. Ví dụ: bạn có thể cung cấp một đối số không hợp lệ hoặc tài khoản của bạn có thể đã đạt đến hạn mức tạo chiến dịch mới. Trong những trường hợp như vậy, API sẽ trả về một lỗi để cho bạn biết vấn đề đã xảy ra.
Hướng dẫn này giải thích cách đọc và xử lý lỗi API để bạn có thể xây dựng các ứng dụng mạnh mẽ hơn.
Cấu trúc lỗi
Nếu bạn đang sử dụng một trong các thư viện ứng dụng của chúng tôi, thì lỗi API sẽ xuất hiện dưới dạng trường hợp ngoại lệ. Các trường hợp ngoại lệ này chứa thông tin chi tiết giúp bạn hiểu lý do xảy ra lỗi.
Google Ads API trả về thông tin lỗi ở định dạng tiêu chuẩn. Nếu xảy ra
lỗi, phản hồi sẽ chứa một
GoogleAdsFailure đối tượng. Đối tượng
này chứa danh sách các đối tượng
GoogleAdsError riêng lẻ, mỗi đối tượng nêu chi tiết
một lỗi cụ thể.
Mỗi đối tượng GoogleAdsError cung cấp:
error_code: Một mã lỗi cụ thể cho bạn biết loại lỗi, chẳng hạn nhưAuthenticationError.NOT_ADS_USER.message: Nội dung mô tả mà con người có thể đọc được về lý do xảy ra lỗi.trigger: Giá trị gây ra lỗi, chẳng hạn như "1234".location: Thông tin chi tiết về phần nào trong yêu cầu gây ra lỗi, chẳng hạn như tên trường cụ thể.
Ngoài danh sách lỗi,
GoogleAdsFailure còn chứa
requestId, là mã nhận dạng duy nhất
cho yêu cầu API dẫn đến lỗi.
Ví dụ về lỗi
Sau đây là ví dụ về lỗi ở định dạng JSON. Lỗi này cho biết rằng trường name của ad_group ở chỉ mục 0 bị thiếu trong yêu cầu.
{
"code": 3,
"message": "Request contains an invalid argument.",
"details": [
{
"@type": "type.googleapis.com/google.ads.googleads.v26.errors.GoogleAdsFailure",
"errors": [
{
"errorCode": {
"requestError": "REQUIRED_FIELD_MISSING"
},
"message": "Required field is missing",
"location": {
"fieldPathElements": [
{
"fieldName": "ad_group",
"index": 0
},
{
"fieldName": "name"
}
]
}
}
],
"requestId": "unique_request_id_12345"
}
]
}
Hãy xem bài viết Tìm hiểu về lỗi API để tìm hiểu thêm về lỗi API.
Ví dụ về thư viện ứng dụng
Phần sau đây cho biết cách xử lý lỗi trong nhiều thư viện ứng dụng.
Java
try {
// Make an API call.
...
} catch (GoogleAdsException gae) {
// GoogleAdsException is the base class for most exceptions thrown by an
// API request. Instances of this exception have a message and a
// GoogleAdsFailure that contains a collection of GoogleAdsErrors that
// indicate the underlying causes of the GoogleAdsException.
System.err.printf(
"Request ID %s failed due to GoogleAdsException. Underlying"
+ " errors:%n",
gae.getRequestId());
int i = 0;
for (GoogleAdsError googleAdsError :
gae.getGoogleAdsFailure().getErrorsList()) {
System.err.printf(" Error %d: %s%n", i++, googleAdsError);
}
}
C#
try
{
// Make an API call.
...
}
catch (GoogleAdsException e)
{
Console.WriteLine($"Request with ID '{e.RequestId}' has failed.");
Console.WriteLine("Google Ads failure details:");
foreach (GoogleAdsError error in e.Failure.Errors)
{
Console.WriteLine($"{error.ErrorCode}: {error.Message}");
}
}
PHP
try {
// Make an API call.
...
} catch (GoogleAdsException $googleAdsException) {
printf(
"Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
$googleAdsException->getRequestId(),
PHP_EOL,
PHP_EOL
);
$errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
foreach ($errors as $error) {
/** @var GoogleAdsError $error */
printf(
"\t%s: %s%s",
$error->getErrorCode()->getErrorCode(),
$error->getMessage(),
PHP_EOL
);
}
}
Python
try:
# Make an API call.
...
except GoogleAdsException as ex:
print(
f"Request with ID '{ex.request_id}' failed with status "
f"'{ex.error.code().name}' and includes the following errors:"
)
for error in ex.failure.errors:
print(
f"\tError with message '{error.message}' and code "
f"'{error.error_code}'."
)
Ruby
begin
# Make an API call.
...
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
puts "API call failed with request ID: #{e.request_id}"
e.failure.errors.each do |error|
puts "\t#{error.error_code}: #{error.message}"
end
end
Perl
# Try sending a mutate request to add the ad group ad.
...
if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
printf "Google Ads failure details:\n";
foreach my $error (@{$response->get_google_ads_failure()->{errors}}) {
printf "\t%s: %s\n",
[keys %{$error->{errorCode}}]->[0], $error->{message};
}
}
Cách thu thập nhật ký
Để khắc phục sự cố, hãy thu thập nhật ký lỗi do máy chủ Google Ads API trả về và kiểm tra nội dung của nhật ký đó. Hãy làm theo hướng dẫn sau để bật tính năng ghi nhật ký và thu thập nhật ký API.
Java
Hãy tham khảo hướng dẫn ghi nhật ký của thư viện ứng dụng Java guide để biết hướng dẫn.
C#
Bạn có thể khởi động tính năng ghi nhật ký bằng cách thêm dòng sau vào phương thức Main trước khi thực hiện bất kỳ lệnh gọi API nào. Điều này đảm bảo rằng thư viện sẽ tạo nhật ký cho tất cả các lệnh gọi API do ứng dụng của bạn thực hiện.
using Google.Ads.GoogleAds.Util;
...
// Detailed logs.
TraceUtilities.Configure(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
"/path/to/your/logs/details.log", System.Diagnostics.SourceLevels.All);
// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
"/path/to/your/logs/summary.log", System.Diagnostics.SourceLevels.All);
Hãy tham khảo hướng dẫn ghi nhật ký của thư viện.NET để biết các lựa chọn khác.
PHP
Bạn có thể đặt cấu hình ghi nhật ký trong tệp
google_ads_php.ini
của thư viện ứng dụng. Đặt logLevel thành NOTICE để bắt đầu thu thập nhật ký lỗi chi tiết.
[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"
Hãy tham khảo hướng dẫn ghi nhật ký của thư viện ứng dụng PHP để biết hướng dẫn.
Python
Bạn có thể đặt cấu hình ghi nhật ký trong tệp
google-ads.yaml
của thư viện ứng dụng. Đặt cấp độ ghi nhật ký thành DEBUG để bắt đầu thu thập nhật ký lỗi chi tiết.
Hãy tham khảo hướng tạo ghi nhật ký của thư viện Python để biết các lựa chọn khác.
Ruby
Bạn có thể đặt cấu hình ghi nhật ký trong tệp
google_ads_config.rb
của thư viện ứng dụng. Đặt cấp độ ghi nhật ký thành INFO để bắt đầu thu thập nhật ký lỗi chi tiết.
Hãy tham khảo hướng dẫn ghi nhật ký của thư viện Ruby để biết các lựa chọn khác.
Perl
Để khởi chạy tính năng ghi nhật ký, hãy thêm dòng sau vào tập lệnh Perl trước khi thực hiện bất kỳ lệnh gọi API nào.
Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();
Hãy tham khảo hướng dẫn ghi nhật ký của thư viện Perl để biết các lựa chọn khác.
curl
curl in các phản hồi không thành công vào stderr theo mặc định.
Cách xử lý lỗi
Nếu bạn gặp lỗi, hãy làm theo các bước sau:
- Bắt trường hợp ngoại lệ và thu thập nhật ký: Bắt đầu bằng cách bắt các trường hợp ngoại lệ và tuỳ ý thu thập nhật ký API.
- Kiểm tra danh sách
errors: Xem từngGoogleAdsErrortrong đối tượngGoogleAdsFailure. Theerror_codevàmessagesẽ cho bạn biết vấn đề đã xảy ra. - Kiểm tra giá trị
location: Trườnglocationcó thể giúp bạn xác định vị trí xảy ra vấn đề trong yêu cầu của mình. - Tham khảo tài liệu: Đối với các mã lỗi cụ thể, hãy xem trang các lỗi thường gặp hoặc tài liệu tham khảo đầy đủ về mã lỗi để biết thêm thông tin chi tiết về lỗi và cách khắc phục.
- Điều chỉnh yêu cầu: Dựa trên thông báo lỗi, hãy sửa yêu cầu API
của bạn. Ví dụ: nếu bạn thấy
REQUIRED_FIELD_MISSING, hãy đảm bảo rằng bạn cung cấp trường đó trong yêu cầu của mình. - Ghi nhật ký
request_id: Nếu bạn không thể tìm ra cách giải quyết lỗi và cần liên hệ với nhóm hỗ trợ, hãy cung cấp nhật ký đầy đủ về yêu cầu và phản hồi cho yêu cầu không thành công. Đảm bảo cung cấprequest_id. Mã nhận dạng này giúp các kỹ sư của Google xác định vị trí thông tin chi tiết về yêu cầu không thành công trong nhật ký máy chủ Google Ads API và điều tra vấn đề của bạn.
Các bước tiếp theo
- Xem bài viết Các lỗi thường gặp để biết danh sách các vấn đề thường gặp và giải pháp cho các vấn đề đó.
- Để biết các kỹ thuật xử lý lỗi nâng cao hơn, bao gồm cả logic thử lại và lỗi một phần, hãy xem bài viết Tìm hiểu về lỗi API errors.