Używanie masek pól

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

Aby porównać, co jest zwracane w treści odpowiedzi, gdy nie używasz maski pól, a gdy jej używasz, zobacz Praca z zasobami częściowymi.

Odczyt z maską pól

Prezentacje mogą być duże, a często nie potrzebujesz wszystkich części zasobu presentations zwracanych przez żądanie odczytu. Możesz ograniczyć to, co jest zwracane w odpowiedzi interfejsu Slides API, za pomocą parametru URL fields. Aby uzyskać najlepszą wydajność, wyraźnie wymień w odpowiedzi tylko te pola, których potrzebujesz.

Format parametru fields jest taki sam jak kodowanie JSON maski pól. Krótko mówiąc, wiele różnych pól jest rozdzielonych przecinkami, a pola podrzędne – kropkami. Nazwy pól można określić w formacie camelCase lub separated_by_underscores. Dla wygody można wymienić w nawiasach wiele pól podrzędnych tego samego typu.

Poniższy presentations.get przykład żądania metody używa maski pól slides.pageElements(objectId,size,transform)aby pobrać tylko identyfikator obiektu, Sizei transformację obiektu pageElement na wszystkich slajdach prezentacji:

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

Odpowiedź na to wywołanie metody to obiekt presentations zawierający komponenty żądane w masce pól:

{
  "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 z maską pól

Czasami trzeba zaktualizować tylko niektóre pola w obiekcie, a pozostałe pozostawić 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 pól, pozostawiając je z ich bieżącymi wartościami.

Możesz też usunąć ustawienie pola, nie określając go w zaktualizowanej wiadomości, ale dodając pole do maski. Spowoduje to usunięcie dotychczasowej wartości pola.

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

Poniższy przykład używa 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"
      }
    }
  ]
}