Microsoft Advertising Scripts

https://learn.microsoft.com/en-us/advertising/scripts/
Admin
Documentation for Microsoft Advertising Scripts, a JavaScript-based scripting platform for...
Tokens:160,583
Snippets:1,814
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Select and Switch Accounts in Microsoft Advertising Scripts

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/accountsapp

This example demonstrates how to get the currently processed account, select a different account by its ID, perform operations with the new account, and then switch back to the original account.

```javascript
    // Get the account that the script is currently processing.
    var oldAccount = AdsApp.currentAccount();

    // Get another account that the user manages.
    var newAccount = AccountsApp.accounts()
        .withIds(["123456789"])
        .get()
        .next();

    // Make the new account the current account that the script processes.
    AccountsApp.select(newAccount);

    // Do something with the new account

    // Change the current account back to the old account
    AccountsApp.select(oldAccount);

```

--------------------------------

### getStartDate

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroup

Get the date when ads in this ad group start serving.

```APIDOC
## getStartDate

### Description
Get the date when ads in this ad group start serving.

### Method
Not applicable (SDK method)

### Returns
#### Success Response
- **BingAdsDate** - The date when ads in this ad group start serving.
```

--------------------------------

### withStartDate (Object)

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroupbuilder

Sets the date when ads in the ad group start serving. Call this method only if you want ads in the group to start serving on a specific date; otherwise, ads start serving immediately.

```APIDOC
## withStartDate(Object startDate)

### Description
Sets the date when ads in the ad group start serving. Call this method only if you want ads in the group to start serving on a specific date; otherwise, ads start serving immediately.

### Arguments
* **startDate** (Object) - The date to start serving ads. Specify the date using an object with the following fields: year, month, day.

### Returns
* **AdGroupBuilder** - Ad group builder with the start date applied.
```

--------------------------------

### withStartDate (string)

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroupbuilder

Sets the date when ads in the ad group start serving. Call this method only if you want ads in the group to start serving on a specific date; otherwise, ads start serving immediately.

```APIDOC
## withStartDate(string startDate)

### Description
Sets the date when ads in the ad group start serving. Call this method only if you want ads in the group to start serving on a specific date; otherwise, ads start serving immediately.

### Arguments
* **startDate** (string) - The date to start serving ads. Specify the date in the form, YYYYMMDD.

### Returns
* **AdGroupBuilder** - Ad group builder with the start date applied.
```

--------------------------------

### get

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/userlistselector

Gets an iterator used to iterate through the list of user lists. This is the primary method to start retrieving user lists.

```APIDOC
## get

### Description
Gets an iterator used to iterate through the list of user lists.

### Returns
#### Success Response
- **UserListIterator** - An iterator used to iterate through the selected user lists.
```

--------------------------------

### Set Ad Group Start Date with String

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroup

Sets the date when ads in an ad group start serving, specified as a YYYYMMDD string. Ads start immediately if no start date is set.

```javascript
ad_group.setStartDate("20180513");
```

--------------------------------

### Set Ad Group Start Date with Object

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroup

Sets the date when ads in an ad group start serving, using a date object. Ads start immediately if no start date is set.

```javascript
var date = {year: 2018, month: 5, day: 13};
ad_group.setStartDate(date);
```

--------------------------------

### GET Request with Authorization Header

Source: https://learn.microsoft.com/en-us/advertising/scripts/examples/fetch-resources

When a resource requires authentication, specify the `headers` parameter in the `fetch` method. This example demonstrates setting an `Authorization` header with a Bearer token.

```javascript
    var token = "<the oauth token goes here>";
    var response = UrlFetchApp.fetch('https://contoso.com', { headers: { Authorization: `Bearer ${token}` } });    
    var jsonObject = JSON.parse(response.getContentText());    
```

--------------------------------

### Simple GET Request

Source: https://learn.microsoft.com/en-us/advertising/scripts/examples/fetch-resources

Use `fetch(url)` for basic GET requests to retrieve a web resource. The response can be read using methods like `getContentText()`.

```javascript
    var response = UrlFetchApp.fetch('https://www.contoso.com');
```

--------------------------------

### Get and Iterate Through Accounts

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/bingadsaccountselector

This snippet demonstrates how to retrieve a list of accounts using a condition and then iterate through them. Use `withCondition` to filter accounts and `get` to obtain an iterator.

```javascript
    var accounts = AccountsApp.accounts()
        .withCondition("Name CONTAINS_IGNORE_CASE 'PARTIAL ACCOUNT NAME GOES HERE'")
        .get();

    while (accounts.hasNext()) {
        var account = accounts.next();
    }
```

--------------------------------

### fetch(string url)

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/urlfetchapp

Gets a resource from the web using an HTTP GET request. This method waits until the request completes.

```APIDOC
## fetch(string url)

### Description
Gets a resource from the web. This is the equivalent of an HTTP GET request. This method waits until the request completes.

### Arguments
#### url
- **url** (string) - Required - The URL of the web resource to get. Supports HTTP and HTTPS requests. The URL may include query parameters.

### Returns
#### HTTPResponse
- **HTTPResponse** - Contains the methods for getting the response's payload and status code.
```

--------------------------------

### withLimit

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/keywordselector

Gets the top _n_ keywords that match the selection criteria.

```APIDOC
## withLimit(int limit)

### Description
Gets the top _n_ keywords that match the selection criteria.

### Arguments
#### Path Parameters
* **limit** (int) - Required - The number of keywords to return. The actual number may be less.

### Returns
#### Success Response
* **KeywordSelector** - Selector with limit applied.
```

--------------------------------

### OneDrive OAuth Grant Code URL Example

Source: https://learn.microsoft.com/en-us/advertising/scripts/examples/fetch-resources

