Skip to content

Working with Selectors

Jump to bottom
Anash P. Oommen edited this page May 25, 2016 · 3 revisions

When working with the AdWords API, you need to build a Selector to retrieve objects through the get() methods. The AdWords API .NET library includes various utility methods to help you build selectors easily.

Building a selector

When building a selector, you can use the object initializer syntax to initialize the selector. For instance, the following selector retrieves the id, name and status of all the campaigns in your account:

Selector selector = new Selector() {
  fields = new string[] {
    Campaign.Fields.Id, Campaign.Fields.Name, Campaign.Fields.Status
  },
  paging = Paging.Default
};

Fields

When building a selector, you need to specify selector field names that correspond to the fields you wish to retrieve. The autogenerated stub for each type contains a nested SelectableFields subclass that lists all the valid selector field values that may be used with that type. For instance, if you need to retrieve the id, name and status fields of a Campaign, you’d specify

Selector selector = new Selector() {
  fields = new string[] {
    Campaign.SelectableFields.Id,
    Campaign.SelectableFields.Name,
    Campaign.SelectableFields.Status
  },
  ...
};

Predicates

When building selectors, you can specify predicates to filter your results. The Predicate class has utility extension methods that allows you to easily build predicates. For instance, the following code snippet retrieves the id and name of all ad groups that belong to campaign ID 1234.

Selector selector = new Selector() {
  fields = new string[] { AdGroup.Fields.Id, AdGroup.Fields.Name },
  predicates = new Predicate[] {
    Predicate.Equals(AdGroup.FilterableFields.CampaignId, 1234)
  },
  ...
};

The supported predicate operators are listed below.

Method Signature Details 
Equals(string field, long value)

Equals(string field, string value)

Adds a filter to select only items where the value of field is equal to value.

 
NotEquals(string field, string value)

Adds a filter to select only items where the value of field is not equal to value.

 
In(string field, List<string> values)

In(string field, string[] values)

Adds a filter to select only items where the value of field is equal to one of the values provided in values.

 
NotIn(string field, string[] values)

Adds a filter to select only items where the value of field is not equal to any of the values provided in values.

 
GreaterThan(string field, string value)

Adds a filter to select only items where the value of field is greater than value.

 
GreaterThanEquals(string field, string value)

Adds a filter for items where the value of field is greater than or equal to value.

 
LessThan(string field, string value)

Adds a filter to select only items where the value of field is less than value.

 
LessThanEquals(string field, string value)

Adds a filter to select only items where the value of field is less than or equal to value.

 
StartsWith(string field, string value)

Adds a filter to select only items where the value of field starts with value.

 
StartsWithIgnoreCase(string field, string value)

Adds a filter to select only items where the value of field starts with value when letter case is ignored.

 
Contains(string field, string value)

Adds a filter to select only items where the value of field contains value.

 
ContainsIgnoreCase(string field, string value)

Adds a filter to select only items where the value of field contains value when lettercase is ignored.

 
DoesNotContain(string field, string value)

Adds a filter to select only items where the value of field does not contain value.

 
DoesNotContainIgnoreCase(string field, string value)

Adds a filter to select only items where the value of field does not contain value when letter case is ignored.

 
ContainsAll(string field, string[] values)

Adds a filter to select only items where the value of field contains all of the values provided in values.

 
ContainsNone(string field, string[] values)

Adds a filter to select only items where the value of field contains none of the values provided in values.

 
ContainsAny(string field, string[] values)

Adds a filter to select only items where the value of field contains any of the values provided in values.

Paging

When retrieving objects, be aware that the number of results may exceed the maximum page size. You should download the results as multiple pages whose size is below the maximum page size supported by AdWords API. The Paging class has utility methods that help you loop through the pages using the recommended page size. The following code snippet shows how this may be done.

Selector selector = new Selector() {
  fields = new string[] {
    Campaign.Fields.Id, Campaign.Fields.Name, Campaign.Fields.Status
  },
  paging = Paging.Default
};

do {
  // Get the campaigns.
  page = campaignService.get(selector);

  // Process the results.
  if (page != null && page.entries != null) {
    int i = selector.paging.startIndex;
    foreach (Campaign campaign in page.entries) {
      ...
    }
  }
  selector.paging.IncreaseOffset();
} while (selector.paging.startIndex &lt; page.totalNumEntries);

The above code snippet sets a default page size using the Paging.Default method and then and uses the IncreaseOffset() method to iterate through successive pages until all the items are retrieved.

You can use a custom page size as follows:

Selector selector = new Selector() {
  ...
  paging = new Paging() {
    startIndex = 0,
    numberResults = YOUR_CUSTOM_PAGE_SIZE
  };
};

...
selector.paging.IncreaseOffsetBy(YOUR_CUSTOM_PAGE_SIZE);

Ordering

You may also sort the results by specifying the ordering field of the selector. The OrderBy class has utility methods to simplify your code. The following selector retrieves the list of AdGroups, and sorts them by their name in ascending order.:

Selector selector = new Selector() {
  fields = new string[] { AdGroup.Fields.Id, AdGroup.Fields.Name },
  ordering = new OrderBy[] {OrderBy.Asc(AdGroup.Fields.Name)}
  ...
};

The supported methods are listed below.

Method Signature Details 
Asc(string field)

Creates an ascending sorting order to be used with a selector.

 
Desc(string field)

Creates a descending sorting order to be used with a selector.
Clone this wiki locally