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 Search and Display 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 方法，限制指令碼擷取的帳戶數量。

執行時間限制

如要進一步瞭解 Ads Manager 指令碼執行時間限制，請參閱限制說明文件。