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

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