Tymczasowe nazwy zasobów
GoogleAdsService.Mutate obsługuje tymczasowe nazwy zasobów, do których można później odwoływać się w tym samym żądaniu. Dzięki temu możesz na przykład utworzyć kampanię i powiązane z nią grupy reklam, reklamy, słowa kluczowe itd. w jednym żądaniu.
Możesz to zrobić, określając resource_name nowego zasobu w celu zastosowania negatywnego identyfikatora. Jeśli na przykład utworzysz kampanię i określisz jej nazwę zasobu jako customers/<YOUR_CUSTOMER_ID>/campaigns/-1, to podczas tworzenia grupy reklam w trakcie późniejszej operacji możesz odwoływać się do niej za pomocą tej nazwy zasobu, a podany -1 zostanie automatycznie zastąpiony rzeczywistym identyfikatorem utworzonej kampanii.
Podczas korzystania z tymczasowych nazw zasobów pamiętaj o tych kwestiach:
- Tymczasowej nazwy zasobu można użyć dopiero po zdefiniowaniu jej w zasobie. W poniższym przykładzie operacja grupy reklam pojawi się po operacji kampanii na liście operacji.
- Tymczasowe nazwy zasobów nie są zapamiętywane w zadaniach ani żądaniach mutacji. Aby odwołać się do zasobu utworzonego w poprzednim zadaniu lub do mutacji, użyj jego rzeczywistej nazwy zasobu.
- W przypadku pojedynczego zadania lub żądania mutacji każda tymczasowa nazwa zasobu musi mieć niepowtarzalną ujemną liczbę, nawet jeśli pochodzą one z różnych typów zasobów. Jeśli tymczasowy identyfikator zostanie ponownie użyty w pojedynczym zadaniu lub żądaniu mutacji, zostanie zwrócony błąd.
Przykład
Aby podać bardziej konkretny przykład sytuacji opisanej powyżej, załóżmy, że chcesz dodać kampanię, grupę reklam i reklamę w jednym żądaniu do interfejsu API. Utwórz strukturę żądania analogiczną do tej:
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"
...
}
}
},
]
Zwróć uwagę, że w tej grupie reklam używany jest nowy identyfikator tymczasowy, ponieważ nie możemy ponownie użyć -1 w tej kampanii. Poza tym odwołujemy się do tej grupy reklam podczas tworzenia reklamy w grupie reklam. Sama grupa reklam odwołuje się do nazwy zasobu określonej przez nas w ramach wcześniejszej operacji żądania, a element resource_name w elemencie ad_group_ad_operation nie jest potrzebny, ponieważ nie odwołuje się do niego żadna inna operacja.
Operacje grup tego samego typu
Ważne jest, aby przy korzystaniu z GoogleAdsService.Mutate grupować operacje według ich zasobu w tablicy powtarzanych operacji. Ogólnie ta metoda mutacji umożliwia automatyczne sekwencyjne wywoływanie poszczególnych metod mutacji poszczególnych zasobów. W tym celu odczytuje dane dotyczące operacji, dopóki nie znajdzie 1 zasobu dla innego typu zasobów, a następnie grupuje wszystkie operacje tego samego typu w jednym żądaniu.
Jeśli na przykład masz 5 operacji kampanii, a następnie 10 operacji grup reklam w powtórzonym polu operations w wywołaniu Mutate, system przeprowadzi 2 całkowite wywołania w backendzie – jedno do CampaignService dla 5 operacji, a następne obok AdGroupService w przypadku 10 operacji.
Jeśli jednak pogrupujesz je inaczej, skuteczność może być znacznie gorzej. Jeśli utworzysz tylko 2 kampanie i 2 grupy reklam, ale ustawisz je tak, aby działania miały kolejność [campaign, ad group, campaign, ad group], zostaną zsumowane 4 wywołania w backendzie. Może to spowolnić działanie interfejsu API i w skrajnych przypadkach nawet spowodować przekroczenie limitu czasu.
Pobieranie zmiennych atrybutów z odpowiedzi
Jeśli response_content_type żądania mutacji zmienisz na MUTABLE_RESOURCE, odpowiedź będzie zawierać wartości wszystkich pól zmodyfikowanych dla każdego obiektu utworzonego lub zaktualizowanego w żądaniu. Użyj tej funkcji, aby uniknąć dodatkowych żądań search lub searchStream po każdym żądaniu mutacji.
Jeśli nie ustawisz response_content_type, interfejs Google Ads API otrzyma domyślną wartość RESOURCE_NAME_ONLY, a odpowiedź będzie zawierać tylko nazwy zasobów każdego utworzonego lub zaktualizowanego zasobu.
Oto przykład pobrania zmodyfikowanego zasobu z wywołania interfejsu 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};