Değiştirme ile ilgili en iyi uygulamalar

Performansı optimize etmek, işlemler arasındaki bağımlılıkları yönetmek ve Google Ads API'de kaynakları değiştirirken yanıtları işlemek için aşağıdaki en iyi uygulamalardan yararlanın.

Geçici kaynak adları

Hem GoogleAdsService.Mutate hem de BatchJobService, sonraki işlemlerde referans verilebilecek geçici kaynak adlarını destekler. Bu sayede, tek bir değişiklik isteğinde veya toplu işte bir kampanya ve ilişkili reklam grupları, reklamlar ve anahtar kelimeler oluşturabilirsiniz.

Aynı değişiklik isteği veya toplu iş içinde yeni oluşturulan bir kaynağa referans vermek için yeni kaynağın resource_name alanında negatif bir tam sayı kimliği (ör. -1 veya -2, 0 hariç) belirtin. Örneğin, toplu istekte kampanya oluştururken kaynak adını customers/CUSTOMER_ID/campaigns/-1 olarak ayarlayın. Aynı istekteki sonraki bir işlemde reklam grubu oluştururken üst kampanya olarak customers/CUSTOMER_ID/campaigns/-1 öğesini referans alın. API, oluşturma sırasında oluşturulan gerçek kampanya kimliğiyle -1 değerini otomatik olarak değiştirir.

Kullanım kısıtlamaları

Geçici kaynak adlarını kullanırken aşağıdaki kuralları göz önünde bulundurun:

• Sıra önemlidir: Geçici kaynak adını yalnızca tanımladıktan sonra referans olarak kullanabilirsiniz. Bir işlemler listesinde, bağımlı işlem (ör. reklam grubu oluşturma), üst kaynağını oluşturan işlemden (ör. kampanya oluşturma) sonra görünmelidir.
• Tek istek veya toplu iş kapsamı: Geçici kaynak adları ayrı işlerde veya değiştirme isteklerinde kalıcı olmaz. Önceki bir işte veya değişiklik isteğinde oluşturulan bir kaynağa referans vermek için sistem tarafından oluşturulan gerçek kaynak adını kullanın.
• Global benzersizlik: Tek bir iş veya değişiklik isteğinde, her geçici kaynak adı tüm kaynak türlerinde benzersiz bir negatif tam sayı kullanmalıdır. Örneğin, aynı istekte hem bir kampanyaya hem de bir reklam grubuna -1 atayamazsınız. Aynı istek veya toplu iş içinde geçici bir kimliğin yeniden kullanılması NewResourceCreationError.DUPLICATE_TEMP_IDS hatası döndürür.

Örnek yük

Tek bir API isteğine veya toplu işe kampanya, reklam grubu ve reklam eklemek istediğinizi varsayalım. Aşağıdaki REST JSON örneğinde gösterildiği gibi (kısa olması için diğer gerekli kaynak alanları çıkarılmıştır) mutateOperations dizisini bir GoogleAdsService.Mutate veya BatchJobService.AddBatchJobOperations istek yükünde yapılandırabilirsiniz:

{
  "mutateOperations": [
    {
      "campaignOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/adGroups/-2",
          "campaign": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupAdOperation": {
        "create": {
          "adGroup": "customers/CUSTOMER_ID/adGroups/-2"
        }
      }
    }
  ]
}

Bu örnekte aşağıdaki önemli ayrıntılar gösterilmektedir:

• Reklam grubu, -1 kampanyaya zaten atandığı için yeni bir geçici ID (-2) kullanıyor.
• Reklam grubu, kendisini önceki işlemde oluşturulan kampanyaya bağlamak için customers/CUSTOMER_ID/campaigns/-1 öğesini referans alıyor.
• İstekle ilgili sonraki işlemler yeni reklama referans vermediğinden adGroupAdOperation, customers/CUSTOMER_ID/adGroups/-2 öğesine referans veriyor ve resourceName öğesini atlıyor.

Aynı türdeki işlemleri gruplandırma

GoogleAdsService.Mutate kullanılırken üst öğe ve alt öğe bağımlılıklarına uyarak tekrarlanan mutate_operations dizisinde kaynak türüne göre işlemleri birlikte gruplandırın. Bu yöntem, farklı bir kaynak türüyle karşılaşana kadar işlemleri sırayla okur ve ardından aynı türdeki tüm bitişik işlemleri tek bir arka uç hizmeti isteğinde toplar.

