Usa le maschere di campo

Le maschere di campo sono un modo per i chiamanti dell'API di elencare i campi che una richiesta deve restituire o aggiornare. L'utilizzo di un FieldMask consente all'API di evitare il lavoro non necessario e migliora le prestazioni. Maschera dei campi viene utilizzato sia per il metodo di lettura sia per quello di aggiornamento nell'API Presentazioni Google.

Lettura con una maschera dei campi

Le presentazioni possono essere grandi e spesso non sono necessarie tutte le parti Presentation risorsa restituita da una richiesta di lettura. Puoi limitare ciò che viene restituito in Risposta dell'API Presentazioni, utilizzando il parametro URL fields. Per il meglio delle prestazioni, indicare esplicitamente solo i campi di cui hai bisogno nella risposta.

Il formato del parametro field è identico a quello del parametro Codifica JSON di una FieldMask. In breve, più campi diversi sono separati da virgole, mentre i campi secondari separati da punti. I nomi dei campi possono essere specificati in camelCase o separated_by_underscores. Per praticità, sono presenti vari campi secondari può essere elencato tra parentesi.

I seguenti presentations.get di richiesta di esempio utilizza una maschera del campo slides.pageElements(objectId,size,transform) per recuperare solo l'ID oggetto, Size e trasformare di pageElement in tutte le slide di una presentazione:

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

La risposta a questa chiamata al metodo è Oggetto Presentation contenente i componenti richiesti nella maschera dei campi:

{
  "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"
          }
        }
     ]
    }
  ]
}

Aggiornamento con una maschera dei campi

A volte è necessario aggiornare solo alcuni campi di un oggetto senza uscire dal gli altri campi non sono stati modificati. Richieste di aggiornamento all'interno di un presentations.batchUpdate utilizza le maschere dei campi per indicare all'API i campi che vengono modificati. La la richiesta di aggiornamento ignora i campi non specificati nella maschera del campo, lasciando i valori attuali.

Puoi anche annullare l'impostazione di un campo non specificandolo nel messaggio aggiornato, ma aggiungendo il campo alla maschera. In questo modo viene cancellato qualsiasi valore precedente al campo che ha avuto.

La sintassi per le maschere dei campi di aggiornamento è la stessa delle maschere dei campi di lettura.

L'esempio seguente utilizza il metodo UpdateShapePropertiesRequest per modificare il riempimento del colore di una forma con il colore del tema DARK1 e annullare l'impostazione del colore struttura:

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"
      }
    }
  ]
}