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

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

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

برای جزئیات درباره محدودیت‌های زمانی اجرای اسکریپت‌های «مدیر آگهی‌ها»، سند محدودیت‌ها را ببینید.