أفضل ممارسات التبديل

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

أسماء الموارد المؤقتة

يتوافق 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 التي استخدمناها للحملة، ونشير أيضًا إلى هذه المجموعة الإعلانية عند إنشاء إعلان مجموعة إعلانية. تشير المجموعة الإعلانية نفسها إلى اسم المورد الذي أنشأناه للحملة في عملية سابقة في الطلب، في حين أن resource_name في ad_group_ad_operation غير ضروري نظرًا لعدم وجود عملية إضافية تشير إلى ذلك.

تجميع العمليات من النوع نفسه

عند استخدام GoogleAdsService.Mutate، من المهم تجميع العمليات معًا وفقًا لموردها في مصفوفة العمليات المتكررة. تعمل طريقة التبديل هذه بشكل أساسي كطريقة لاستدعاء أسلوب التبديل الخاص بكل مورد على حدة بشكل تسلسلي. ولتنفيذ ذلك، تتم قراءة هذه العملية في العمليات حتى تعثر على مورد لنوع مختلف من الموارد، ثم تدمج جميع العمليات من النوع نفسه معًا في طلب واحد.

على سبيل المثال، إذا كان لديك 5 عمليات حملة، متبوعة بـ 10 عمليات على مستوى المجموعة الإعلانية في حقل operations المتكرر في طلب Mutate، سيُجري النظام إجمالي مكالمتين في الخلفية، واحدة إلى CampaignService لخمس عمليات، والثانية بجوار AdGroupService لعشر عمليات. ولكن إذا كان عليك تجميعها بشكل مختلف، فقد يكون الأداء أسوأ بكثير. إذا أنشأت حملتين فقط ومجموعتين إعلانيتين، ولكن نسجتهما بحيث يتم ترتيب العمليات على النحو التالي [campaign, ad group, campaign, ad group]، فحينئذٍ سينتج عن ذلك أربعة استدعاءات إجمالية في الخلفية. وسيؤدي هذا إلى بطء أداء واجهة برمجة التطبيقات وفي الحالات القصوى قد يؤدي ذلك إلى انتهاء المهلات.

استرداد السمات القابلة للتغيير من الاستجابة

في حال ضبط response_content_type على طلب التبديل إلى MUTABLE_RESOURCE، ستحتوي الاستجابة على قيم جميع حقول الإحالة الناجحة لكل عنصر تم إنشاؤه أو تعديله في الطلب. استخدِم هذه الميزة لتجنّب طلب search أو searchStream إضافي بعد كل طلب تبديل.

في حال عدم ضبط response_content_type، سيتم ضبط واجهة برمجة التطبيقات مع "إعلانات Google" تلقائيًا على RESOURCE_NAME_ONLY، وستحتوي الاستجابة فقط على اسم المورد لكل مورد تم إنشاؤه أو تعديله.

في ما يلي مثال لاسترداد مورد قابل للتحويل من طلب بيانات من واجهة برمجة التطبيقات:

لغة Java

// Constructs a request to add the bid modifier.
MutateCampaignBidModifiersRequest request =
    MutateCampaignBidModifiersRequest.newBuilder()
        .addOperations(op)
        .setCustomerId(String.valueOf(customerId))
        // Specifies that we want to the request to return the mutated object and not just its
        // resource name.
        .setResponseContentType(ResponseContentType.MUTABLE_RESOURCE)
        .build();

// Sends the operation in a mutate request.
try (CampaignBidModifierServiceClient agcServiceClient =
    googleAdsClient.getLatestVersion().createCampaignBidModifierServiceClient()) {
  MutateCampaignBidModifiersResponse response =
      agcServiceClient.mutateCampaignBidModifiers(request);
  /**
   * The resource returned in the response can be accessed directly in the results list. Its
   * fields can be read directly, and it can also be mutated further and used in subsequent
   * requests, without needing to make additional Get or Search requests.
   */
  CampaignBidModifier mutableResource = response.getResults(0).getCampaignBidModifier();
  System.out.printf(
      "Created campaign bid modifier with resource_name "
          + "'%s', criterion ID "
          + "%d, and bid modifier value "
          + "%s, under the campaign with "
          + "resource_name '%s'.%n",
      mutableResource.getResourceName(),
      mutableResource.getCriterionId(),
      mutableResource.getBidModifier(),
      mutableResource.getCampaign());
}
AddCampaignBidModifier.java

#C

// Construct an operation to create the campaign bid modifier.
CampaignBidModifierOperation op = new CampaignBidModifierOperation()
{
    Create = campaignBidModifier
};

// Construct a request, and set the ResponseContentType field to
// ResponseContentType.MutableResource, so that the response contains
// the mutated object and not just its resource name.
MutateCampaignBidModifiersRequest request = new MutateCampaignBidModifiersRequest()
{
    CustomerId = customerId.ToString(),
    ResponseContentType = ResponseContentType.MutableResource,
    Operations = { op }
};

