اسکریپت های مدیر تبلیغات

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

بازیابی لیست حساب‌ها

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

کار موازی روی حساب‌ها

اسکریپت‌های گوگل ادز به شما امکان می‌دهند با استفاده از متد executeInParallel از کلاس ManagedAccountSelector ، روی چندین حساب کاربری به صورت موازی کار کنید. متد executeInParallel دارای امضای زیر است:

function executeInParallel(functionName, optionalCallbackFunctionName, optionalInput);

متد executeInParallel تابعی را که توسط functionName مشخص شده است، روی هر ManagedAccount که ManagedAccountSelector با آن مطابقت دارد، اجرا می‌کند. پس از پردازش تمام حساب‌ها، تابع callback، در صورتی که توسط 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 به تابع callback ارسال می‌شوند. اگر یک رشته 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، به مستندات محدودیت‌ها مراجعه کنید.