Yuma 4×4

Media and Communications

Google Ads API Workshop – Spring 2019 – Overview

Google Ads API Workshop – Spring 2019 – Overview


DEVIN CHASANOFF: Hi everyone. You all hear me? Everyone hear me? Yes? AUDIENCE: Yes. DEVIN CHASANOFF: Excellent. [LAUGHTER] Cool. Welcome, everybody. It’s so great to see
so many faces here. I think I’ve met a lot of
you in the elevator already, but I guess I can do
a formal introduction. My name is Devin Chasanoff,
and I’m a developer advocate here at Google. Part of our job, if you haven’t
figured that out already, is to make sure that you all
have an awesome experience using this API. So it’s really a pleasure
for us to be here, meeting you, hearing
how you use the API, learning about these
interesting use cases, so that we can continue to make
that experience better for you. So as Adam mentioned, there
is a lot of information today. Everything from migrations
to best practices. We have a code lab plan. But before we get into
that, it’s really important that we lay a
foundation, and that’s what this portion
of the day is for. This is what we’ll
be going through, the agenda for
this presentation. So first, we’ll just talk
about getting started. And this is basic stuff,
just account management authentication. Then we’ll move on to
resources and services, which are the building
blocks of this API. And if you can understand
the pattern that we use here, it’ll be pretty easy
for you moving forward in terms of implementing
different functionality. Next, we’ll talk about
some special services. Namely we’ll talk about
that special search service that we have, as
well as introspective discovery services. After that, we’ll actually
look at a quick example using the REST API. We’ll take a deep dive
into those developer tools, and Adam promised a live demo. This is the presentation
where we do it, so hopefully all goes well. And then finally we’ll have
a brief preview of the client libraries before we
open it up to some Q&A. So with that, let’s jump in. In order to actually begin
using the Google Ads API, what do you need? Well, first and foremost a
Google Ads manager account. And if you’re not familiar,
this is the type of account that you can use
to aggregate view and modify many
accounts at once. And it’s through this
account that you’ll create a developer token. You’ll also need a client
customer ID, which you’ll get from your client account. So just to distinguish
between the two, a client account is what
you’ll use to actually create advertisements, and
a client account can have zero or more managers. A manager can have
zero or more clients. And a manager account can even
manage other managers accounts. Next, you’ll need an
OAuth2 client ID and secret pair, which you’ll then use to
get OAuth2 access or refresh token. So let’s take a look at what
that process looks like. Oh, and before I move on,
just quick show of hands– and sorry if Adam
did this already– who are our previous
AdWords users? OK. Awesome. So you’ve probably gone
through this flow already. If you have your credentials,
I’ll go through this quickly. If you have your
credentials, you can use your same credentials. So that’s the good news. You don’t have to do this again. However, if you are using
one of our client libraries, you may have to make some tweaks
to your configuration file, such as changing the word
AdWords to Google Ads. But that’s all covered in
the client library specific documentation. With that being
said, the credentials themselves will stay the same. So since a lot of you already
have your credentials, I’ll go through this
somewhat quickly. But the first step is
obtaining a developer token. And this really grants you
generic access to the API. It’s not specific
to your account. You’ll hear this analogy later. It’s kind of like a
driver’s license, in that it enables you to drive many, cars
not tied to one specific car. In order to create this,
just head to that Tools link. It’s the Wrench icon at the
top right of your screen. API center. Follow the prompts, and you’ll
get your developer token. Upon doing that, your developer
token, for the first time, will have to be approved
for production use. While you’re waiting
for that, you won’t be able to make API
calls to a production account, but you can still make API
calls to a test account. Next, you’ll obtain
your OAuth2 credentials. And you’ll do so in
the Google API console. Now, keep in mind,
this API console is not specific to Google Ads. It is the same API console you
might use for any other Google API. However, you will have
to enable the Google Ads API in the API library. After doing that, head over
to the Credentials page. Click Create Credentials. Follow the flow there,
and for most cases, the installed
application type is OK. Once you’ve gone
through that, you’ll have a client ID as
well as a client secret, which you’ll need
for the next step– obtaining your OAuth2
access or refresh tokens. So if your developer token
is like a driver’s license, you can think of your
access token as similar to a key to a specific car. But that key
dissolves every hour, which wouldn’t be great
for an actual car. But that’s why we
have refresh tokens, because if you use
one of our client libraries along with
the refresh token, it’ll automatically generate
new access tokens for you. So you don’t actually have to
worry about this authentication process every single time
you’re making API calls. So you’ll actually go through
this process a little bit later in the code lab, making
a request with the HTTP method. However, the easiest way to
actually obtain these refresh and access tokens is by using
the client-specific libraries. So if you look at
your favorite library, head over to the
examples folder, it will be an authentication
sub directory. In there, there will be a
file called Authenticate in Standalone Application. So let’s look at how we do
this in PHP, for example. Simply run that application. You’ll enter in your client ID
as well as your client’s secret that you generated. And upon doing that,
you’ll be presented with a prompt like this. It will say, “Paste this
URL into your browser.” You click the URL. Then you can log
into your account. Keep in mind the account
that you log in with and the email that you log in
with is the email associated with that access
or refresh token. So once you’ve logged in, you’ll
allow Google Ads API access to your Google account. Out pops an authorization code. You’ll paste that into
the prompt, at which point you will finally get your
access and refresh token. All right. You’re now able
to make API calls. You’ll enter that into
your configuration file within your
client-specific library. By default, these generally
live in your home directory, but you can specify where
you want it to live and just point to where that file is. And at that point, you are
ready to make API calls. So I know that was a lot,
but once you get through that, it’s a lot more
fun working with the API. All right. So now that we know
what accounts we need and what authentication
looks like in Google Ads API, let’s take a look at
resources and services, which, as I mentioned before, are the
building blocks of the API. So a resource within Google
Ads is a conceptual entity within the product, within
the platform, right? That’s anything like a campaign,
a customer, an ad group, a keyword. And within the client
libraries, these are represented by objects. And these entities
and objects also encapsulate all the information
about that particular resource. For example, if you were
looking at a campaign, this would include the campaign
name, network settings, advertising channel,
and so forth. One of the big changes between
AdWords API and Google Ads API is how we identify
each unique resource. Whereas in the AdWords API
we used IDs, in Google Ads we use this concept
of resource names. And if you’ve used
a RESTful API, this should look
pretty familiar to you. But a resource name is a
string with a structure that looks like the middle
of the screen here, which is customers with
an ID, campaigns, and then the campaign ID, instead
of campaigns that could be any sort of resource. And what’s really
nice about this is, if you append that resource
name to the base URL on path, it begins to look like a URL
that follows conventional REST patterns. So it’s very easy to understand
what’s going on here. So if a resource is one of
those conceptual entities that we are interacting
with, services provide a mechanism by
which to actually interact with those resources. How do we retrieve them, create
them, update or remove them? So each resource will– many resources have
services, and they have a name that looks
like you’ll see here. So for example, the
customer resource has a CustomerService,
CampaignResource, CampaignService. It should be pretty
easy to follow. And each service client
has different methods associated with it. So for example, if you
are in the documentation and you went to the References
section, References tab on the top left of your screen,
you’d see a tab for a link to all the services. You can find the
CampaignService, and you’d see all the
methods available to you for the CampaignService, one
of which is MutateCampaigns. And mutate is how you
would do any operation that is add, create, or update– everything but search. And every mutate method will
have a similar signature. It will be called
MutateResource. So this accepts a
MutateCampaignsRequest. It returns a
MutateCampaignsResponse. So what goes into that
MutateCampaignsRequest? So there’s a lot going
on in this slide. Hopefully it’ll make
sense by the end. But if you can understand
this conceptual pattern, making API calls to
any resource will be very straightforward for you. At that point, it’ll
just be a matter of understanding what resource
you want to interact with, and then looking at the
documentation or syntax and attributes related
to that resource. So let’s work our
way left to right. So the first thing
you’ll do is you’ll create a campaign
operation, or an operation generally for any resource. In this case, will be
a campaign operation, which is comprised of a
resource– in this case our campaign. We’ll then set an operation
to that resource, such as set create, update, or remove. And this is similar
to the AdWords API if you’ve used this in the past. However, the syntax is
a little more concise. So a little less code, so
it’s good for everybody. And then finally, in
the Google Ads API, we introduced this concept
of a field mask, which you’ll learn a bit more about later. But the basic premise
here is that you can let the API
know which fields you’ll be updating in a
mutate call, which makes life a lot easier when you’re passing
it, if you only want to update, say, one specific field or two
specific fields for a given resource. So we package all
of those together into a single
campaign operation, which we then pass into our
middle box, the request. So this is the
MutateCampaignsRequest parameter that we saw
on the previous page. It’s comprised of a
customer ID, as well as an array of operations. So you’ll hear more about this
in the best practices deck, but using this array is a
great way to batch operations together. That prevents you from
making multiple requests to the API server. And what’s great about this
is that operations array is atomic, so either all go
through, or none of them will go through. Next, we package that in. We send that to our method as
shown on the previous page, which is our service client. And out pops your response. So if you can follow that
pattern, the entire API, every mutate more or less
follows this pattern. So if you can follow this,
you’ll be in great shape. Now, we’ve covered what
resources and services are, as well as how to
make mutate requests. So one thing I’ll
note is that if you did follow what I was saying and
went to the campaign service, you’ll see that there
were two methods there. There was the MutateCampaigns
method, as well as a GetCampaigns method. For any of these
methods, we do not recommend using that Get
method in production. It’s really only meant for
testing and development. Instead, as Adam alluded to,
we have a special service for searching and reporting. So instead of using a
specific resource client to retrieve information from
the Google Ads API server, instead what you’ll do is
use a special service called the Google Ads Client Service. And that service has a
special search method which you pass in
a query string that is made up of the Google
Ads query language that you’ve heard about already. And the query language
looks something like this. You just select what fields you
want to look at from the entity resource. Specify any conditions. And then you can order
or limit your results. So in the example here,
we’re selecting a campaign ID and name from campaign, and
we’ll order by campaign ID. Pretty straightforward. So one caveat here. I know this looks a
little bit like SQL. It’s not SQL. The good news is, if you’ve
used a query language, this should be pretty
straightforward, too. However, if you try to use
all of SQL’s functionality, it won’t work. So I wouldn’t try. So for example, the select star
operator isn’t supported here. And we’ll talk a little bit
later about why that is. In addition, we
don’t support joins, but we’ve built this query
language in a way that it’s implicitly supported,
in that you can actually select child resources
from a given resource, or even metrics. And we’ll cover that
in the next slide. In addition, we don’t support
group by, but using segments, as we’ll show you
in just a second, you can actually get that
functionality as well. So as you’ll hear
throughout the day, you’re going to use
this both for just retrieving a single item, as
well as general reporting. Instead of using many
different reports, you’ll just used this
exact same service client with that search method
and a query stream. When you’re looking
at reporting, you’ll probably want to get
some metrics such as clicks, page views, and so forth. You’ll also want to
take a look at segments, which is a great way to
group or filter your results. So in the example
here, you can see where, in addition to
campaign name and status, we’re also getting metrics about
impressions, clicks, and CTR. And as you can see
here, you don’t have to do any fancy joins. It’s all included. All you have to do is just
put that additional criteria into your select query. In addition, like
I said, group by– you can use segments,
not device here. It makes your life a lot easier. And then finally in
the Where clause, we can filter our
results by date to just see the last 30 days. When you run a query like
this, the result that you get will be a unique row
for every combination of the main resource
and segmented values. So this is all good and well. Google Ads Query Language
sounds pretty awesome, right? But how do you know what
fields are available to you? How do you know how to use it? Lots of great resources
and tools for you. First and foremost, of course,
you can look at the docs– always a great place to start. On the bottom left
of the Resources tab is a list of
all the fields you can explore at your leisure. We also have a
REST discovery API. If you look at this
end point here, there’s a $discovery there. And you can actually
click that, if you want, if you’re following along. And you’ll actually
see a JSON response of all of the resources and
methods available to you in the entire API. And it’s machine readable
if, for example, you want to generate some
sort of query on the fly. Finally, Google Ads introduces
a new service called the Google Ads Field Service, which you
can use to find out information about a particular resource. So in this example here,
we have Google Ads Fields along with campaign, and that
will return the fields metrics and segments available
on the campaign resource. And you’ll actually do this a
little bit later in the code lab. I should note, this does
require authentication, whereas if you’ve
clicked the middle link, the discovery API does not. So now we know how to search
with the Google Ads API and also do reporting,
which is one of the same. And we’ve also seen how to
learn more about queries. So let’s take a look at a quick
example using the Google Ads API with REST. So as you’ve heard by now,
and you’ll hear many times, the new API is built
using gRPC, but we do expose a functionally
equivalent REST API, which accepts
JSON as an input and will give you
JSON as an output. One thing to note, if
you are using that API, there is a little
bit of a difference between a conventional
RESTful API and what you’ll do here, in
that you for the most part won’t use verbs like “get,”
“put,” “patch,” and “delete.” You’ll almost always use “post.” And then you’ll specify the
verb “search” or “mutate” at the end of the end point. Let’s take a look at
what that looks like. So here, don’t worry about
digging into the details. You’ll do this in the code lab. But you can see we’re making a
POST request to our base URL, plus our customer’s
resource name, and then we’re hitting the
Google Ads service client and search it. Got all that authentication
information we got earlier, our query
string at the bottom, and out pops a JSON response. Awesome. Now we know how to
actually make API calls, let’s take a look at
some of the tools that will make your life easier,
especially as you get up the learning curve. Now, first, my awesome teammate
Cory over there, he actually built this Google
Ads Query Builder. So this is a tool
for you to learn more about what fields will
be available to you when constructing
those query strings. And rather than– of course we
have the docs, discovery, API and the fields resource. We’ve given you
one more tool here. And this is a UI-based product
hosted on our developer site. And the beauty here, is that
you can start with the resource that you want to look at. And then you’ll be provided
with dropdown menus only containing the criteria that
are actually available to you based on that specific resource. So rather than talking about
this, let’s try a live demo. All right. So hang with me here, because
this setup is a little more complicated than it looks. All right. Excellent. OK. Here we are. Excellent. So you can actually
navigate to this yourself. The link is in the presentation. And as I said earlier, you come
in here, select your resource. So for example, if I
were to select campaign, now when I select
the dropdown fields, I’ll see all of the attributes
available to me to select. And this also includes
child attributes, as well as metrics and segments
available to you. So we’ll come in here. I’ll try to do this quickly. So let’s say we want
to look at campaign ID. Campaign name, that’s
usually pretty important. Then maybe we’ll look at– it seems to be frozen on me. Live demos, am I right? [LAUGHTER] For the sake of speeding
things up, I will just move on. So in here, we’ll select
what filters we want. OK. All right. Yes, that’s probably right. SPEAKER: Yeah. DEVIN CHASANOFF: All right. Take two. SPEAKER: Try again. DEVIN CHASANOFF: That pane. We’ll just do name this time,
because it’s right here. Now you can see the metrics
we have available to us. So let’s look at, for
example, average CPC. We’ll select the Filter. So here maybe we’ll
only look at– let’s say we only want to
look at campaign.status is enabled, because
we only want to look at our active campaigns. This green button to add,
and now at the bottom of the here, this is what you’ve
all been waiting for anxiously. We have our query text. So if you see this
button here, I can copy. And now what I can do is just
paste this exact query string into the Chrome request,
or even the client library. You can see this makes
query building a lot easier. It’s actually a
lot easier when you don’t have 100 people
looking at you, but this should be a great
tool for you to learn. So the next tool, and I’m
going to stay on this slide, is the Google Web
Navigation tool that Adam referred to earlier. Bear with me here. This guy. And I’ll show you how it works. But basically the premise
here is, as Adam said, if you’re already
in the UI, you’re looking at a
particular resource, you want to learn more about it. You want some guides. You want some documentation. If you have this Chrome
extension installed, simply click on the extension
when you’re logged in, and it will give you pointers
to all of those resources. So let’s take a look. So as you can see here,
I’m logged into an account. And because of that, this
Chrome extension here is active. Now, if I were to
go to Campaigns– you can see all these
really interesting campaigns that we’re running here. And if we were to
click on that icon, you can see now we have links
to guides, fields, and so forth. And you can see,
especially as you’re learning about new
features, how this can be really useful to you. OK. Excellent. All right. Live demo. Yes. So now we’ve done a brief
intro to our client libraries. Because you’ll have an entire
presentation on this later, so I won’t spend
too much time on it. But I will say this
is the preferred way to access the API. As Adam mentioned, the client
libraries all utilized gRPC, and if you are using
the client libraries, you get the benefits
of the new technology. However, it’s all, for the most
part, abstracted away from you, so you don’t really have
to worry about the details. So we support five libraries– Java, PHP, Python,
Ruby and .NET. And if you’re using them
and you follow that off flow that we went
through earlier, you can save your credentials
in a configuration file. And then you won’t
really have to worry about authenticating every time
you want to make an API call. You can just worry about
implementing the application logic that you’re
building with the API. Finally, they’re
all open source. They’re all available on GitHub. If you do want to
contribute maybe examples or questions or anything
like that, we of course love hearing from the community. All right. And this wouldn’t be complete
without a resources slide, which is also a
great opportunity to recap what we’ve went
through in this presentation. First and foremost,
getting started. If you didn’t follow any of
the flows, authentication, or even just understanding the
resources and services model, this is a great place to start–
the Google Ads Developer Site, as well as the API reference. We also have a link here
to the query language to learn more about
the query language, though by now it seems like
you should all be experts. We also have developer
tools that we just went through, such as the
Interactive Query Builder, the Web Navi, as well as
the REST Discovery API. And then on the right
are links to all of our open source client
library repositories on GitHub.

Leave comment

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