Send a mutate request

  • Combining multiple mutate operations into a single request simplifies the creation of dependent entities like those in a Smart campaign.

  • Using a single mutate request prevents the existence of orphaned entities if an operation fails.

  • When using temporary resource names in a single request, ensure that entities with dependencies are created first.

Now that we've seen how to create mutate operations for the individual entities required to create a new Smart campaign, we can combine them into a single request that creates them all at once.

The benefits of using a single mutate request are:

  • Reduces complexity since these entities are not shared and highly dependent on each other.
  • Prevents orphaned entities from existing if one of the operations fails for any reason.

When using temporary resource names to create entities in a single request like this, ensure that you order the operations such that entities with dependencies are created first.

Java

/**
 * Sends a mutate request with a group of mutate operations.
 *
 * <p>The {@link GoogleAdsServiceClient} allows batching together a list of operations. These are
 * executed sequentially, and later operations my refer to previous operations via temporary IDs.
 * For more detail on this, please refer to
 * https://developers.google.com/google-ads/api/docs/batch-processing/temporary-ids.
 */
private void sendMutateRequest(
    GoogleAdsClient googleAdsClient, long customerId, List<MutateOperation> operations) {
  try (GoogleAdsServiceClient client =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    MutateGoogleAdsResponse outerResponse = client.mutate(String.valueOf(customerId), operations);
    for (MutateOperationResponse innerResponse :
        outerResponse.getMutateOperationResponsesList()) {
      OneofDescriptor oneofDescriptor =
          innerResponse.getDescriptorForType().getOneofs().stream()
              .filter(o -> o.getName().equals("response"))
              .findFirst()
              .get();
      Message createdEntity =
          (Message)
              innerResponse.getField(innerResponse.getOneofFieldDescriptor(oneofDescriptor));
      String resourceName =
          (String)
              createdEntity.getField(
                  createdEntity.getDescriptorForType().findFieldByName("resource_name"));
      System.out.printf(
          "Created a(n) %s with resource name: '%s'.%n",
          createdEntity.getClass().getSimpleName(), resourceName);
    }
  }
}
AddSmartCampaign.java

C#

// The below methods create and return MutateOperations that we later provide to
// the GoogleAdsService.Mutate method in order to create the entities in a single
// request. Since the entities for a Smart campaign are closely tied to one-another
// it's considered a best practice to create them in a single Mutate request; the
// entities will either all complete successfully or fail entirely, leaving no
// orphaned entities. See:
// https://developers.google.com/google-ads/api/docs/mutating/overview
MutateOperation campaignBudgetOperation =
    CreateCampaignBudgetOperation(customerId, suggestedBudgetAmount);
MutateOperation smartCampaignOperation =
    CreateSmartCampaignOperation(customerId);
MutateOperation smartCampaignSettingOperation =
    CreateSmartCampaignSettingOperation(customerId, businessProfileLocation,
        businessName);
IEnumerable<MutateOperation> campaignCriterionOperations =
    CreateCampaignCriterionOperations(customerId, keywordThemeInfos,
        suggestionInfo);
MutateOperation adGroupOperation = CreateAdGroupOperation(customerId);
MutateOperation adGroupAdOperation = CreateAdGroupAdOperation(customerId,
    adSuggestions);

// Send the operations in a single mutate request.
MutateGoogleAdsRequest mutateGoogleAdsRequest = new MutateGoogleAdsRequest
{
    CustomerId = customerId.ToString()
};
// It's important to create these entities in this order because they depend on
// each other, for example the SmartCampaignSetting and ad group depend on the
// campaign, and the ad group ad depends on the ad group.
mutateGoogleAdsRequest.MutateOperations.Add(campaignBudgetOperation);
mutateGoogleAdsRequest.MutateOperations.Add(smartCampaignOperation);
mutateGoogleAdsRequest.MutateOperations.Add(smartCampaignSettingOperation);
mutateGoogleAdsRequest.MutateOperations.Add(campaignCriterionOperations);
mutateGoogleAdsRequest.MutateOperations.Add(adGroupOperation);
mutateGoogleAdsRequest.MutateOperations.Add(adGroupAdOperation);

MutateGoogleAdsResponse response =
    googleAdsServiceClient.Mutate(mutateGoogleAdsRequest);

PrintResponseDetails(response);
AddSmartCampaign.cs

PHP

    // The below methods create and return MutateOperations that we later provide to the
    // GoogleAdsService.Mutate method in order to create the entities in a single request.
    // Since the entities for a Smart campaign are closely tied to one-another it's considered
    // a best practice to create them in a single Mutate request so they all complete
    // successfully or fail entirely, leaving no orphaned entities.
    // See: https://developers.google.com/google-ads/api/docs/mutating/overview.
    $campaignBudgetOperation = self::createCampaignBudgetOperation(
        $customerId,
        $suggestedBudgetAmount
    );
    $smartCampaignOperation = self::createSmartCampaignOperation($customerId);
    $smartCampaignSettingOperation = self::createSmartCampaignSettingOperation(
        $customerId,
        $businessProfileLocationResourceName,
        $businessName
    );
    $campaignCriterionOperations = self::createCampaignCriterionOperations(
        $customerId,
        $keywordThemeInfos,
        $suggestionInfo
    );
    $adGroupOperation = self::createAdGroupOperation($customerId);
    $adGroupAdOperation = self::createAdGroupAdOperation($customerId, $adSuggestions);

    // Issues a single mutate request to add the entities.
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    $response = $googleAdsServiceClient->mutate(MutateGoogleAdsRequest::build(
        $customerId,
        // It's important to create these entities in this order because they depend on
        // each other, for example the SmartCampaignSetting and ad group depend on the
        // campaign, and the ad group ad depends on the ad group.
        array_merge(
            [
                $campaignBudgetOperation,
                $smartCampaignOperation,
                $smartCampaignSettingOperation,
            ],
            $campaignCriterionOperations,
            [
                $adGroupOperation,
                $adGroupAdOperation
            ]
        )
    ));

    self::printResponseDetails($response);
}
AddSmartCampaign.php