This is an example of the URL that will appear in the browser's address bar after successful authentication. You need to extract the 'code' parameter value from this URL.

```URL
https://login.live.com/oauth20_desktop.srf?code=M7ab570e5-a1c0-32e5-a946-e4490c822954&lc=1033

```

--------------------------------

### getDescription

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/label

Gets the label's description.

```APIDOC
## getDescription

### Description
Gets the label's description.

### Returns
* **string** - The label's description.
```

--------------------------------

### getValue()

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/producttype

Gets the product type's value.

```APIDOC
## getValue

### Description
Gets the product type's value.

### Returns
Type: string
Description: The product type's value.
```

--------------------------------

### getValue

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/productcategory

Gets the product's category name.

```APIDOC
## getValue

### Description
Gets the product's category name.

### Returns
- **string** - The product's category name.
```

--------------------------------

### Batch Create Keywords Efficiently

Source: https://learn.microsoft.com/en-us/advertising/scripts/concepts/builders

This example shows the recommended approach for creating multiple keywords by queuing all build operations first and then processing them in batches. This improves performance by avoiding immediate processing of each request.

```javascript
    // An array to hold the operations, so you 
    // can process them after all the entities are queued.
    var operations = []; 

    // Create all the new entities.
    for (var i = 0; i < keywords.length; i++) {
        var keywordOperation = AdsApp.adGroups().get().next()
          .newKeywordBuilder()
          .withText(keywords[i])
          .build();
        operations.push(keywordOperation);
    }

    // Now call the operation method so the build requests
    // get processed in batches.
    for (var i = 0; i < operations.length; i++) {
        var newKeyword = operations[i].getResult();
    }


```

--------------------------------

### Preview Mode Keyword Addition Example

Source: https://learn.microsoft.com/en-us/advertising/scripts/concepts/preview-mode

This script demonstrates how code behaves differently in preview mode versus live mode when adding a keyword. In preview mode, the keyword is not actually created, so `getId()` returns -1 and subsequent keyword retrieval yields no results.

```JavaScript
function main() {

    // Get an ad group that does not have keywords.
    var adGroup = AdsApp.adGroups()
        .withIds(["123456789"])
        .get()
        .next();

    // Add a keyword to the ad group
    var operation = adGroup.newKeywordBuilder()
        .withText('mykeyword')
        .build();

    // In preview mode, the keyword is not created, so getId() returns -1.
    if (operation.isSuccessful()) {
        var keyword = operation.getResult();
        Logger.log(`added keyword, ${keyword.getText()} (${keyword.getId()})`);
    }
    else {
        for (var error in operation.getErrors()) {
            Logger.log(`Error adding keyword, ${error}.`);
        }
    }

    // Get the ad group's keywords. In preview mode,
    // the keyword is not created, so no keywords are logged.
    var keywords = AdsApp.keywords()
        .withCondition(`AdGroupName CONTAINS '${adGroup.getName()}'`)
        .get();

    while (keywords.hasNext()) {
        var keyword = keywords.next();
        Logger.log(`added keyword, ${keyword.getText()} (${keyword.getId()})`);
    }
}
```

--------------------------------

### Get All Ad Groups

Source: https://learn.microsoft.com/en-us/advertising/scripts/guides/single-account-access

Use the AdsApp.adGroups().get() method to retrieve all ad groups in the account. This is the starting point for accessing entities.

```javascript
    var iterator = AdsApp.adGroups().get();
```

--------------------------------

### KeywordBuilder Example

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/keywordbuilder

Demonstrates how to use the KeywordBuilder to create a new keyword with specified text, CPC bid, and final URL. It also shows how to check for operation success and log errors.

```APIDOC
## KeywordBuilder

This class provides methods to define and create keywords.

### Example Usage
```javascript
var operation = adGroup.newKeywordBuilder()
    .withText("KEYWORD TEXT GOES HERE")
    .withCpc(0.5)
    .withFinalUrl("http://www.contoso.com")
    .build();

if (!operation.isSuccessful()) {
    for (var error of operation.getErrors()) {
        Logger.log(`${error}\n`);
    }
}
```

## Methods

### `build()`

Creates the keyword and returns an operation object used to check whether the keyword was successfully added.

*   **Returns**: `KeywordOperation` - An operation object used to check whether the keyword was successfully added.

### `withCpc(double cpc)`

Sets the keyword's maximum CPC bid.

Specifies the bid amount to use when the keyword matches the user's search term. Applies only if the ad group's bidding strategy is set to MANUAL_CPC.

*   **Arguments**:
    *   `cpc` (double) - The maximum CPC bid to apply to the keyword. The account's currency determines the minimum and maximum bid values.
*   **Returns**: `KeywordBuilder` - Keyword builder with the CPC bid applied.

### `withCustomParameters(Object customParameters)`

Sets the keyword's custom parameters.

Custom parameters are helpful with sharing dynamic information across multiple URLs.

*   **Arguments**:
    *   `customParameters` (Object) - A map of up to custom parameters to apply to the keyword's final URL. For example, `{key1: 'value1', key2: 'value2', key3: 'value3'}`. The name may contain a maximum of 16 8-byte characters and the value may contain a maximum of 200 8-byte characters.
*   **Returns**: `KeywordBuilder` - Keyword builder with the custom parameters applied.

### `withFinalUrl(string finalUrl)`

Sets the keyword's final URL.

The final URL identifies the webpage that the user is taken to when they click the ad. If not specified, the entity inherits the final URL from its parent entity.

*   **Arguments**:
    *   `finalUrl` (string) - The final URL that identifies the webpage the user is taken to when they click the ad.
*   **Returns**: `KeywordBuilder` - Keyword builder with the final URL applied.

### `withMobileFinalUrl(string mobileFinalUrl)`

Sets the keyword's final URL for mobile devices.

*   **Returns**: `KeywordBuilder` - Keyword builder with the mobile final URL applied.

### `withText(string text)`

Sets the keyword's text.

*   **Arguments**:
    *   `text` (string) - The text of the keyword.
*   **Returns**: `KeywordBuilder` - Keyword builder with the text applied.

### `withTrackingTemplate(string trackingTemplate)`

Sets the keyword's tracking template.

*   **Returns**: `KeywordBuilder` - Keyword builder with the tracking template applied.
```

