WESLEY CHUN: Greetings, developers, and welcome
to "The G Suite Dev Show."
In this episode, we conclude our two-part series on field masks.
I'm your host Wesley Chun.
In the last video, we discussed reading data from an API
and how you can use field masks to control
the amount of data that gets returned-- you know,
partial response?
Well, today we'll focus on rights,
or more likely updates--
you know, via post, put, or patch?
Well, you already know that field masks
aren't things you wear but instead work like a filter.
More specifically for updates, think of them as a bit mask,
where data represented by bits that are on
will be updated, whereas those that are off are ignored
and remain the same.
You pass in a field you're updating along with its name
in the mask.
Generally, the field mask will consist
of exactly the attributes you're updating.
If you provide additional fields in the mask that
are not in the request, those attributes will be reset.
Yes, I'll show you what I mean in a bit.
Right now let's look at our first example, this Google
sheet.
Let's say we want to bold the first row.
You'd send this JSON to the API.
Ignoring fields for a moment, you
can clearly see that the repeat cell
request affects the first row.
In particular, we want to set the cells user entered
format slash text format slash bold attribute to true.
The payload looks legit without fields, so why is it there?
Well, remember how I said that the field
mask will consist of exactly the fields you're updating?
Well, here we only want to affect
each cell's bold attribute but no other text format field.
Well, for fun, let's add the italic flag.
Now our request affects bold and italics.
Since we don't have a italics in the request, bold will be set,
but italics will be reset.
Make sense?
All right, here's a more extreme example.
Let's just remove the last part of that mask.
Well, now it's a super-set making up all text format
fields.
Any field not in the request will be reset.
In this case, while bold will still be set,
all others will be reset.
Yep, you can kiss italics goodbye again.
But now the same goes for strike-through and underline.
The original font family and size will come back too.
Well, if you want to specify all fields,
you can use asterisk as a shorthand alternative
to listing every single one, which
you'd have to look up anyway.
But be wary that if the API changes,
you could have inadvertent side effects.
So minimize your use of the asterisk.
Here's the original JSON in actual Python code
that bolds row number one, leaving all other attributes
untouched.
Also see the Sheets API page on update field masks.
Now let's bold some text with Google Slides.
Instead of cells, it's text on the slide.
Given you already have the text box ID,
this JSON bolds the first eight characters in the text box.
Notice that the field's value is simpler here,
no user entered format slash text format.
Well, that's because the root object
for the slide's request is style so you don't have to specify
any other attributes.
Whereas for Sheets, the root object
was cell, meaning you needed the full path from the cell down
to the bold flag, meaning user entered format
slash text format slashed bold.
Each API differs, so check the docs
to determine your root objects.
Here's some Python that implements
bolding of the first eight characters of the text box.
And that's almost the entire story on field masks.
I'd like to share a few parting tips as we wrap up.
One, for the Sheets and Slides APIs,
fields for read operations is an API call parameter,
like you see here.
But for write operations, they're
an attribute you set in your requests.
Updates may also have fields as a parameter.
But this depends on the API and possibly your client library.
Two, some recent APIs have also started
supporting the dotted attribute notation,
so you can use periods instead of slashes.
This makes the APIs more consistent with Google protocol
buffers.
But not all API is supported yet.
So if you try it and it doesn't work,
you're going to get an HTTP 400 error
and need to change the dots back to slashes.
Want to learn more about proto buffs and field masks?
Check out this page in the docs.
Three, when we discussed field masks with read,
it's all about what comes back in the response and not
the actual API request.
In other words, you can have non-read actions that send back
data that you can filter.
In this example, creating a new presentation
with the Slides API isn't a read operation but acts like one
due to its response payload.
The API creates a document and then returns a payload
as if you called get on it, which then you can filter.
The field masks we're using requests just
a presentation ID plus the IDs of all the slide
pages and objects on each page.
We pass in those fields in the same way
for this massive write-plus-read operation.
And four, to complete our journey,
we'll look at another read-plus-write example
that uses both read and write field masks.
The example updates a Google sheet,
but it has this include spreadsheet in response flag
you see here.
That requests the updated Sheet data
be added to the response payload, which
then can be filtered, limiting the amount of data returned.
The data has a header row and a first column made up
of time stamps, where the update request changes the time
stamps, adjusts the date in year, month, day format.
In the code, we request the API return
just a Sheet's name and the URL plus the names
of all the individual Sheets.
Well, how's that for the kitchen sink example?
Field masks in the update request body
and field masks in the call to obtain a partial response--
well, that wraps up our journey into field masks.
Be sure to tune into part 1 if you missed
our show on partial response.
The field masks guide in the Slides API docs
is the most comprehensive, covering read and write.
So check it out if you haven't already.
And check out the last link to see more episodes of "The G
Suite Dev Show."
Now that you know how to use field masks in read
and write API calls, it's time for you
to try out field masks to build that awesome app.
Be sure to subscribe to our channel
to get the latest from Google Developers.
This is Wesley Chun, and we'll see you the next time on "The G
Suite Dev Show."