Maski pól to sposób na podanie przez wywołujących interfejs API listy pól, które żądanie powinno zwrócić lub zaktualizować. Korzystanie z FieldMask pozwala interfejsowi API uniknąć niepotrzebnej pracy i zwiększa wydajność. Maska pola jest używana zarówno w metodach odczytu, jak i aktualizacji w interfejsie Google Docs API.
Odczytywanie z maską pola
Dokumenty mogą być duże i często nie potrzebujesz wszystkich części zasobu Document zwróconego przez żądanie odczytu. Za pomocą parametru URL fields możesz ograniczyć zakres zwracanych danych w odpowiedzi interfejsu Docs API. Aby uzyskać najlepsze wyniki,
w odpowiedzi podaj tylko te pola, których potrzebujesz.
Format parametru fields jest taki sam jak kodowanie JSON obiektu FieldMask. Krótko mówiąc, wiele różnych pól jest rozdzielanych przecinkami, a pola podrzędne są rozdzielane kropkami. Nazwy pól mogą być podane w sposób wielka_litera_z_małą lub oddzielone_podkreśleniem. Dla wygody możesz podać w nawiasach wiele pól podrzędnych tego samego typu.
W tym przykładzie zapytania documents.get użyto maski pola title,tabs(documentTab(body.content(paragraph))),revisionId, aby pobrać title dokumentu, Paragraph obiektu Body (ze wszystkich kart) oraz revisionId dokumentu:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId
Odpowiedzią na to wywołanie metody jest obiekt Document zawierający komponenty określone w masce pola:
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
}
Aktualizacja za pomocą maski pola
Czasami trzeba zaktualizować tylko niektóre pola obiektu, pozostawiając inne bez zmian. Żądania aktualizowania w ramach operacji documents.batchUpdate używają masek pól, aby poinformować interfejs API, które pola mają zostać zmienione. Żądanie aktualizacji ignoruje pola, które nie są określone w masce pola, pozostawiając ich bieżące wartości.
Możesz też zresetować pole, nie określając go w zaktualizowanej wiadomości, ale dodając do maski. Spowoduje to usunięcie wartości, która była wcześniej w polu.
Składnia mask pól do aktualizowania jest taka sama jak w przypadku mask pól do odczytu.
W tym przykładzie użyto UpdateTextStyleRequest, aby nadać wyrazom „Google Docs API” w dokumencie styl pogrubienia w zakresie range 5–20:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{
"endIndex": 1,
"sectionBreak": {
"sectionStyle": {
"columnSeparatorStyle": "NONE",
"contentDirection": "LEFT_TO_RIGHT",
"sectionType": "CONTINUOUS"
}
}
},
{
"startIndex": 1,
"endIndex": 59,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 5,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
},
{
"startIndex": 5,
"endIndex": 20,
"textRun": {
"content": "CONTENT",
"textStyle": {
"bold": true
}
}
},
{
"startIndex": 20,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
{
... // style details
},
}
}
],
}