Google 広告スクリプトでは、Google Ads API で利用可能な汎用的な変更をサポートしています。GoogleAdsService.mutate
から実行できるほとんどの操作(キャンペーンの作成や管理など)は、Google 広告スクリプトでも実行できます。
この機能では Google Ads API の大部分にアクセスできるため、この機能を使用するには、Google Ads API の規約を基本的に理解しておくことが重要です。デベロッパー トークンや認証など、多くの側面は Google 広告スクリプトによって処理されるためスキップできますが、有効な変更リクエストを作成する必要があります。
このガイドに進む前に、Google Ads API REST インターフェースに関する基本的なリソースをいくつかご紹介します。
基本的な例
機能を示すために、キャンペーン予算を作成する次の基本的な例を考えてみましょう。
const budgetResult = AdsApp.mutate({
campaignBudgetOperation: {
create: {
amountMicros: 10000000,
explicitlyShared: false
}
}
});
AdsApp.mutate
の呼び出しでは、単一の MutateOperation
を表す JSON オブジェクトが使用されます。このオブジェクト内で、実行するオペレーションの種類(この場合は campaignBudgetOperation
)を指定します。次に、create
、remove
、または update
と updateMask
の両方を指定します。create
と update
内の特定のフィールドは、オペレーションを実行するリソースのタイプによって異なります。
オペレーションを構築する
有効なオペレーションを構築するために使用できる戦略がいくつかあります。キャンペーン予算の例で説明すると、キャンペーン予算の REST リファレンス ドキュメントで、有効なフィールドのリストを確認し、適切なフィールドに入力するか、スクリプトでカスタム JavaScript コードを記述して適切なオブジェクトを構築します。
または、キャンペーン予算の「お試し」機能を使用してオペレーションを動的に構築することもできます。この機能を使用すると、追加するフィールドを選択してリクエスト本文を動的に構築できます。その後、生成された結果からオペレーションの内容を抽出し、オペレーション タイプを指定してから mutate
呼び出しに追加できます。
オペレーション タイプ
作成
オペレーションで create
を指定し、作成するリソースのオブジェクト表現を渡します。
create
オペレーションの例については、上記をご覧ください。
削除
オペレーションで remove
を指定し、削除するリソースのリソース名を渡します。例:
AdsApp.mutate({
adGroupOperation: {
remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
}
});
エンティティのリソース名がわからない場合は、Adsapp.search
リクエストを使用して取得できます。
更新
オペレーションで update
を指定し、リソース名が指定されたオブジェクトを渡して、更新するオブジェクトをシステムが特定できるようにします。また、値を更新するフィールドに入力し、このリクエストで変更するフィールドを正確に示す updateMask
を指定します。更新マスクにリソース名を含めないでください。
update
オペレーションの例:
const campaignResult = AdsApp.mutate({
campaignOperation: {
update: {
resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
status: "PAUSED",
name: "[Paused] My campaign"
},
updateMask: "name,status"
}
});
結果の処理
オペレーションのタイプに関係なく、戻り値は MutateResult
です。返されたリソース名を使用して、変更後のリソースの現在の状態をクエリし、オペレーションが成功したかどうか、エラーが発生した場合はどのようなエラーが発生したかを確認できます。
結果を確認してログに情報を出力する基本的なフローの例を次に示します。
const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
console.log("Errors encountered:");
for (const error of result.getErrorMessages()) {
console.log(error);
}
}
複数のオペレーション
Google 広告スクリプトでは、AdsApp.mutateAll
メソッドを使用して、1 つのリクエストで複数のオペレーションを変更することもできます。相互に依存するエンティティ(キャンペーンの完全な階層など)を 1 回のリクエストで作成できます。必要に応じて、一連のオペレーション全体をアトミックにすることができます。これにより、いずれかのオペレーションが失敗した場合、どのオペレーションも実行されなくなります。
戻り値は MutateResult
オブジェクトの配列です。指定したオペレーションごとに 1 つのオブジェクトが返され、初期オペレーションと同じ順序で返されます。
この機能は Google Ads API の機能と同じように動作します。一時 ID やその他の考慮事項について詳しくは、Google Ads API のベスト プラクティス ガイドをご覧ください。なお、このガイドではフィールド名を表すために snake_case
を使用していますが、Google Ads スクリプトのドキュメントでは lowerCamelCase
を使用しています。どちらの場合も Google 広告スクリプトで受け入れられるため、そのガイドからコードを直接コピーできます。
単一のリクエストで複数のオペレーションを行うには、すべてのオペレーションを配列に収集してから AdsApp.mutateAll
を呼び出します。mutateAll
呼び出しは、オペレーションの配列を最初の引数として受け取り、オプションの 2 番目の引数として、次のオプションを受け取ります。
apiVersion
: スクリプトのデフォルト以外のバージョンを使用する場合は、V20
などのカスタム API バージョンを指定できます。その時点で一般公開されているバージョンを使用できます。partialFailure
: このフィールドのデフォルトはtrue
です。true
に設定すると、有効なオペレーションが実行され、失敗したオペレーションはエラーを返します。false
に設定すると、オペレーションが失敗した場合、オペレーションは実行されず、このオペレーション セットはアトミックになります。
以下は、アトミック リクエストでキャンペーン予算、キャンペーン、広告グループを作成する複数のオペレーションの例です。
const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
campaignBudgetOperation: {
create: {
resourceName: budgetId,
amountMicros: 10000000,
explicitlyShared: false
}
}
});
operations.push({
campaignOperation: {
create: {
resourceName: campaignId,
name: 'New Campaign ' + new Date(),
advertisingChannelType: 'SEARCH',
manualCpc: {},
campaignBudget: budgetId,
advertisingChannelType: 'DISPLAY',
networkSettings: {
targetContentNetwork: true
}
}
}
});
operations.push({
adGroupOperation: {
create: {
campaign: campaignId,
name: 'New AdGroup ' + new Date(),
optimizedTargetingEnabled: true
}
}
});
const results = AdsApp.mutateAll(
operations, {partialFailure: false});