دستورگان‌های «مدیر آگهی‌ها»

کلاس AdsManagerApp در «دستورگان Google Ads» به شما امکان می‌دهد حساب‌های پیوندشده تحت حساب مدیر خود را مدیریت کنید. می‌توانید همه حساب‌های تبلیغ‌کننده خود را ازطریق یک اسکریپت واحد مدیریت کنید، به‌جای اینکه برای هر حساب یک اسکریپت جداگانه ایجاد کنید.

بازیابی فهرست حساب‌ها

می‌توانید حساب‌های تحت حساب مدیر را بااستفاده از روش 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 استفاده کنید تا زمینه اجرا را به حساب مشتری تغییر دهید. پس‌از انتخاب حساب مشتری، هرگونه فراخوانی API بعدی برای حساب مشتری اعمال می‌شود تا زمانی که صریحاً حساب دیگری را انتخاب کنید:

// 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 Ads به شما امکان می‌دهد بااستفاده از روش 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.
  ...
}

اگر می‌خواهید شیء پیکربندی جاوا اسکریپت را که حاوی تنظیمات مختص حساب است ارسال کنید، ابتدا می‌توانید آن را بااستفاده از روش 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 را از تابع برگردانده‌اید، می‌توانید آن را بااستفاده از روش JSON.parse دوباره به شیء جاوا اسکریپت تبدیل کنید:

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

روش executeInParallel حداکثر روی ۵۰ accounts حساب کار می‌کند، بنابراین باید محدودیت‌های خودتان را برای محدود کردن تعداد حساب‌هایی که دستورگان شما بازیابی می‌کند پیاده‌سازی کنید. می‌توانید از روش withLimit یا withIds کلاس ManagedAccountSelector برای محدود کردن تعداد حساب‌هایی که دستورات شما بازیابی می‌کند استفاده کنید.

محدودیت‌های زمانی اجرا

برای جزئیات مربوط به محدودیت‌های زمان اجرای «برنامه‌های Ads Manager»، به مستندات محدودیت‌ها مراجعه کنید.