Bonnes pratiques de mutation

Noms de ressources temporaires

GoogleAdsService.Mutate accepte les noms de ressources temporaires qui peuvent être référencés ultérieurement dans la même requête. Cela vous permet, par exemple, de créer une campagne et ses groupes d'annonces, annonces, mots clés, etc. associés dans une seule demande.

Pour ce faire, spécifiez le paramètre resource_name de la nouvelle ressource afin d'utiliser un ID à exclure. Par exemple, si vous créez une campagne et spécifiez customers/<YOUR_CUSTOMER_ID>/campaigns/-1 comme nom de ressource, lorsque vous créerez le groupe d'annonces lors d'une opération ultérieure, vous pourrez le référencer avec ce nom de ressource. Le -1 que vous avez spécifié sera automatiquement remplacé par l'ID réel de la campagne créée.

Voici quelques points à garder à l'esprit lorsque vous utilisez des noms de ressources temporaires:

• Un nom de ressource temporaire ne peut être utilisé qu'après avoir été défini dans une ressource. Dans l'exemple ci-dessous, l'opération de groupe d'annonces doit apparaître après l'opération de campagne dans la liste des opérations.
• Les noms de ressources temporaires ne sont pas mémorisés dans les tâches ou les requêtes de mutation. Pour référencer une ressource créée dans une tâche ou une requête de mutation précédente, utilisez son nom de ressource réel.
• Pour une seule tâche ou requête de mutation, chaque nom de ressource temporaire doit utiliser un nombre négatif unique, même s'ils proviennent de types de ressources différents. Si un ID temporaire est réutilisé dans une seule tâche ou requête de mutation, une erreur est renvoyée.

Exemple

Pour donner un exemple plus concret de la situation mentionnée ci-dessus, supposons que vous souhaitiez ajouter une campagne, un groupe d'annonces et une annonce dans une seule requête API. Vous devez créer une structure pour votre requête semblable à celle-ci:

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

Notez qu'un nouvel ID temporaire est utilisé pour le groupe d'annonces, car nous ne pouvons pas réutiliser l'élément -1 que nous avons utilisé pour la campagne. Nous faisons également référence à ce groupe d'annonces lors de la création de l'annonce correspondante. Le groupe d'annonces lui-même fait référence au nom de ressource que nous avons établi pour la campagne lors d'une précédente opération de la demande. En revanche, resource_name dans ad_group_ad_operation n'est pas nécessaire, car aucune autre opération ne le référence.

Regrouper des opérations de même type

Lorsque vous utilisez GoogleAdsService.Mutate, il est important de regrouper les opérations en fonction de leur ressource dans le tableau d'opérations répétées. Cette méthode mutate permet essentiellement d'appeler automatiquement et de manière séquentielle la méthode mutate de chaque ressource individuelle. Pour ce faire, il lit les opérations jusqu'à ce qu'il en trouve une pour un autre type de ressources, puis regroupe toutes les opérations du même type dans une requête.

Par exemple, si vous avez 5 opérations au niveau de la campagne, suivies de 10 opérations de groupe d'annonces dans le champ répété operations de votre appel Mutate, le système effectuera alors deux appels au total dans le backend : un sur CampaignService pour 5 opérations et l'autre à côté de AdGroupService pour 10 opérations. Toutefois, si vous les regroupez différemment, les performances risquent d'être beaucoup moins bonnes. Si vous créez seulement deux campagnes et deux groupes d'annonces, mais que vous les fiez pour classer les opérations selon l'ordre [campagne, groupe d'annonces, campagne, groupe d'annonces], quatre appels au total seront alors effectués dans le backend. Cela ralentit les performances de l'API et peut même entraîner des délais avant expiration dans des cas extrêmes.

Important :Regroupez toutes les opérations sur le même type de ressource dans vos appels GoogleAdsService.Mutate.

Récupérer les attributs modifiables à partir de la réponse

Si vous définissez le paramètre response_content_type de votre demande de mutation sur MUTABLE_RESOURCE, la réponse contiendra les valeurs de tous les champs modifiables pour chaque objet créé ou mis à jour par la requête. Utilisez cette fonctionnalité pour éviter d'envoyer une requête search ou searchStream supplémentaire après chaque demande de mutation.

Remarque :Les informations supplémentaires renvoyées lorsque vous demandez le type de réponse MUTABLE_RESOURCE augmentent la taille de la charge utile de réponse. N'utilisez cette fonctionnalité que lorsque votre application a besoin de renvoyer des informations supplémentaires.