--------------------------------

### Example Usage

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/negativekeywordlistselector

Demonstrates how to use the NegativeKeywordListSelector to retrieve and process negative keyword lists, including filtering by count and ordering by name.

```JavaScript
var iterator = AdsApp.negativeKeywordLists()
    .withCondition("MemberCount > 10")
    .orderBy("Name")
    .get();

while (iterator.hasNext()) {
    var nkwList = iterator.next();
}
```

--------------------------------

### getValue

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/productchannelexclusivity

Gets the product's channel exclusivity name.

```APIDOC
## getValue

### Description
Gets the product's channel exclusivity name.

### Returns
- **string** (string) - The product's channel exclusivity name. This is the same value that the getChannelExclusivity method returns.
```

--------------------------------

### Inefficiently Create Keywords in a Loop

Source: https://learn.microsoft.com/en-us/advertising/scripts/concepts/builders

This example demonstrates an inefficient way to create keywords by calling `getResult()` within the same loop used for building. This forces immediate processing of each request, negating batching performance gains.

```javascript
    for (var i = 0; i < keywords.length; i++) {
        var keywordOperation = AdsApp.adGroups().get().next()
          .newKeywordBuilder()
          .withText(keywords[i])
          .build();

        // Don't get results in the same loop that creates
        // the entity because Scripts then only processes one
        // entity at a time.
        var newKeyword = keywordOperation.getResult();
    }


```

--------------------------------

### get

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/bingadsaccountselector

Retrieves an iterator that can be used to loop through the list of selected accounts.

```APIDOC
## get()

### Description
Gets an iterator used to iterate through the list of accounts.

### Returns
BingAdsAccount - An iterator used to iterate through the selected accounts.
```

--------------------------------

### Initialize Configuration for Broken URL Checker

Source: https://learn.microsoft.com/en-us/advertising/scripts/solutions/check-ad-keyword-urls

Sets up essential configuration variables for the script, including notification recipients, the entity type to check (Ads or Keywords), file names for data storage, batch size, and options for email notifications and including inactive entities. Replace placeholder email addresses with your own.

```javascript
// Add a comma-delimited list of email addresses that should receive the 
// notification email
const NOTIFY = ['someone@example.com'];

// Set this value to 'Ad' to check ad URLs or 'Keyword' to check keyword URLs
const ENTITY_NAME = 'Ad'; // Valid values: 'Ad', 'Keyword'

const SCRIPT_NAME = `Microsoft Advertising - ${ENTITY_NAME} URL Checker`;
const ACCOUNTS_FILE_NAME = `MicrosoftAds-Scripts-Broken${ENTITY_NAME}Urls-AccountList.json`;
const SPREADSHEET_PREFIX = `MicrosoftAds-Scripts-Broken${ENTITY_NAME}Urls`;
const ACCOUNT_BATCH_SIZE = 50;

// Set this value to true to get an email even if no broken URLs were found
const SEND_EMAIL_EVEN_IF_NO_BROKEN_URLS_FOUND = false;

// Set this value to true to include inactive entities in the check
const INCLUDE_INACTIVE_ENTITIES = false;

// Add custom response checks to this function if needed
const checkResponse = function (url, response, entity) {
/*
  var responseText = response.getContentText();

  if (responseText.includes('out of stock')) {
    return { isGood: false, error: 'Received out of stock response' };
  }
*/
  return { isGood: true };
}

// See this page to get Google credentials: https://learn.microsoft.com/advertising/scripts/examples/authenticating-with-google-services
// If you chose option 1 in Getting an access token, set accessToken to 
// the token you received from Google OAuth playground. Otherwise, if you
// chose option 2, set clientId, clientSecret, and refreshToken.

const credentials = {
  accessToken: '',
  clientId: '',
  clientSecret: '',
  refreshToken: ''
};

function main() {
  const remainingQuota = UrlFetchApp.getRemainingDailyQuota();

  if (remainingQuota < 50) {
    Logger.log(`Remaining URL fetch quota ${remainingQuota} is not enough to run this script now`);

    return;
  }

  // If it's the first time the script has run, the function creates
  // the JSON file. The file contains a list of JSON objects.
  // Each object contains an account ID field (id) and a time
  // stamp field (lastChecked) when the account was last checked
  // for broken URLs.

  createFileIfNotExists(ACCOUNTS_FILE_NAME, false);

  // Load the list of objects from the JSON file, or if the file is empty,
  // set the list to empty.

  const accountsList = loadObject(ACCOUNTS_FILE_NAME) || [];

```

--------------------------------

### get

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/labelselector

Gets an iterator used to iterate through the list of labels.

```APIDOC
## get

### Description
Gets an iterator used to iterate through the list of labels.

### Returns
#### LabelIterator
An iterator used to iterate through the selected labels.
```

--------------------------------

### Create a Responsive Search Ad

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/responsivesearchadbuilder

This snippet demonstrates how to initialize the ResponsiveSearchAdBuilder, set the final URL, and build the ad. It includes error handling for the ad creation operation.

