Używanie masek pól

Maski pól umożliwiają wywołującym interfejs API wyświetlanie listy pól, które powinny być zwracane lub aktualizowane przez żądanie. Użycie 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 za pomocą maski pola

Dokumenty mogą być duże, a często nie potrzebujesz wszystkich części zasobu Document zwróconego przez żądanie odczytu. Za pomocą parametru URL fields możesz ograniczyć zakres informacji zwracanych w odpowiedzi interfejsu Docs API. Aby uzyskać najlepsze wyniki, w odpowiedzi wymień tylko te pola, których potrzebujesz.

Format parametru fields jest taki sam jak kodowanie JSON elementu FieldMask. Krótko mówiąc, różne pola są rozdzielone przecinkami, a pola podrzędne – kropkami. Nazwy pól można podawać w formacie camelCase lub separated_by_underscores. Dla wygody wiele pól podrzędnych tego samego typu można umieścić w nawiasach.

W tym przykładzie documents.get żądania użyto maski pola title,tabs(documentTab(body.content(paragraph))),revisionId do pobrania title dokumentu, Paragraph obiektu Body (ze wszystkich kart) i 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 żądane 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"
                }
              }
            }
          ]
        }
      }
    }
  ]
}

Aktualizowanie za pomocą maski pola

Czasami trzeba zaktualizować tylko niektóre pola w obiekcie, pozostawiając inne pola 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, i pozostawia w nich bieżące wartości.

Możesz też usunąć pole, nie określając go w zaktualizowanej wiadomości, ale dodając je do maski. Spowoduje to usunięcie wartości, która była wcześniej w tym polu.

Składnia masek pól aktualizacji jest taka sama jak w przypadku masek pól odczytu.

Maska pola * jest traktowana jak symbol wieloznaczny i jest skrótem oznaczającym wszystkie pola w wiadomości. Składnia symboli wieloznacznych może w przyszłości powodować niepożądane wyniki, jeśli interfejs API zostanie zaktualizowany, ponieważ pola tylko do odczytu i nowo dodane pola mogą powodować błędy. W przypadku aplikacji produkcyjnych zawsze wymieniaj w maskach pól konkretne pola, które są aktualizowane, i unikaj używania symboli wieloznacznych *.

W tym przykładzie użyto elementu UpdateTextStyleRequest do zastosowania stylu pogrubienia do słów „Google Docs API” w dokumencie 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
        },
      }
    }
  ],
}