बदलाव करने के सबसे सही तरीके

अस्थायी संसाधन के नाम

GoogleAdsService.Mutate अस्थायी संसाधन के नामों का समर्थन करता है, जिन्हें एक ही अनुरोध में बाद में रेफ़र किया जा सकता है. उदाहरण के लिए, इससे एक ही अनुरोध में कैंपेन और उससे जुड़े विज्ञापन ग्रुप, विज्ञापन, कीवर्ड वगैरह बनाए जा सकते हैं.

इसके लिए, नए संसाधन का resource_name तय करके, नेगेटिव आईडी का इस्तेमाल किया जा सकता है. उदाहरण के लिए, मान लीजिए कि आपने एक कैंपेन बनाया है और उसका संसाधन नाम customers/<YOUR_CUSTOMER_ID>/campaigns/-1 तय किया है. बाद में, विज्ञापन ग्रुप बनाते समय, उसे उस संसाधन नाम से रेफ़र किया जा सकता है. साथ ही, आपके तय किए गए -1 की जगह, बनाए गए कैंपेन का असली आईडी अपने-आप आ जाएगा.

अस्थायी संसाधन के नाम इस्तेमाल करते समय, इन बातों का ध्यान रखें:

  • अस्थायी संसाधन के नाम का इस्तेमाल सिर्फ़ तब किया जा सकता है, जब उसे किसी संसाधन में तय किया गया हो. यहां दिए गए उदाहरण में, कार्रवाइयों की सूची में विज्ञापन ग्रुप की कार्रवाई, कैंपेन की कार्रवाई के बाद दिखनी चाहिए.
  • अस्थायी संसाधन के नाम, अलग-अलग कामों या बदलाव के अनुरोधों में याद नहीं रखे जाते. पिछले किसी काम या बदलाव के अनुरोध में बनाए गए संसाधन को रेफ़र करने के लिए, उसके असली संसाधन के नाम का इस्तेमाल करें.
  • एक ही काम या बदलाव के अनुरोध के लिए, हर अस्थायी संसाधन के नाम में एक यूनीक नेगेटिव नंबर इस्तेमाल करना ज़रूरी है. भले ही, वे अलग-अलग तरह के संसाधन हों. अगर एक ही काम या बदलाव के अनुरोध में किसी अस्थायी आईडी को दोबारा इस्तेमाल किया जाता है, तो गड़बड़ी का मैसेज दिखता है.

उदाहरण

मान लीजिए कि आपको एपीआई के एक ही अनुरोध में कोई कैंपेन, विज्ञापन ग्रुप, और विज्ञापन जोड़ना है. इसके लिए, आपको अपने अनुरोध के लिए ऐसा स्ट्रक्चर बनाना होगा जैसा यहां दिखाया गया है:

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

विज्ञापन ग्रुप के लिए, एक नया अस्थायी आईडी इस्तेमाल किया जाता है, क्योंकि कैंपेन के लिए इस्तेमाल किए गए -1 को दोबारा इस्तेमाल नहीं किया जा सकता. विज्ञापन ग्रुप का विज्ञापन बनाते समय भी, हम इस विज्ञापन ग्रुप को रेफ़र करते हैं. अनुरोध में, विज्ञापन ग्रुप खुद उस संसाधन के नाम को रेफ़र करता है जिसे हमने पहले की कार्रवाई में कैंपेन के लिए तय किया था. वहीं, ad_group_ad_operation में resource_name की ज़रूरत नहीं होती, क्योंकि कोई और कार्रवाई इसे रेफ़र नहीं कर रही है.

एक ही तरह की कार्रवाइयों को ग्रुप में शामिल करना

GoogleAdsService.Mutate का इस्तेमाल करते समय, यह ज़रूरी है कि दोहराई गई कार्रवाइयों के कलेक्शन में, कार्रवाइयों को उनके संसाधन के हिसाब से ग्रुप में शामिल किया जाए. बदलाव करने का यह तरीका, असल में हर संसाधन के बदलाव करने के तरीके को क्रम से अपने-आप कॉल करने का काम करता है. इसके लिए, यह कार्रवाइयों को तब तक पढ़ता है, जब तक उसे अलग-अलग तरह के संसाधनों के लिए कोई कार्रवाई नहीं मिल जाती. इसके बाद, यह एक ही तरह की सभी कार्रवाइयों को एक अनुरोध में बैच कर देता है.

उदाहरण के लिए, अगर आपके Mutate कॉल में, दोहराए गए operations फ़ील्ड में पांच कैंपेन की कार्रवाइयां हैं और उसके बाद 10 विज्ञापन ग्रुप की कार्रवाइयां हैं, तो सिस्टम बैकएंड में कुल दो कॉल करेगा. पहला कॉल, पांच कार्रवाइयों के लिए CampaignService को और दूसरा कॉल, 10 कार्रवाइयों के लिए AdGroupService को किया जाएगा. हालांकि, अगर आपने उन्हें अलग-अलग ग्रुप में शामिल किया, तो परफ़ॉर्मेंस काफ़ी खराब हो सकती है. अगर आपने सिर्फ़ दो कैंपेन और दो विज्ञापन ग्रुप बनाए हैं, लेकिन उन्हें इस तरह से जोड़ा है कि कार्रवाइयों का क्रम [कैंपेन, विज्ञापन ग्रुप, कैंपेन, विज्ञापन ग्रुप] हो, तो बैकएंड में कुल चार कॉल किए जाएंगे. इससे एपीआई की परफ़ॉर्मेंस धीमी हो जाएगी. साथ ही, कुछ मामलों में टाइम आउट भी हो सकता है.

GoogleAdsService.Mutate

जवाब से, बदलाव किए जा सकने वाले एट्रिब्यूट पाना

अगर आपने बदलाव के अनुरोध के response_content_type को MUTABLE_RESOURCE, पर सेट किया है, तो जवाब में, अनुरोध से बनाए या अपडेट किए गए हर ऑब्जेक्ट के लिए, बदलाव किए जा सकने वाले सभी फ़ील्ड की वैल्यू शामिल होंगी. इस सुविधा का इस्तेमाल करके, बदलाव के हर अनुरोध के बाद, search या searchStream का कोई और अनुरोध करने से बचें.

अगर आपने response_content_type सेट नहीं किया है, तो Google Ads API डिफ़ॉल्ट रूप से RESOURCE_NAME_ONLY पर सेट हो जाता है. साथ ही, जवाब में सिर्फ़ बनाए या अपडेट किए गए हर संसाधन का संसाधन नाम शामिल होता है.

यहां एपीआई कॉल से, बदलाव किए जा सकने वाले संसाधन को पाने का एक उदाहरण दिया गया है:

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);
  }
}
      

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.V24.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);
}

      

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];
}
      

Python

This example is not yet available in Python; you can take a look at the other languages.
    

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
      

Perl

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

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

  push @$operations,
    Google::Ads::GoogleAds::V24::Services::ExperimentArmService::ExperimentArmOperation
    ->new({
      create => Google::Ads::GoogleAds::V24::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];
}
      

curl