```javascript
    var operation = adGroup.newAd().responsiveSearchAdBuilder()
        .withFinalUrl('LANDING PAGE URL GOES HERE')
        .build();

    // See the Builders topic for performance considerations
    // when using the operation object's methods.
    if (!operation.isSuccessful()) {
        for (var error of operation.getErrors()) {
            Logger.log(`${error}\n`);
        }
    }


```

--------------------------------

### List account labels with conditions and limits

Source: https://learn.microsoft.com/en-us/advertising/scripts/examples/labels

Demonstrates how to retrieve labels from an account using various conditions and limits. It shows how to get all labels, filter by name, set a limit, and combine filtering with limits.

```JavaScript
function main() {

    // Gets all the labels in the account
    var accountLabels = AdsApp.labels()
        .get();  
    
    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    // Gets all the labels in the account that contain foo in the name
    accountLabels = AdsApp.labels()
        .withCondition("Name CONTAINS 'foo'")
        .get();
    
    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    // Gets the first 15 labels in the account
    accountLabels = AdsApp.labels()
        .withLimit(15)
        .get();
    
    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    // Gets the first 15 labels in the account that contain foo in the name
    accountLabels = AdsApp.labels()
        .withCondition("Name CONTAINS 'foo'")
        .withLimit(15)
        .get();

    Logger.log(`selector returned ${accountLabels.totalNumEntities()} labels that matched the selector's conditions`);

    while (accountLabels.hasNext()){
        var label = accountLabels.next();
    }

}
```

--------------------------------

### newAd

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroup

Gets an object that contains methods for getting ad builders.

```APIDOC
## newAd

### Description
Gets an object that contains methods for getting ad builders.

### Method
Not applicable (SDK method)

### Returns
#### Success Response
- **AdBuilderSpace** - An object containing methods for getting ad builders.
```

--------------------------------

### Create a Single Keyword Using Builder and Operation

Source: https://learn.microsoft.com/en-us/advertising/scripts/concepts/builders

This example demonstrates creating a single keyword using the `newKeywordBuilder` and checking its success with the `isSuccessful` method. Use this flow for creating one or a few entities.

```javascript
    // Gets the first ad group in the account.
    var adGroup = AdsApp.adGroups().get().next();

    // Use the 'with' methods to specify the keyword's property values.
    // The .build() method adds the build request to the build queue.
    var keywordOperation = adGroup.newKeywordBuilder()
        .withCpc(1.2)
        .withText("shirts")
        .withFinalUrl("https://www.contoso.com/shirts")
        .build();

    // Call isSuccessful() to determine if the build succeeded.
    // Calling any of the operation object's method processes the
    // build request immediately. 
    if (keywordOperation.isSuccessful()) {
        // You only need to call getResult if you need to access
        // the new keyword entity.
        var keyword = keywordOperation.getResult();
    } else {
        // Handle the errors.
        for (var error of keywordOperation.getErrors()) {
            Logger.log("${error}\n");
        }
    }


```

--------------------------------

### Get Ad Iterator with get

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adselector

Retrieves an iterator to loop through the selected ads. This is typically used after applying selection criteria.

```javascript
var iterator = adSelector.get();
```

--------------------------------

### NegativeKeywordListBuilder Usage

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/negativekeywordlistbuilder

Demonstrates how to use the NegativeKeywordListBuilder to create a new negative keyword list with a specified name. It also shows how to check the success of the operation and log any errors.

```APIDOC
## NegativeKeywordListBuilder

This builder allows for the definition and creation of negative keyword lists.

### Methods

*   **`withName(string name)`**: Sets the name of the negative keyword list.
    *   **Arguments**:
        *   `name` (string): The name of the negative keyword list. Maximum 255 characters.
    *   **Returns**:
        *   `NegativeKeywordListBuilder`: The builder with the name applied.

*   **`build()`**: Creates the negative keyword list.
    *   **Returns**:
        *   `NegativeKeywordListOperation`: An operation object to check the success of the list creation.

### Example Usage
```javascript
var operation = AdsApp.newNegativeKeywordListBuilder()
    .withName("NKW NAME GOES HERE")
    .build();

if (!operation.isSuccessful()) {
    for (var error of operation.getErrors()) {
        Logger.log(`${error}\n`);
    }
}
```
```

--------------------------------

### enable

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/campaign

Enables this campaign.

```APIDOC
## enable

### Description
Enables this campaign.

### Returns
* **void** - Returns nothing.
```

--------------------------------

### Get Account Performance Stats

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/bingadsaccountstats

Retrieves performance statistics for an account over a specified date range. Use this to get metrics like conversion rate, conversions, and cost.

```javascript
    var account = AccountsApp.accounts()
        .forDateRange("LAST_WEEK")
        .get()
        .next();

    var stats = account.getStats();
    var conversionRate = stats.getConversionRate();
    var convertedClicks = stats.getConversions();
    // etc.

```

--------------------------------

### Chaining get() directly to selector methods

Source: https://learn.microsoft.com/en-us/advertising/scripts/concepts/selectors

You can chain the get() method directly to the selector methods to retrieve entities in a single statement. This combines selector definition and retrieval.

```javascript
var campaigns = AdsApp.campaigns()
    .withCondition("ClickConversionRate > 0.5")
    .withCondition("Cost > 4.0")
    .forDateRange("LAST_WEEK")
    .withLimit(10)
    .get();
```

--------------------------------

### enable

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/ad

Enables this ad.

```APIDOC
## enable()

### Description
Enables this ad.

### Returns
#### Success Response
- void - Returns nothing.
```

--------------------------------

### Retrieving entities using get() after creating a selector

Source: https://learn.microsoft.com/en-us/advertising/scripts/concepts/selectors

Call the get() method on a selector to retrieve an iterator for the selected entities. This is done after defining all filter and sort criteria.

```javascript
var campaigns = selector.get();
```

--------------------------------

### withLimit

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/negativekeywordlistselector

Gets the top _n_ negative keywords lists that match the selection criteria.

```APIDOC
## withLimit(int limit)

