Page Summary
-
Initialize the client library by creating a
GoogleAdsConfigobject with necessary settings and then using it to create aGoogleAdsClientinstance. -
The
GoogleAdsClientinstance is crucial for creating pre-configured service classes that make API calls. -
Use the
GetServicemethod of theGoogleAdsClientinstance with the appropriateServicesenumeration to create a specific Ads service. -
Handle potential API errors by catching the
GoogleAdsExceptionwhich provides details about the failure. -
Avoid sharing a single
GoogleAdsClientinstance across multiple threads due to potential configuration conflicts. -
To keep applications responsive when making API calls, consider using the
Grpc.Corelibrary for legacy .NET Framework applications or utilizing asynchronous methods.
The basic usage of the client library is as follows:
// Initialize a GoogleAdsConfig class.
GoogleAdsConfig
config
=
new
GoogleAdsConfig
()
{
DeveloperToken
=
"******"
,
OAuth2Mode
=
OAuth2Flow
.
SERVICE_ACCOUNT
,
OAuth2SecretsJsonPath
=
"PATH_TO_CREDENTIALS_JSON"
,
LoginCustomerId
=
******
};
// Initialize a GoogleAdsClient class.
GoogleAdsClient
client
=
new
GoogleAdsClient
(
config
);
// Create the required service.
CampaignServiceClient
campaignService
=
client
.
GetService
(
Services
.
V22
.
CampaignService
);
// Make more calls to service class.
Create a GoogleAdsClient
instance
The most important classes in the Google Ads API .NET library is the GoogleAdsClient
class. It lets you create a pre-configured service class that
can be used for making API calls. To configure a GoogleAdsClient object, you
need to create a GoogleAdsConfig
object and set the necessary settings. Refer
to the Configuration guide
to learn
more.
// Initialize a GoogleAdsConfig class.
GoogleAdsConfig
config
=
new
GoogleAdsConfig
()
{
DeveloperToken
=
"******"
,
OAuth2Mode
=
OAuth2Flow
.
SERVICE_ACCOUNT
,
OAuth2SecretsJsonPath
=
"PATH_TO_CREDENTIALS_JSON"
,
LoginCustomerId
=
******
};
// Initialize a GoogleAdsClient class.
GoogleAdsClient
client
=
new
GoogleAdsClient
(
config
);
// Modify the GoogleAdsClient afterwards.
client
.
Config
.
LoginCustomerId
=
******
;
Create a service
GoogleAdsClient
provides a GetService
method that can be used to create an
Ads service.
CampaignServiceClient
campaignService
=
client
.
GetService
(
Services
.
V22
.
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 V22
of the Google Ads API,
you need to call the GoogleAdsClient.GetService
method with Services.V22.CampaignService
as the argument, as shown
in the previous example.
Error handling
Not every API call 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 to help you figure out what went wrong:
public void Run ( GoogleAdsClient client , long customerId ) { // Get the GoogleAdsService. GoogleAdsServiceClient googleAdsService = client . GetService ( Services . V22 . GoogleAdsService ); // Create a query that will retrieve all campaigns. string query = @"SELECT campaign . id , campaign . name , campaign . network_settings . target_content_network FROM campaign ORDER BY campaign . id "; try { // Issue a search request. googleAdsService . SearchStream ( customerId . ToString (), query , delegate ( SearchGoogleAdsStreamResponse resp ) { foreach ( GoogleAdsRow googleAdsRow in resp . Results ) { Console . WriteLine ( "Campaign with ID {0} and name '{1}' was found." , googleAdsRow . Campaign . Id , googleAdsRow . Campaign . Name ); } } ); } catch ( GoogleAdsException e ) { Console . WriteLine ( "Failure:" ); Console . WriteLine ( $ "Message: {e.Message}" ); Console . WriteLine ( $ "Failure: {e.Failure}" ); Console . WriteLine ( $ "Request ID: {e.RequestId}" ); throw ; } }
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 and making calls to multiple
services in parallel 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.
...
}
Keep your application responsive
The Google Ads API API method calls may take a while to complete, depending on how big the requests are. To keep your application responsive, we recommend the following steps:
Use the Grpc.Core
library
If you are developing an application that targets .NET Framework and uses a
legacy technology such as ASP.NET Web Forms or WinForms application, we
recommend using the legacy Grpc.Core
library as follows:
GoogleAdsConfig
config
=
new
GoogleAdsConfig
();
config
.
UseGrpcCore
=
true
;
GoogleAdsClient
client
=
new
GoogleAdsClient
(
config
);
```
###
Use
the
asynchronous
methods
{:
#
asynchronous
}
You
can
use
asynchronous
methods
to
keep
your
application
responsive
.
Here
are
a
couple
of
examples
.
####
Retrieve
the
list
of
campaigns
,
and
populate
a
`
ListView
`
```
c
#
private
async
void
button1_Click
(
object
sender
,
EventArgs
e
)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient
googleAdsService
=
client
.
GetService
(
Services
.
V22
.
GoogleAdsService
);
// Create a query that will retrieve all campaigns.
string
query
=
@"SELECT
campaign.id,
campaign.name,
campaign.network_settings.target_content_network
FROM campaign
ORDER BY campaign.id"
;
List<ListViewItem>
items
=
new
List<ListViewItem>
();
Task
t
=
googleAdsService
.
SearchStreamAsync
(
customerId
.
ToString
(),
query
,
delegate
(
SearchGoogleAdsStreamResponse
resp
)
{
foreach
(
GoogleAdsRow
googleAdsRow
in
resp
.
Results
)
{
ListViewItem
item
=
new
ListViewItem
();
item
.
Text
=
googleAdsRow
.
Campaign
.
Id
.
ToString
();
item
.
SubItems
.
Add
(
googleAdsRow
.
Campaign
.
Name
);
items
.
Add
(
item
);
}
}
);
await
t
;
listView1
.
Items
.
AddRange
(
items
.
ToArray
());
}
```
####
Update
a
campaign
budget
and
display
a
Message
box
alert
```
c
#
private
async
void
button2_Click
(
object
sender
,
EventArgs
e
)
{
// Get the BudgetService.
CampaignBudgetServiceClient
budgetService
=
client
.
GetService
(
Services
.
V22
.
CampaignBudgetService
);
// Create the campaign budget.
CampaignBudget
budget
=
new
CampaignBudget
()
{
Name
=
"Interplanetary Cruise Budget #"
+
ExampleUtilities
.
GetRandomString
(),
DeliveryMethod
=
BudgetDeliveryMethod
.
Standard
,
AmountMicros
=
500000
};
// Create the operation.
CampaignBudgetOperation
budgetOperation
=
new
CampaignBudgetOperation
()
{
Create
=
budget
};
// Create the campaign budget.
Task<MutateCampaignBudgetsResponse>
t
=
budgetService
.
MutateCampaignBudgetsAsync
(
customerId
.
ToString
(),
new
CampaignBudgetOperation
[]
{
budgetOperation
});
await
t
;
MutateCampaignBudgetsResponse
response
=
t
.
Result
;
MessageBox
.
Show
(
response
.
Results
[
0
].
ResourceName
);
}
```
