Usa le maschere di campo

Le maschere di campo consentono ai chiamanti dell'API di elencare i campi che una richiesta deve restituire o aggiornare. L'utilizzo di una FieldMask consente all'API di evitare lavoro non necessario e migliora il rendimento. Una maschera di campo viene utilizzata sia per i metodi di lettura che di aggiornamento nell'API Google Slides.

Per un confronto tra ciò che viene restituito nel corpo di una risposta quando non utilizzi una maschera di campo e quando la utilizzi, consulta la sezione Utilizzo di risorse parziali.

Lettura con una maschera di campo

Le presentazioni possono essere di grandi dimensioni e spesso non hai bisogno di ogni parte della presentations risorsa restituita da una richiesta di lettura. Puoi limitare ciò che viene restituito in una risposta dell'API Slides utilizzando il parametro URL fields. Per un rendimento ottimale, elenca esplicitamente solo i campi di cui hai bisogno nella risposta.

Il formato del parametro fields è lo stesso della codifica JSON di una FieldMask. In breve, più campi diversi sono separati da virgole e i sottocampi sono separati da punti. I nomi dei campi possono essere specificati in camelCase o separated_by_underscores. Per comodità, più sottocampi dello stesso tipo possono essere elencati tra parentesi.

L'esempio seguente di richiesta del metodo presentations.get utilizza una maschera di campo slides.pageElements(objectId,size,transform) per recuperare solo l'ID oggetto, Size e la trasformazione di un oggetto pageElement in tutte le diapositive di una presentazione:

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

La risposta a questa chiamata al metodo è un presentations oggetto contenente i componenti richiesti nella maschera di campo:

{
  "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 di campo

A volte devi aggiornare solo determinati campi in un oggetto, lasciando invariati gli altri campi. Le richieste di aggiornamento all'interno di un presentations.batchUpdate metodo utilizzano le maschere di campo per indicare all'API quali campi vengono modificati. La richiesta di aggiornamento ignora i campi non specificati nella maschera di campo, mantenendo i valori correnti.

Puoi anche annullare l'impostazione di un campo non specificandolo nel messaggio aggiornato, ma aggiungendolo alla maschera. In questo modo viene cancellato qualsiasi valore precedente del campo.

La sintassi delle maschere di campo di aggiornamento è la stessa delle maschere di campo di lettura.

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

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