Usa le maschere di campo

Le maschere di campo consentono ai chiamanti API di elencare i campi che una richiesta deve restituire o aggiornare. L'utilizzo di un 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 per quelli di aggiornamento nell'API Google Slides.

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

Lettura con una maschera dei campi

Le presentazioni possono essere di grandi dimensioni e spesso non è necessario utilizzare ogni parte della presentations risorsa restituita da una richiesta di lettura. Puoi limitare i contenuti restituiti in una risposta dell'API Slides utilizzando il parametro URL fields. Per ottenere le migliori prestazioni, elenca esplicitamente solo i campi di cui hai bisogno nella risposta.

Il formato del parametro fields è lo stesso della codifica JSON di un 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ù campi secondari dello stesso tipo possono essere elencati tra parentesi.

Il seguente esempio di richiesta di metodo presentations.get utilizza una maschera di campo slides.pageElements(objectId,size,transform) per recuperare solo l'ID oggetto, Size e transform di un pageElement oggetto 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 è un oggetto presentations contenente i componenti richiesti nella maschera del 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 dei campi

A volte devi aggiornare solo determinati campi in un oggetto lasciando invariati gli altri. Le richieste di aggiornamento all'interno di un metodo presentations.batchUpdate utilizzano 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 precedentemente presente nel campo.

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

Una maschera di campo * viene trattata come un carattere jolly ed è una notazione abbreviata per specificare ogni campo di un messaggio. La sintassi con caratteri jolly può produrre risultati indesiderati se l'API viene aggiornata in futuro, poiché i campi di sola lettura e i campi appena aggiunti potrebbero causare errori. Per le applicazioni di produzione, elenca sempre i campi specifici da aggiornare nelle maschere di campo ed evita di utilizzare caratteri jolly *.

L'esempio seguente utilizza il metodo UpdateShapePropertiesRequest per modificare il riempimento di colore di una forma nel colore del tema DARK1 e annullare il 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"
      }
    }
  ]
}