### Description
Gets the top _n_ negative keywords lists that match the selection criteria.

### Arguments
* **limit** (int) - Required - The number of negative keywords lists to return. The actual number may be less.

### Returns
* **NegativeKeywordListSelector** - Selector with limit applied.
```

--------------------------------

### Get and Iterate Negative Keyword Lists

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/negativekeywordlistselector

This snippet demonstrates how to get an iterator for negative keyword lists, apply a condition to filter them (MemberCount > 10), order them by name, and then iterate through the results.

```javascript
    var iterator = AdsApp.negativeKeywordLists()
        .withCondition("MemberCount > 10")
        .orderBy("Name")
        .get();

    while (iterator.hasNext()) {
        var nkwList = iterator.next();
    }
```

--------------------------------

### ResponsiveSearchAdBuilder Methods

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/responsivesearchadbuilder

Methods for configuring Responsive Search Ads.

```APIDOC
## withCustomParameters(customParameters: Object)

### Description
Applies custom parameters to the ad's final URL.

### Arguments
#### customParameters (Object) - Required
A map of up to custom parameters to apply to the ad's final URL. The name may contain a maximum of 16 8-byte characters and the value may contain a maximum of 200 8-byte characters.

### Returns
ResponsiveSearchAdBuilder - Ad builder with the custom parameters applied.

## withDescriptions(descriptions: AdTextAsset[])

### Description
Sets the ad's descriptions.

### Arguments
#### descriptions (AdTextAsset[]) - Required
The ad's descriptions. For information about limits and including dynamic text strings, see Bing Ads API.

### Returns
ResponsiveSearchAdBuilder - Ad builder with the descriptions applied.

## withFinalUrl(finalUrl: string)

### Description
Sets the ad's landing page URL.

### Arguments
#### finalUrl (string) - Required
The ad's landing page URL. For information about URL limits, see Bing Ads API.

### Returns
ResponsiveSearchAdBuilder - Ad builder with the final URL applied.

## withFinalUrlSuffix(finalUrlSuffix: string)

### Description
Sets the ad's final URL suffix.

### Arguments
#### finalUrlSuffix (string) - Required
The ad's final URL suffix. For information about URL limits, see Bing Ads API.

### Returns
ResponsiveSearchAdBuilder - Ad builder with the final URL applied.

## withHeadlines(headlines: Object[])

### Description
Sets the ad's headlines.

### Arguments
#### headlines (Object[]) - Required
The ad's headlines. For information about limits and including dynamic text strings, see Bing Ads API.

### Returns
ResponsiveSearchAdBuilder - Ad builder with the ad's headlines applied.

## withMobileFinalUrl(mobileFinalUrl: string)

### Description
Sets the ad's final URL for mobile devices.

### Arguments
#### mobileFinalUrl (string) - Required
The final URL for mobile devices. For more information, see What tracking or URL parameters can I use?

### Returns
ResponsiveSearchAdBuilder - Ad builder with the mobile final URL applied.

## withPath1(urlPath1: string)

### Description
Sets the first optional path to append to the ad's display URL.

### Arguments
#### urlPath1 (string) - Required
The first optional path to append to the ad's display URL. For usage and limits, see Path1.

### Returns
ResponsiveSearchAdBuilder - Ad builder with the path applied.

## withPath2(urlPath2: string)

### Description
Sets the second optional path to append to the ad's display URL.

### Arguments
#### urlPath2 (string) - Required
The second optional path to append to the ad's display URL. For usage and limits, see Path2.

### Returns
ResponsiveSearchAdBuilder - Ad builder with the path applied.

## withTrackingTemplate(trackingTemplate: string)

### Description
Sets the ad's tracking template.

### Arguments
#### trackingTemplate (string) - Required
The tracking template to use with this ad. For more information, see What tracking or URL parameters can I use?

### Returns
ResponsiveSearchAdBuilder - Ad builder with the tracking template applied.
```

--------------------------------

### Initialize and Sort Accounts List

Source: https://learn.microsoft.com/en-us/advertising/scripts/solutions/check-ad-keyword-urls

Initializes the accounts list if it's empty by fetching all accessible accounts. It then sorts the list to process unprocessed or oldest accounts first. The updated list is saved to a file.

```javascript
if (accountsList.length === 0) {
    const accounts = AccountsApp.accounts().get();

    while (accounts.hasNext()) {
      const account = accounts.next();

      accountsList.push({
        id: account.getAccountId(),
        lastChecked: '',
        lastCheckedId: '0'
      });
    }
  }

  accountsList.sort((a, b) => a.lastChecked.localeCompare(b.lastChecked));

  saveObject(accountsList, ACCOUNTS_FILE_NAME);
```

--------------------------------

### Get Expanded Text Ad Builder

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adbuilderspace

Use this method to get a builder for creating an expanded text ad. This is useful when you need to programmatically add new expanded text ads to an ad group.

```javascript
    var builder = adGroup.newAd().expandedTextAdBuilder();
```

--------------------------------

### UserList Methods

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/userlist

Provides an overview of the methods available for managing UserLists.

```APIDOC
## UserList Methods

This section details the methods for managing a user list.

### Methods

