ビルダーを使用してエンティティを追加します。
Campaign などの各親オブジェクトには、子エンティティの追加に使用するビルダー オブジェクトを取得するメソッドが含まれています。 たとえば、キャンペーンに広告グループを追加するには、 Campaign オブジェクトの newAdGroupBuilder メソッドを呼び出します。
ビルダー オブジェクトには、エンティティのプロパティ値を設定するために使用するメソッドが含まれています。 たとえば、キーワード (keyword)の CPC を指定するには、withCpc メソッドを使用します。 エンティティのすべてのプロパティ値を設定したら、 build メソッドを呼び出してエンティティを作成します。 ビルド プロセスは、要求が他のビルド要求と一緒にキューに入れられ、バッチで処理される非同期プロセスです。 バッチ処理された要求は、スクリプトが終了する前に完了します。
ビルド要求が成功したかどうかを確認するには、ログを確認するか、 build メソッドが返す操作オブジェクトを使用します。 たとえば、 AdGroupBuilder は AdGroupOperation を返します。 操作オブジェクトのメソッド (isSuccessful、 getResult、または getErrors) のいずれかを呼び出して、スクリプトがエンティティを正常に作成したかどうかを判別できます。 ただし、これらのメソッドを呼び出すときは、パフォーマンスに関する考慮事項があります ( 「パフォーマンスに関する考慮事項」を参照してください)。
次の例は、ビルダー オブジェクトと操作オブジェクトを使用してキーワード (keyword)を作成する方法を概念的に示しています。 多くの場合、このフローは 1 つ (または少数のエンティティ) を作成する場合にのみ使用する必要があります。
// Gets the first ad group in the account.
var adGroup = AdsApp.adGroups().get().next();
// Use the 'with' methods to specify the keyword's property values.
// The .build() method adds the build request to the build queue.
var keywordOperation = adGroup.newKeywordBuilder()
.withCpc(1.2)
.withText("shirts")
.withFinalUrl("https://www.contoso.com/shirts")
.build();
// Call isSuccessful() to determine if the build succeeded.
// Calling any of the operation object's method processes the
// build request immediately.
if (keywordOperation.isSuccessful()) {
// You only need to call getResult if you need to access
// the new keyword entity.
var keyword = keywordOperation.getResult();
} else {
// Handle the errors.
for (var error of keywordOperation.getErrors()) {
Logger.log(`${error}\n`);
}
}
パフォーマンスに関する考慮事項
パフォーマンスを向上させるために、スクリプトはビルド要求をバッチで処理します。 ビルド要求の操作メソッドを呼び出すと、スクリプトはキューに入れられたビルド要求をすぐに処理し、パフォーマンスの向上は無効になります。 複数のエンティティを作成する場合は、エンティティの構築に使用するのと同じループで操作メソッドを実行しないでください。 これにより、一度に 1 つのエンティティしか処理されないため、パフォーマンスが低下します。 代わりに、操作の配列を作成し、ビルド ループの後に処理します。
操作
// An array to hold the operations, so you
// can process them after all the entities are queued.
var operations = [];
// Create all the new entities.
for (var i = 0; i < keywords.length; i++) {
var keywordOperation = AdsApp.adGroups().get().next()
.newKeywordBuilder()
.withText(keywords[i])
.build();
operations.push(keywordOperation);
}
// Now call the operation method so the build requests
// get processed in batches.
for (var i = 0; i < operations.length; i++) {
var newKeyword = operations[i].getResult();
}
実行してはならない操作
for (var i = 0; i < keywords.length; i++) {
var keywordOperation = AdsApp.adGroups().get().next()
.newKeywordBuilder()
.withText(keywords[i])
.build();
// Don't get results in the same loop that creates
// the entity because Scripts then only processes one
// entity at a time.
var newKeyword = keywordOperation.getResult();
}
以下はビルダーのリストです。