Esta página foi traduzida pela API Cloud Translation.

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. Assim, é possível criar uma campanha e os grupos de anúncios, anúncios, palavras-chave etc. em uma única solicitação.

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

Veja alguns pontos a serem considerados ao usar nomes de recursos temporários:

Um nome de recurso temporário só pode ser usado depois de ser definido em um recurso. No exemplo abaixo, a operação do grupo de anúncios teria que aparecer após a operação da campanha na lista de operações.
Os nomes de recursos temporários não são memorizados em jobs ou solicitações de modificação. Para fazer referência a um recurso criado em uma solicitação de job ou mutação anterior, use o nome de recurso real.
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 recurso. Se um ID temporário for reutilizado em uma única solicitação de job ou mutação, um erro será retornado.

Exemplo

Para ver um exemplo mais concreto da 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. É preciso criar uma estrutura para a solicitação parecida com 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 referenciamos 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 no ad_group_ad_operation não é necessário, já que nenhuma outra operação o faz referência.

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 essencial funciona como uma maneira de chamar automaticamente o método de mutação sequencial de cada recurso individual. Para fazer isso, ele lê as 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 por 10 operações de grupo de anúncios no campo operations repetido na sua chamada Mutate, o sistema vai realizar 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 poderá ser muito pior. Se você criar apenas duas campanhas e dois grupos de anúncios, mas os unir para que as operações sejam ordenadas como [campanha, grupo de anúncios, campanha, grupo de anúncios], isso resultará em um total de quatro chamadas no back-end. Isso vai resultar em um desempenho de API mais lento e, em casos extremos, o tempo limite pode ser atingido.

Recuperar atributos mutáveis da resposta

Se você definir o response_content_type da solicitação de modificação 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 o response_content_type, a API Google Ads será definida como RESOURCE_NAME_ONLY por padrão, e a resposta incluirá apenas o nome do recurso de cada recurso criado ou atualizado.

Veja um exemplo de 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());
}AddCampaignBidModifier.java

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;
}AddCampaignBidModifier.cs

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
);AddCampaignBidModifier.php

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}', "
)add_campaign_bid_modifier.py

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}'"
endadd_campaign_bid_modifier.rb

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};add_campaign_bid_modifier.pl

Mutações em massa