Discover v201008 - Track your account notifications with AlertService

When you’re managing a large number of accounts using the AdWords API you may want to retrieve account alerts. This was previously possible with AccountService in v13. The v201008 version introduces the AlertService, which brings similar functionality to the new AdWords API. This blog post discusses the differences between how alerts are retrieved using these two services.

Retrieving client account alerts

In v13, you could retrieve the alerts associated with list of client accounts linked to a My Client Center (MCC) using the getMccAlerts method of AccountService. In v201008, you can use the get method of AlertService to get the same results. The following code shows the service in action:

// Get the AlertService.
AlertService alertService = (AlertService) user.GetService(
    AdWordsService.v201008.AlertService);
 
// Create the alert query.
AlertQuery query = new AlertQuery();
query.filterSpec = FilterSpec.ALL;
query.clientSpec = ClientSpec.ALL;
query.triggerTimeSpec = TriggerTimeSpec.ALL_TIME;
query.severities = new AlertSeverity[] {AlertSeverity.GREEN,
    AlertSeverity.YELLOW, AlertSeverity.RED};

query.types = new AlertType[] {AlertType.CAMPAIGN_ENDING, 
    AlertType.CAMPAIGN_ENDED};
 
// Create the selector.
AlertSelector selector = new AlertSelector();
selector.query = query;
selector.paging = new Paging();
selector.paging.startIndex = 0;
selector.paging.numberResults = 10;

AlertPage page = alertService.get(selector);

Once you retrieve the alerts, you can display them by enumerating the page entries.

if (page != null && page.entries != null && page.entries.Length > 0) {
  Console.WriteLine("Retrieved {0} alerts out of {1}.",
      page.entries.Length, page.totalNumEntries);

  for (int i = 0; i < page.entries.Length; i++) {
    Alert alert = page.entries[i];
    Console.WriteLine("{0}) Customer Id is {1:###-###-####}, " +
        "Alert type is '{2}',Severity is {3}", i + 1, 
        alert.clientCustomerId, alert.alertType, alert.alertSeverity);
    for (int j = 0; j < alert.details.Length; j++) {
           Console.WriteLine("  - Triggered at {0}", alert.details[j].triggerTime);
    }
  }
} else {
  Console.WriteLine("No alerts were found.");
}

Differences between AccountService.getAllMccAlerts and AlertService.get

The main differences between the v13 AccountService.getAllMccAlerts and v201008 AlertService.get are in the table below.

AccountService.getAllMccAlerts	AlertService.get
Returns alerts for all the client accounts immediately under the MCC.	You can choose to retrieve alerts for all the child accounts, for immediate child accounts only, or for a specific list of customers by using the clientSpec and clientCustomerIds fields of AlertQuery.
Returns all available types of alerts for your client accounts.	Returns only the types of alerts you request in your AlertQuery.
MccAlert provides multiple fields like clientLogin, clientName and clientCustomerId to associate an alert with a customer.	Alert provides only clientCustomerId field to associate the alert with a customer.
Gives you one MccAlert object for each occurrence of the alert.	Groups alerts of the same type for a given customer as a single Alert object. You can access the alert details from the details field of the alert object.
Alert priority can be low or high.	Alert severity can be red, yellow or green.

The v201008 version of AlertService.get allows you to retrieve alerts only by predefined trigger time ranges. We plan to include support for filtering by custom date ranges in a future version of the AdWords API.

We have added support for AlertService in all of our client libraries, so please take advantage of this service and share your feedback with us on the forum.

-- Anash P. Oommen, AdWords API Team