KEVIN WINTER: Hi everyone.
As I was introduced, my name is Kevin Winter.
I am a developer programs engineer here at Google on the
developer relations team.
And I support the AdWords API.
I am going to be talking about some updates to
reporting for v201109.
To start off with, the v13 Report Service was introduced
a while ago, also pretty limited.
v13 Report Service is fairly old.
It has been around for a while now.
It was originally intended to be sunset in August of 2011.
So starting with v201109, we're using kind of a new
paradigm, a new way of approaching reports.
Calls to the API
ReportDownload Service are free.
We have a number of improvements we have been
making to v201109 to make it a very suitable replacement for
running lots of reports and removing some of the downsides
of v201101.
And making it a much more viable alternative to v13
cross client reports than v201101 ever was.
So to give you a quick example, this is what a
v201109 Report Definition looks like.
It's fairly straightforward.
As I mentioned before, you have a selector.
Which in this case, only has a list of fields.
You can add predicates to the selector to specify, I only
want to get my active campaigns.
Your report name is mostly for your own use at this point.
You can still specify the Report type.
Your Date Range type, which will be using one of these
dynamic date ranges we added in v201101.
Or you can use a Custom Date Range, and specify them on the
fly for three quarters ago, which is something the current
dynamic date ranges don't support.
When making an AdHoc Report Request, as mentioned, you
actually send the report definition as the HTTP request
body when downloading the report.
You can make an HTTP POST Request, or you can make an
HTTP GET Request. And I'll go to that in a few seconds.
But when you make these requests, you need to still
specify authentication and ClientCustomerID headers.
As I'll get into later, you're going to only be able to use
ClientCustomerID in 201109 and forward.
The body of the requests will need to be URL encoded.
In the previous example, when I showed you the
ReportDefinitionXML, it was not simply for clarity.
But when you're making this request, you will need to URL
encode the body.
This is just in case you have any non-URL safe
characters in this.
And when we interpret the request, we know
exactly what you mean.
You're going to want to use a name parameter, __rdxml, to
reference the report definition.
So when you send your Report Request, you can use the
content type of form URL encoded, which is a very
common content type.
This is supported by many HTTP libraries in many languages.
And all you need to do is just make sure that you do URL
encode the body and use the request parameter.
It is going to be __rdmxl.
So when you're making report downloads, you still need to
specify some form of authentication.
A lot of times when you're managing a lot of reports, we
strongly recommend that you use an MCC account to manage
these accounts.
And you use an Auth Token requested for
that specific MCC.
So when you download your report, the only thing that's
changing every time is the ClientCustomerID header.
The other option you now have is OAuth authentication, which
is new for 201109.
You can now use OAuth to access the MCC, or even the
individual accounts, if that's the way you'd want to do it.
And you can sign each individual group or download
request using the OAuth access token and still specify the
ClientCustomerID to identify which account the
report will be for.
So here's an example of how a Report Request will look.
You have your URL, which as you may note, is now version.
You now have adwords.google.c om/api/adwords/reportdownload
which was your normal URL.
And it's now /v201109.
This is also new for 201109.
The key benefit of this is that now we can start
versioning report downloads.
So instead of having us make a change that changes the way
the reports return, we can now make them in a version change
without having you worried about your code instantly
breaking because we have to fix a bug or make some change
that, when your code is relying on a slightly older
version of the API.
You're still going to use your HTTP POST Request header, such
as ClientCustomerID.
Your authorization, which will have the Auth token specified
at the Google login.
And your content type is form URL encoded.
And the request body would look very similar to this,
except that, as I keep mentioning, it does need to be
URL encoded, just to make sure that we can correctly
interpret your request.
So now we're going to show you in Java how you can download
that report using a very simple library.
So we're defining a very simple interface here, where
you are specifying the Auth token, the CID, and the
ReportDefinitionXML, which are the three key components.
If you're downloading for a lot of accounts with an MCC's
Auth token, the only thing that will be changing when you
make this request will be the CID for each of these
subserver requests.
In our case, we're using an HTTP URL connection, which is
built into the Java JPK.
It's also supported on App Engine, if you ever decide to
develop for App Engine.
And what we do is we open a connection to our Report
Service URL.
We then set DoOutput, which is basically saying we're going
to be putting stuff in the request body.
We set our request properties, ie.
HTTP headers, for our ClientCustomerID, the
authorization, and content type.
And we set the RequestMethod at the POST. Because we're
going to be posting the message to them.
Then we're going to just obtain a OutputStream Writer.
And wrap that around the OutputStream for the HTTP URL
connection, so we can write directly to the request body.
Next, we write our parameter, __rdxml.
And then we URL encode our ReportDefinitionXml.
As I said, so we can interpret it properly.
Then we simply get the response code, which actually
makes the request and interprets the response, and
gets to know what the result is.
I'll get into what these status codes will mean for you
in a little bit.
But in our case, we're simply checking is the response OK?
Which means that the report download was successful.
And in this case, we're simply creating a temporary file.
We are copying function body omitted from the input stream
of the connection to the output stream of the file.
And we're just closing that and returning back in
reference to the file.
There are a lot of things you could do right here.
You could write it into database, do some later
processing, what have you.
But in this example, this is all we're doing.
So when the Report Request finishes and you get your HTTP
response code, these codes will mean different things.
200 is OK.
It means your report downloaded successfully.
The response body will contain your report as requested.
400 indicates a BAD_REQUEST. It means that there was
something wrong about the request that you made.
Maybe you forgot to URL encode the report definition.
Maybe you're missing a header.
Maybe you didn't specify the content-type properly.
These will return as 400.
500 is an INTERNAL_SERVER_ERROR.
This covers any number of things.
It could be a transient temporary failure.
It could be some other sort of internal problem.
But generally, this is the type of issue that shouldn't
normally be happening.
You should be able to retry after a short wait
just to make sure.
Another thing is, we will get RATE_EXCEEDED_ERRORs if you
make too many report requests too quickly from here.
So you definitely want to double check this.
And if you get this, you want to delay before making another
request just so that you don't hit our servers too much and
get blocked.
The other thing to mention is that when you do get anything
other than a 200, the response body will contain some text
that will tell you a little bit more about why you
received this error.
It will tell you that your report definition was invalid.
Or it might say that just the request itself was wrong.
But it will give you some more information.
We also have an explicit flag for getting Rows with Zero
Impressions.
In v201109, we will not include Zero Impression Rows
unless you explicitly add this header and set it to True.
So we also added a new CRITERIA_PERFORMANCE_REPORT.
A lot of people have asked for this.
We previously had our KEYWORDS_PERFORMANCE_REPORT,
URL_PERFORMANCE_REPORT.
Now there's a simple CRITERIA_PERFORMANCE_REPORT
that includes all of these types of
criteria in a single report.
So you can get consistent statistics across all of your
criteria in a single report, instead of requiring several
reports or relying on special behavior and the
KEYWORD_PERFORMANCE_REPORT.