Cómo usar máscaras de campo

Las máscaras de campo permiten que los llamadores de la API enumeren los campos que una solicitud debe devolver o actualizar. Con un FieldMask permite que la API evite el trabajo innecesario y mejore el rendimiento. Una máscara de campo se usa para los métodos de lectura y actualización en la API de Presentaciones de Google.

Lee con una máscara de campo

Las presentaciones pueden ser grandes y, a menudo, no necesitas todas las partes Presentation recurso que muestra una solicitud de lectura. Puedes limitar lo que se devuelve en un Respuesta de la API de Presentaciones con el parámetro de URL fields Lo mejor rendimiento, Enumera de forma explícita solo los campos que necesitas. en la respuesta.

El formato del parámetro de campos es el mismo que el de Codificación JSON de una FieldMask. Dicho en pocas palabras, varios campos diferentes están separados por comas y los subcampos se separados por puntos. Los nombres de los campos pueden especificarse con el formato camelCase o separated_by_underscores. Para mayor comodidad, hay varios subcampos del mismo pueden aparecer entre paréntesis.

Los siguientes presentations.get ejemplo de solicitud usa una máscara de campo de slides.pageElements(objectId,size,transform) para recuperar solo el ID del objeto, Size y transformar de un pageElement en todas las diapositivas de una presentación:

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

La respuesta a esta llamada de método es una Objeto Presentation que contenga los componentes solicitados en la máscara de 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"
          }
        }
     ]
    }
  ]
}

Actualizar con una máscara de campo

A veces, es necesario actualizar solo ciertos campos de un objeto y, al mismo tiempo, dejar otros campos sin modificar. Solicitudes de actualización en un presentations.batchUpdate usan máscaras de campo para indicarle a la API qué campos se modificarán. El la solicitud de actualización ignora los campos que no se especifiquen en la máscara de campo, y dejarlos con sus valores actuales.

También puedes anular la configuración de un campo si no lo especificas en el mensaje actualizado, pero agregando el campo a la máscara. Esto borra cualquier valor del campo anterior que tenían.

La sintaxis de las máscaras de campo de actualización es la misma que la de las máscaras de campo de lectura.

En el siguiente ejemplo, se usa la UpdateShapePropertiesRequest para cambiar el relleno de color de una forma al color de tema DARK1 y desactivar el color descripción:

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