نصوص برمجية لمدير الإعلانات

تتيح لك فئة AdsManagerApp في نصوص "إعلانات Google" البرمجية إدارة الحسابات المرتبطة ضمن حسابك الإداري. يمكنك إدارة جميع حسابات المعلنين من خلال نص برمجي واحد بدلاً من إنشاء نص برمجي منفصل لكل حساب.

استرداد قائمة الحسابات

يمكنك استرداد الحسابات ضمن حساب إداري باستخدام accounts مثل:

const accountSelector = AdsManagerApp.accounts()
    .withCondition('customer_client.descriptive_name = "My Account"');

const accountIterator = accountSelector.get();

هناك بعض القيود على الحسابات التي يمكن استردادها:

  • لا يمكن استرداد حسابات المدير إذا كان لديك تسلسل هرمي لعدة مستويات. لا يمكن اختيار سوى حسابات العملاء.
  • لا يتم تلقائيًا عرض الحسابات المغلقة والمُلغاة والمُعلّقة. يمكنك إلغاء هذا السلوك من خلال استدعاء withCondition مع تحديد فلتر مختلفcustomer_client.status.

يسترد الاستدعاء accounts قائمة جميع حسابات العملاء ضمن التدرّج الهرمي للحساب الإداري بشكلٍ تلقائي. يمكنك استخدام الأسلوب withLimit في فئة ManagedAccountSelector لحصر عدد الحسابات التي يسترجعها النص البرمجي. هناك خيار آخر وهو اختيار الحسابات حسب أرقام تعريف العملاء باستخدام الأسلوب withIds :

// Hyphens in the account ID are optional.
const accountSelector = AdsManagerApp.accounts()
    .withIds(['123-456-7890', '234-567-8901', '345-678-9012']);

العمل على حسابات العملاء

بعد استرداد حسابات العملاء، يمكنك تكرارها باستخدام للمكرر hasNext أو next الطرق. عليك استخدام الوسيطة select لتبديل سياق التنفيذ إلى حساب عميل. بعد اختيار حساب عميل، تنطبق أي طلبات أخرى لواجهة برمجة التطبيقات على حساب العميل إلى أن تتم اختيار حساب آخر صراحةً:

// Keep track of the manager account for future reference.
const managerAccount = AdsApp.currentAccount();

// Select your accounts
const accountIterator = AdsManagerApp.accounts()
// ... Write some logic here to select the accounts you want using
// withCondition or withIds

// Iterate through the list of accounts
for (const account of accountIterator) {
  // Select the client account.
  AdsManagerApp.select(account);

  // Select campaigns under the client account
  const campaignIterator = AdsApp.campaigns().get();

  // Operate on client account
  ...
}

العمل على حسابات بالتوازي

تتيح لك نصوص "إعلانات Google" البرمجية العمل على حسابات عملاء متعددة بالتوازي، وذلك باستخدام executeInParallel طريقة ManagedAccountSelector الصف. تحتوي طريقة executeInParallel على التوقيع التالي:

function executeInParallel(functionName, optionalCallbackFunctionName, optionalInput);

تنفّذ الطريقة executeInParallel دالة يتم تحديدها من خلال functionName. في كل ManagedAccount لأن ManagedAccountSelector تطابق. بعد معالجة جميع الحسابات، يتم تنفيذ دالة الاستدعاء مرة واحدة، إذا كانت محددة بواسطة optionalCallbackFunctionName، مع تمرير قائمة بعناصر ExecutionResult كوسيطة لها لإجراء أي معالجة أخرى. يتم عرض معدّل الاستخدام المعتاد أدناه:

function main() {
  const accountSelector = AdsManagerApp.accounts()
      .withLimit(50)
      .withCondition('customer_client.currency_code = "USD"');

  accountSelector.executeInParallel("processClientAccount", "afterProcessAllClientAccounts");
}

function processClientAccount() {
  const clientAccount = AdsApp.currentAccount();

  // Process your client account here.
  ...

  // optionally, return a result, as text.
  return "";
}

function afterProcessAllClientAccounts(results) {
  for (const result of results) {
    // Process the result further
    ...
  }
}

يمكن للدالة التي تحدّدها الدالة functionName قبول سلسلة بشكل اختياري. الوسيطة (optionalInput). يمكن استخدام هذه المعلمة لتمرير علامة معلَمة إلى جميع الطرق المتوازية التي تستدعيها executeInParallel:

function main() {
  const accountSelector = AdsManagerApp.accounts().withIds([1234567890, 3456787890]);
  const sharedParameter = "INSERT_SHARED_PARAMETER_HERE";
  accountSelector.executeInParallel("processClientAccount", null, sharedParameter);
}

function processClientAccount(sharedParameter) {
  // Process your client account here.
  ...
}

إذا أردت تمرير كائن تهيئة JavaScript يحتوي على الحساب، يمكنك أولاً تحويله إلى سلسلة باستخدام JSON.stringify :

function main() {
  ...
  const accountFlags = {
    '1234567890': {
       'label': 'Brand 1 campaigns',
     },
    '3456787890': {
       'label': 'Brand 2 campaigns',
     }
  };
  accountSelector.executeInParallel("processClientAccount", null,
      JSON.stringify(accountFlags));
  ...
}

function processClientAccount(sharedParameter) {
  const accountFlags = JSON.parse(sharedParameter);
  // Process your client account here.
  ...
}

يمكن للدالة المحدّدة بواسطة functionName أيضًا عرض سلسلة بدلاً من عنصر من خلال JSON.stringify:

function processClientAccount() {
  ...
  const jsonObj = {value: 10, list: [1,2,3,4,5,6], name: "Joe Smith"};
  return JSON.stringify(jsonObj);
}

يتم تمرير القيم المعروضة إلى وظيفة ردّ الاتصال في قائمة بكائنات ExecutionResult . إذا عرضت سلسلة JSON من الدالة، يمكنك تحويلها مجددًا إلى عنصر JavaScript باستخدام JSON.parse الطريقة:

function callbackFunctionName(results) {
  for (var i = 0; i < results.length; i++) {
    var resultObj = JSON.parse(results[i].getReturnValue());
  }
}

تشير رسالة الأشكال البيانية executeInParallel تعمل الطريقة بحد أقصى 50 accounts، لذلك سيتعين عليك تنفيذ القيود الخاصة بك للحد من عدد الحسابات التي يستردها النص البرمجي. يمكنك استخدام الأسلوب withLimit أو withIds في فئة ManagedAccountSelector لحصر عدد الحسابات التي يسترجعها النص البرمجي.

الحدود الزمنية لتنفيذ الإجراءات

راجع هذه الصفحة لـ تفاصيل عن حدود مدة تنفيذ النصوص البرمجية في "مدير إعلانات Google".