Örneğin, tekrarlanan mutate_operations alanına 5 kampanya işlemi ve ardından 10 reklam grubu işlemi eklerseniz sistem iki arka uç çağrısı gerçekleştirir: 5 kampanya işlemi için CampaignService'ye bir çağrı ve 10 reklam grubu işlemi için AdGroupService'ye ikinci bir çağrı.

Buna karşılık, işlemleri [campaign, ad group, campaign, ad group] şeklinde sıralayarak araya yerleştirmek dört ayrı arka uç çağrısıyla sonuçlanır. Araya eklenmiş çağrılar API performansını düşürür ve büyük gruplarda istek zaman aşımlarına neden olabilir.

Önemli Nokta: GoogleAdsService.Mutate çağrılarınızda aynı kaynak türü üzerindeki tüm işlemleri birlikte gruplandırın. Bu sırada, üst kaynakların (ör. geçici kimliklere sahip kampanyalar) bağımlı alt kaynaklardan (ör. reklam grupları) önce geldiğinden emin olun.

Kısmi hataları ve toplu işlem sınırlarını işleme

Varsayılan olarak, tek bir işlem başarısız olursa GoogleAdsService.Mutate tüm isteği geri alır. Aynı isteğin diğer işlemleri başarısız olsa bile geçerli işlemlerin işlenmesi için istekte partial_failure değerini true olarak ayarlayın ve yanıttaki partial_failure_error değerini inceleyin. partial_failure, true olduğunda, geçici bir kimlik tanımlayan bir üst işlem (ör. customers/CUSTOMER_ID/campaigns/-1) doğrulaması başarısız olursa aynı istekte bu geçici kimliğe referans veren tüm bağımlı alt işlemler de NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS ile başarısız olur. Daha fazla bilgi için kısmi hata kılavuzuna bakın.

Ayrıca istek boyutu, alt gruplama ve sıklık sınırlarını da göz önünde bulundurun:

• İstek ve parça boyutu sınırları: Tek bir GoogleAdsService.Mutate isteği 10.000 değiştirme işlemi (veya istekteki tüm işlemler AdGroupCriterionOperation ise 20.000) sınırı uygular (aşılırsa RequestError.TOO_MANY_MUTATE_OPERATIONS döndürülür) ve en fazla 100 işlem işlemi (RequestError.TOO_MANY_ACTION_OPERATIONS) içerir. BatchJobService.AddBatchJobOperations, çağrı başına en fazla 10.000 işlem, tek bir MutateOperation başına 10.484.504 bayt ve AddBatchJobOperationsRequest başına 41.937.920 bayt sınırı uygular (herhangi bir sınır aşılırsa BatchJobError.REQUEST_TOO_LARGE döndürülür ve toplu iş başına toplamda en fazla 1.000.000 işlem yapılabilir). Aynı kampanyayı veya hesabı hedefleyen eşzamanlı değişiklikler DatabaseError.CONCURRENT_MODIFICATION hatalarına neden olabilir.
• BatchJobService Atomik alt gruplandırma: Toplu işler kısmi hata semantiği altında yürütülse de (varsayılan olarak dahili alt toplu iş başına 1.000 işlem), BatchJobService aynı üst kimliğe sahip belirli bitişik bağımlı işlemleri otomatik olarak atomik alt toplu işler halinde gruplandırır:
  • Aynı AssetGroupOperation (create) kimliği için bitişik AssetGroupAssetOperation (create) işlemlerini içeren bir AssetGroup (toplamda en fazla 1.000 işlem, BatchJobError.ASSET_GROUP_AND_ASSET_GROUP_ASSET_TRANSACTION_FAILURE ile atomik olarak başarısız olur; her AssetGroupOperation update veya remove bağımsız bir tek işlemli alt grupta yürütülür).
  • Aynı Campaign kimliği için bitişik CampaignAssetOperation (create) işlemleriyle birlikte bir Maksimum Performans CampaignOperation (create, Marka Kuralları etkinleştirildiğinde geçerlidir. brand_guidelines_enabled,false olarak ayarlanmadığı veya hotel_property_asset_set ayarlanmadığı sürece varsayılan değerdir) (toplamda 1.000'e kadar işlem, BatchJobError.CAMPAIGN_AND_CAMPAIGN_ASSET_TRANSACTION_FAILURE ile atomik olarak başarısız olur).
  • Aynı üst öğe (AssetGroup veya AdGroup) için sıralı AssetGroupListingGroupFilterOperation (max 10,000, BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE ile atomik olarak başarısız oluyor) veya AdGroupCriterionOperation (listing_group, max 20,000, CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION ile atomik olarak başarısız oluyor) işlemleri.

Yanıtla birlikte değiştirilebilir özellikleri alma

Değişiklik isteğinizin response_content_type değerini MUTABLE_RESOURCE olarak ayarlarsanız yanıt, istek tarafından oluşturulan veya güncellenen (kaldırılmayan) her desteklenen nesne için resource_name ve değiştirilebilir alanlarıyla doldurulmuş kaynak nesnesini (döndürülen kaynakta sistem tarafından doldurulmuş temel alanlar da dahil, örneğin ExperimentArm.in_design_campaigns) içerir. remove işlemleri veya MUTABLE_RESOURCE döndürmeyi desteklemeyen kaynak türleri için yanıt her zaman yalnızca resource_name döndürür. Her mutasyon çağrısından sonra ek bir Search veya SearchStream isteği göndermemek için bu özelliği kullanın.

Not: MUTABLE_RESOURCE isteğinde bulunmak, yanıt yükünün boyutunu artırır. Bu seçeneği yalnızca uygulamanızın döndürülen alan değerlerini gerektirdiği durumlarda kullanın ve gerekmedikçe çok büyük toplu işlemlerde etkinleştirmeyin.

response_content_type değerini ayarlamazsanız Google Ads API varsayılan olarak RESOURCE_NAME_ONLY değerini kullanır ve yalnızca her değiştirilen kaynağın resource_name değerini döndürür.

Aşağıdaki örnekte, bir mutasyon çağrısından değiştirilebilir bir kaynağın nasıl alınacağı gösterilmektedir:

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(
              // In standard campaign experiments, creating the treatment arm automatically
              // generates a draft campaign 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);
  }
}
CreateSearchCustomExperiment.java
      

