一時的なリソース名
GoogleAdsService.Mutate は、同じリクエストで後で参照できる一時的なリソース名をサポートしています。たとえば、キャンペーンとそれに関連する広告グループ、広告、キーワードなどをすべて 1 つのリクエストで作成できます。
これを行うには、新しいリソースの resource_name を指定して負の ID を使用します。たとえば、キャンペーンを作成し、そのリソース名を customers/<YOUR_CUSTOMER_ID>/campaigns/-1 として指定した場合、後のオペレーションで広告グループを作成するときに、そのリソース名で参照できます。指定した -1 は、作成されたキャンペーンの実際の ID に自動的に置き換えられます。
一時的なリソース名を使用する場合は、次の点に注意してください。
- 一時的なリソース名は、リソースで定義された後でのみ使用できます。以下の例では、オペレーションのリストで、広告グループのオペレーションの後に広告グループのオペレーションを表示する必要があります。
- 一時的なリソース名は、ジョブまたは変更リクエスト間では記憶されません。前のジョブまたは変更リクエストで作成したリソースを参照するには、実際のリソース名を使用します。
- 単一のジョブまたは変更リクエストでは、異なるリソースタイプからの場合でも、各一時リソース名は一意の負の数を使用する必要があります。一時 ID が単一のジョブまたは変更リクエストで再利用されると、エラーが返されます。
例
上記の状況の具体的な例で、キャンペーン、広告グループ、広告を 1 つの API リクエストに追加する例を示します。リクエストの構造は次のようなものになります。
mutate_operations: [
{
campaign_operation: {
create: {
resource_name: "customers/<YOUR_CUSTOMER_ID>/campaigns/-1",
...
}
}
},
{
ad_group_operation: {
create: {
resource_name: "customers/<YOUR_CUSTOMER_ID>/adGroups/-2",
campaign: "customers/<YOUR_CUSTOMER_ID>/campaigns/-1"
...
}
}
},
{
ad_group_ad_operation: {
create: {
ad_group: "customers/<YOUR_CUSTOMER_ID>/adGroups/-2"
...
}
}
},
]
広告グループには新しい一時 ID が使用されます。キャンペーンで使用した -1 は再利用できないため、この広告グループの作成時に広告グループも参照します。広告グループ自体は、リクエストの以前のオペレーションでキャンペーンのために設定したリソース名を参照します。一方、ad_group_ad_operation の resource_name は、それ以上のオペレーションが参照されていないため、は必要ありません。
同じタイプのオペレーションをグループ化する
GoogleAdsService.Mutate を使用するときは、繰り返しオペレーション配列内のリソースに従ってオペレーションをグループ化することが重要です。この mutate メソッドは基本的には、個々のリソース固有の mutate メソッドを自動的に順番に呼び出す方法として機能します。これを行うには、異なるタイプのリソースに対してオペレーションが見つかるまでオペレーションを読み取り、1 つのリクエストで同じタイプのオペレーションをすべてバッチ処理します。
たとえば、Mutate 呼び出しの operations フィールドに繰り返し 5 つのキャンペーン演算が続き、その後に 10 個の広告グループ演算が続く場合、システムはバックエンドで合計 2 回の呼び出しを実行します。1 回は CampaignService に対して 5 回実行され、次の呼び出しは 10 回の実行に対して AdGroupService に対して行われます。ただし、グループ化方法が異なる場合は、パフォーマンスが大幅に低下する可能性があります。2 つのキャンペーンと 2 つの広告グループしか作成せず、それらを [キャンペーン、広告グループ、キャンペーン、広告グループ] として順番に並べると、バックエンドでの呼び出しは合計 4 回になります。その結果、API のパフォーマンスが低下し、極端な場合はタイムアウトにつながる可能性もあります。
レスポンスから可変属性を取得する
変更リクエストの response_content_type を MUTABLE_RESOURCE に設定すると、リクエストによって作成または更新されたすべてのオブジェクトの可変フィールドの値がレスポンスに含まれます。この機能を使用して、変更リクエストの後に search または searchStream リクエストを追加しないようにします。
response_content_type を設定しない場合、Google Ads API はデフォルトで RESOURCE_NAME_ONLY に設定され、レスポンスには作成または更新された各リソースのリソース名のみが含まれます。
API 呼び出しから可変リソースを取得する例を次に示します。
Java
// Constructs a request to add the bid modifier.
MutateCampaignBidModifiersRequest request =
MutateCampaignBidModifiersRequest.newBuilder()
.addOperations(op)
.setCustomerId(String.valueOf(customerId))
// Specifies that we want to the request to return the mutated object and not just its
// resource name.
.setResponseContentType(ResponseContentType.MUTABLE_RESOURCE)
.build();
// Sends the operation in a mutate request.
try (CampaignBidModifierServiceClient agcServiceClient =
googleAdsClient.getLatestVersion().createCampaignBidModifierServiceClient()) {
MutateCampaignBidModifiersResponse response =
agcServiceClient.mutateCampaignBidModifiers(request);
/**
* The resource returned in the response can be accessed directly in the results list. Its
* fields can be read directly, and it can also be mutated further and used in subsequent
* requests, without needing to make additional Get or Search requests.
*/
CampaignBidModifier mutableResource = response.getResults(0).getCampaignBidModifier();
System.out.printf(
"Created campaign bid modifier with resource_name "
+ "'%s', criterion ID "
+ "%d, and bid modifier value "
+ "%s, under the campaign with "
+ "resource_name '%s'.%n",
mutableResource.getResourceName(),
mutableResource.getCriterionId(),
mutableResource.getBidModifier(),
mutableResource.getCampaign());
}
C#
// Construct an operation to create the campaign bid modifier.
CampaignBidModifierOperation op = new CampaignBidModifierOperation()
{
Create = campaignBidModifier
};
// Construct a request, and set the ResponseContentType field to
// ResponseContentType.MutableResource, so that the response contains
// the mutated object and not just its resource name.
MutateCampaignBidModifiersRequest request = new MutateCampaignBidModifiersRequest()
{
CustomerId = customerId.ToString(),
ResponseContentType = ResponseContentType.MutableResource,
Operations = { op }
};
// Send the operation in a mutate request.
try
{
MutateCampaignBidModifiersResponse response =
campaignBidModifierService.MutateCampaignBidModifiers(request);
Console.WriteLine("Added {0} campaign bid modifiers:", response.Results.Count);
// The resource returned in the response can be accessed directly in the
// results list. Its fields can be read directly, and it can also be mutated
// further and used in subsequent requests, without needing to make
// additional Get or Search requests.
foreach (MutateCampaignBidModifierResult result in response.Results)
{
Console.WriteLine($"\tCreated campaign bid modifier with " +
$"resource name '{result.ResourceName}', " +
$"criterion ID '{result.CampaignBidModifier.CriterionId}', " +
$"and bid modifier value {result.CampaignBidModifier.BidModifier}, " +
$"under the campaign with resource_name " +
$"'{result.CampaignBidModifier.Campaign}'");
}
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
PHP
// Issues a mutate request to add the campaign bid modifier.
// Here we pass the optional parameter ResponseContentType::MUTABLE_RESOURCE so that the
// response contains the mutated object and not just its resource name.
$campaignBidModifierServiceClient = $googleAdsClient->getCampaignBidModifierServiceClient();
$response = $campaignBidModifierServiceClient->mutateCampaignBidModifiers(
$customerId,
[$campaignBidModifierOperation],
['responseContentType' => ResponseContentType::MUTABLE_RESOURCE]
);
// The resource returned in the response can be accessed directly in the results list.
// Its fields can be read directly, and it can also be mutated further and used in
// subsequent requests, without needing to make additional Get or Search requests.
/** @var CampaignBidModifier $addedCampaignBidModifier */
$addedCampaignBidModifier = $response->getResults()[0]->getCampaignBidModifier();
printf(
"Added campaign bid modifier with resource_name '%s', criterion ID %d, and "
. "bid modifier value %f, under the campaign with resource name '%s'.%s",
$addedCampaignBidModifier->getResourceName(),
$addedCampaignBidModifier->getCriterionId(),
$addedCampaignBidModifier->getBidModifier(),
$addedCampaignBidModifier->getCampaign(),
PHP_EOL
);
Python
# Add the campaign bid modifier. Here we pass the optional parameter
# response_content_type=MUTABLE_RESOURCE so that the response contains
# the mutated object and not just its resource name.
request = client.get_type("MutateCampaignBidModifiersRequest")
request.customer_id = customer_id
request.operations = [campaign_bid_modifier_operation]
request.response_content_type = (
client.enums.ResponseContentTypeEnum.MUTABLE_RESOURCE
)
campaign_bm_response = campaign_bm_service.mutate_campaign_bid_modifiers(
request=request
)
# The resource returned in the response can be accessed directly in the
# results list. Its fields can be read directly, and it can also be mutated
# further and used in subsequent requests, without needing to make
# additional Get or Search requests.
mutable_resource = campaign_bm_response.results[0].campaign_bid_modifier
print(
"Created campaign bid modifier with resource_name "
f"'{mutable_resource.resource_name}', criterion ID "
f"'{mutable_resource.criterion_id}', and bid modifier value "
f"'{mutable_resource.bid_modifier}', under the campaign with "
f"resource_name '{mutable_resource.campaign}', "
)
Ruby
# Add the campaign bid modifier. Here we pass the optional parameter
# response_content_type=MUTABLE_RESOURCE so that the response contains
# the mutated object and not just its resource name.
response = campaign_bid_modifier_service.mutate_campaign_bid_modifiers(
customer_id: customer_id,
operations: [operation],
response_content_type: :MUTABLE_RESOURCE,
)
puts "Added #{response.results.size} campaign bid modifiers:"
response.results.each do |added_campaign_bid_modifier|
# The resource returned in the response can be accessed directly in the
# results list. Its fields can be read directly, and it can also be mutated
# further and used in subsequent requests, without needing to make
# additional Get or Search requests.
mutable_resource = added_campaign_bid_modifier.campaign_bid_modifier
puts "\tCreated campaign bid modifier with " \
"resource_name '#{mutable_resource.resource_name}', " \
"criterion ID #{mutable_resource.criterion_id}, " \
"bid_modifier #{mutable_resource.bid_modifier}, " \
"under the campaign with resource_name '#{mutable_resource.campaign}'"
end
Perl
# Add the campaign bid modifier. Here we pass the optional parameter
# responseContentType => MUTABLE_RESOURCE so that the response contains the
# mutated object and not just its resource name.
my $campaign_bid_modifiers_response =
$api_client->CampaignBidModifierService()->mutate({
customerId => $customer_id,
operations => [$campaign_bid_modifier_operation],
responseContentType => MUTABLE_RESOURCE
});
# The resource returned in the response can be accessed directly in the
# results list. Its fields can be read directly, and it can also be mutated
# further and used in subsequent requests, without needing to make additional
# Get or Search requests.
my $mutable_resource =
$campaign_bid_modifiers_response->{results}[0]{campaignBidModifier};
printf
"Created campaign bid modifier with resource name '%s', criterion ID %d, "
. "and bid modifier value %s, under the campaign with resource name '%s'.\n",
$mutable_resource->{resourceName}, $mutable_resource->{criterionId},
$mutable_resource->{bidModifier}, $mutable_resource->{campaign};