| Method Name | Return Type | Description |
|---|---|---|
| getDescription | string | Gets this user list's description. |
| getEntityType | string | Gets this entity's type, which is UserList. |
| getId | string | Gets the ID that uniquely identifies this user list. |
| getMembershipLifeSpan | int | Gets how far back in time (number of days) Microsoft Advertising should look for actions that match this user list definition. |
| getName | string | Gets this user list's name. |
| getSizeForAudienceNetwork | long | Gets this user list's size in the Audience network. |
| getSizeForSearch | long | Gets this user list's size in the Search network. |
| getType | string | Gets this user list's type. |
| setDescription(string description) | void | Sets this user list's description. |
| setMembershipLifeSpan(int membershipLifeSpan) | void | Sets how far back in time (number of days) Microsoft Advertising should look for actions that match this user list definition. |
| setName(string name) | void | Sets this user list's name. |
| targetedAdGroups | AdGroupSelector | Gets a selector used to filter the list of ad groups targeted by the user list. |

## getDescription

Gets the user list's description.

### Returns

| Type | Description |
|---|---|
| string | The user list's description. |

## getEntityType

Gets this entity's type.

### Returns

| Type | Description |
|---|---|
| string | This entity's type, which is _UserList_. |

## getId

Gets the ID that uniquely identifies this user list.

### Returns

| Type | Description |
|---|---|
| string | The ID that uniquely identifies this user list. |

## getMembershipLifeSpan

Gets how far back in time (number of days) Microsoft Advertising should look for actions that match this user list definition.

### Returns:

| Type | Description |
|---|---|
| string | The user list's membership life span (number of days). |

## getName

Gets this user list's name.

### Returns:

| Type | Description |
|---|---|
| string | The user list's name. |

## getSizeForAudienceNetwork

Gets this user list's size in the Audience network.

### Returns:

| Type | Description |
|---|---|
| long | The user list's size in the Audience network. |

## getSizeForSearch

Gets this user list's size in the Search network.

### Returns:

| Type | Description |
|---|---|
| long | The user list's size in the Search network. |

## getType

Gets this user list's type.

### Returns:

| Type | Description |
|---|---|
| string | The user list's type. |

## setDescription(string description)

Sets this user list's description.

### Arguments

| Name | Type | Description |
|---|---|---|
| description | string | The user list's description. |

### Returns

| Type | Description |
|---|---|
| void | Returns nothing. |

## setMembershipLifeSpan(string membershipLifeSpan)

Sets how far back in time (number of days) Microsoft Advertising should look for actions that match this user list definition.

### Arguments

| Name | Type | Description |
|---|---|---|
| membershipLifeSpan | string | The user list's membership life span (number of days). |

### Returns

| Type | Description |
|---|---|
| void | Returns nothing. |

## setName(string name)

Sets this user list's name.

### Arguments

| Name | Type | Description |
|---|---|---|
| name | string | The user list's name. |

### Returns

| Type | Description |
|---|---|
| void | Returns nothing. |

## targetedAdGroups

Gets a selector used to filter the list of ad groups targeted by the user list.

### Returns

| Type | Description |
|---|---|
| AdGroupSelector | A selector used to filter the list of ad groups targeted by the user list. |

```

--------------------------------

### getText

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/keyword

Gets the keyword's text.

```APIDOC
## getText

### Description
Gets the keyword's text.
```

--------------------------------

### setStartDate(string startDate)

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroup

Sets the date when ads in this ad group begin serving.

```APIDOC
## setStartDate(string startDate)

### Description
Sets the date when ads in this ad group begin serving.

### Method
Not applicable (SDK method)

### Parameters
#### Path Parameters
- **startDate** (string) - Required - The date when ads should start serving.
```

--------------------------------

### getCampaign

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/keyword

Gets the campaign that this keyword belongs to.

```APIDOC
## getCampaign

### Description
Gets the campaign that this keyword belongs to.

### Returns
* **Campaign** - The campaign that this keyword belongs to.
```

--------------------------------

### getDescriptions()

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/responsivesearchad

Retrieves the descriptions associated with the responsive search ad.

```APIDOC
## getDescriptions()

### Description
Gets this ad's descriptions.

### Returns
AdTextAsset[] - An array of ad descriptions.
```

--------------------------------

### getName

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/label

Gets the label's name.

```APIDOC
## getName

### Description
Gets the label's name.

### Returns
* **string** - The label's name.
```

--------------------------------

### Get All Keywords in an Account with Error Handling

Source: https://learn.microsoft.com/en-us/advertising/scripts/examples/keywords

Fetches all keywords at the account level, with a fallback to fetching by campaign if the account has too many keywords. This is useful for handling large accounts.

```javascript
function* getEntities() {
    const applyConditions = _ => _
        .withCondition('CampaignStatus = ENABLED')
        .withCondition('AdGroupStatus = ENABLED')
        .withCondition('Status = ENABLED')
        .withCondition("CombinedApprovalStatus = DISAPPROVED");

    try {
        // Get the account's keywords. 
        const keywords = applyConditions(AdsApp.keywords()).get();

        while (keywords.hasNext()) {
            yield keywords.next();
        }
    } catch (e) {
        if (!e.message.startsWith('There are too many entities')) {
            throw e;
        }

        // If there are too many keywords at the account level,
        // get keywords by campaigns under the account.
        const campaigns = AdsApp.campaigns().get();

        while (campaigns.hasNext()) {
            const campaign = campaigns.next();

            const keywords = applyConditions(campaign.keywords()).get();

            while (keywords.hasNext()) {
                yield keywords.next();
            }
        }
    }
}
```

--------------------------------

### Select and Process Individual Accounts

Source: https://learn.microsoft.com/en-us/advertising/scripts/guides/multi-account-access

Demonstrates how to select specific accounts using `withIds()` and then iterate through them, selecting each one as the current account to process its entities using `AdsApp` methods.

```javascript
function main() {
    // This call logs null. Before using any
    // of the AdsApp methods, you must first
    // select an account to process.

    Logger.log(AdsApp.currentAccount());

    // Select the accounts to process

    var accounts = AccountsApp.accounts()
        .withIds(['123', '456', '789'])
        .get();

    while (accounts.hasNext()) {
        AccountsApp.select(accounts.next());

        // AdsApp is now set to the current account.
        // Do something with the account's entities.
    }
}
```

--------------------------------

### withFinalUrl

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/expandedtextadbuilder

Sets the ad's landing page URL.

```APIDOC
## withFinalUrl(string finalUrl)