// Send the operation in a mutate request.
try
{
    MutateCampaignBidModifiersResponse response =
        campaignBidModifierService.MutateCampaignBidModifiers(request);
    Console.WriteLine("Added {0} campaign bid modifiers:", response.Results.Count);

    // The resource returned in the response can be accessed directly in the
    // results list. Its fields can be read directly, and it can also be mutated
    // further and used in subsequent requests, without needing to make
    // additional Get or Search requests.
    foreach (MutateCampaignBidModifierResult result in response.Results)
    {
        Console.WriteLine($"\tCreated campaign bid modifier with " +
            $"resource name '{result.ResourceName}', " +
            $"criterion ID '{result.CampaignBidModifier.CriterionId}', " +
            $"and bid modifier value {result.CampaignBidModifier.BidModifier}, " +
            $"under the campaign with resource_name " +
            $"'{result.CampaignBidModifier.Campaign}'");
    }
}
catch (GoogleAdsException e)
{
    Console.WriteLine("Failure:");
    Console.WriteLine($"Message: {e.Message}");
    Console.WriteLine($"Failure: {e.Failure}");
    Console.WriteLine($"Request ID: {e.RequestId}");
    throw;
}
AddCampaignBidModifier.cs

لغة PHP

// Issues a mutate request to add the campaign bid modifier.
// Here we pass the optional parameter ResponseContentType::MUTABLE_RESOURCE so that the
// response contains the mutated object and not just its resource name.
$campaignBidModifierServiceClient = $googleAdsClient->getCampaignBidModifierServiceClient();
$response = $campaignBidModifierServiceClient->mutateCampaignBidModifiers(
    $customerId,
    [$campaignBidModifierOperation],
    ['responseContentType' => ResponseContentType::MUTABLE_RESOURCE]
);

// The resource returned in the response can be accessed directly in the results list.
// Its fields can be read directly, and it can also be mutated further and used in
// subsequent requests, without needing to make additional Get or Search requests.
/** @var CampaignBidModifier $addedCampaignBidModifier */
$addedCampaignBidModifier = $response->getResults()[0]->getCampaignBidModifier();
printf(
    "Added campaign bid modifier with resource_name '%s', criterion ID %d, and "
    . "bid modifier value %f, under the campaign with resource name '%s'.%s",
    $addedCampaignBidModifier->getResourceName(),
    $addedCampaignBidModifier->getCriterionId(),
    $addedCampaignBidModifier->getBidModifier(),
    $addedCampaignBidModifier->getCampaign(),
    PHP_EOL
);
AddCampaignBidModifier.php

لغة Python

# Add the campaign bid modifier. Here we pass the optional parameter
# response_content_type=MUTABLE_RESOURCE so that the response contains
# the mutated object and not just its resource name.
request = client.get_type("MutateCampaignBidModifiersRequest")
request.customer_id = customer_id
request.operations = [campaign_bid_modifier_operation]
request.response_content_type = (
    client.enums.ResponseContentTypeEnum.MUTABLE_RESOURCE
)

campaign_bm_response = campaign_bm_service.mutate_campaign_bid_modifiers(
    request=request
)

# The resource returned in the response can be accessed directly in the
# results list. Its fields can be read directly, and it can also be mutated
# further and used in subsequent requests, without needing to make
# additional Get or Search requests.
mutable_resource = campaign_bm_response.results[0].campaign_bid_modifier
print(
    "Created campaign bid modifier with resource_name "
    f"'{mutable_resource.resource_name}', criterion ID "
    f"'{mutable_resource.criterion_id}', and bid modifier value "
    f"'{mutable_resource.bid_modifier}', under the campaign with "
    f"resource_name '{mutable_resource.campaign}', "
)
add_campaign_bid_modifier.py

Ruby

# Add the campaign bid modifier. Here we pass the optional parameter
# response_content_type=MUTABLE_RESOURCE so that the response contains
# the mutated object and not just its resource name.
response = campaign_bid_modifier_service.mutate_campaign_bid_modifiers(
  customer_id: customer_id,
  operations: [operation],
  response_content_type: :MUTABLE_RESOURCE,
)

puts "Added #{response.results.size} campaign bid modifiers:"
response.results.each do |added_campaign_bid_modifier|
  # The resource returned in the response can be accessed directly in the
  # results list. Its fields can be read directly, and it can also be mutated
  # further and used in subsequent requests, without needing to make
  # additional Get or Search requests.
  mutable_resource = added_campaign_bid_modifier.campaign_bid_modifier
  puts "\tCreated campaign bid modifier with " \
    "resource_name '#{mutable_resource.resource_name}', " \
    "criterion ID #{mutable_resource.criterion_id}, " \
    "bid_modifier #{mutable_resource.bid_modifier}, " \
    "under the campaign with resource_name '#{mutable_resource.campaign}'"
end
add_campaign_bid_modifier.rb

Perl

# Add the campaign bid modifier. Here we pass the optional parameter
# responseContentType => MUTABLE_RESOURCE so that the response contains the
# mutated object and not just its resource name.
my $campaign_bid_modifiers_response =
  $api_client->CampaignBidModifierService()->mutate({
    customerId          => $customer_id,
    operations          => [$campaign_bid_modifier_operation],
    responseContentType => MUTABLE_RESOURCE
  });

# The resource returned in the response can be accessed directly in the
# results list. Its fields can be read directly, and it can also be mutated
# further and used in subsequent requests, without needing to make additional
# Get or Search requests.
my $mutable_resource =
  $campaign_bid_modifiers_response->{results}[0]{campaignBidModifier};

printf
  "Created campaign bid modifier with resource name '%s', criterion ID %d, "
  . "and bid modifier value %s, under the campaign with resource name '%s'.\n",
  $mutable_resource->{resourceName}, $mutable_resource->{criterionId},
  $mutable_resource->{bidModifier},  $mutable_resource->{campaign};
add_campaign_bid_modifier.pl

السابق
التبديلات المجمّعة