AARON KARP: Generic Selectors.
We have a new Generic Selector type.
It replaces the Service Specific Selectors that you've
been using before.
So whereas, say, Campaign Service had its own selector
type, now we have one single selector object that is used
across services.
Now the biggest difference you guys will notice immediately
is that instead of selecting all of the fields for an
object at once, you now have to specify the individual
field that you want back.
This also provides for powerful filtering and storing
options within your selectors.
So Generic Selectors return objects specific to the
service that they're used with.
What does that mean?
It means that you can use the same selector objects on the
Campaign Service, that you can use on the AdGroup AdService
or the AdGroup service.
And it will automatically return a list of AdGroups, or
campaigns, or ads, or whatever it is that you're using it in
conjunction with.
You could also do this previously.
But we've maintained the stash retrieval functionality for
specific date ranges, request ordering, and request paging.
These are the services that are
moving to Generic Selectors.
I'm sure you guys will recognize quite a few that you
use selectors on yourselves.
So this whole list is available through the
documentation.
So fields can be either selectable,
filterable, or neither.
These are the fields of an object.
So if it's selectable, it means that it can be retrieved
with a Selector via a get operation.
So that's something like the campaign ID.
Filterable means values can be filtered using a Predicate
within a Selector.
Not all fields fit into both categories.
Here for the AdGroup object, you have the AdGroup ID.
It says that it is Filterable and Selectable.
The status is also Filterable and Selectable.
So what does the new Selector object look like?
It would have the following five fields.
The fields field, which is the list of fields
that you want to select.
This is the one required field, here.
The predicate.
This is what you use for filtering.
The date range for stats that you want.
The ordering--
fields to sort off.
You can sort on multiple fields, as
well as the sort order.
So you can do campaign name ascending, and then by click,
for example.
Paging has rules for paginating of the results.
So, for example, we want to get these four fields back for
any Campaign Object.
Then we will use the following Selector.
Set the field as an array of strings, these four.
And then this Selector could be used as a get operation
just as it is.
Remember, I've said that the fields field is the only
required property you have to set on the Selector.
So if you only want to retrieve a campaign with a
specific ID, or you only want to retrieve a campaign with
more than 200 clicks over a specific date range, you can
do all of these quite powerful things using predicates.
Here we say, for this predicate object, we're
setting the field that we want filter on as ID.
We're setting the operator as in, so the ID is in
this array of values.
And then we add that predicate to our Selector Object.
So here we're going to sort by two different properties.
First by name ascending and then by start date descending.
Again, pretty easy.
We create our order by objects and set the field names to
name and start date.
We set the order here to descending, Because we don't
need to put the defaults for the other one.
Paging works quite similarly to how it
did in the old version.
So we set our start index.
We set the number of results we want.
Pretty straightforward, right?
Good, now let's talk about selecting Stats.
So you use the Selector dateRange to specify the Stats
fields that you want returned.
So if you are selecting the following fields--
Id, Text, Clicks, Ctr, and Cost--
and if we want to filter where the Clicks are greater than
200, then you'd use the following Selector.
Here we're setting the fields that we want back.
And we're setting the date range specified
in the strings above.
Then we're adding a predicate.
We're saying that we want to filter on fields, where the
value is greater than 200.
So the list of available predicate
operators is pretty big.
It will be the full list in the documentation.
So the Response Objects is the same type that you got back in
previous versions.
If you're using Generic Selectors for the
CampaignService, you get back a Campaign Object.
Using them for the AdGroup service, you
get an AdGroup back.
Now one thing to note is that you may get null values back
for fields that you don't request. So if your code is
currently indiscriminately accessing fields on the
objects, you might need to add in some null checking.
An easy way to do the migration is just check which
fields you need in your existing code, and then build
your Selector to match that.
So what are some best practices?
First of all, specify only the fields you actually want.
Don't try to imitate the Select Star functionality of
the previous version.
This defeats the purpose.
And you'll always be playing catchup as
we modify the objects.
These are the two errors you will most commonly see with
Generic Selectors--
the invalid field name and the invalid predicate field name--
which are pretty self-explanatory.
You give us a string that we don't know how to handle,
we'll give you back this error.
And then, use Generic Selectors to add new and
interesting functionality.
So, get criteria with clicks greater than 200 and ctr of
less than 2.0 last week.
So if you don't have all of the data for a given account
cached in your system, you can select it all on the fly,
based on your user's needs of your application.
So we have put together a Selector Migration Guide.
It includes both a mapping of the fields in each object to
their selector names, if you will, selector field names.
And it also includes some sample code and PHP that shows
roughly what I've put up on the board today.
Thank you very much.