جهش بهترین شیوه ها

نام منابع موقت

GoogleAdsService.Mutate از نام‌های منابع موقتی پشتیبانی می‌کند که بعداً در همان درخواست می‌توان به آنها اشاره کرد. این به شما امکان می دهد، برای مثال، یک کمپین و گروه های تبلیغاتی مرتبط با آن، تبلیغات، کلمات کلیدی و غیره را در یک درخواست ایجاد کنید.

می توانید این کار را با تعیین resource_name منبع جدید برای استفاده از شناسه منفی انجام دهید. برای مثال، اگر یک کمپین ایجاد می‌کنید و نام منبع آن را به‌عنوان customers/<YOUR_CUSTOMER_ID>/campaigns/-1 مشخص می‌کنید، پس از ایجاد گروه تبلیغاتی در عملیات بعدی، می‌توانید آن را با نام منبع و -1 ارجاع دهید. به طور خودکار با شناسه واقعی کمپین ایجاد شده جایگزین خواهد شد.

در اینجا مواردی وجود دارد که هنگام استفاده از نام منابع موقت باید به خاطر داشته باشید:

• نام منبع موقت فقط پس از تعریف در یک منبع قابل استفاده است. در مثال زیر، عملیات گروه تبلیغات باید بعد از عملیات کمپین در لیست عملیات ظاهر شود.
• نام منابع موقت در بین مشاغل یا درخواست های تغییر یافته به خاطر نمی ماند. برای ارجاع به یک منبع ایجاد شده در کار قبلی یا تغییر درخواست، از نام منبع واقعی آن استفاده کنید.
• برای یک کار یا درخواست جهش، هر نام منبع موقت باید از یک عدد منفی منحصر به فرد استفاده کند، حتی اگر از انواع منابع مختلف باشد. اگر یک شناسه موقت در یک کار واحد یا درخواست جهش مجدد استفاده شود، یک خطا برگردانده می شود.

مثال

برای ارائه مثال ملموس تر به وضعیت ذکر شده در بالا، فرض کنید می خواهید یک کمپین، یک گروه تبلیغاتی و یک تبلیغ را در یک درخواست API اضافه کنید. شما می توانید یک ساختار مشابه با موارد زیر برای درخواست خود ایجاد کنید:

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 که برای کمپین استفاده کرده‌ایم دوباره استفاده کنیم، و همچنین هنگام ایجاد یک تبلیغ گروه تبلیغاتی به این گروه تبلیغاتی ارجاع می‌دهیم. خود گروه آگهی به نام منبعی که ما برای کمپین در عملیات قبلی ایجاد کردیم در درخواست ارجاع می دهد، در حالی که resource_name در ad_group_ad_operation ضروری نیست زیرا هیچ عملیات دیگری به آن ارجاع نمی دهد.

گروه عملیات همان نوع

هنگام استفاده از GoogleAdsService.Mutate ، مهم است که عملیات را بر اساس منبع آنها در آرایه عملیات مکرر گروه بندی کنید. این روش جهش اساساً به عنوان راهی برای فراخوانی خودکار متوالی روش جهش هر منبع فردی عمل می کند. برای انجام این کار، آن را در عملیات می خواند تا زمانی که منبعی را برای نوع متفاوتی از منابع پیدا کند، سپس همه عملیات های یک نوع را با هم در یک درخواست دسته بندی می کند.

به عنوان مثال، اگر 5 عملیات کمپین داشته باشید، به دنبال آن 10 عملیات گروه تبلیغاتی در قسمت operations مکرر در تماس Mutate شما انجام می شود، سیستم دو تماس کل را در backend انجام می دهد، یکی به CampaignService برای 5 عملیات، و بعدی AdGroupService برای 10 عملیات. با این حال، اگر بخواهید آنها را متفاوت گروه بندی کنید، عملکرد می تواند بسیار بدتر باشد. اگر فقط 2 کمپین و 2 گروه تبلیغاتی ایجاد کنید، اما آنها را طوری ببافید که عملیات به صورت [کمپین، گروه تبلیغات، کمپین، گروه تبلیغات] مرتب شوند، در مجموع چهار تماس در پشتیبان ایجاد می شود. این باعث کندی عملکرد API می شود و در موارد شدید حتی می تواند منجر به وقفه شود.

نکته کلیدی: همه عملیات مربوط به یک نوع منبع را در GoogleAdsService.Mutate خود گروه بندی کنید. تماس ها را تغییر دهید.

ویژگی های قابل تغییر را از پاسخ بازیابی کنید

اگر response_content_type درخواست جهش خود را روی MUTABLE_RESOURCE تنظیم کنید، پاسخ حاوی مقادیر تمام فیلدهای قابل تغییر برای هر شیء ایجاد شده یا به روز شده توسط درخواست خواهد بود. از این ویژگی برای جلوگیری از search اضافی یا درخواست searchStream بعد از هر درخواست جهش استفاده کنید.

توجه: اطلاعات اضافی که هنگام درخواست نوع پاسخ MUTABLE_RESOURCE برگردانده می شود، اندازه بار پاسخ را افزایش می دهد. فقط زمانی از این ویژگی استفاده کنید که برنامه شما نیاز به بازگرداندن اطلاعات اضافی داشته باشد.

اگر response_content_type را تنظیم نکنید، API Google Ads به طور پیش‌فرض روی RESOURCE_NAME_ONLY تنظیم می‌شود و پاسخ فقط حاوی نام منبع هر منبع ایجاد شده یا به‌روزرسانی شده است.

در اینجا نمونه ای از بازیابی یک منبع قابل تغییر از یک تماس API آورده شده است:

جاوا

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
      

سی شارپ

/// <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
      

پایتون

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
      

روبی

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
      

پرل

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