### Description
Sets the ad's landing page URL.

### Arguments
#### finalUrl (string) - Required - The ad's landing page URL. For information about URL limits, see Bing Ads API.

### Returns
ExpandedTextAdBuilder - Ad builder with the final URL applied.
```

--------------------------------

### getName

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/campaign

Gets this campaign's name.

```APIDOC
## getName

### Description
Gets this campaign's name.

### Returns
* **string** - The name of the campaign.
```

--------------------------------

### withAudience Method

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroupaudiencebuilder

Sets the associated user list.

```APIDOC
## withAudience(Object userList)

### Description

Sets the associated user list.

### Arguments

- **userList** (string) - The associated user list.
```

--------------------------------

### getBudget

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/campaign

Gets this campaign's budget.

```APIDOC
## getBudget

### Description
Gets this campaign's budget.

### Returns
* **Budget** - The budget of the campaign.
```

--------------------------------

### getCampaign

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/ad

Gets the campaign that this ad belongs to.

```APIDOC
## getCampaign()

### Description
Gets the campaign that this ad belongs to.

### Returns
#### Success Response
- Campaign - The campaign that this ad belongs to.
```

--------------------------------

### enable

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroupaudience

Enables this association, making it active for ad serving.

```APIDOC
## enable

### Description
Enables this association.

### Returns
* **void**: Returns nothing.
```

--------------------------------

### getValue

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/productgroup

Gets this product group's value.

```APIDOC
## getValue

### Description
Gets this product group's value.

### Returns
- **String** - This product group's value. Returns null if this is the root group.
```

--------------------------------

### Batching Keyword Creation Operations

Source: https://learn.microsoft.com/en-us/advertising/scripts/concepts/best-practices

Use this pattern to queue keyword creation operations and process them in batches after the build loop for better performance.

```javascript
    // An array to hold the operations, so you 
    // can process them after all the entities are queued. 
    var operations = []; 

    // Create all the new entities. 
    for (var i = 0; i < keywords.length; i++) {
        var keywordOperation = AdsApp.adGroups().get().next() 
          .newKeywordBuilder() 
          .withText(keywords[i]) 
          .build(); 
        operations.push(keywordOperation); 
    } 

    // Now call the operation method so the build requests 
    // get processed in batches. 
    for (var i = 0; i < operations.length; i++) {
        var newKeyword = operations[i].getResult(); 
    } 


```

--------------------------------

### getTargetingStatus

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/targetedlocation

Gets the targeting status of this targeted location.

```APIDOC
## getTargetingStatus

### Description
Gets the targeting status of this targeted location.

### Returns
* **string** - The targeting status of this targeted location.
```

--------------------------------

### getTargetType

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/targetedlocation

Gets the target type of this targeted location.

```APIDOC
## getTargetType

### Description
Gets the target type of this targeted location.

### Returns
* **string** - The target type of this targeted location.
```

--------------------------------

### Example of using orderBy

Source: https://learn.microsoft.com/en-us/advertising/scripts/concepts/selectors

Use orderBy to sort the returned entities by a specified field. This is equivalent to a SQL ORDER BY clause.

```javascript
orderBy("Clicks DESC")
```

--------------------------------

### getName

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/targetedlocation

Gets this targeted location's name.

```APIDOC
## getName

### Description
Gets this targeted location's name.

### Returns
* **string** - The name of this targeted location.
```

--------------------------------

### Example of using withLimit

Source: https://learn.microsoft.com/en-us/advertising/scripts/concepts/selectors

Use withLimit to restrict the number of entities returned by the selector. This is similar to a SQL TOP clause.

```javascript
withLimit(50)
```

--------------------------------

### getCountryCode

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/targetedlocation

Gets the country code of this targeted location.

```APIDOC
## getCountryCode

### Description
Gets the country code of this targeted location.

### Returns
* **string** - The country code of this targeted location.
```

--------------------------------

### getCampaign

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/targetedlocation

Gets the campaign that this targeted location belongs to.

```APIDOC
## getCampaign

### Description
Gets the campaign that this targeted location belongs to.

### Returns
* **Campaign** - The campaign that this targeted location belongs to.
```

--------------------------------

### withPath1

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/expandedtextadbuilder

Sets the first optional path to append to the ad's display URL.

```APIDOC
## withPath1(string urlPath1)

### Description
Sets the first optional path to append to the ad's display URL.

### Arguments
#### urlPath1 (string) - Required - The first optional path to append to the ad's display URL. Microsoft uses the domain specified in `withFinalUrl` as the display URL. If the final URL's domain is _contoso.com_ and the path is _shoes_ , the ad's display URL is _contoso.com/shoes_. For usage and limits, see Path1.

### Returns
ExpandedTextAdBuilder - Ad builder with the path applied.
```

--------------------------------

### enable

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/keyword

Enables this keyword.

```APIDOC
## enable

### Description
Enables this keyword.

### Returns
* **void** - Returns nothing.
```

--------------------------------

### getStats

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/keyword

Gets this keyword's performance data.

```APIDOC
## getStats

### Description
Gets this keyword's performance data.
```

--------------------------------

### getQualityScore

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/keyword

Gets this keyword's quality score.

```APIDOC
## getQualityScore

