أفضل الممارسات

تتناول هذه الصفحة أفضل الممارسات المختلفة لتطوير النصوص البرمجية في "إعلانات Google".

المحددات

الفلترة باستخدام أدوات الاختيار

استخدِم الفلاتر لطلب الكيانات التي تحتاج إليها فقط، متى أمكن ذلك. إليك المزايا التالية لتطبيق فلاتر مناسبة:

  • تكون الرموز البرمجية أبسط وأسهل فهمًا.
  • سيتم تنفيذ النص البرمجي بشكل أسرع بكثير.

قارِن بين مقتطفات الرمز البرمجي التالية:

منهج الترميز مقتطف الرمز
الفلترة باستخدام المحدّدات (إجراء يُنصح به) 
var keywords = AdsApp.keywords()
    .withCondition('Clicks > 10')
    .forDateRange('LAST_MONTH')
    .get();
while (keywords.hasNext()) {
  var keyword = keywords.next();
  // Do work here.
}
الفلترة في الرمز (غير مقترَح) 
var keywords = AdsApp.keywords().get();

while (keywords.hasNext()) {
  var keyword = keywords.next();
  var stats = keyword.getStatsFor(
      'LAST_MONTH');
  if (stats.getClicks() > 10) {
    // Do work here.
  }
}

لا يُنصح باستخدام الطريقة الثانية لأنّها تحاول استرداد قائمة بجميع الكلمات الرئيسية في حسابك فقط لتطبيق فلتر على القائمة.

تجنُّب التنقّل في التدرّج الهرمي للحملة

عندما تريد استرداد كيانات على مستوى معيّن، استخدِم أسلوب جمع على هذا المستوى بدلاً من التنقّل في التسلسل الهرمي للحملة بالكامل. بالإضافة إلى أنّ هذا الإجراء أبسط، سيحقّق أيضًا أداءً أفضل بكثير: لن يحتاج النظام إلى قراءة جميع الحملات والمجموعات الإعلانية بدون داعٍ.

قارِن بين مقتطفات الرموز التالية التي تسترجع جميع الإعلانات في حسابك:

منهج الترميز مقتطف الرمز
استخدام طريقة جمع البيانات المناسبة (إجراء يُنصح به) 

var ads = AdsApp.ads();
التنقّل في التدرّج الهرمي (غير مقترَح) 
var campaigns = AdsApp.campaigns().get();
while (campaigns.hasNext()) {
  var adGroups = campaigns.next().
      adGroups().get();
  while (adGroups.hasNext()) {
    var ads = adGroups.next().ads().get();
    // Do your work here.
  }
}

لا يُنصح بالنهج الثاني لأنّه يحاول جلب هرميات كاملة للعناصر (الحملات والمجموعات الإعلانية) في حين أنّ الإعلانات فقط مطلوبة.

استخدام طرق معيّنة لاسترداد بيانات الوالدَين

في بعض الأحيان، تحتاج إلى الحصول على العنصر الرئيسي للكائن الذي تم استرجاعه. في هذه الحالة، يجب استخدام طريقة استرجاع بيانات مقدَّمة بدلاً من جلب التسلسلات الهرميّة بالكامل.

قارِن بين المقتطفات التالية من الرموز البرمجية التي تسترجع المجموعات الإعلانية التي تتضمّن إعلانات نصية حصدت أكثر من 50 نقرة في الشهر الماضي:

