Google Ads API にリクエストを送信すると、さまざまな理由で失敗することがあります。たとえば、無効な引数を指定した場合や、アカウントが新しいキャンペーンの作成上限に達した場合などです。このような場合、API はエラーを返して問題の内容を通知します。
このガイドでは、API エラーを読み取って処理し、より堅牢なアプリケーションを構築する方法について説明します。
エラーの構造
Google のクライアント ライブラリのいずれかを使用している場合、API エラー は例外として表面化します。これらの例外には、エラーが発生した理由を理解するのに役立つ詳細が含まれています。
Google Ads API は、標準形式でエラー情報を返します。エラーが発生すると、レスポンスに
GoogleAdsFailure オブジェクトが含まれます。この
オブジェクトには、個々の
GoogleAdsErrorオブジェクトのリストが含まれており、それぞれが
特定のエラーの詳細を示しています。
各 GoogleAdsError オブジェクトは次の情報を提供します。
error_code: エラーの種類を示す特定のエラー コード(AuthenticationError.NOT_ADS_USERなど)。message: エラーが発生した理由に関する説明(人が読める形式)。trigger: エラーの原因となった値(「1234」など)。location: リクエストのどの部分でエラーが発生したかについての詳細(特定のフィールド名など)。
エラーのリストに加えて、
GoogleAdsFailure には requestId が含まれています。これは、エラーが発生した
API リクエストの一意の識別子です。
エラーの例
JSON 形式のエラーの例を次に示します。このエラーは、インデックス 0 の ad_group の name フィールドがリクエストにないことを示しています。
{
"code": 3,
"message": "Request contains an invalid argument.",
"details": [
{
"@type": "type.googleapis.com/google.ads.googleads.v24.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"
}
]
}
API エラーの詳細については、ガイドをご覧ください 。
クライアント ライブラリの例
次のセクションでは、さまざまなクライアント ライブラリでエラーを処理する方法について説明します。
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
);
foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() 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 '{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};
}
}
ログの取得方法
エラーのトラブルシューティングを行うには、Google Ads API サーバーから返されたエラーログを取得し、その内容を調べます。ロギングを有効にして API ログを取得する手順は次のとおりです。
Java
手順については、Java クライアント ライブラリのロギング ガイドをご覧ください。
C#
ロギングを初期化するには、API 呼び出しを行う前に Main メソッドに次の行を追加します。これにより、ライブラリはアプリケーションが行うすべての API 呼び出しのログを生成します。
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);
その他のオプションについては、.NET ライブラリのロギング ガイドをご覧ください。
PHP
ロギング構成は、クライアント ライブラリの
google_ads_php.ini
ファイルで設定できます。詳細なエラーログの取得を開始するには、logLevel を NOTICE に設定します。
[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"
手順については、PHP クライアント ライブラリのロギング ガイドをご覧ください。
Python
ロギング構成は、クライアント ライブラリの
google-ads.yaml
ファイルで設定できます。詳細なエラーログの取得を開始するには、ロギングレベルを DEBUG に設定します。
その他のオプションについては、Python ライブラリのロギング ガイドをご覧ください。
Ruby
ロギング構成は、クライアント ライブラリの
google_ads_config.rb
ファイルで設定できます。詳細なエラーログの取得を開始するには、ロギングレベルを INFO に設定します。
その他のオプションについては、Ruby ライブラリのロギング ガイド をご覧ください。
Perl
ロギングを初期化するには、API 呼び出しを行う前に、Perl スクリプトに次の行を追加します。
Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();
その他のオプションについては、Perl ライブラリのロギング ガイド をご覧ください。
curl
curl は、デフォルトで失敗したレスポンスを stderr に出力します。
エラーの処理方法
エラーが発生した場合は、次の手順を行います。
- 例外をキャッチしてログを取得する: まず、 例外をキャッチし、必要に応じて API ログを取得します。
errorsリストを確認する:GoogleAdsFailureオブジェクトの各GoogleAdsErrorを確認します。error_codeとmessageで問題の内容を確認できます。- **`
location` 値を確認する**: **`location`** フィールドを使用すると、リクエストのどの部分で問題が発生したかを特定できます。 - ドキュメントを参照する: 特定のエラーコードについては、一般的な エラーのページまたはエラーコードの リファレンス全体で、エラーの詳細と 修正方法を確認してください。
- リクエストを調整する: エラー メッセージに基づいて、API
リクエストを修正します。たとえば、
REQUIRED_FIELD_MISSINGが表示された場合は、リクエストでそのフィールドを指定していることを確認します。 request_idを記録する: エラーの解決方法がわからず、サポートに問い合わせる必要がある場合は、失敗したリクエストのリクエスト ログとレスポンス ログをすべて含めてください。request_idを含めるようにしてください。この ID を使用すると、Google のエンジニアは Google Ads API サーバーログで失敗したリクエストの詳細を特定し、問題を調査できます。
次のステップ
- よくあるエラーで、よく発生する問題とその解決策を確認します。
- 再試行ロジックや 部分的な失敗など、高度なエラー処理手法については、API エラーについて をご覧ください。