### Description
Gets this keyword's quality score.
```

--------------------------------

### Iterate Through All Product Groups

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/productgroupiterator

This snippet demonstrates how to get an iterator for all product groups in an account and then loop through them using hasNext() and next().

```javascript
    // Gets the iterator that iterates all product groups
    // in the account.
    var iterator = AdsApp.productGroups().get();

    // Loops through all product groups in the account.
    while (iterator.hasNext()) {
        var group = iterator.next();
    }
}
```

--------------------------------

### setStartDate(Object startDate)

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/adgroup

Sets the date when ads in this ad group begin serving.

```APIDOC
## setStartDate(Object startDate)

### Description
Sets the date when ads in this ad group begin serving.

### Method
Not applicable (SDK method)

### Parameters
#### Path Parameters
- **startDate** (Object) - Required - The date when ads should start serving.
```

--------------------------------

### getMatchType

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/keyword

Gets this keyword's match type.

```APIDOC
## getMatchType

### Description
Gets this keyword's match type.
```

--------------------------------

### Define Main and Custom Functions in Microsoft Advertising Script

Source: https://learn.microsoft.com/en-us/advertising/scripts/concepts/main-function

This script defines a mandatory `main` function that serves as the entry point and calls a custom function `getAllCampaigns` to retrieve campaign data.

```javascript
function main() {
    getAllCampaigns();
}

function getAllCampaigns() {
  var campaigns = AdsApp.campaigns().get();
    while(campaigns.hasNext()){
        var campaign = campaigns.next();
    }
}
```

--------------------------------

### getId

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/keyword

Gets the ID that uniquely identifies this keyword.

```APIDOC
## getId

### Description
Gets the ID that uniquely identifies this keyword.
```

--------------------------------

### getDimension

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/productcategory

Gets this product group's dimension.

```APIDOC
## getDimension

### Description
Gets this product group's dimension.

### Returns
- **String** - This product group's dimension, which is set to CATEGORY.
```

--------------------------------

### Iterate Through All User Lists

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/userlistiterator

This snippet demonstrates how to get an iterator for all user lists in an account and then loop through each user list using hasNext() and next().

```javascript
    // Gets the iterator that iterates all user lists
    // in the account.
    var iterator = AdsApp.userLists().get();

    // Loops through all user lists in the account.
    while (iterator.hasNext()) {
        var userList = iterator.next();
    }

```

--------------------------------

### getCampaign

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/productcategory

Gets the campaign that this product group belongs to.

```APIDOC
## getCampaign

### Description
Gets the campaign that this product group belongs to.

### Returns
- **Campaign** - The campaign that this product group belongs to.
```

--------------------------------

### Executing the PowerShell Token Script

Source: https://learn.microsoft.com/en-us/advertising/scripts/examples/authenticating-with-google-services

This command demonstrates how to execute the saved PowerShell script from the command prompt. Ensure you are in the directory where the script was saved.

```Shell
powershell.exe -File .\GetTokens.ps1

```

--------------------------------

### Get first description of an ad (using getDescription1)

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/expandedtextad

Retrieves the first description of the ad. This method returns the same value as getDescription.

```javascript
function main() {
  var ad = AdsApp.ads() 
      .withCondition("AdGroupAd.Ad.Headline.Part1 = 'Example Headline 1'")
      .get() 
      .next();

  // Get the ad's first description.
  var description1 = ad.getDescription1();
  Logger.log("Description 1: " + description1);
}
```

--------------------------------

### parent

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/productchannel

Gets this product group's parent.

```APIDOC
## parent

### Description
Gets this product group's parent.

### Returns
* **ProductGroup**: This product group's parent.
```

--------------------------------

### getName

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/negativekeywordlist

Gets the name of this negative keyword list.

```APIDOC
## getName

### Description
Gets this negative keyword list's name.

### Returns
string - The name of this negative keyword list.
```

--------------------------------

### Iterate Through Product Groups with Conditions and Ordering

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/productgroupselector

This snippet demonstrates how to select product groups based on a click conversion rate condition, order them by clicks in descending order, and iterate through the results to access their metrics. It uses `withCondition`, `orderBy`, and `forDateRange`.

```javascript
    var iterator = AdsApp.productGroups()
        .withCondition("ClickConversionRate > 0.3")
        .forDateRange("LAST_WEEK")
        .orderBy("Clicks DESC")
        .get();

    while (iterator.hasNext()) {
        var productGroup = iterator.next();
        var metrics = productGroup.getStats();
    }
```

--------------------------------

### withDescription

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/expandedtextadbuilder

Sets the ad's first description. This method is an alias for withDescription1.

```APIDOC
## withDescription(string description)

### Description
Sets the ad's first description. For information about copy limits and including dynamic text strings, see Bing Ads API.

### Arguments
#### description (string) - Required - The ad's first description.

### Returns
ExpandedTextAdBuilder - Ad builder with the description applied.
```

--------------------------------

### getId

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/label

Gets the ID that uniquely identifies this label.

```APIDOC
## getId

### Description
Gets the ID that uniquely identifies this label.

### Returns
* **string** - The ID that uniquely identifies this label.
```

--------------------------------

### withLimit(int limit)

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/userlistselector

Gets the top _n_ user lists that match the selection criteria.

```APIDOC
## withLimit(int limit)

### Description
Gets the top _n_ user lists that match the selection criteria.

### Arguments
* **limit** (int) - Required - The number of user lists to return. The actual number may be less.

### Returns
* **UserListSelector** - Selector with limit applied.
```

--------------------------------

### getStats

Source: https://learn.microsoft.com/en-us/advertising/scripts/reference/campaign

Gets this campaign's performance data.

```APIDOC
## getStats

### Description
Gets this campaign's performance data.

### Returns
* **Stats** - The performance data of the campaign.
```
Tokens:
Raw