C#

private static (MutateExperimentArmResult, MutateExperimentArmResult)
    CreateExperimentArms(GoogleAdsClient client, long customerId, long baseCampaignId,
        string experimentResourceName)
{
    // Get the ExperimentArmService.
    ExperimentArmServiceClient experimentService = client.GetService(
        Services.V25.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.
    // In standard campaign experiments, creating the treatment arm automatically
    // generates a draft campaign 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);
}
CreateSearchCustomExperiment.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: GoogleAdsClient,
    customer_id: str,
    base_campaign_id: str,
    experiment: str,
) -> str:
    """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: List[ExperimentArmOperation] = []

    campaign_service: CampaignServiceClient = client.get_service(
        "CampaignService"
    )

    # The "control" arm references an already-existing campaign.
    operation_1: ExperimentArmOperation = client.get_type(
        "ExperimentArmOperation"
    )
    exa_1: ExperimentArm = 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)

    # In standard campaign experiments, creating the treatment arm automatically
    # generates a draft campaign that you can modify before starting the experiment.
    operation_2: ExperimentArmOperation = client.get_type(
        "ExperimentArmOperation"
    )
    exa_2: ExperimentArm = 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: ExperimentArmServiceClient = client.get_service(
        "ExperimentArmService"
    )
    request: MutateExperimentArmsRequest = 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: MutateExperimentArmsResponse = (
        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: Any = response.results[0]
    treatment_arm_result: Any = 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_search_custom_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::V25::Services::ExperimentArmService::ExperimentArmOperation
    ->new({
      create => Google::Ads::GoogleAds::V25::Resources::ExperimentArm->new({
          # The "control" arm references an already-existing campaign.
          control   => "true",
          campaigns => [
            Google::Ads::GoogleAds::V25::Utils::ResourceNames::campaign(
              $customer_id, $base_campaign_id
            )
          ],
          experiment   => $experiment,
          name         => "control arm",
          trafficSplit => 40
        })});

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

curl

Not: Bu adım için doğrudan bir REST kodu örneği burada verilmemiştir ancak manuel bir REST isteği kullanarak bunu gerçekleştirebilirsiniz.

Google Ads API REST arayüzü belgelerine ve yönteme özel referans sayfalarına bakın. JSON yükünü proto tanımlarına göre oluşturmanız gerekir.

Key Resources:

• REST'i kullanma
• REST Arayüz Yapısı
• JSON Alan Eşlemeleri
• Belirli bir hizmet ve yöntem için REST API Referansı'na bakın.