Używanie masek pól

Maski pól to sposób na podanie przez wywołujących interfejs API listy pól, które żądanie powinno zwracać lub aktualizować. Korzystanie z FieldMask pozwala interfejsowi API uniknąć niepotrzebnej pracy i zwiększa wydajność. Maska pola jest używana w metodach odczytu i aktualizacji w interfejsie Google Slides API.

Porównanie tego, co zwracane jest w ciele odpowiedzi, gdy nie używasz maski pola, a gdy używasz, znajdziesz w artykule Praca z częściowymi zasobami.

Odczytywanie z maską pola

Prezentacje mogą być duże i często nie potrzebujesz wszystkich części zasobu presentations zwróconego przez żądanie odczytu. Za pomocą parametru URL fields możesz ograniczyć zakres zwracanych danych w odpowiedzi interfejsu Slides API. Aby uzyskać najlepszą wydajność, wymień w odpowiedzi 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 podpola – 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.

Ten przykład żądania metody presentations.get używa maski pola slides.pageElements(objectId,size,transform), aby pobrać tylko identyfikator obiektu Size i przekształcić obiekt 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 określone 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"
          }
        }
     ]
    }
  ]
}

Aktualizacja za pomocą maski pola

Czasami trzeba zaktualizować tylko niektóre pola obiektu, pozostawiając inne pola bez zmian. Żądania aktualizacji w metodach presentations.batchUpdate używają masek pól, aby poinformować interfejs API, które pola mają zostać zmienione. Żądanie aktualizacji ignoruje wszystkie 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 przypisana do tego pola.

Składnia mask pól do aktualizowania jest taka sama jak w przypadku mask pól do odczytu.

W tym przykładzie użyjemy metody UpdateShapePropertiesRequest, aby zmienić kolor wypełnienia kształtu na kolor motywu DARK1 i usunąć obrys 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"
      }
    }
  ]
}