Yuma 4×4

Media and Communications

Google Ads API Workshop – Spring 2019 – Best Practices

Google Ads API Workshop – Spring 2019 – Best Practices

Hi, everybody. My name is Thanet
Knack Praneenararat. I’m working as the
developer programs engineer based in Tokyo,
and today I’m very happy to have an
opportunity to give you a talk about the best practices
of the Google Ads API. And this is the agenda
of my talk today. I will start with the
value of best practices, and then I will
merely talk about how to efficiently fetch, create,
update, and remove your data. And after that I will
cover error handling, which is a concept borrowed
from the AdWords API but still holds true
in the Google Ads API. So why are we interested
in best practices? The best practices can sometimes
be defined as the attempt to achieve the difference
between this graph and this graph, provided that
the graph represents something that your business cares
about, like the time to execute operations. So the lower is the better. So when you can
execute your operations per second more
and more, it means that you can surf more
accounts and more customers. And finally, it means that
you can provide more business values to your customers. And that’s why we are
talking about best practices today, because it’s
good for your business. And when you follow
the best practices, it’s more likely that you
can achieve this difference. So who is interested
in best practices? We can divide the
API stakeholders into two groups, the developers
and the Google engineers. The developers, or you,
actually understand your product very well and also
understand how your technology set operates. And the Google engineers,
on the other hand, understand the APIs very
well and also understand the intricacies of
the infrastructure. Although these two groups
seem to be quite different, actually they have
a common interest, which is the interest in saving
time, money, and resources. So what are the benefits of
following best practices? So the first and obvious benefit
is the performance and skill. You can do more things
with less effort by using the
efficient techniques, and you can scale up to
demand very easily when following best practices. Secondly, you have shared
understanding with us. So with the shared
expectations, it means that you will have
fewer surprises because you understand how the API works. And in the meantime,
we understand how you intend to use it, so
over time we can predict– or, optimize our
software components to better work with your
data patterns or [INAUDIBLE] patterns. And, finally, the stability. When you use the
best practices, you can rest assured that you will
have a consistent and reliable system to use because these
practices are tried and tested. And every time we add a new
thing in the Google Ads API, we ensure that they are
validated with the best practices so that the
best practices still hold true at all times. So let’s get started with our
first main topic of my session today, which is the fetching. In the Google Ads API, one
of the common misconceptions is that Google Ads
Query Language is SQL. Actually, it’s not. Although it looks
similar to SQL, they are not the same thing. It is built on the
top of the system that requires you to explicitly
select fields, metrics, and segments so that
it can translate your query into a request
in the back-end correctly. And that’s why we like to
encourage selecting only what you need in order to reduce
the size of the responses, as well as unnecessary
fetching of the resources. And this will ultimately
help our Google engineers to optimize further data
paths that you actually need. So in short, have a look at
the top query of this slide. We would like to encourage
you to do something like that, selecting only what you need. In this case, we select only
ad_group_criterion.criterion_id and the metrics dot impressions,
which is pretty concise. On the other hand, in the
below query, as you can see, we select so many
things in this example, and it’s not quite effective. So think carefully about
which attributes, metrics, and also segment fields
you would like to request. Requesting
unnecessary fields can make the query more expensive
because additional resources are required behind
the scenes in order to generate your results. So more efficient
queries mean more queries processed per second. We have done an empirical
test on selecting some keyword metrics. So in this graph,
as you can see, the left hand side
is the case when we selected all the metrics
of the keyword view, and the right hand side
is when we selected only one required metric. And this graph
represents the time to download keyword
metrics per account, so the lower is the better. So based on our
test, we have found that when selecting only
one required metric, it could save up to 50% of
the time compared to when we selected all the metrics. So a better understanding of the
Google Ads API infrastructure and mechanisms like this can
make you be more effective. Let’s have a look
at another example. This is simplified Google
Ads API architecture. And we have three layers
here, Google Ads API, the caching layer, and finally
the back-end databases. So when you sent a request,
like search request, to the Google Ads API layer,
it will translate your query into the request of
the back-end databases. And after that when
it can figure out what results to be
returned to you, it will be returned
via the cache layer. So the result will be
returned via the cache layer and saved there before returning
back to you via the Google Ads API layer. So in case you use paging
request, which is also available in the
AdWords API as well, and request for a next
page, what happens here is instead
of going deep down into the databases
like the first page, it will be passed to
the cache layer instead. And your result will be
returned almost immediately from the cache layer back
to you as a response. And that’s exactly the benefit
of using paging request. So to use the paging
request, what you need to do is to pass a pageSize
parameter to the search method, like showing the slide. Apart from passing the
customer ID and also the query [INAUDIBLE],, you can
pass an area of the page size like that. The Google Ads API
will internally cache the following pages so
that the subsequent requests are faster than the first one. And as you can
see, in this slide we use the PHP library,
meaning that all the client libraries actually support
handling the pages for free. We have done another test
for this particular feature. And by using the sample query,
like shown in this slide, we set the page
size equal to 1,000, and it resulted in
360 separate requests. The size of the response is
almost the same for each page because we sent the same
amount of the requests and also get back almost the
same amount of the response size. So for the first page, it
spins around 16 seconds. When we asked for
subsequent pages, it took only around one second. This is because internally
your subsequent pages’ results are already cached. And in this case, the more
important thing to mention here is to tweak the page
size appropriately to reach the sweet
spot between the number of the results in the page
and the number of queries to be set. Also, this depends on your
business requirements. So unfortunately, we
don’t have a one step solution or a universal
number for the page size. You need to find that
spot by yourself. But the important
thing is that you wouldn’t want to use too large
of a page size or too small of a page size. Apart from that, know that
this number I subtracted by using the REST API. So when you use client
libraries or gRPC requests, the number might be a
little bit different, but the performance
improvement here is still approximately the same. So apart from using the
paging request in order to reduce the size
of a request, you can also use
segmentation by date in order to reduce the
overall number of the returns’ responses and also the
size of the responses. So to use the
segmentation by date, you can do so by using
[INAUDIBLE] clause like this. Specify the filtering condition
by using the specific date or a date range. In this way, you
can further reduce the size of the response. Without an individual
date or date range, you could be requesting
all the data at all times. And imagine that you have
a long history called data. This could result in
the increase of the time it takes to generate
your response. And apart from the date
segmentation– actually, we have another
option for you, which is the filtering condition. You can use IDs, statuses, and
other metrics and attributes to use to filter your
response as well. One of the two popular filtering
conditions that you can use is, first, metrics dot
impressions greater than zero, which makes
sense in many cases because you are probably
interested in only the data that performed, only
the ad group ad that performed or the ad group
criterion that performed. So whenever the
impressions is 0, it means that they are
not performing at all. Another one is the status. You can filter like this,
ad_group_criterion.status equal to enabled, meaning that you
want to fetch only the ad group criterion that are
not yet deleted. The next topic is about
creating, updating, and removing the data. So to create multiple objects
in the Google Ads API, we have a feature called
atomically creating objects. And this is actually partially
available in the AdWords API as well in the backdrop
service, in case you use the AdWords API. I think you might be
familiar with this concept. So atomicity means that
your operations all work or all fail. So you will not end up
in a strange situation when you are trying to create
a campaign budget in order to be used in the campaign
operation creation. But somehow when you are trying
to create a campaign operation, somehow the error occurs, and
then you cannot create any campaigns at all. In that case, you might have
already created some campaign budgets, right? And that will put
you in a situation in that you have many
dangling campaign budgets not in use at all. So to avoid that situation, you
can use this atomicity concept in order to create
all campaign budgets, all campaigns together, or
not creating them at all. So to do so, in the Google
Ads API what you need to do is to send your request to
the Google Ads service dot mutate [INAUDIBLE] together
with temporary IDs, which is actually the negative
value as references. So here, shown in this
slide, is actually the example of the request. And we have hidden some of
the mutate operations in here to show only what is needed. And because of the
space limitation as well, as you can
see, the campaign budget operation here– you can create the
campaign budget by populating many fields here. But what is different here
from the normal situation is that you need to put the
resource name fields here, too. OK? So in other normal
situations, you may just populate other
fields like the amount of the budget and et cetera. But in case you want
to use atomicity, you need to put the
resource name fields. And in this case,
we use minus 1. Actually, it can be
any negative value, but it’s good to start
from the minus one so that you can keep
track of what numbers you have already used. OK? So after that when we are
trying to create a campaign here down below, as you can see, when
we want to specify the campaign budget, in a normal situation we
usually use the real ID, right, which would be something
like a long digit number. But, in this case,
because we want to create them altogether
using the atomicity concept, we need to reference
the campaign budget here by using the negative values. OK? So this is exactly
the same as this. And know that we also set the
resource name for the campaign here as minus 2. So, in case you want to
create ad groups after this, you can refer to
this campaign ID. And the same, when you
want to create an ad group ad or ad group criterion,
you can set a temporary ID for the ad group. This will result in better
consistency and performance overall in your accounts. The next thing that I would
like to share in this session is the update. So in the Google
Ads API, as you have seen a little bit in the
previous sessions before, we have made a significant
innovation of the Google Ads API for updating objects. It is called Field Mask. So it requires you to
explicitly describe which fields are to be updated. So at first glance, you may
think that it’s actually more work for you, right? You need to further
provide another field when you want to update things. But it actually can
resolve ambiguity for you. So in the AdWords API, when
you want to update some data and you also store your
data in the local databases, you may just fetch your data
from the local databases, modify some fields,
and then send back to the AdWords
API, right, as is. So your object may contain many
other fields that you actually have not updated them. But the AdWords
API will not know what fields you
actually want to update. So the AdWords API will
update all the fields present in your request, and
it is not quite effective, as you can see. Alternatively, you can create
a new object every time you want to update things and
populate only what is required. That’s probably fine. Actually, it’s more effective
in the AdWords API server. However, you need to
do that by yourself, so it’s quite cumbersome. That’s why in the
Google Ads API, we combine these
concepts together. You can use whatever
fields here you want. You may just fetch other fields
here from your local databases. But, at the end of
the day, you may want to update only the name. So you can go ahead,
update the name, and then in the Field
Mask, just specify that, OK, the name
field is the thing that I want to update, not the
status, not the other fields. Next, about REMOVE. In the Google Ads API to
use the REMOVE operation is pretty easy. You just specify the
resource name here, as the remove field for the
operation, and that’s it. You can remove any objects
in the Google Ads API by using this kind of code. However, in the Google Ads– note that I’m using the words
Google Ads, not the Google Ads API or the AdWords API, but I
mean the Google Ads overall– objects are not
permanently deleted. And that is because we
want to preserve metrics. In case you want to still
fetch some reporting about the historical
data, you can do so by using Google Ads
service dot search and get back your removed
objects’ performance data. However, even though they
are not permanently deleted, once they are removed they
cannot be re-enabled, OK? Another thing I
would like to share with you about the removal of
objects in the Google Ads API is, in the AdWords API, when you
use campaign service, ad group service, or any other
services to fetch your data, the removed objects will be
filtered out automatically. But in the Google Ads API,
because we provide you more flexibility, you
need to be more explicit. So, in most cases,
you probably want to put this condition
in the [INAUDIBLE],, like the campaign dot
status not equal to removed. If you omit that condition
it will return to you all the objects that you
have in your account. And most of the
time, you may not be interested in fetching the
data of the removed objects anymore, so please
be aware of that. Finally, I want to briefly talk
about the error handling here. We have four types of errors– actually, the same as
in the AdWords API. And the first one is
the retryable errors, which are the errors that
are actually transient. And most of the time, you
may just wait for some time and then retry the requests,
and it can go through. OK? So in this case,
we are recommending using the exponential backoff
policy, because in that way you can ensure that
you are not ending up being read limited
because of too aggressive requests sending. The second one is
the validation error, which happens when your input
is not valid or not acceptable, like you are trying to
set too large or too small of IDs for an object
or you are trying to set an immutable item. The third one is
sync related, and it happens when you are storing
your data in local databases as well and you are trying to
modify things that are already, for example, removed. That can’t happen
because maybe you are handling the data for your
customers, and in that case, your customers have access
to the accounts as well. And they may just remove
something already, and you are not aware of that. So, in this case, we recommend
using the change status service to keep track of
what has changed since the last time
you have synced with the remote databases. Finally, authentication
errors, actually one of the popular errors that
most beginners will encounter. And it happens mainly because
of the misunderstanding of all the credentials
information concept. And for particularly
the Google Ads API case, it can happen when
we have started requiring the login
customer ID, the new HTTP header that I think we have
covered in the keynote session as well. In that case, if you did not
provide a login customer ID, you end up with the
authentication error as well. In the next slide,
I will show you the review of the concepts of
the credential information. But for now, I would like to
emphasize that the links here are actually very useful. So when you have time, make
sure that you go over them. OK. For the credential information
used in the Google Ads API, we have many concepts. A developer token is actually
analogous to a drivers license. It means that you are
allowed to drive a car, right, when you have
a driver’s license. But the license will not tell
you what car plate numbers that you can drive. Similarly, developer token
in the Google Ads API just allows you to use
Google Ads API itself. It doesn’t define what
accounts you can access. So that’s why we
have another concept. It is access token, which is
analogous to a key of the car. It allows you to
drive a specific car, but for a certain
amount of time. So the access token,
similarly, allows you to manage a specific account
for a certain amount of time. And after that it
will be expired and you need to
generate a new one. So to generate a new one,
we have a refresh token, which serves as a utility for
you in case your access token is already expired. You can generate
a new access token by using the refresh token. And in case you use
the client libraries and provide the developer token
and refresh token already, you can just rest
assured that the access token will be generated
automatically when needed. And yeah, to summarize,
these practices can help you be more efficient
and do more within constraints. And also we suggest sending
optimized queries by, for example, using
a paging request or using filtering conditions
and submission by date in order to squeeze down
the size of the response to help you request the Google
Ads API in a much quicker way. Thirdly, understanding the
Google Ads API infrastructure, such as the paging
request mechanism, can be useful to your
business as well. So ensure that you
understand the infrastructure I have shown to you in
this session very well. Next, be aware of the methods
to efficiently update the data. Now, in the Google Ads
API, we have provided you the Field Mask
mechanism, so you don’t need to send everything and let
the Google Ads API figure out by themselves what fields
you are trying to update. Or you don’t need to create
a new object every time you want to update things anymore. And, finally, understanding
common handling actually is a key for your
stability of the application. So ensure that you review
all the concepts available in the best practices guide
and also in the error guides. This is the resources list. It is pretty the same
as in the keynote and also the overview sessions. But I would like to highlight
here the best practices guides. We have provided the Google
Ads API best practices guide and also the AdWords API best
practices guides as well. And that is because
the AdWords API best practices concepts
mostly are still applicable in the
Google Ads API. So it’s no harm to maybe review
some concepts in that guide, too.

Leave comment

Your email address will not be published. Required fields are marked with *.