一時的なリソース名
GoogleAdsService.Mutate は、後で同じリクエストで参照できる一時的なリソース名をサポートしています。これにより、1 つのリクエストでキャンペーンとそれに関連する広告グループ、広告、キーワードなどを作成できる、などのメリットがあります。
その場合は、新しいリソースの resource_name を指定して負の ID を使用します。たとえば、キャンペーンを作成し、リソース名を customers/<YOUR_CUSTOMER_ID>/campaigns/-1 として指定した場合、後のオペレーションで広告グループを作成する際に、そのリソース名で参照できます。指定した -1 は、作成したキャンペーンの実際の 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"
...
}
}
},
]
キャンペーン用の -1 は再利用できないため、この広告グループには新しい一時的な ID が使用されます。また、広告グループの広告を作成する際にもこの広告グループを参照します。広告グループ自体は、リクエストの前のオペレーションでキャンペーン用に確立されたリソース名を参照しますが、それ以上のオペレーションは参照していないため、ad_group_ad_operation の resource_name は必要ありません。
同じタイプのオペレーションをグループ化する
GoogleAdsService.Mutate を使用する場合は、繰り返しオペレーションの配列内のリソースに基づいてオペレーションをグループ化することが重要です。この mutate メソッドは基本的には、個々のリソース固有の mutate メソッドを自動的に順番に呼び出す方法として機能します。これを行うために、異なるタイプのリソースに対する 1 つのリソースが見つかるまでオペレーションを読み込み、同じタイプのオペレーションをすべて 1 つのリクエストでバッチ処理します。
たとえば、Mutate 呼び出しの繰り返し operations フィールドに 5 件のキャンペーン オペレーションがあり、その後に Mutate 呼び出しの繰り返しフィールドで 10 件の広告グループ オペレーションがある場合、バックエンドでは合計 2 件の呼び出しが行われます。1 件は 5 件のオペレーションの CampaignService に、次数は 10 件のオペレーションです。ただし、別の方法でグループ化すると、パフォーマンスが大幅に低下する可能性があります。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};