Zmień sprawdzone metody

Tymczasowe nazwy zasobów

GoogleAdsService.Mutate obsługuje tymczasowe nazwy zasobów, do których można później wrócić 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.

W tym celu możesz określić nowy zasób resource_name, aby użyć ujemnego identyfikatora. Jeśli na przykład utworzysz kampanię i określisz jej nazwę zasobu jako customers/<YOUR_CUSTOMER_ID>/campaigns/-1, podczas tworzenia grupy reklam w późniejszym działaniu możesz utworzyć odwołanie do 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 w zasobie. W poniższym przykładzie operacja grupy reklam pojawi się po działaniu kampanii na liście operacji.
  • Tymczasowe nazwy zasobów nie są zapamiętywane w zadaniach ani mutacjach. Aby odwołać się do zasobu utworzonego w poprzednim żądaniu lub mutacji, użyj jego rzeczywistej nazwy.
  • W przypadku pojedynczego zadania lub żądania mutacji każda tymczasowa nazwa zasobu musi mieć unikalną liczbę ujemną, nawet jeśli pochodzą z różnych typów zasobów. Jeśli tymczasowy identyfikator zostanie użyty ponownie w jednym 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 pojedynczym żądaniu interfejsu API. W tym przypadku utworzysz strukturę podobnego do tego:

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 grupie reklam został użyty nowy identyfikator tymczasowy, ponieważ nie możemy użyć ponownie -1 w kampanii. Odwołamy się też do tej grupy reklam podczas tworzenia reklamy. Sama grupa reklam odwołuje się do nazwy zasobu określonej dla kampanii we wcześniejszej operacji w żądaniu, natomiast właściwość resource_name w polu ad_group_ad_operation nie jest wymagana, ponieważ nie odwołuje się do niej żadna inna operacja.

Operacje operacyjne tego samego typu

W przypadku GoogleAdsService.Mutate ważne jest, aby grupować operacje według zasobu w tablicy powtórzonych operacji. Ta metoda mutacji zasadniczo jest metodą sekwencyjnego wywoływania poszczególnych zasobów w ramach mutacji. W tym celu odczytuje operacje, dopóki nie znajdzie 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 związanych z kampanią, a następnie 10 operacji grup reklam w powtórzonym polu operations w wywołaniu Mutate, system wywoła 2 całkowite wywołania w backendzie – jedno do CampaignService w przypadku 5 operacji, a kolejne – AdGroupService w przypadku 10 operacji. Jeśli jednak pogrupujesz je w inny sposób, skuteczność może się pogorszyć. Jeśli utworzysz tylko 2 kampanie i 2 grupy reklam, ale połączysz je w taki sposób, że operacje będą uporządkowane jako [kampania, grupa reklam, kampania, grupa reklam], uzyskasz łącznie 4 wywołania w backendzie. Zmniejszy to wydajność interfejsu API, a w skrajnych przypadkach może nawet spowodować przekroczenie czasu oczekiwania.

Pobieranie zmiennych zmiennych z odpowiedzi

Jeśli ustawisz response_content_type żądania mutacji na MUTABLE_RESOURCE, odpowiedź będzie zawierać wartości wszystkich pól zmiennych każdego obiektu utworzonego lub zaktualizowanego przez żądanie. Za pomocą tej funkcji możesz uniknąć dodatkowych żądań search lub searchStream po każdym mutacji.

Jeśli nie ustawisz response_content_type, interfejs Google Ads API otrzyma domyślnie wartość RESOURCE_NAME_ONLY, a w odpowiedzi będzie zawierać tylko nazwę zasobu każdego utworzonego lub zaktualizowanego zasobu.

Oto przykład pobieranego 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};