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

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