Si vous ne définissez pas response_content_type, l'API Google Ads utilise par défaut RESOURCE_NAME_ONLY et la réponse ne contient que le nom de chaque ressource créée ou mise à jour.

Voici un exemple de récupération d'une ressource modifiable à partir d'un appel d'API:

Java

private String createExperimentArms(
    GoogleAdsClient googleAdsClient, long customerId, long campaignId, String experiment) {
  List<ExperimentArmOperation> operations = new ArrayList<>();
  operations.add(
      ExperimentArmOperation.newBuilder()
          .setCreate(
              // The "control" arm references an already-existing campaign.
              ExperimentArm.newBuilder()
                  .setControl(true)
                  .addCampaigns(ResourceNames.campaign(customerId, campaignId))
                  .setExperiment(experiment)
                  .setName("control arm")
                  .setTrafficSplit(40)
                  .build())
          .build());
  operations.add(
      ExperimentArmOperation.newBuilder()
          .setCreate(
              // The non-"control" arm, also called a "treatment" arm, will automatically
              // generate draft campaigns that you can modify before starting the experiment.
              ExperimentArm.newBuilder()
                  .setControl(false)
                  .setExperiment(experiment)
                  .setName("experiment arm")
                  .setTrafficSplit(60)
                  .build())
          .build());

  try (ExperimentArmServiceClient experimentArmServiceClient =
      googleAdsClient.getLatestVersion().createExperimentArmServiceClient()) {
    // Constructs the mutate request.
    MutateExperimentArmsRequest mutateRequest = MutateExperimentArmsRequest.newBuilder()
        .setCustomerId(Long.toString(customerId))
        .addAllOperations(operations)
        // We want to fetch the draft campaign IDs from the treatment arm, so the easiest way to do
        // that is to have the response return the newly created entities.
        .setResponseContentType(ResponseContentType.MUTABLE_RESOURCE)
        .build();

    // Sends the mutate request.
    MutateExperimentArmsResponse response =
        experimentArmServiceClient.mutateExperimentArms(mutateRequest);

    // Results always return in the order that you specify them in the request. Since we created
    // the treatment arm last, it will be the last result.  If you don't remember which arm is the
    // treatment arm, you can always filter the query in the next section with
    // `experiment_arm.control = false`.
    MutateExperimentArmResult controlArmResult = response.getResults(0);
    MutateExperimentArmResult treatmentArmResult = response.getResults(
        response.getResultsCount() - 1);

    System.out.printf("Created control arm with resource name '%s'%n",
        controlArmResult.getResourceName());
    System.out.printf("Created treatment arm with resource name '%s'%n",
        treatmentArmResult.getResourceName());

    return treatmentArmResult.getExperimentArm().getInDesignCampaigns(0);
  }
}
CreateExperiment.java
      

C#

/// <summary>
/// Creates the experiment arms.
/// </summary>
/// <param name="client">The Google Ads client.</param>
/// <param name="customerId">The customer ID for which the call is made.</param>
/// <param name="baseCampaignId">ID of the campaign for which the control arm is
/// created.</param>
/// <param name="experimentResourceName">Resource name of the experiment.</param>
/// <returns>The control and treatment arms.</returns>
private static (MutateExperimentArmResult, MutateExperimentArmResult)
    CreateExperimentArms(GoogleAdsClient client, long customerId, long baseCampaignId,
        string experimentResourceName)
{
    // Get the ExperimentArmService.
    ExperimentArmServiceClient experimentService = client.GetService(
        Services.V17.ExperimentArmService);

    // Create the control arm. The control arm references an already-existing campaign.
    ExperimentArmOperation controlArmOperation = new ExperimentArmOperation()
    {
        Create = new ExperimentArm()
        {
            Control = true,
            Campaigns = {
                ResourceNames.Campaign(customerId, baseCampaignId)
            },
            Experiment = experimentResourceName,
            Name = "Control Arm",
            TrafficSplit = 40
        }
    };

    // Create the non-control arm. The non-"control" arm, also called a "treatment" arm,
    // will automatically generate draft campaigns that you can modify before starting the
    // experiment.
    ExperimentArmOperation treatmentArmOperation = new ExperimentArmOperation()
    {
        Create = new ExperimentArm()
        {
            Control = false,
            Experiment = experimentResourceName,
            Name = "Experiment Arm",
            TrafficSplit = 60
        }
    };

    // We want to fetch the draft campaign IDs from the treatment arm, so the
    // easiest way to do that is to have the response return the newly created
    // entities.
    MutateExperimentArmsRequest request = new MutateExperimentArmsRequest
    {
        CustomerId = customerId.ToString(),
        Operations = { controlArmOperation, treatmentArmOperation },
        ResponseContentType = ResponseContentType.MutableResource
    };


    MutateExperimentArmsResponse response = experimentService.MutateExperimentArms(
        request
    );

    // Results always return in the order that you specify them in the request.
    // Since we created the treatment arm last, it will be the last result.
    MutateExperimentArmResult controlArm = response.Results.First();
    MutateExperimentArmResult treatmentArm = response.Results.Last();

    Console.WriteLine($"Created control arm with resource name " +
        $"'{controlArm.ResourceName}.");
    Console.WriteLine($"Created treatment arm with resource name" +
      $" '{treatmentArm.ResourceName}'.");
    return (controlArm, treatmentArm);
}
CreateExperiment.cs
      

