Práticas recomendadas para mutação

Nomes de recursos temporários

GoogleAdsService.Mutate é compatível com nomes de recursos temporários que podem ser referenciados posteriormente na mesma solicitação. Isso permite, por exemplo, criar uma campanha e os grupos de anúncios, anúncios, palavras-chave etc. associados, tudo em uma única solicitação.

Para fazer isso, especifique o novo resource_name do recurso para usar um ID negativo. Por exemplo, se você criar uma campanha e especificar o nome de recurso como customers/<YOUR_CUSTOMER_ID>/campaigns/-1, quando criar o grupo em uma operação posterior, será possível referenciá-lo pelo nome do recurso, e o -1 especificado será substituído pelo ID real da campanha criada automaticamente.

Veja algumas informações importantes ao usar nomes de recurso temporários:

  • Um nome de recurso temporário só pode ser usado depois que for definido em um recurso. No exemplo abaixo, a operação do grupo de anúncios precisaria aparecer após a operação da campanha na lista de operações.
  • Os nomes de recursos temporários não são memorizados entre jobs ou solicitações de mutações. Para fazer referência a um recurso criado em um job ou solicitação de mutação anterior, use o nome do recurso real dele.
  • Para uma única solicitação de job ou mutação, cada nome de recurso temporário precisa usar um número negativo exclusivo, mesmo que sejam de diferentes tipos de recursos. Se um ID temporário for reutilizado em um único job ou solicitação de mutação, um erro será retornado.

Exemplo

Para dar um exemplo mais concreto à situação mencionada acima, suponha que você queira adicionar uma campanha, um grupo de anúncios e um anúncio em uma única solicitação de API. Você criaria uma estrutura para sua solicitação semelhante a esta:

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"
        ...
      }
    }
  },
]

Um novo ID temporário é usado para o grupo de anúncios, já que não podemos reutilizar o -1 usado para a campanha. Também fazemos referência a esse grupo de anúncios ao criar um anúncio do grupo de anúncios. O próprio grupo de anúncios faz referência ao nome do recurso que estabelecemos para a campanha em uma operação anterior na solicitação, enquanto resource_name em ad_group_ad_operation não é necessário, já que nenhuma outra operação está fazendo referência a ele.

Agrupar operações do mesmo tipo

Ao usar GoogleAdsService.Mutate, é importante agrupar operações de acordo com o recurso na matriz de operações repetidas. Esse método de mutação serve basicamente como uma maneira de chamar automaticamente sequencialmente cada método mutável de cada recurso individual. Para isso, ele lê em operações até encontrar um para um tipo diferente de recursos e, em seguida, agrupa todas as operações do mesmo tipo em uma solicitação.

Por exemplo, se você tiver cinco operações de campanha, seguidas de 10 operações de grupo de anúncios no campo operations repetido na chamada Mutate, o sistema vai executar duas chamadas totais no back-end, uma para o CampaignService para cinco operações e outra para o AdGroupService para 10 operações. No entanto, se você as agrupar de forma diferente, o desempenho pode ser muito pior. Se você criar apenas duas campanhas e dois grupos de anúncios, mas as misturar para que as operações sejam ordenadas como [campanha, grupo de anúncios, campanha, grupo de anúncios], isso resultará em quatro chamadas no back-end. Isso resultará em um desempenho de API mais lento e, em casos extremos, pode até atingir o tempo limite.

Recuperar atributos mutáveis da resposta

Se você definir response_content_type da solicitação mutada como MUTABLE_RESOURCE, a resposta conterá os valores de todos os campos mutáveis para cada objeto criado ou atualizado pela solicitação. Use esse recurso para evitar uma solicitação search ou searchStream adicional após cada solicitação de modificação.

Se você não definir response_content_type, a API Google Ads as definirá como RESOURCE_NAME_ONLY por padrão, e a resposta conterá somente o nome do recurso de cada recurso criado ou atualizado.

Este é um exemplo da recuperação de um recurso mutável de uma chamada de 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};