臨時資源名稱
GoogleAdsService.Mutate 支援臨時資源名稱，您稍後可以在同一個要求中參照。例如，您可以在一個要求中製作廣告活動，以及相關聯的廣告群組、廣告等關鍵字。
方法是指定新資源的 resource_name 使用負值 ID。舉例來說，如果您建立了一個廣告活動，並將資源名稱指定為 customers/<YOUR_CUSTOMER_ID>/campaigns/-1，那麼當您在後續作業中建立廣告群組時，可以按照該資源名稱參照該參照，然後把您指定的 -1 替換成所建立廣告活動的實際編號。
使用臨時資源名稱時，請注意下列事項：
- 臨時資源名稱只能在資源中定義之後才能使用。在以下範例中，廣告活動作業必須在廣告活動運作之後顯示在作業清單中。
- 系統不會記住工作或變化要求中的臨時資源名稱；如要參照在先前工作或 Variant 要求中建立的資源，請使用實際資源名稱。
- 針對單一工作或 DAI 要求，每個臨時資源名稱都必須使用不重複的負數，即使它們來自不同的資源類型也一樣。如果在單一工作或變化要求中重複使用臨時 ID，系統會傳回錯誤。
範例
為了更明確地說明上述情況，假設您想在單一 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，因此建立廣告群組將會使用新的暫時 ID；此外，建立廣告群組廣告時也會參照這個廣告群組。廣告群組本身會參照先前在要求中為廣告活動建立的資源名稱，而不需要使用 ad_group_ad_operation 中的 resource_name，因為無需進一步操作。
將同類型的作業分組
使用 GoogleAdsService.Mutate 時，請務必根據重複作業陣列中的資源，將作業分組。這種 變更 的 方法， 可 是 自動 呼叫 個別 個別 的 變異 方法。為此，函式會讀取作業，直到為不同類型的資源找到一項作業，然後再將所有相同類型的作業批次處理為單一要求。
舉例來說，如果您有 5 個廣告活動作業，而在 Mutate 呼叫中重複的 operations 欄位中執行了 10 項廣告群組作業，系統就會在後端執行兩項呼叫，總計為 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};