PHP

private static function createExperimentArms(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $campaignId,
    string $experimentResourceName
): string {
    $operations = [];
    $experimentArm1 = new ExperimentArm([
        // The "control" arm references an already-existing campaign.
        'control' => true,
        'campaigns' => [ResourceNames::forCampaign($customerId, $campaignId)],
        'experiment' => $experimentResourceName,
        'name' => 'control arm',
        'traffic_split' => 40
    ]);
    $operations[] = new ExperimentArmOperation(['create' => $experimentArm1]);
    $experimentArm2 = new ExperimentArm([
        // The non-"control" arm, also called a "treatment" arm, will automatically
        // generate draft campaigns that you can modify before starting the
        // experiment.
        'control' => false,
        'experiment' => $experimentResourceName,
        'name' => 'experiment arm',
        'traffic_split' => 60
    ]);
    $operations[] = new ExperimentArmOperation(['create' => $experimentArm2]);

    // Issues a request to create the experiment arms.
    $experimentArmServiceClient = $googleAdsClient->getExperimentArmServiceClient();
    $response = $experimentArmServiceClient->mutateExperimentArms(
        MutateExperimentArmsRequest::build($customerId, $operations)
            // We want to fetch the draft campaign IDs from the treatment arm, so the easiest
            // way to do that is to have the response return the newly created entities.
            ->setResponseContentType(ResponseContentType::MUTABLE_RESOURCE)
    );
    // Results always return in the order that you specify them in the request.
    // Since we created the treatment arm last, it will be the last result.
    $controlArmResourceName = $response->getResults()[0]->getResourceName();
    $treatmentArm = $response->getResults()[count($operations) - 1];
    print "Created control arm with resource name '$controlArmResourceName'" . PHP_EOL;
    print "Created treatment arm with resource name '{$treatmentArm->getResourceName()}'"
        . PHP_EOL;

    return $treatmentArm->getExperimentArm()->getInDesignCampaigns()[0];
}
CreateExperiment.php
      

Python

def create_experiment_arms(client, customer_id, base_campaign_id, experiment):
    """Creates a control and treatment experiment arms.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
        base_campaign_id: the campaign ID to associate with the control arm of
          the experiment.
        experiment: the resource name for an experiment.

    Returns:
        the resource name for the new treatment experiment arm.
    """
    operations = []

    campaign_service = client.get_service("CampaignService")

    # The "control" arm references an already-existing campaign.
    operation_1 = client.get_type("ExperimentArmOperation")
    exa_1 = operation_1.create
    exa_1.control = True
    exa_1.campaigns.append(
        campaign_service.campaign_path(customer_id, base_campaign_id)
    )
    exa_1.experiment = experiment
    exa_1.name = "control arm"
    exa_1.traffic_split = 40
    operations.append(operation_1)

    # The non-"control" arm, also called a "treatment" arm, will automatically
    # generate draft campaigns that you can modify before starting the
    # experiment.
    operation_2 = client.get_type("ExperimentArmOperation")
    exa_2 = operation_2.create
    exa_2.control = False
    exa_2.experiment = experiment
    exa_2.name = "experiment arm"
    exa_2.traffic_split = 60
    operations.append(operation_2)

    experiment_arm_service = client.get_service("ExperimentArmService")
    request = client.get_type("MutateExperimentArmsRequest")
    request.customer_id = customer_id
    request.operations = operations
    # We want to fetch the draft campaign IDs from the treatment arm, so the
    # easiest way to do that is to have the response return the newly created
    # entities.
    request.response_content_type = (
        client.enums.ResponseContentTypeEnum.MUTABLE_RESOURCE
    )
    response = experiment_arm_service.mutate_experiment_arms(request=request)

    # Results always return in the order that you specify them in the request.
    # Since we created the treatment arm second, it will be the second result.
    control_arm_result = response.results[0]
    treatment_arm_result = response.results[1]

    print(
        f"Created control arm with resource name {control_arm_result.resource_name}"
    )
    print(
        f"Created treatment arm with resource name {treatment_arm_result.resource_name}"
    )

    return treatment_arm_result.experiment_arm.in_design_campaigns[0]