منهج الترميز مقتطف الرمز
استخدام طريقة الوصول المناسبة إلى العنصر الرئيسي (إجراء يُنصح به) 
var ads = AdsApp.ads()
    .withCondition('Clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();

while (ads.hasNext()) {
  var ad = ads.next();
  var adGroup = ad.getAdGroup();
  var campaign = ad.getCampaign();
  // Store (campaign, adGroup) to an array.
}
التنقّل في التسلسل الهرمي (غير مستحسن) 
var campaigns = AdsApp.campaigns().get();
while (campaigns.hasNext()) {
  var adGroups = campaigns.next()
      .adGroups()
      .get();
  while (adGroups.hasNext()) {
    var ads = adGroups.ads()
       .withCondition('Clicks > 50')
       .forDateRange('LAST_MONTH')
       .get();
    if (ads.totalNumEntities() > 0) {
      // Store (campaign, adGroup) to an array.
    }
  }
}

لا يُنصح بالطريقة الثانية لأنّها تُجلب التسلسلات الهرمية للحملات والمجموعات الإعلانية بالكامل في حسابك، في حين أنّك تحتاج فقط إلى مجموعة فرعية من الحملات والمجموعات الإعلانية المرتبطة بمجموعة إعلاناتك. يقتصر الأسلوب الأول على جلب مجموعة الإعلانات ذات الصلة فقط، ويستخدم طريقة مناسبة للوصول إلى العناصر الرئيسية لها.

استخدام فلاتر معيّنة للوالدَين

للوصول إلى الكيانات ضمن حملة أو مجموعة إعلانية معيّنة، استخدِم ملف شخصي فلترة معيّنًا في أداة الاختيار بدلاً من جلب التسلسل الهرمي ثم التنقّل فيه.

قارِن بين المقتطفات التالية من الرمز البرمجي التي تسترجع قائمة الإعلانات النصية ضمن حملة ومجموعة إعلانية محدّدتين تلقّتا أكثر من 50 نقرة في الشهر الماضي.

منهج الترميز مقتطف الرمز
استخدام الفلاتر المناسبة على مستوى أحد الوالدَين (إجراء يُنصَح به) 
var ads = AdsApp.ads()
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .withCondition('Clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();

while (ads.hasNext()) {
  var ad = ads.next();
  var adGroup = ad.getAdGroup();
  var campaign = ad.getCampaign();
  // Store (campaign, adGroup, ad) to
  // an array.
}
التنقّل في التسلسل الهرمي (غير مستحسن) 
var campaigns = AdsApp.campaigns()
    .withCondition('Name = "Campaign 1"')
    .get();

while (campaigns.hasNext()) {
  var adGroups = campaigns.next()
      .adGroups()
      .withCondition('Name = "AdGroup 1"')
      .get();
  while (adGroups.hasNext()) {
    var ads = adGroups.ads()
       .withCondition('Clicks > 50')
       .forDateRange('LAST_MONTH')
       .get();
    while (ads.hasNext()) {
      var ad = ads.next();
      // Store (campaign, adGroup, ad) to
      // an array.
    }
  }
}

لا يُنصح بالطريقة الثانية لأنّها تتكرّر على التسلسل الهرمي للحملات والمجموعات الإعلانية في حسابك، في حين أنّك تحتاج فقط إلى مجموعة محدّدة من الإعلانات، والحملات والمجموعات الإعلانية الرئيسية لها. يحدّد النهج الأول التكرار بقائمة الإعلانات من خلال تطبيق فلتر محدّد للكيانات الرئيسية على أداة الاختيار.

استخدام المعرّفات للفلترة كلما أمكن

عند الفلترة حسب الكيانات، من الأفضل الفلترة حسب معرّفاتها بدلاً من الحقول الأخرى.

راجِع مقتطفات الرموز البرمجية التالية التي تختار حملة.

منهج الترميز مقتطف الرمز
الفلترة حسب رقم التعريف (إجراء مقترَح) 
var campaign = AdsApp.campaigns()
    .withIds([12345])
    .get()
    .next();
الفلترة حسب الاسم (أقل فعالية) 
var campaign = AdsApp.campaigns()
    .withCondition('Name="foo"')
    .get()
    .next();

إنّ المنهج الثاني أقل فعالية لأنّنا نفلتر حسب حقل غير رقم تعريفي.

الفلترة حسب أرقام تعريف الوالدَين كلما أمكن

عند اختيار عنصر، فلتِر حسب أرقام تعريف العناصر الرئيسية كلما أمكن. سيؤدي ذلك إلى تسريع طلبات البحث من خلال الحد من قائمة الكيانات التي يتم استرجاعها من قبل الخوادم عند فلترة النتائج.

راجِع مقتطف الرمز البرمجي التالي الذي يسترجع مجموعة إعلانية حسب معرّفها. نفترض أنّه معروف رقم تعريف الحملة الرئيسية.

منهج الترميز مقتطف الرمز
الفلترة حسب أرقام تعريف الحملات والمجموعات الإعلانية (إجراء يُنصح به) 
var adGroup = AdsApp.adGroups()
    .withIds([12345])
    .withCondition('CampaignId="54678"')
    .get()
    .next();
الفلترة حسب رقم تعريف المجموعة الإعلانية فقط (أقلّ فعالية) 
var adGroup = AdsApp.adGroups()
    .withIds([12345])
    .get()
    .next();

على الرغم من أنّ كلا المقتطفَين من الرموز يقدّمان نتائج متطابقة، فإنّ عملية ال filtering الإضافية في المقتطف 1 من الرموز باستخدام معرّف الأصل (CampaignId="54678") تجعل الرمز أكثر فعالية من خلال حصر قائمة الكيانات التي يجب أن يكرّرها الخادم عند فلترة النتائج.

استخدام التصنيفات عندما يكون هناك عدد كبير جدًا من شروط الفلترة

عندما يكون لديك عدد كبير جدًا من شروط الفلترة، من الأفضل إنشاء تصنيف للكيانات التي تعالجها واستخدام هذا التصنيف لفلترة الكيانات.

راجِع المقتطف التالي من الرمز البرمجي الذي يسترجع قائمة بالحملات حسب أسمائها.

منهج الترميز مقتطف الرمز
استخدام تصنيف (إجراء يُنصح به) 
var label = AdsApp.labels()
    .withCondition('Name = "My Label"')
    .get()
    .next();
var campaigns = label.campaigns.get();
while (campaigns.hasNext()) {
  var campaign = campaigns.next();
  // Do more work
}
إنشاء أدوات اختيار معقّدة (لا يُنصح به) 
var campaignNames = [‘foo’, ‘bar’, ‘baz’];

for (var i = 0; i < campaignNames.length; i++) {
  campaignNames[i] = '"' + campaignNames[i] + '"';
}

var campaigns = AdsApp.campaigns
    .withCondition('CampaignName in [' + campaignNames.join(',') + ']')
    .get();

while (campaigns.hasNext()) {
  var campaign = campaigns.next();
  // Do more work.
}

على الرغم من أنّ كلا المقتطفَين من الرمز يوفّران لك مستوى أداء مشابهًا، يميل الأسلوب الثاني إلى إنشاء رمز أكثر تعقيدًا مع زيادة عدد الشروط في أداة الاختيار. من الأسهل أيضًا تطبيق التصنيف على عنصر جديد مقارنةً بتعديل النص البرمجي لتضمين عنصر جديد.

الحد من عدد الشروط في عبارة IN

عند تشغيل النصوص البرمجية، تكون حالة الاستخدام الشائعة هي تشغيل تقرير لقائمة بالعناصر. ويحقّق المطوّرون ذلك عادةً من خلال إنشاء طلب بحث AWQL طويل جدًا لفلترة أرقام تعريف الكيانات باستخدام عبارة IN. يعمل هذا النهج بشكل جيد عندما يكون عدد الكيانات محدودًا. ومع ذلك، مع زيادة طول طلب البحث، يتدهور أداء النص البرمجي لسببين:

  • يستغرق تحليل طلب البحث الأطول وقتًا أطول.
  • كل رقم تعريفي تضيفه إلى عبارة IN هو شرط إضافي يجب تقييمه، وبالتالي يستغرق وقتًا أطول.

في ظلّ هذه الظروف، من الأفضل تطبيق تصنيف على الكيانات، ثمَّ فلترة البيانات حسب LabelId.

منهج الترميز مقتطف الرمز
تطبيق تصنيف والفلترة حسب رقم تعريف التصنيف (إجراء يُنصح به) 
// The label applied to the entity is "Report Entities"
var label = AdsApp.labels()
    .withCondition('LabelName contains "Report Entities"')
    .get()
    .next();

var report = AdsApp.report('SELECT AdGroupId, Id, Clicks, ' +
    'Impressions, Cost FROM KEYWORDS_PERFORMANCE_REPORT ' +
    'WHERE LabelId = "' + label.getId() + '"');
إنشاء طلب بحث طويل باستخدام عبارة IN (غير مقترَح) 
var report = AdsApp.report('SELECT AdGroupId, Id, Clicks, ' +
    'Impressions, Cost FROM KEYWORDS_PERFORMANCE_REPORT WHERE ' +
    'AdGroupId IN (123, 456) and Id in (123,345, 456…)');

تعديلات الحساب

التغييرات المجمّعة

عند إجراء تغييرات على عنصر في "إعلانات Google"، لا تنفِّذ نصوص "إعلانات Google" البرمجية التغيير على الفور. بدلاً من ذلك، يحاول دمج تغييرات متعددة في مجموعات، حتى يتمكّن من إصدار طلب واحد يُجري تغييرات متعدّدة. ويؤدي هذا النهج إلى تسريع نصوصك البرمجية وتقليل الضغط على ملفّات خادم "إعلانات Google". ومع ذلك، هناك بعض أنماط الرموز البرمجية التي تجبر نصوص "إعلانات Google" البرمجية على محو مجموعة عملياتها بشكل متكرّر، ما يؤدي إلى تنفيذ النص البرمجي ببطء.

راجِع النص البرمجي التالي الذي يعدّل عروض أسعار قائمة من الكلمات الرئيسية.

منهج الترميز مقتطف الرمز
تتبُّع العناصر المعدَّلة (إجراء يُنصح به) 
var keywords = AdsApp.keywords()
    .withCondition('Clicks > 50')
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .forDateRange('LAST_MONTH')
    .get();

var list = [];
while (keywords.hasNext()) {
  var keyword = keywords.next();
  keyword.bidding().setCpc(1.5);
  list.push(keyword);
}

for (var i = 0; i < list.length; i++) {
  var keyword = list[i];
  Logger.log('%s, %s', keyword.getText(),
      keyword.bidding().getCpc());
}
استرداد العناصر المعدَّلة في حلقة ضيقة (لا يُنصح به) 
var keywords = AdsApp.keywords()
    .withCondition('Clicks > 50')
    .withCondition('CampaignName = "Campaign 1"')
    .withCondition('AdGroupName = "AdGroup 1"')
    .forDateRange('LAST_MONTH')
    .get();

while (keywords.hasNext()) {
  var keyword = keywords.next();
  keyword.bidding().setCpc(1.5);
  Logger.log('%s, %s', keyword.getText(),
      keyword.bidding().getCpc());
}

لا يُنصح باستخدام الطريقة الثانية لأنّ طلب الإجراء keyword.bidding().getCpc() يفرض على نصوص "إعلانات Google" البرمجية إزالة عملية setCpc() وتنفيذ عملية واحدة فقط في كل مرة. على الرغم من أنّ النهج الأول مشابه للنهج الثاني، إلا أنّه يقدّم ميزة إضافية تتيح تجميع الطلبات، لأنّه يتم تنفيذ طلب getCpc() في حلقة منفصلة عن الحلقة التي يتم فيها تنفيذ طلب setCpc().

استخدام أدوات الإنشاء كلما أمكن

تتيح نصوص "إعلانات Google" طريقتَين لإنشاء عناصر جديدة، وهما أدوات الإنشاء وطرق الإنشاء. تكون الأدوات أكثر مرونة من طرق الإنشاء، لأنّها تمنحك إمكانية الوصول إلى العنصر الذي تم إنشاؤه من طلب واجهة برمجة التطبيقات.

راجِع المقتطفات التالية من الرموز البرمجية:

منهج الترميز مقتطف الرمز
استخدام أدوات الإنشاء (إجراء يُنصح به) 
var operation = adGroup.newKeywordBuilder()
    .withText('shoes')
    .build();
var keyword = operation.getResult();
استخدام طُرق الإنشاء (غير مُستحسَن) 
adGroup.createKeyword('shoes');
var keyword = adGroup.keywords()
    .withCondition('KeywordText="shoes"')
    .get()
    .next();

لا يُفضّل استخدام المنهج الثاني بسبب عملية الاختيار الإضافية المرتبطة باسترداد الكلمة الرئيسية. بالإضافة إلى ذلك، سيتم أيضًا إيقاف طُرق الإنشاء نهائيًا.

ومع ذلك، يُرجى العِلم أنّ أدوات الإنشاء، عند استخدامها بشكل غير صحيح، يمكن أن تمنع نصوص "إعلانات Google" من تجميع عملياتها.

راجِع المقتطفات التالية من الرموز البرمجية التي تنشئ قائمة بالكلمات الرئيسية، وتُطبع رقم تعريف الكلمات الرئيسية التي تم إنشاؤها حديثًا:

منهج الترميز مقتطف الرمز
تتبُّع العناصر المعدَّلة (إجراء يُنصح به) 
var keywords = [‘foo’, ‘bar’, ‘baz’];

var list = [];
for (var i = 0; i < keywords.length; i++) {
  var operation = adGroup.newKeywordBuilder()
      .withText(keywords[i])
      .build();
  list.push(operation);
}

for (var i = 0; i < list.length; i++) {
  var operation = list[i];
  var result = operation.getResult();
  Logger.log('%s %s', result.getId(),
      result.getText());
}
استرداد العناصر المعدَّلة في حلقة ضيقة (لا يُنصح به) 
var keywords = [‘foo’, ‘bar’, ‘baz’];

for (var i = 0; i < keywords.length; i++) {
  var operation = adGroup.newKeywordBuilder()
      .withText(keywords[i])
      .build();
  var result = operation.getResult();
  Logger.log('%s %s', result.getId(),
      result.getText());
}

لا يُفضَّل الأسلوب الثاني لأنّه يستدعي operation.getResult() ضمن الحلقة نفسها التي تنشئ العملية، ما يجبر نصوص "إعلانات Google" البرمجية على تنفيذ عملية واحدة في كل مرة. على الرغم من أنّ المنهج الأول مشابه، إلا أنّه يسمح بالمعالجة دُفعة واحدة لأنّنا نُطلِق operation.getResult() في حلقة مختلفة عن النقطة التي تم فيها إنشاؤه.

ننصحك باستخدام عمليات التحميل المجمَّعة لإجراء تعديلات كبيرة.

من المهام الشائعة التي ينفّذها المطوّرون هي عرض التقارير وتعديل سمات العناصر (مثل عروض أسعار الكلمات الرئيسية) استنادًا إلى قيم الأداء الحالية. عندما تحتاج إلى تعديل عدد كبير من العناصر، تحقّق عمليات التحميل المجمّعة عادةً أداءً أفضل. على سبيل المثال، فكِّر في النصوص البرمجية التالية التي تزيد قيمة MaxCpc للكلمات الرئيسية التي سجّلت TopImpressionPercentage > 0.4 خلال الشهر الماضي:

منهج الترميز مقتطف الرمز
استخدام ميزة "التحميل المجمّع" (إجراء يُنصح به) 

var report = AdsApp.report(
  'SELECT AdGroupId, Id, CpcBid FROM KEYWORDS_PERFORMANCE_REPORT ' +
  'WHERE TopImpressionPercentage > 0.4 DURING LAST_MONTH');

var upload = AdsApp.bulkUploads().newCsvUpload([
  report.getColumnHeader('AdGroupId').getBulkUploadColumnName(),
  report.getColumnHeader('Id').getBulkUploadColumnName(),
  report.getColumnHeader('CpcBid').getBulkUploadColumnName()]);
upload.forCampaignManagement();

var reportRows = report.rows();
while (reportRows.hasNext()) {
  var row = reportRows.next();
  row['CpcBid'] = row['CpcBid'] + 0.02;
  upload.append(row.formatForUpload());
}

upload.apply();
اختيار الكلمات الرئيسية وتعديلها حسب رقم التعريف (أقلّ فعالية) 
var reportRows = AdsApp.report('SELECT AdGroupId, Id, CpcBid FROM ' +
    'KEYWORDS_PERFORMANCE_REPORT WHERE TopImpressionPercentage > 0.4 ' +
    ' DURING LAST_MONTH')
    .rows();

var map = {
};

while (reportRows.hasNext()) {
  var row = reportRows.next();
  var adGroupId = row['AdGroupId'];
  var id = row['Id'];

  if (map[adGroupId] == null) {
    map[adGroupId] = [];
  }
  map[adGroupId].push([adGroupId, id]);
}

for (var key in map) {
  var keywords = AdsApp.keywords()
      .withCondition('AdGroupId="' + key + '"')
      .withIds(map[key])
      .get();

  while (keywords.hasNext()) {
    var keyword = keywords.next();
    keyword.bidding().setCpc(keyword.bidding().getCpc() + 0.02);
  }
}

على الرغم من أنّ الطريقة الثانية تمنحك أداءً جيدًا جدًا، يُفضَّل استخدام الطريقة الأولى في هذه الحالة لأنّ

  • تفرض نصوص "إعلانات Google" حدًّا أقصى لعدد العناصر التي يمكن استرجاعها أو تعديلها في عملية واحدة، وتُحتسَب عمليات الاختيار والتعديل في الأسلوب الثاني ضمن هذا الحدّ الأقصى.

  • تفرض عمليات التحميل المجمّعة حدودًا أعلى من حيث عدد الكيانات التي يمكن تعديلها ووقت التنفيذ العام.

تجميع عمليات التحميل المجمّعة حسب الحملات

عند إنشاء عمليات التحميل المجمّعة، حاوِل تجميع عملياتك حسب الحملة الأساسية. ويؤدي ذلك إلى زيادة الكفاءة والحدّ من احتمال حدوث أخطاء تتعلّق بتضارب التغييرات أو التزامن.

لنفترض أنّ هناك مهمتَي تحميل مجمّع يتم تنفيذهما بالتوازي. يوقف أحدهما الإعلانات مؤقتًا في مجموعة إعلانية، ويُعدّل الآخر عروض أسعار الكلمات الرئيسية. على الرغم من أنّ العمليات غير مرتبطة ببعضها، قد تنطبق العمليات على الكيانات ضمن المجموعة الإعلانية نفسها (أو مجموعتَين إعلانيتين مختلفتَين ضمن الحملة نفسها). عند حدوث ذلك، سيقفل النظام العنصر الرئيسي (المجموعة الإعلانية أو الحملة المشترَكة)، ما يؤدي إلى حظر المهام لتحميل البيانات المجمّعة على بعضها.

يمكن للنصوص البرمجية في "إعلانات Google" تحسين التنفيذ ضمن مهمة تحميل مجمّع واحدة، لذا إنّ أبسط إجراء يمكنك اتّخاذه هو تنفيذ مهمة تحميل مجمّع واحدة فقط لكل حساب في الوقت نفسه. إذا قرّرت إجراء أكثر من عملية تحميل مجمّعة واحدة لكل حساب، تأكَّد من أنّ عمليات التحميل المجمّعة تعمل على قائمة حصرية من الحملات (والعناصر الفرعية لها) لتحقيق الأداء الأمثل.

إعداد التقارير

استخدام التقارير لجلب الإحصاءات

عندما تريد استرداد كميات كبيرة من الكيانات وإحصاءاتها، من المفضّل في أغلب الأحيان استخدام التقارير بدلاً من طرق AdsApp العادية. يُفضَّل استخدام تقارير الأداء للأسباب التالية:

  • تمنحك التقارير أداءً أفضل لطلبات البحث الكبيرة.
  • لن تتجاوز التقارير حصص الجلب العادية.

قارِن بين مقتطفات الرموز البرمجية التالية التي تُستخدَم لاسترداد النقرات ومرّات الظهور والتكلفة والنص لجميع الكلمات الرئيسية التي تلقّت أكثر من 50 نقرة في الشهر الماضي:

منهج الترميز مقتطف الرمز
استخدام التقارير (إجراء يُنصح به) 
  report = AdsApp.search(
      'SELECT ' +
      '   ad_group_criterion.keyword.text, ' +
      '   metrics.clicks, ' +
      '   metrics.cost_micros, ' +
      '   metrics.impressions ' +
      'FROM ' +
      '   keyword_view ' +
      'WHERE ' +
      '   segments.date DURING LAST_MONTH ' +
      '   AND metrics.clicks > 50');
  while (report.hasNext()) {
    var row = report.next();
    Logger.log('Keyword: %s Impressions: %s ' +
        'Clicks: %s Cost: %s',
        row.adGroupCriterion.keyword.text,
        row.metrics.impressions,
        row.metrics.clicks,
        row.metrics.cost);
  }
استخدام الدوالّ المتكرّرة في AdsApp (غير مقترَح) 
var keywords = AdsApp.keywords()
    .withCondition('metrics.clicks > 50')
    .forDateRange('LAST_MONTH')
    .get();
while (keywords.hasNext()) {
  var keyword = keywords.next();
  var stats = keyword.getStatsFor('LAST_MONTH');
  Logger.log('Keyword: %s Impressions: %s ' +
      'Clicks: %s Cost: %s',
      keyword.getText(),
      stats.getImpressions(),
      stats.getClicks(),
      stats.getCost());
}

لا يُفضَّل الأسلوب الثاني لأنّه يكرّر الكلمات الرئيسية ويسترِد الإحصاءات لكيان واحد في كل مرة. تُحقّق التقارير أداءً أسرع في هذا الوضع لأنّها تُجلب جميع البيانات في طلب واحد وتبثّها كما هو مطلوب. بالإضافة إلى ذلك، يتم احتساب الكلمات الرئيسية التي تم استرجاعها في الطريقة الثانية ضمن حصة نصك البرمجي لعدد الكيانات التي تم استرجاعها باستخدام دعوة get().

استخدام البحث بدلاً من التقرير

تم إنشاء طريقة إعداد التقارير للبنية الأساسية القديمة، وستُخرج النتائج بتنسيق مسطّح حتى إذا كنت تستخدم GAQL. وهذا يعني أنّه يجب تحويل نتائج طلب البحث لمطابقة الطراز القديم، وهو ليس متاحًا لجميع الحقول ويضيف عبءً إضافيًا إلى كلّ طلب بحث.

ننصحك باستخدام البحث بدلاً من ذلك للاستفادة من جميع ميزات reporting الجديدة في Google Ads API.

تفضيل GAQL على AWQL

على الرغم من أنّ لغة AWQL لا تزال متاحة في طلبات بحث التقارير وطلبات withCondition، يتم تنفيذها من خلال طبقة ترجمة لا تتوافق بشكل كامل مع لغة AWQL الحقيقية. للتحكّم بشكل كامل في طلبات البحث، تأكَّد من استخدام GAQL.

إذا كانت لديك طلبات بحث حالية في AWQL تريد ترجمتها، لدينا أداة نقل طلبات البحث لمساعدتك.

لا تختَر صفوفًا أكثر من التي تحتاج إليها.

تعتمد سرعة تنفيذ التقارير (وأدوات الاختيار) على إجمالي عدد الصفوف التي سيعرضها التقرير، بغض النظر عمّا إذا كنت تكرّر تصفّحها. وهذا يعني أنّه عليك دائمًا استخدام فلاتر محدّدة لتقليل مجموعة النتائج قدر الإمكان لمطابقة حالة الاستخدام.

على سبيل المثال، لنفترض أنّك تريد العثور على مجموعات إعلانية تتضمّن عروض أسعار خارج بعض النطاقات المحدّدة. سيكون من الأسرع إجراء طلبَي بحث منفصلَين، أحدهما لعروض الأسعار التي تقل عن الحدّ الأدنى والآخر لعروض الأسعار التي تزيد عن الحدّ الأقصى، مقارنةً بجلبها جميع المجموعات الإعلانية وتجاهل تلك التي لا تهمّك.

منهج الترميز مقتطف الرمز
استخدام طلبَي بحث (إجراء مقترَح) 
var adGroups = []
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group WHERE ad_group.cpc_bid_micros < 1000000');

while (report.hasNext()) {
  var row = report.next();
  adGroups.push(row.adGroup);
}
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group WHERE ad_group.cpc_bid_micros > 2000000');

while (report.hasNext()) {
  var row = report.next();
  adGroups.push(row.adGroup);
}
الفلترة من طلب بحث عام (غير مستحسن) 
var adGroups = []
var report = AdsApp.search(
    'SELECT ad_group.name, ad_group.cpc_bid_micros' +
    ' FROM ad_group');

while (report.hasNext()) {
  var row = report.next();
  var cpcBidMicros = row.adGroup.cpcBidMicros;
  if (cpcBidMicros < 1000000 || cpcBidMicros > 2000000) {
    adGroups.push(row.adGroup);
  }
}

النصوص البرمجية لخدمة "مدير إعلانات Google" (مركز عملائي)

يُفضَّل استخدام executeInParallel بدلاً من التنفيذ التسلسلي.

عند كتابة نصوص برمجية للحسابات الإدارية، استخدِم executeInParallel() بدلاً من التنفيذ التسلسلي متى أمكن. يوفّر executeInParallel() لنصك البرمجي وقت معالجة إضافيًا (يصل إلى ساعة واحدة) ويصل إلى 30 دقيقة لكل حساب تتم معالجته (بدلاً من 30 دقيقة مجتمعة للتنفيذ التسلسلي). يمكنك الاطّلاع على صفحة الحدود القصوى للحصول على مزيد من التفاصيل.

جداول البيانات

استخدام عمليات مجمّعة عند تعديل جداول البيانات

عند تعديل جداول البيانات، حاوِل استخدام طرق العمليات المجمّعة (مثل getRange()) بدلاً من الطرق التي تعدّل خلية واحدة في كل مرة.

راجِع مقتطف الرمز البرمجي التالي الذي ينشئ نمطًا كسيريًا في جدول ملف شخصي.

منهج الترميز مقتطف الرمز
تعديل نطاق من الخلايا في مكالمة واحدة (إجراء مقترَح) 
var colors = new Array(100);
for (var y = 0; y < 100; y++) {
  xcoord = xmin;
  colors[y] = new Array(100);
  for (var x = 0; x < 100; x++) {
    colors[y][x] = getColor_(xcoord, ycoord);
    xcoord += xincrement;
  }
  ycoord -= yincrement;
}
sheet.getRange(1, 1, 100, 100).setBackgroundColors(colors);
تعديل خلية واحدة في كل مرة (لا يُنصح به) 
var cell = sheet.getRange('a1');
for (var y = 0; y < 100; y++) {
  xcoord = xmin;
  for (var x = 0; x < 100; x++) {
    var c = getColor_(xcoord, ycoord);
    cell.offset(y, x).setBackgroundColor(c);
    xcoord += xincrement;
  }
  ycoord -= yincrement;
  SpreadsheetApp.flush();
}

على الرغم من أنّ "جداول بيانات Google" تحاول تحسين مقتطف الرمز البرمجي الثاني من خلال تخزين قيمة القيم مؤقتًا، إلا أنّه لا يزال يقدّم أداءً ضعيفًا مقارنةً بالمقتطف الأول، ويعود سبب ذلك إلى عدد طلبات البيانات التي يتم إجراؤها من خلال واجهة برمجة التطبيقات.