Migrating from v13 to v2009 – AdWords API Hack Day

Migrating from v13 to v2009 – AdWords API Hack Day


>>ROGAL: Hi, everyone. So, my name is Adam
Rogal. And I’m a Developer Program Engineer at Google specifically for the AdWords API
along with everyone else in the room who is also either going to be a developer advocate
or a development program engineer. So, just to give you brief introduction about like
our job and what our core duties are. We try and help developers develop for our API. So,
that means writing code samples, writing documentation, writing client libraries, doing [INDISTINCT]
like these, and supporting our APIs through the forums and through email and phone calls.
>>Hey, Adam, can you use the mic? I’m sorry.>>ROGAL: Sure thing.
>>Thanks.>>ROGAL: Okay. So, what I’m going to be talking
about first today is Migrating from v13 to v2009. Just to show of hands, how many people
here have started migrating? Great, okay, so it looks like a few of you haven’t. So
it should–this should be a good kind of introduction to it. But those of you who have, we’re going
to reiterate on a few points and we’ll have some best practices and, you know, as Aaron
(ph) said, if this seems all boring, there’s Wi-Fi and you can start coding on your own
stuff or asking people in the back any questions. So first off is the timeline. And I’m sure
many of you have heard of this so far. But, there’s going to be a sunset of our v13 services
on April 22nd 2010. So, what does this means? There’s going to be two parts. The first part
that’s going to be sunset is going to be all the campaign management stuff, InfoService,
and targeting idea of the services that equate to targeting idea services. So essentially,
you know, you can get started on all the–all the people who said that they’ve begun migrating.
That means that they’ve probably been migrating over the campaign management stuff. They’ve
been keeping their, you know, started migrating. Maybe they’re targeting IT stuff or targeting
idea service, and maybe migrating over their InfoService as well as exploring like add
parameters [INDISTINCT] service. There will be a full v13 sunset. The way we’re going
to approach this is every time a service is released that has feature parity of its v13
equivalent then we set a sunset clock at four to six months before that service is deprecated
and turned off–I’m sorry, sunset. It’s deprecated one of feature parity version is released.
So for example, one on here that I don’t have is report service. So, the v2009 version report
service is in the works, it’s close to database. And when it does, what we’re going to do is
make sure that its feature parity. We’re going to get feedback and when we believe it’s reached
feature parity, that’s when we set the sunset clock. So we’re just locating plenty of times
to migrate over the services that we haven’t released yet. Okay. And if anyone has any
questions, feel free to ask questions as we go along. But, we’ll have a likely Q&A session
after this as well. So, some of the resources to upgrade to v2009, I think one of the greatest
resources is our client libraries. So, just a–you know, show of hands, how many people
in here used one of our client libraries? Okay, so roughly half the room saying, “They
do.” My job today is to convert the other half. You know, whether or not, you know,
if you’re not using the client library, do you really want to know why? You know–I think,
when we had one of these sessions in San Francisco a little bit ago. And the key feedback that
we got from there was, well, one, “I didn’t know that client libraries existed.” So we–you
know, today we’re saying, “Here they are.” The other one was, “I can’t use it because
my system does X and X and X, and my environment is X and X and X.” And we try and make sure
that the client libraries reach that nice little, you know, big part of the bell curve
in terms of compatibility with people’s systems. So, please let us know, like, give us feedback,
you know, why can’t you use it? I’ve used it before and didn’t like it. You know, we
early–we care about all kinds of feedback. And we really want to make sure that people
use the library. Why do we want to make sure that people use the library? v2009 has a few
gotchas. You know, there’s issues with namespacing. So I think, for some of you who have already
started migrating, you realize that there’s many new namespaces now. There’s basically
campaign management namespacing, there’s the info namespace, there’s the job namespace,
there’s that like optimization namespace. All these namespace is playing together and
have a good [INDISTINCT] types and make sure that those are correct. And then even making
sure that your request header is under the CM namespace but it might, you know, the rest
of service might be the other Job Namespace. A lot of these things are very hard to keep
track off. And we make sure that our client libraries are 100% compatible with the API.
And other things we have lots of code examples. So we recently went back to our client libraries
and we said “What do people have the most trouble with?” And what we did is we made
pretty much one example for every piece of functionality in the API. So, you know, for
CampaignService, we have–someone’s running Avast. I recognize that. So, for CampaignService,
we have, like, you know, AddCampaigns, getAllCampaigns, getAllPostCampaigns, UpdateCampaigns, [INDISTINCT]
for CampaignService. So pretty much every service we have a set of examples that cover
all functionality. So you could just use our examples like a toolkit and get started. So
this is great for, you know, beginners, it’s great for intermediate who kind of like, you
know, saying, “Well, I don’t want to remember how to do this.” and it’s really great for,
you know, maybe expert users who want to have another pair of eyes on how we’re doing it.
All right, and you know, there’s going to be a lot of links throughout these slides.
So, you know, if you want the copy to down, we gave you the link. Really, you know, use
these slides as you’re going along in the future for, you know, just a reference back
to all the resources that we provide. So then, there’s the ring part of all the resources.
And these include the articles and documentation and our blog post. So, I’m sorry for all the
show of hands, but how many people are reading our blog currently? Great, that’s awesome.
So yeah, so you guys have seen that our blog is, you know a great resource of finding out
if one things are changed in the API, looking at downtime. You know, we have a new series
called Discover v2009 which kind of talks about all the new features. And, you know,
we’ve gotten some great feedback about how this is actually helping see all the new services
that we’re offering. So, we’re going to continue to do that as we release more services. We
also have lots of articles and documentation. The three that I think are most helpful for
migrating to 2009 is/are “What’s changed in v2009?”, our “Migrating v13 to v2009.” and
our “Per-call migration guide.” So, considering a lot of you had already start migrating,
I assumed that you guys have seen these documents. For those who haven’t, you know, you could
take a look during today and let us know what you think of them and, you know, what else
might be a good idea to add to these? All right, so. Where to start? So, as I said earlier,
the services that are–we are sub-setting on “We’re turning off on April 22nd, 2010”
is the campaign management stuff is everything under the CM namespace. The SiteSuggestionService
and the KeywordToolService which is being replaced by the TargetingIdeaService. We have
a blog post that kind of describes how you would migrate from one to the other. Just
specifically today, I won’t show any code examples about migrating that. But it’s fairly
straightforward. And then, we have the InfoService which has been completely rewritten. So, you
know, you might want to take a look at that if you have to do any kind of [INDISTINCT]
management or operation management. You know, mostly tracking like free events and stuff
like that. The services that aren’t good, and that’s AccountService, ReportService and
TrafficEstimatorService. All three of those are currently in the work for v2009. We haven’t
reached the point where we want to release those yet. When we do release them, again,
we’re going to get feedback. We’re going to make sure that people are happy with them
that they have all the feature parity. And when we do get to the point that we realized
that they have feature parity, then we’ll begin the sunset clock. Okay, so, we can get
into the coding part. The way that I recommend going about upgrading your code. And I think,
Aaron touched on this briefly when he was up here, is I really like the divide and conquer
method. So, there’s really three steps of this. There’s the breaking of the code into
the first service chunks. There’s referencing objects by its primitive IDs. So that means,
you know, instead of passing around the campaign object, you know, passing around any of the
long campaign ID. And there’s migrating the code chunks. So, you know, why do I choose
these three steps? Well, we have a lot of internal tools that we had to deal with. And
when we try to migrating them all just in one big kind of blog, we found that, you know,
maybe our stuff wasn’t as decoupled as we want it to be. So, while we are breaking up
the code into first service chunks. And then, upgrading the primitive IDs, we also notice
that it’s very easy to run co-version code. So, you know, right now, we don’t actually
offer, you know, the ReportService for v2009. But when you break up the code into first
service chunks and these service chunks can either be in the same–in the same class or
different classes, you’re able to like say, “Use AdGroups of v13 and Campaigns of v2009,”
by reference the primitive IDs. So this is a way that you could migrate your code in
steps rather than, you know, tackling all at once of adding, you know, lots of Red Xs
all over your Eclipse project. Okay, so I have–on the same thing that I’ve been showing
all along. There’s also an example project that you guys can follow along with. I don’t
think it’s changed too much since I posted it there, but there might be a few differences.
But basically, it’s kind of just an empty project–the couple of projects that you promote
into Eclipse and play along as I go along. Okay. So, I’m going to switch over to Eclipse
now. Can everyone see the code all right? Yup, okay. So, I have one–so, basically the
coding example I have here is the same one as on our article of migrating from v13 to
v2009. The goal of the example is to show that you can [INDISTINCT] use v13 code along
with v2009 code and how you would do that. Just a show of hands, how many people are
using the Java coder, Java [INDISTINCT]? Okay, so roughly half of you are Java programmers.
In the other languages, I’m guessing either “.net”, PHP, or Python, one of the–you know,
the other main ones. You know, it’s very–it’s going to be similar on to how you would do
co-working code. Obviously, “.net” would be very more similar than Python and PHP. We
only have v2009 right now. We’re not–we really don’t support APIlity or have that integrated
to v2009. We’re suggesting to migrate it to our v2009 client library. And we can take
any questions about that going forward as well. So I’m going to do all of my examples
in Java, but that should be pretty easily transferred to any other languages. Okay,
so just to get started–I just want to look at my computer–we’re going to start off by
just kind of reviewing what we do in Java to, you know, get a service. The first thing
you want to do is you want to create an AdWords user. And what this is doing is going to be
credentials from the–basically, my home directory on Windows and the properties file from it.
So, really briefly, we can talk about basically the credentials of v2009. The biggest change
is the authentication token. And this is a very radical change from v13. In v13, we had,
basically, email password. And we were expecting a lot of people to store that. And that’s
not very secure. So what instead we’re doing is we’re moving to a token phased system.
And use the–use the client login API to generate this token. And then you can set the token
into your client library. And you don’t have to worry about having any passwords lying
around. What I’ll be doing going forward is just showing how to pull this properties file,
which does pull an email password and generate the client library, generates the token for
it if it needs it for v2009. But, all the client libraries have the functionality of–either
setting a token manually or pulling the email password and have it, the client library,
generate the token for you. All right, so this is my new user is just setup so that
it’s just a client manager talking to a client. So basically, that client is setup with a
bunch of campaigns, a bunch of AdGroups keyword and whatnot. And the goal this piece of code
is to, one, get all the campaigns, then it iterates through each campaign, it gets every
AdGroup for the campaigns. So notice here, this is what I was talking about that AdGroup
service had a function called getActiveAdGroups, which is not consistent with anything on all
the other services. So again, this is just v13 code. This gets the AdGroups. It then
collects all the AdGroup IDs. It schedules are record job which is of type AdGroup. It’s
we’re going to call a campaign number, you know, a campaign number because it’s all the
AdGroups that belong to that particular campaign that we’re iterating there. It’s going to
set the columns, it’s going to set the columns as Campaign, AdGroup, Clicks, CPC, CTR. So
this might be a simple report if you might do the–you know, kind of give a performance,
you know, very, very huddle on the performance overview of that particular campaign. All
right, notice here that we’re doing “setAdGroups(adGroupIDs)”. So, this already is not expecting cognitive.
And then we just schedule a ReportJob and then move backwards. So again, we’re going
through each campaign that we find, going through each AdGroup, we’re collecting all
the adGroupIDs and then we’re scheduling a ReportJob for all those adGroupIDs. So, if
you look back in my three steps, what we want to do is we want to do break up, then we want
to do primitive IDs, and then we want to migrate our code. So the first step that I would go
upon looking at this is saying “How can I get a general kind of way of dealing with
this outer structure?” So right now, everything’s kind of blogged together in this one class.
What I want to do is maybe have, you know, maybe a new method that gets all the hours’
campaigns and maybe a new method that gets all the adGroupIDs, and then maybe a method
that that schedules as actual ReportJob. So, we go to our new code example, we’re going
to call it Breakup. I’m going to copy the text over as I go to discuss–less typos,
but I’ll walk through it. So, this is my new method. It’s called–this is the same thing
as before which is monthlyReportCreator. And I’m–I’m sort of specking it out right now.
I’m saying that, “I’m going to have this new campaign called–I’m going to have this new
method called getAllAdWordsCampaignIds. It’s going to return an int array of campaignIds,
which–where I’m going to show you, you have to upgrade because it’s v2009. It’s going
to go through each ID and it’s then going to get all the active adGroupIds for each
ID. And that’s going to schedule–it’s going to schedule the CampaignReport for that campaignId
and those adGroupIds. So, the first thing I want to do is tackle that method called
getAllAdWordsCampaignIds and, again, this is just v13 code. All right, let me expand
that. All right. So, I have this method now called getAllAdWordsCampaignIds. Notice that
at the beginning of it, I’m creating the user. In all my methods, I’m just creating the user
and creating the service, and then sort of forgetting about them and letting the garbage
collector take care of it itself. I would suggest that you’re going to need–using the
client library that, you know, you can keep track at these user, keep track at these services,
that’s really a big feedback to us as to how you are using these client libraries. Are
you throwing away the object? Are you holding on to the object? What kind of memory performances
are you seeing, you know? If you’re a reseller, you probably have tons and tons of clients
that you’re creating. You know, if you’re a home user, you probably only have maybe
three or four hours users that you’re creating. But it’s really important to us to make a
solution of, you know, that tells everyone’s needs. All right, so, I’m getting the CampaignService
just by doing user.getService AdWordsService.v13.CAMPAIGN_SERVICE and this will vary depending on the client
library but it’s all generally the same when you create this user and then you get the
service from the user. And then, getting the campaigns running getAllAdWordsCampaigns and
giving that dummy a variable, which is just one in this case. I then go through every
campaign and just pull out the IDs in this array, and then I return that array. So, it’s
a nice little, you know, chunk of pill that only deals with the CampaignService. And I’m
not dealing with campaign objects after that part. So you can imagine that instead of just
returning maybe campaignIds, I could put them into a database. I could send them along with
some socket. I could do whatever I want. Having these primitive IDs really allows me to explore
my options and the APIs really setup to handle these primitive IDs as well. And the next
step that I want to do is make the AdGroup breakout. So, I’m going to copy the rest of
the code in there. Okay, and then, I have this getActiveAdGroupIds. And remember, this
is the next step in the loop. This is just pulling out all the AdGroups the same way
we pulled out the campaigns in collecting the IDs together. Notice that these AdGroupIDs
are long. So again, where were we? We had just generated the campaignIds and the AdGroupIds.
Going up to this top loop, we have campaignIds coming from getAllAdWordsCampaignIds, which
is what I make, which is what I’ve created. I go through each of those and I get all the
active AdGroupIds. I then, schedule this CampaignReport, which I’ll now show you right now which takes
that one CampaignID that I’m iterating through and all the AdGroupIds that belong to that
campaign. So, going down here on the bottom, you notice the same little overhead every
time. I do–I get the user, I create the service, and then I just define the ReportJob and set
all of the fields that I’ve talked about before. So, I’m just taken that code of chunk that
was existing in the for loop before and moving into it’s own method. All right, so, the key
thing that I want people to look at before we go to upgrading to v2009. Notice that this
is an integer array for campaignIds right now. In v2009, campaignIds moved to long values.
That’s not because we ran out of integers for campaigns. It was more along the lines
of all of the other, all the other IDs were longs to begin with. And it just was kind
of a pain to have, you know, all the IDs being longs and then have the campaign begins. And
this was a direct feedback from everybody. So this is an example of feedback working
us all back in to the API group. All right, so we’ll move to the upgrade section. So,
notice that I still have the same method now. I’ve just–I’ve just change campaignIds to
longs, instead of int. So that was the beauty of breaking out. My main logic part of the
code remains completely unchanged when I’m operating, because I’m only dealing with primitive
values. So now, I’m able to say, okay, I’m going to start by upgrading getAllAdWordsCampaignIds
to v2009. What I’ll do is I’ll copy over the upgrade part and then walk through it. Okay,
so notice I still have my getAllAdWordsCampaignIds. And this is my old example from v13–sorry,
I’m in the wrong file. So, I’m just going to paste this in here and what I’m going to
do now is–this part of the code is already now upgraded to v2009. So, notice it’s the
same overhead. We have the user then we get the getService, and now we have the service
client for v2009. The only difference is before I had .v13 and now I have .v200909, so you
[INDISTINCT] to worry about imports and using these correct objects. So, it looks simple,
it’s deceiving a little bit but if you notice up here, you’ll see that I have a mixture
of v13 and v2009 objects. So, right now I have the v200909 campaign objects and I have
the v13 report objects sitting there. And no one’s getting [INDISTINCT] each other because
you use primitive values. I wouldn’t–I wouldn’t, for example, be able to say add campaign in
v13 with the v2009 campaign. They wouldn’t be able to fit. So this is why, you know,
we can do co-version code but we need to be careful about which version we’re dealing
with when we build complex objects. Okay, so let’s walk through the getAllAdWordsCampaigns
for v200909. So, the first part is I get the user, then I get the service. And at this
point because it’s v200909, it’s generating up indication token for me and it’s setting
that in this CampaignService object in the request header, header’s portion. The next
step is I want to create a selector. And this is where v200909 really differs from v13.
In v200909, we have selectors and getMethods as oppose to getAllMethods. So, these selectors
allow you to pull out individual campaigns by ID, maybe pullout a campaigns that only
have a certain status. It really depends on the selector for each service and it’d be
great if you guys told us, I mean, what do you want to see in those selectors. You know,
maybe someone wants to pullout all campaigns that have a certain click-through rate of
this or that, you know, like, things like that are really great feedback in terms of
what you want the selectors to do. Notice that I’m supplying an empty selector. When
you supply an empty selector through the API that just means getAll. So in this case, I’m
just sending in an empty selector. I get the campaign page back. And then, I’m going through
the campaignPage.entries, which is all those entries in the page and I’m just selecting
the campaignIds out of all those entries in the page, and putting them into an array.
So, just specifically right here, I do campaignPage.getEntries, which is an array of campaigns. I pick up
the one that I’m iterating through and then I just say .getID on it. So, this is a subject
that I don’t think a lot of people grasp with the paging aspect. In some of our–in some
of our selectors not all just yet, but we’re making sure that it get consistent, you’re
able to page through objects. So, you’re able to say, “Give me 500 objects at a time, and
then, offset by this and offset by this then offset by this.” So, the start index changes
and the total results of that slide will determine how many pages that you want to get. So, you
would just have a wide opening that would go through it and say, “Give me 500, change
the start index, give me the next 500, change the start index, give me the next 500–oh,
I’m sorry, change the offset.” It really depends on–I think I’m not–let me double check it
real quick. I’m not sure if it’s start index or–right, so the paging object, pass. So,
you pass it in the new paging. And then now it takes the start index and a number of–yeah,
so, you would get a start index every time that you get a page. So, the paging object
has start index and then the number of results. So, if I want to do 500 at a time, I would
just say number of results 500 and I’ll just change the start index from zero to then 500,
to then 1,000 and then I’ll get 500 objects every time.
>>So, it’s better the selector then to [INDISTINCT] I guess they’re uploaded [INDISTINCT]. I was
thinking about that.>>ROGAL: Yeah, so I think that’s one of the
things that’s a little bit confusing as the whole paging aspects just because it’s completely
new to v200909. You know, it’s a very good feedback that there’s no code examples for
it right now besides what we do in targeting idea service. I believe we do new paging in
that. But I think that’s a good point and we’ll be adding an examples all the time,
I’ll raise the show paging through objects. But it’s–and again, it’s pretty simple, I’ll
show you really quickly. Did you notice that CampaignSelector takes a number of things
like IDs, statuses that I want to select, I know it’s a small font so I’m reading it.
Stats that you want to select and then the last one is paging. And then again, when you
send in your paging object, that’s my last–it would be my last thing, so I do null for everything.
And then in my last one, I would send in a paging. This takes a start index, so I’ll
give it zero and then 500, and this would take out the first 500 objects. And then,
for my next segregation through, I might choose start index of 500 and until 500 again, and
null for the next 500. So, at this point I’m now done migrating my–I’m now done migrating
my CampaignService stuff to v2009. If I still have my v13 stuff flying around for AdGroups,
it would then work in the same program. Because I have separated everything out of these services,
I’m dealing with just the primitive IDs. The objects don’t collide with each other and
you’re able to use the two different cell clients for both v13 and v2009. So, the next
step is then operating the Get All AdWords, Get All AdGroups. And I copy that portion
over.
So, let’s just walk through this way quickly. I’m getting my user as always during the AdGroupService,
which generates my authentication token. I’m then creating a selector for AdGroups. Each
selector is defined by a subject that’s going to be selecting. So, you would see something
like–I’ll just import everything to get rid of these arrays. Every time that you create
a selector, if you like AdGroupSelector, CampaignSelector or targeting an ES selector, all of these
different things defined the different selectors. So, basically, AdGroupSelector is very specific
to the AdGroupService. It has–a lot of different things that you can set. One of this is the
CampaignID. So, when I’ve given an AdGroupSelector of CampaignID, that says getting all the AdGroups
that exist underneath this campaign. So notice now that our gets–our getMethod only have
one object, which is the Selector. So now on v13 where we are passing in all the different
parameters to the method, which cause a lot of bloat to the method sometimes, now we have
a lot more dynamic selector objects which, you know, you only have to set things that
you care about. So it gives you a lot from your code like I’ve shown you out. Okay, so,
just following the same structure that I have before, and I have this AdGroupPage. And,
again, I can paste the results if I wanted to. What I’m going to do is I, then, going
to go through all the different AdGroups in the entities. So, you know, basically this
getEntries is just an array of AdGroups. I go through all of them, and I just add these–I
check to see if the AdGroupStatus is enabled. If it is, then I add it to the list of active
AdGroupIds. And then I just turn this into a primitive long array and then return it
back to the method. So, now, this method is now upgraded to v2009. And the [INDISTINCT]
were the only two methods that we’re log on by 2009. I have my old method of scheduled
CampaignReport that needs to–that I don’t need to change. Because I broke up all the
services into different methods, this one only relied on having a CampaignID and then
a list of AdGroupIds, which I’ve now upgraded to my v2009. So, now, this little program
is completely upgraded and ready to go. So, that concludes the coding portion of today.
S, I will open it up to any Q&A now. And I’ll leave it on the slide right here. The main
takeaways from today, again, are that April 22nd is fast approaching. And we think that
client libraries are one of the better ways of upgrading to v2009. If you can’t use a
client library, please let us know. I really like the feedback so far in client libraries
and, you know, we are going to be taking this feedback and immediately integrating it into
our [INDISTINCT] because the feedback that you guys give today is extremely of high priority.
It’s direct feedback which traps all else. You know, we’re here to help. We have the
forums which I think are the best way to get–get the answers. Either you can search for forums
or you can ask questions on there. And people will either–or the forum members will answers
them or we have a dedicated staff that will answer the questions in the forum as well.
We had the documentation researches. We have the document resources like documentation,
articles and blog post. And just, you know, divide and conquer and jump in and take step
and then let us know once you’re having difficulty with that so we can help.

Leave a Reply

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