WESLEY CHUN: Howdy, developers.
Some of you are probably wondering
why I'm wearing a mask that looks like a grassy field.
Well, that's the subject of today's video, field masks.
Love the mask, but it makes it hard for me to talk to you.
Hi, I'm your host, Wesley Chun.
And welcome to another episode of the G Suite Dev show.
[MUSIC PLAYING]
WESLEY CHUN: While we do look at several G Suite
APIs in this video, field masks are general
and apply across Google APIs, from YouTube
to the Google Cloud Platform.
So what are field masks?
Well, they're not masks that you wear.
The best way to think of them is as a filter.
While they work differently when reading
data from, versus writing data to, an API,
the filter analogy is still the most appropriate.
So why discuss field masks?
Well, they're not the most straightforward feature,
and can be confusing for some.
Because the docs are often terse,
it may not be clear as to what they do or how to use them.
So we're going to clear the air so you
can hit the ground running.
Let's start with read.
When making an API call to get information,
response sizes vary between APIs.
Some return just a trickle of data
while others give you an ocean.
If you're using a particularly verbose API, this can add up.
Field masks can help control the amount of data that comes back.
This is commonly referred to as partial response
in the documentation.
Let's look at a few examples from various Google APIs,
starting with Gmail.
In another video, I show users how
to use the Gmail API to update email signatures.
To change a user signature, you need
to loop through all email addresses
to find the ones you want to change.
If you're changing just the primary signature,
you need the isPrimary flag too.
Both are part of the send as array return in the API
response you see here, along with plenty other fields
we don't need.
To tell the API that those are the only fields we
want, specify them as comma separated parent
slash child fields.
An alternative shortcut is to group
the children with parentheses, making it a bit easier to read.
Either way, this instructs the API to drop all other fields.
Well, to see what it looks like in real life,
here's some pseudo code.
Well, OK, it's actual Python.
The snippet displays all of your email addresses
and flags your primary address with a P.
We drop in the fields parameter just like how we drew it up
on the previous slide.
Also see the Gmail API docs page on partial response.
Moving on.
In another video, we showed you how
to display the first 100 files and folders in your Google
Drive, but didn't filter the response.
In a bit, we'll see how this impacts performance in terms
of both space and time.
For now we can use these field mask values so only the IDs,
file names, and MIME types come back in the response.
As before, we can also group with parentheses.
Here's a Python code that uses field masks to get and display
these three fields for each of the 100 files.
The Drive API docs also has a page
on partial response and other good performance practices.
Before leaving this example, I want
to share the results of a little test I ran with the Drive
version to API without fields, like the call you see here,
and then run it again, but with fields.
Guess what?
The payload for the data for all 100 files
comes in at 242k, almost 16 times
the 15K used when getting just the IDs, file
names, and MIME types, saving about 94% in memory cost.
Similarly, executing the API call with fields
took just 144 milliseconds, almost three times faster
than the 554 needed for all of the data.
It wasn't a rigorous study, but gives you a rough idea
as to what field masks can do.
If the API payload is small, the server
doesn't have much work to do to throw those responses together.
But on the other hand, if it has to assemble a car,
you've got some extra overhead.
Why should you incur additional network costs
and negatively impact latency for data you don't need?
Making some sense now?
For the last demo, we'll fetch a spreadsheet's name
plus the names and IDs of each of the individual sheets.
This example is a bit more complex than the first pair
as the values are in different fields,
as you can see from the get response.
This time, the full paths down to each field are too long.
We can do some parenthetical grouping, but in the end
you're going to have a mix and can't really
get it shorter than this.
Here's the corresponding Python snippet
that does what we want with the help of field masks.
There's also a partial response page in the sheet's API docs.
You got the hang of it now?
Well, that was reading from an API.
In part two, we'll look at writing data with field masks,
as well as share some best practices for both read
and write.
Find out more about partial response from this page
in the client library docs.
The field masks guides in the Slides API docs
is the most comprehensive, covering read and write.
So check it out to get a preview before the next video.
And the last link takes you to more episodes of the G Suite
Dev Show.
Well, that's it for today.
Now that we took the mystery out of using them for read API
calls, it's time for you to put on your field mask
and cut down on your API response payloads.
Be sure to tune into part two of our two-part series
to learn more about using field masks with right API calls
and subscribe to our channel.
This is, Wesley Chun, and we'll see you the next time on the G
Suite Dev Show.
[MUSIC PLAYING]