ANASH P. OOMMEN: Hi, I'm Anash P. Oommen with the Google
Developer Relations team.
This screencast will show you how to get started with the
AdWords API .NET Client Library.
The library requires Microsoft .NET runtime version 2.0.
The library also works on Mono version 2.4.4.
The library depends on the System.Configuration,
System.XML, System.Web, and System.Web.Services runtime
assemblies.
It doesn't depend on any third party assemblies.
The first thing you need to do is to download the library.
The best way to find it is to go to the AdWords API
documentation at code.google.com/apis/adwords.
From here, click on Docs, and then on Client Libraries.
And click on .Net Client Library.
This is the main project page of the AdWords
API .Net client library.
On the left-bottom side of the page are links to download the
latest version of the library.
Now click the link to download the latest
version of the library.
Once you've downloaded the library, extract it to the
folder of your choice.
The library distribution contains docs, examples in C#
and VB for various API versions, a precompiled
version of the assembly, and solution files for various
versions of Visual Studio.
Open the AdWords.sln in Visual Studio.
The solution consists of one project each for C# examples,
VB examples, and OAuth.
Both C# and VB example project consist of code examples for
all the major API versions.
OAuth code example is designed as an ASP.NET website that
retrieves all the campaigns from a user's account.
Before you can run the code examples, you need to fill in
the AdWords credential in your application's app.config or a
website's web.config.
Let's do it for AdWords.Examples.CSharp.
Open the app.config.
We will run the code examples against
the AdWords API Sandbox.
Details on how to use the AdWords API Sandbox is
available at code.google.com/ apis/adwords/docs/sandbox.html
When using the Sandbox, your client email is client_n plus
your email address, where n can be from one to five.
Your developer token is your Google account plus, plus,
currency code.
For example, John.Doe@gmail.com++USD.
The email and password is your Google account email
address/password.
You also need to change the AdWords API server URL to
https://adwords- sandbox.google.com.
Note that the client library uses two different keys for
configuring the AdWords API server URLs.
For V13 API it uses a key named LegacyAdWordsApi.Server.
And for other questions of the API it uses a key named
AdWordsApi.Server.
Make sure you set both keys appropriately when making
calls to the AdWords API Sandbox.
The Sandbox needs to be initialized by running the Get
All Campaigns example.
You can run a code example by setting the example name as a
command line argument for the code examples [? port. ?]
To run the v201101 version of Get All Campaigns, you need to
set v201101.GetAllCampaigns as the command line argument.
Now run the code example.
The code example returns an empty list. This is to be
expected, since the Sandbox is initially empty and you have
to populate it with campaigns, ad groups, et
cetera to use it.
Let's create a new campaign by running the Add
Campaign code example.
Set the command line argument to be 201101.AddCampaign and
run the code example.
This creates a new campaign and displays the
campaign ID and name.
Now run the Get All Campaigns again.
The code example now returns the campaign you created.
Let's now build a simple AdWords application to get a
better understanding of the library and its use.
Our sample application is a console application that
retrieves a list of campaigns for the user and prints the
list to console.
Note that, though this video shows a console project for
brevity, you can follow similar steps to build a
Windows form application or an ASP.NET website.
Let's start by creating a new console application.
Now copy the left folder from AdWords API .NET Client
Library distribution into your projects folder.
Then add a reference to
\Google.adwords.dll in your project.
Also add reference to a assemblies System.XML,
System.Web, System.Configuration, and
System.Web.Services.
Now add an application configuration
file to your project.
Now open example/csharp/app.config from
the Adwords API .NET library distribution and copy its
contents into your app.config file.
In case your app.config already have other content,
then mod its content with the values of app.config.
Now fill your credentials in the app.config.
Let's start developing our application.
We will start by defining an AdWords user object in our
main method.
AdWords user is the entry point of the library and
allows you to create services for making AdWords API call.
The AdWords user [? pro ?] has two constrictors.
The first one creates an AdWords user object with
credentials mentioned in your app.config.
If you want to set credentials at the runtime instead of
specifying them in an app.config, then you can use
the overloaded AdWords user constructor.
You can also modify a user object after its creation by
setting appropriate configuration parameters
through the user's config property.
Let's add the functionality to retrieve and
display all the campaigns.
You'll start by getting an instance of v200101
CampaignService using the Get Service
method of AdWords user.
This call creates a CampaignService object
configured with the current settings of the user object.
You can also modify an existing service object's
configuration by modifying its request [UNINTELLIGIBLE]
property.
Now create a selector and set the
fields we want to retrieve.
Now call the CampaignService.get method to
get the campaigns.
You'll get back a campaign page object, and its entries
field hold the list of campaigns.
You can look through them and display their cells.
Now run our application.
As expected, the application displays
the list of all campaigns.
AdWords API services throw exceptions whenever something
goes wrong at its end.
Let's add some error handling to our application.
The two most common exceptions thrown by an AdWords API
server are AuthToken exception and AdWords API exception.
An AdWords API exception gets thrown whenever the AdWords
API server throws an error.
The API exception field of AdWords API exception object
holds the underlying API exception.
The API exception object in turn may contain one or more
errors which need to be handled appropriately.
An AuthToken exception gets thrown whenever the service
fails to retrieve an auth token using decline login API.
The details of the error can be found in the ErrorCode
field of AuthTokenException object.
Let's trigger these exceptions to check our code.
To trigger an AuthToken exception, let's set a bad
user password.
Now run the application.
As expected, our application handles the AuthToken token
exception thrown by the server and prints an error message.
Now let's trigger an AdWords API exception by setting a bad
client email login.
Now run the application.
As expected, our application handles the AdWords API
exception thrown by the server and displays an appropriate
error message.
This concludes the getting started video for the AdWords
API .NET Client Library.
If you have more questions, feel free to ask them on our
forum at groups.google.co m/group/adwords-api.