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

تتيح لك فئة 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" البرمجية.