create_experiment.py
      

Ruby

def create_experiment_arms(client, customer_id, base_campaign_id, experiment)
  operations = []
  operations << client.operation.create_resource.experiment_arm do |ea|
    # The "control" arm references an already-existing campaign.
    ea.control = true
    ea.campaigns << client.path.campaign(customer_id, base_campaign_id)
    ea.experiment = experiment
    ea.name = 'control arm'
    ea.traffic_split = 40
  end
  operations << client.operation.create_resource.experiment_arm do |ea|
    # The non-"control" arm, also called a "treatment" arm, will automatically
    # generate draft campaigns that you can modify before starting the
    # experiment.
    ea.control = false
    ea.experiment = experiment
    ea.name = 'experiment arm'
    ea.traffic_split = 60
  end

  response = client.service.experiment_arm.mutate_experiment_arms(
    customer_id: customer_id,
    operations: operations,
    # We want to fetch the draft campaign IDs from the treatment arm, so the
    # easiest way to do that is to have the response return the newly created
    # entities.
    response_content_type: :MUTABLE_RESOURCE,
  )

  # Results always return in the order that you specify them in the request.
  # Since we created the treatment arm last, it will be the last result.
  control_arm_result = response.results.first
  treatment_arm_result = response.results.last

  puts "Created control arm with resource name #{control_arm_result.resource_name}."
  puts "Created treatment arm with resource name #{treatment_arm_result.resource_name}."

  treatment_arm_result.experiment_arm.in_design_campaigns.first
end
create_experiment.rb
      

Perl

sub create_experiment_arms {
  my ($api_client, $customer_id, $base_campaign_id, $experiment) = @_;

  my $operations = [];
  push @$operations,
    Google::Ads::GoogleAds::V17::Services::ExperimentArmService::ExperimentArmOperation
    ->new({
      create => Google::Ads::GoogleAds::V17::Resources::ExperimentArm->new({
          # The "control" arm references an already-existing campaign.
          control   => "true",
          campaigns => [
            Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
              $customer_id, $base_campaign_id
            )
          ],
          experiment   => $experiment,
          name         => "control arm",
          trafficSplit => 40
        })});

  push @$operations,
    Google::Ads::GoogleAds::V17::Services::ExperimentArmService::ExperimentArmOperation
    ->new({
      create => Google::Ads::GoogleAds::V17::Resources::ExperimentArm->new({
          # The non-"control" arm, also called a "treatment" arm, will automatically
          # generate draft campaigns that you can modify before starting the
          # experiment.
          control      => "false",
          experiment   => $experiment,
          name         => "experiment arm",
          trafficSplit => 60
        })});

  my $response = $api_client->ExperimentArmService()->mutate({
    customerId => $customer_id,
    operations => $operations,
    # We want to fetch the draft campaign IDs from the treatment arm, so the
    # easiest way to do that is to have the response return the newly created
    # entities.
    responseContentType => MUTABLE_RESOURCE
  });

  # Results always return in the order that you specify them in the request.
  # Since we created the treatment arm last, it will be the last result.
  my $control_arm_result   = $response->{results}[0];
  my $treatment_arm_result = $response->{results}[1];

  printf "Created control arm with resource name '%s'.\n",
    $control_arm_result->{resourceName};
  printf "Created treatment arm with resource name '%s'.\n",
    $treatment_arm_result->{resourceName};
  return $treatment_arm_result->{experimentArm}{inDesignCampaigns}[0];
}
create_experiment.pl