Skip to content

Getting Started

Jump to bottom
Anash P. Oommen edited this page Sep 6, 2018 · 12 revisions

Introduction

This guide gives a brief overview of how to get started with the Ads API client libraries. Note that the code examples in this guide use AdWords API, but the code is similar for other supported APIs. Separate code snippets are given for each API when the code looks significantly different.

Understanding the Ads user classes

The most important classes in the Ads API .NET library are the AdsUser classes. AdsUser classes typically encapsulate a single account in the corresponding Ads system. For example,

  • AdWordsUser class encapsulates an AdWords account.
  • AdManagerUser class encapsulates a single Google Ad Manager account.

AdsUser allows you to create a pre-configured service class that can be used for making API calls.

Creating an Ads user instance

All the AdsUser classes provide a default constructor that creates a user object using the settings specified in your application’s App.config / Web.config. Refer to this wiki article for details on various settings supported in the client library.

// Create a new AdWordsUser with the App.config settings.
AdWordsUser user = new AdWordsUser();

Creating a service

All the AdsUser classes provide a GetService method that can be used to create an Ads service. All Ads services are derived from the AdsSoapClient class.

CampaignService campaignService = (CampaignService) user.GetService(
    AdWordsService.v201806.CampaignService);
// Now make calls to CampaignService.

We provide one AdsService class per supported API, that enumerates all the supported API versions and services. The GetService method accepts these enumeration objects as argument when creating the service.

For example, AdWordsService enumerates all the supported versions and services for the AdWords API. To create an instance of CampaignService for version v201806 of AdWords API, you need to call AdWordsUser.GetService method with AdWordsService.v201806.CampaignService as the argument, as shown earlier.

Authenticating your API calls

All the Ads APIs use OAuth2 as authentication mechanism. Refer to one of the following wiki articles depending on your use case.

Configuring the Ads user instance at runtime.

AdsUser objects are configured using AppConfig instances. There’s one AppConfig type per type of AdsUser:

  • AdWordsAppConfig configures an AdWordsUser instance
  • AdManagerAppConfig configures a AdManagerUser instance

You can use the Config property of the AdsUser object to configure that user at runtime. E.g.:

// Create a default AdWordsUser instance. If any configuration
// is available in App.config, those will be used.
AdWordsUser user = new AdWordsUser();

// Override a specific setting at runtime.
AdWordsAppConfig config = (AdWordsAppConfig) user.Config;
user.Config.clientCustomerId = "123-456-7890";

Another option is to use the constructor that accepts an AdWordsAppConfig instance. E.g.

// Create a config object with the values in App.config.
AdWordsAppConfig config = new AdWordsAppConfig();

// Override any specific setting you wish to change.
user.Config.clientCustomerId = "123-456-7890";

AdWordsUser user = new AdWordsUser(config);

Note that any configuration change you make to an AdsUser object doesn’t affect the service instances created by that AdsUser earlier. For example,

AdWordsUser user = new AdWordsUser();
CampaignService campaignService = (CampaignService) user.GetService(
    AdWordsService.v201806.CampaignService);

// Override a specific setting at runtime. This will not affect the campaignService
// instance that was created earlier.
AdWordsAppConfig config = (AdWordsAppConfig) user.Config;
user.Config.clientCustomerId = "123-456-7890";

// Create an AdGroupService instance with the updated configuration
AdGroupService adGroupService = (AdGroupService) user.GetService(
    AdWordsService.v201806.AdGroupService);

Refer to this wiki article for details on various settings supported by the client library.

Thread safety

It is not safe to share an AdsUser instance between multiple threads, since the configuration changes you make on an instance in one thread might affect the services you create on other threads. Operations like obtaining new service instances from an AdsUser instance, making calls to multiple services in parallel, etc., are thread-safe.

A multithreaded application would look something like this:

AdWordsUser user1 = new AdWordsUser();
((AdWordsAppConfig) user1.Config).clientCustomerId = "123-456-7890";

AdWordsUser user2 = new AdWordsUser();
((AdWordsAppConfig) user2.Config).clientCustomerId = "345-567-7890";

Thread userThread1 = new Thread(addAdGroups);
Thread userThread2 = new Thread(addAdGroups);

userThread1.start(user1);
userThread2.start(user2);

userThread1.join();
userThread2.join();

public void addAdGroups(object data) {
  AdWordsUser user = (AdWordsUser) data;
  // Do more operations here.
  ...
}

Handling errors

Not all API calls will succeed, the server can throw errors if your API calls will fail for some reason. It is important to capture API errors and handle them appropriately.

AdWords and Google Ad Manager APIs provide detailed error objects to help you figure out what went wrong. Here are some examples of error handling code:

AdWords API

try {
  retVal = service.mutate(operations);
} catch (AdWordsApiException e) {
  ApiException innerException = e.ApiException as ApiException;
  if (innerException == null) {
    // Failed to get ApiError. Refer to innerException properties for
    // more details.      
  }
  // Examine each ApiError received from the server.
  foreach (ApiError apiError in innerException.errors) {
  int index = ErrorUtilities.GetOperationIndex(apiError.fieldPath);
  if (index == -1) {
    // This API error is not associated with a particular operand
    // (e.g. rate exceeded error), and may require a special handling.
  } else {
    // This API error is associated with a particular operand.
    // You can either fix the operand, or remove this operand and retry
    // the API call. 
    switch (apiError.ApiErrorType) {
      case “PolicyViolationError”:
        PolicyViolationError policyError = (PolicyViolationError) apiError;
        // handle policy error.
      }
    }
  }
}

Google Ad Manager API

try {
  Network network = networkService.getCurrentNetwork();
} catch (AdManagerApiException e) {
  ApiException innerException = e.ApiException as ApiException;
  if (innerException == null) {
    // Failed to get ApiError. Refer to innerException properties for
    // more details.      
  }
  // Examine each ApiError received from the server.
  foreach (ApiError apiError in innerException.errors) {
    if (apiError is QuotaError) {
      // Handle QuotaError
    } else if (apiError is FeatureError) {
      // Handle FeatureError
    }
  }
}

Capturing Logs

SOAP logs are very useful when debugging API code since they show the exact data being sent to and received from the Ads servers. Refer to this wiki guide for details on how to capture SOAP logs.

Clone this wiki locally