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

تتيح لك الفئة 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 Search and Display 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".