Maski pól umożliwiają osobom wywołującym interfejs API wyświetlanie listy pól, które żądanie powinno zwrócić lub zaktualizować. Użycie FieldMask (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 API Dokumentów Google.
Czytaj z maską pola
Dokumenty mogą być duże i często nie potrzebujesz każdej części zasobu Document zwróconego w żądaniu odczytu. Możesz ograniczyć ilość danych zwracanych w odpowiedzi interfejsu Dokumentów Google przy użyciu parametru adresu URL fields. Aby uzyskać jak największą wydajność, w odpowiedzi wymień 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 rozdzielonych przecinkami, a pola podrzędne – kropkami. Nazwy pól można podać w formacie camelCase lub resolution_by_underscores. Dla wygody możesz podać w nawiasach wiele pól podrzędnych tego samego typu.
W tym przykładzie żądania documents.get użyto maski pola title,body.content(paragraph),revisionId do pobrania wartości title dokumentu, Paragraph obiektu Body i revisionId dokumentu w dokumencie:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,body.content(paragraph),revisionId
Odpowiedź na to wywołanie metody to obiekt Document zawierający komponenty żądane w masce pola:
{
"title": ""TITLE",
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": ""CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
"revisionId": "REVISION_ID"
}
Zaktualizuj za pomocą maski pola
Czasami trzeba zaktualizować tylko niektóre pola w obiekcie, a pozostałe pola pozostawić bez zmian. Żądania aktualizacji w ramach operacji documents.batchUpdate używają masek pól, aby poinformować interfejs API, które pola są zmieniane. Żądanie aktualizacji ignoruje wszystkie pola, które nie są określone w masce pola, pozostawiając w nich obecne wartości.
Możesz też cofnąć ustawienie pola, nie określając go w zaktualizowanej wiadomości, ale dodając to pole do maski. Powoduje to usunięcie wartości, które wcześniej miało to pole.
Składnia masek pól aktualizacji jest taka sama jak masek pól do odczytu.
W tym przykładzie użyto elementu UpdateTextStyleRequest, aby określić styl słów „Google Docs API” w dokumencie jako pogrubiony w zakresie range 5–20:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"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
},
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID"
}