Ads Manager 指令碼

Google Ads 指令碼中的 AdsManagerApp 類別可讓您管理管理員帳戶下方連結的帳戶。您可以透過單一指令碼管理所有廣告客戶帳戶，而不需要為每個帳戶建立個別指令碼。

擷取帳戶清單

您可以使用 accounts 方法擷取管理員帳戶下的帳戶，例如：

const accountSelector = AdsManagerApp.accounts()
    .withCondition('customer_client.descriptive_name = "My Account"');

const accountIterator = accountSelector.get();

可復原的帳戶有以下限制：

  • 如果您有多層階層，就無法擷取管理員帳戶。只能選取客戶帳戶。
  • 根據預設，系統不會傳回已關閉、已取消和已停權的帳戶。您可以呼叫 withCondition 來覆寫這項行為，並為 customer_client.status 指定不同的篩選器。

根據預設，accounts 呼叫會擷取管理員帳戶階層下所有客戶帳戶的清單。您可以使用 ManagedAccountSelector 類別的 withLimit 方法，限制指令碼擷取的帳戶數量。另一個選項是使用 withIds 方法，根據客戶 ID 選取帳戶：

// 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 campaigns under the client account
  const campaignIterator = AdsApp.campaigns().get();

  // Operate on client account
  ...
}

同時處理多個帳戶

Google Ads 指令碼可讓您使用 ManagedAccountSelector 類別的 executeInParallel 方法，同時對多個客戶帳戶進行操作。executeInParallel 方法的簽名如下：

function executeInParallel(functionName, optionalCallbackFunctionName, optionalInput);

executeInParallel 方法會在 ManagedAccountSelector 比對的每個 ManagedAccount 上，執行 functionName 指定的函式。處理完所有帳戶後，如果回呼函式是由 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 字串，可以使用 JSON.parse 方法將其轉換回 JavaScript 物件：

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

executeInParallel 方法最多可運作 50 個 accounts，因此您必須實作自己的限制，以限制指令碼擷取的帳戶數量。您可以使用 ManagedAccountSelector 類別的 withLimit 或 withIds 方法，限制指令碼擷取的帳戶數量。

執行時間限制

如要進一步瞭解廣告管理工具指令碼執行時間限制，請參閱這個頁面。