Używanie masek pól

Maski pól umożliwiają wywołującym interfejs API wyświetlanie pól, które żądanie powinno zwrócić lub zaktualizować. Użycie FieldMask pozwala interfejsowi API uniknąć niepotrzebnej pracy i zwiększa wydajność. W interfejsie Google Slides API maska pola jest używana zarówno w metodach odczytu, jak i aktualizacji.

Aby porównać, co jest zwracane w treści odpowiedzi, gdy nie używasz maski pola, a co, gdy jej używasz, zapoznaj się z artykułem Praca z częściowymi zasobami.

Odczytywanie za pomocą maski pola

Prezentacje mogą być duże, a często nie potrzebujesz wszystkich części zasobu presentations zwracanych przez żądanie odczytu. Możesz ograniczyć zakres informacji zwracanych w odpowiedzi interfejsu Slides API za pomocą parametru URL fields. Aby uzyskać najlepszą wydajność, 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.

Ten przykład żądania metody presentations.get używa maski pola slides.pageElements(objectId,size,transform), aby pobrać tylko identyfikator obiektu, Size i transform obiektu pageElement na wszystkich slajdach prezentacji:

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

Odpowiedzią na to wywołanie metody jest obiekt presentations zawierający komponenty żądane w masce pola:

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

Aktualizowanie za pomocą maski pola

Czasami trzeba zaktualizować tylko niektóre pola w obiekcie, pozostawiając inne pola bez zmian. Żądania aktualizacji w metodzie presentations.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.

W tym przykładzie użyto metody UpdateShapePropertiesRequest do zmiany koloru wypełnienia kształtu na kolor motywu DARK1 i usunięcia konturu kształtu:

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
 
{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}