This guide gives a brief overview of how to get started with the Google Ads API .NET library.
Installation
The client library binaries are distributed via NuGet. Add a Nuget reference to the Google.Ads.GoogleAds package in your project to use the client library.
Set Up Authentication
To authenticate your API calls, you need to specify your client ID, client secret, refresh token, and developer token to the library.
If you already have credentials...
- Copy the
GoogleAdsApi
node and theGoogleAdsApi
section under theconfigSections
node from the App.config file in GitHub into yourApp.config / Web.config
file. If you used NuGet to install the package, these nodes will be automatically inserted into yourApp.config / Web.config
file. - Include the developer token, the client ID, client secret, and refresh token
in your application's
App.config / Web.config
. The App.config file included in GitHub is well-documented, but you can also refer to the Configuration guide to learn more as well as use alternate configuration settings.
If you need to generate credentials...
- Follow the Developer token guide to obtain your developer token, if you don't already have one.
- Follow the OAuth Installed Application Flow guide to generate a client ID, client secret and a refresh token.
- Copy the
GoogleAdsApi
node and theGoogleAdsApi
section under theconfigSections
node from the App.config file in GitHub into yourApp.config / Web.config
file. If you used NuGet to install the package, these nodes will be automatically inserted into yourApp.config / Web.config
file. - Include the developer token, the client ID, client secret, and refresh token
in your application's
App.config / Web.config
. The App.config file included in GitHub is well-documented, but you can also refer to the Configuration guide to learn more as well as use alternate configuration settings.
Make an API call
The basic usage of the client library is shown below:
// Create a Google Ads client.
GoogleAdsClient client = new GoogleAdsClient();
// Create the required service.
CampaignServiceClient campaignService =
client.GetService(Services.V1.CampaignService);
// make more calls to service class.
Let's try to understand the classes in more detail.
Create a GoogleAdsClient instance
The most important classes in the Google Ads API .NET library is the
GoogleAdsClient
class. It allows you to create a pre-configured service class
that can be used for making API calls. GoogleAdsClient
provides a default
constructor that creates a user object using the settings specified in your
application’s App.config / Web.config
. Refer to
the Configuration guide
for various configuration options.
// Create a new GoogleAdsClient with the App.config settings.
GoogleAdsClient user = new GoogleAdsClient();
Create a service
GoogleAdsClient provides a GetService
method that can be used to create an
Ads service.
CampaignServiceClient campaignService = client.GetService(Services.V1.CampaignService);
// Now make calls to CampaignService.
We provide a Services
class that enumerates all the supported API versions and
services. The GetService
method accepts these enumeration objects as argument
when creating the service. For example, to create an instance of
CampaignServiceClient
for version V1
of Google Ads API, you need to call
GoogleAdsClient.GetService
method with Services.V1.CampaignService
as the
argument, as shown above.
Thread safety
It is not safe to share a GoogleAdsClient
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 a GoogleAdsClient
instance, making calls to
multiple services in parallel, etc., are thread-safe.
A multithreaded application would look something like this:
GoogleAdsClient client1 = new GoogleAdsClient();
GoogleAdsClient client2 = new GoogleAdsClient();
Thread userThread1 = new Thread(addAdGroups);
Thread userThread2 = new Thread(addAdGroups);
userThread1.start(client1);
userThread2.start(client2);
userThread1.join();
userThread2.join();
public void addAdGroups(object data) {
GoogleAdsClient client = (GoogleAdsClient) data;
// Do more operations here.
...
}
Handling errors
Not all API calls will succeed. The server can throw errors if your API calls fail for some reason. It is important to capture API errors and handle them appropriately.
A GoogleAdsException
instance is thrown when an API error occurs. It has
details that help you figure out what went wrong. A minimal example is given
below:
// Get the CampaignService.
CampaignServiceClient campaignService = client.GetService(Services.V1.CampaignService);
// Create a campaign for update.
Campaign campaignToUpdate = new Campaign()
{
ResourceName = ResourceNames.Campaign(customerId, campaignId),
// More fields to update.
// ...
};
// Create the operation.
CampaignOperation operation = new CampaignOperation()
{
Update = campaignToUpdate,
UpdateMask = FieldMasks.AllSetFieldsOf(campaignToUpdate)
};
try
{
// Update the campaign.
MutateCampaignsResponse response = campaignService.MutateCampaigns(
customerId.ToString(), new CampaignOperation[] { operation });
// Display the results.
// ...
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
// Can examine to get more error details.
Console.WriteLine($"Failure: {e.Failure}");
// Can be shared with Google for further troubleshooting.
Console.WriteLine($"Request ID: {e.RequestId}");
}