Leer, escribir y buscar metadatos

La función de metadatos te permite asociar metadatos con varias entidades y ubicaciones en una hoja de cálculo. Luego, puedes consultar estos metadatos y usarlos para encontrar los objetos con los que están asociados.

Puedes asociar metadatos con filas, columnas, hojas o una hoja de cálculo.

Acerca de los metadatos

A continuación, se describen algunos aspectos clave de los metadatos que debes tener en cuenta cuando trabajes con la API de Sheets:

  1. Metadatos como etiquetas: Un uso de los metadatos del desarrollador es una etiqueta que nombra una ubicación en la hoja de cálculo usando solo una clave y una ubicación. Por ejemplo, puedes asociar headerRow con una fila en particular o totals con una columna en particular dentro de una hoja. Las etiquetas se pueden usar para vincular semánticamente partes de una hoja de cálculo a campos en una herramienta o base de datos de terceros, de modo que los cambios en la hoja de cálculo no interrumpan tu app.

  2. Metadatos como propiedades: Los metadatos creados mediante la especificación de una clave, una ubicación, y un valor actúan como un par clave-valor asociado con esa ubicación en una hoja. Por ejemplo, puedes asociar lo siguiente:

    • formResponseId = resp123 con una fila
    • lastUpdated = 1477369882 con una columna

    Esto te permite almacenar y acceder a propiedades con nombres personalizados asociadas con áreas o datos particulares en una hoja de cálculo.

  3. Metadatos visibles del proyecto en comparación con los del documento: Para evitar que un proyecto de desarrollador interfiera con los metadatos de otro, existen dos parámetros de configuración de metadatos visibility settings: project and document. Con la API de Sheets, los metadatos project solo son visibles y accesibles desde el proyecto de Google Cloud que los creó. Se puede acceder a los metadatos document desde cualquier proyecto de Google Cloud con acceso al documento.

    Las consultas que no especifican explícitamente una visibility muestran metadatos document y metadatos project coincidentes para el proyecto de Google Cloud que realiza la solicitud.

  4. Unicidad: Las claves de metadatos no tienen que ser únicas, pero el metadataId debe ser distinto. Si creas metadatos y dejas sin especificar su campo de ID, la API asigna uno. Este ID se puede usar para identificar los metadatos, mientras que las claves y otros atributos se pueden usar para identificar conjuntos de metadatos.

  5. Devuelve metadatos a través de solicitudes a la API: Un DataFilter objeto forma parte de una llamada a la API que describe los datos que se seleccionarán o devolverán de una solicitud a la API.

    Un solo objeto DataFilter solo puede especificar un tipo de criterio de filtro para ubicar datos:

    • developerMetadataLookup: Selecciona los datos asociados con los metadatos del desarrollador especificados que coinciden con los criterios.

    • a1Range: Selecciona los datos que coinciden con el rango de notación A1 especificado. Por ejemplo, Sheet1!A1:B10.

    • gridRange: Selecciona los datos que coinciden con el rango de cuadrícula especificado con índices basados en cero. Por ejemplo, Sheet1!A3:B4 == sheetId: 123456, startRowIndex: 2, endRowIndex: 4, startColumnIndex: 0, endColumnIndex: 2.

    Para filtrar en varias ubicaciones o criterios, puedes usar varios DataFilter objetos en una sola solicitud a la API. Proporciona un array o una lista de DataFilter objetos a una solicitud por lotes como el spreadsheets.values.batchGetByDataFilter método. Se mostrará o modificará cualquier rango que coincida con cualquiera de los filtros de datos de la solicitud.

    Para obtener más información, consulta Lee y escribe valores asociados con metadatos.

Casos de uso

A continuación, se incluyen algunos ejemplos de casos de uso para administrar metadatos:

  • Asocia datos arbitrarios con varias entidades y ubicaciones en una hoja de cálculo: Por ejemplo, asocia totals con la columna D o responseId = 1234 con la fila 7.

  • Encuentra todas las ubicaciones y los datos asociados con una clave o un atributo de metadatos en particular: Por ejemplo, dada la clave totals asociada con la columna D o dado el responseId, muestra todas las filas con los metadatos responseId y el valor de metadatos asociado a ellos.

  • Encuentra todos los datos asociados con una entidad o ubicación en particular: Por ejemplo, dada la columna D, muestra todos los metadatos asociados con esa ubicación.

  • Recupera valores en una ubicación especificando los metadatos asociados: Por ejemplo, dado el totals, muestra una representación de los valores contenidos en la columna o fila asociada, o dado un summary, muestra una representación del recurso de hoja asociado.

  • Actualiza los valores en una ubicación especificando los metadatos asociados: Por ejemplo, en lugar de actualizar los valores en una fila a través de la notación A1, actualiza los valores indicando un ID de metadatos.

Lee y escribe metadatos

El spreadsheets.developerMetadata recurso proporciona acceso a los metadatos asociados con una ubicación o un objeto en una hoja de cálculo. Los metadatos del desarrollador se pueden usar para asociar datos arbitrarios con varias partes de una hoja de cálculo. Los metadatos permanecen asociados en esas ubicaciones a medida que se edita la hoja de cálculo.

Crea metadatos

Para crear metadatos, usa el batchUpdate método en el spreadsheets recurso, y proporciona un CreateDeveloperMetadataRequest con metadataKey, location y visibility valores del spreadsheets.developerMetadata recurso. De manera opcional, puedes especificar un metadataValue o un metadataId explícito.

Si especificas un ID que ya está en uso, la solicitud no se realizará correctamente. Si no proporcionas un ID, la API asigna uno.

En este ejemplo, proporcionamos una clave, un valor y una fila en la solicitud. La respuesta muestra estos valores de metadatos del desarrollador, además del ID de metadatos asignado.

Solicitud

{
  "requests": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "location": {
            "dimensionRange": {
              "sheetId": SHEET_ID,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT",
          "metadataKey": "Sales",
          "metadataValue": "2022"
        }
      }
    }
  ]
}

Respuesta

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "metadataId": METADATA_ID,
          "metadataKey": "Sales",
          "metadataValue": "2022",
          "location": {
            "locationType": "ROW",
            "dimensionRange": {
              "sheetId": SHEET_ID,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT"
        }
      }
    }
  ]
}

Lee un solo elemento de metadatos

Para recuperar un solo metadato del desarrollador distinto, usa el spreadsheets.developerMetadata.get método, especificando el spreadsheetId que contiene los metadatos y el metadataId único de los metadatos del desarrollador.

Solicitud

En este ejemplo, proporcionamos el ID de la hoja de cálculo y el ID de metadatos en la solicitud. La respuesta muestra los valores de metadatos del desarrollador para el ID de metadatos.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/developerMetadata/METADATA_ID

Respuesta

{
  "metadataId": METADATA_ID,
  "metadataKey": "Sales",
  "metadataValue": "2022",
  "location": {
    "locationType": "ROW",
    "dimensionRange": {
      "sheetId": SHEET_ID,
      "dimension": "ROWS",
      "startIndex": 6,
      "endIndex": 7
    }
  },
  "visibility": "DOCUMENT"
}

Lee varios elementos de metadatos

Para recuperar varios elementos de metadatos del desarrollador, usa el spreadsheets.developerMetadata.search método. Debes especificar un DataFilter que coincida con los metadatos existentes en cualquier combinación de propiedades, como clave, valor, ubicación o visibilidad.

En este ejemplo, proporcionamos varios IDs de metadatos en la solicitud. La respuesta muestra los valores de metadatos del desarrollador para cada ID de metadatos.

Solicitud

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    },
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    }
  ]
}

Respuesta

{
  "matchedDeveloperMetadata": [
    {
      "developerMetadata": {
        "metadataId": METADATA_ID,
        "metadataKey": "Revenue",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": SHEET_ID
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      ]
    },
    {
      "developerMetadata": {
        "metadataId": METADATA_ID,
        "metadataKey": "Sales",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": SHEET_ID
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      ]
    }
  ]
}

Actualiza metadatos

Para actualizar los metadatos del desarrollador, usa el spreadsheets.batchUpdate método y proporciona un UpdateDeveloperMetadataRequest. Debes especificar un DataFilter que apunte a los metadatos que se actualizarán, un recurso spreadsheets.developerMetadata con los valores nuevos y una máscara de campo que describa los campos que se actualizarán.

En este ejemplo, proporcionamos el ID de metadatos, el ID de hoja y una nueva clave de metadatos en la solicitud. La respuesta muestra estos valores de metadatos del desarrollador, además de la clave de metadatos actualizada.

Solicitud

{
  "requests": [
    {
      "updateDeveloperMetadata": {
        "dataFilters": [
          {
            "developerMetadataLookup": {
              "metadataId": METADATA_ID
            }
          }
        ],
        "developerMetadata": {
          "location": {
            "sheetId": SHEET_ID
          },
          "metadataKey": "SalesUpdated"
        },
        "fields": "location,metadataKey"
      }
    }
  ]
}

Respuesta

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "updateDeveloperMetadata": {
        "developerMetadata": [
          {
            "metadataId": METADATA_ID,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": SHEET_ID
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

Borra metadatos

Para borrar los metadatos del desarrollador, usa el batchUpdate método y proporciona un DeleteDeveloperMetadataRequest. Debes especificar un DataFilter para seleccionar los metadatos que deseas borrar.

En este ejemplo, proporcionamos el ID de metadatos en la solicitud. La respuesta muestra los valores de metadatos del desarrollador para el ID de metadatos.

Para confirmar que se quitaron los metadatos del desarrollador, usa el spreadsheets.developerMetadata.get método y especifica el ID de metadatos borrado. Deberías recibir una respuesta de código de estado HTTP 404: Not Found, con un mensaje que indique "No developer metadata with ID METADATA_ID.

Solicitud

{
  "requests": [
    {
      "deleteDeveloperMetadata": {
        "dataFilter": {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      }
    }
  ]
}

Respuesta

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "deleteDeveloperMetadata": {
        "deletedDeveloperMetadata": [
          {
            "metadataId": METADATA_ID,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": SHEET_ID
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

Lee y escribe valores asociados con metadatos

También puedes recuperar y actualizar los valores de las celdas en filas y columnas especificando los metadatos del desarrollador asociados y los valores que deseas actualizar. Para ello, usa uno de los siguientes métodos con un DataFilter coincidente.

Obtén valores de celdas por metadatos

Para obtener valores de celdas por metadatos, usa el spreadsheets.values.batchGetByDataFilter método. Debes especificar el ID de la hoja de cálculo y uno o más filtros de datos que coincidan con los metadatos.

En este ejemplo, proporcionamos el ID de metadatos en la solicitud. La respuesta muestra los valores de las celdas de la fila (número de modelo, ventas mensuales) para el ID de metadatos.

Solicitud

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    }
  ],
  "majorDimension": "ROWS"
}

Respuesta

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "valueRange": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "74"
          ]
        ]
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      ]
    }
  ]
}

Obtén una hoja de cálculo por metadatos

Cuando recuperas una hoja de cálculo, puedes mostrar un subconjunto de datos con el spreadsheets.getByDataFilter método. Debes especificar el ID de la hoja de cálculo y uno o más filtros de datos que coincidan con los metadatos.

Esta solicitud funciona como una solicitud "GET de hoja de cálculo" normal, excepto que la lista de metadatos que coinciden con los filtros de datos especificados determina qué hojas, datos de cuadrícula y otros recursos de objetos con metadatos se muestran. Si includeGridData se establece en true, también se muestran los datos de cuadrícula que se cruzan con los rangos de cuadrícula especificados para la hoja. Se ignora el campo includeGridData si se establece una máscara de campo en la solicitud.

En este ejemplo, proporcionamos el ID de metadatos y establecemos includeGridData en false en la solicitud. La respuesta muestra las propiedades de la hoja de cálculo y de la hoja.

Solicitud

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    }
  ],
  "includeGridData": false
}

Respuesta

{
  "spreadsheetId": SPREADSHEET_ID,
  "properties": {
    "title": "Sales Sheet",
    "locale": "en_US",
    "autoRecalc": "ON_CHANGE",
    "timeZone": "America/Los_Angeles",
    "defaultFormat": {
      "backgroundColor": {
        "red": 1,
        "green": 1,
        "blue": 1
      },
      "padding": {
        "top": 2,
        "right": 3,
        "bottom": 2,
        "left": 3
      },
      "verticalAlignment": "BOTTOM",
      "wrapStrategy": "OVERFLOW_CELL",
      "textFormat": {
        "foregroundColor": {},
        "fontFamily": "arial,sans,sans-serif",
        "fontSize": 10,
        "bold": false,
        "italic": false,
        "strikethrough": false,
        "underline": false,
        "foregroundColorStyle": {
          "rgbColor": {}
        }
      },
      "backgroundColorStyle": {
        "rgbColor": {
          "red": 1,
          "green": 1,
          "blue": 1
        }
      }
    },
    "spreadsheetTheme": {
      "primaryFontFamily": "Arial",
      "themeColors": [
        {
          "colorType": "TEXT",
          "color": {
            "rgbColor": {}
          }
        },
        {
          "colorType": "BACKGROUND",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 1,
              "blue": 1
            }
          }
        },
        {
          "colorType": "ACCENT1",
          "color": {
            "rgbColor": {
              "red": 0.25882354,
              "green": 0.52156866,
              "blue": 0.95686275
            }
          }
        },
        {
          "colorType": "ACCENT2",
          "color": {
            "rgbColor": {
              "red": 0.91764706,
              "green": 0.2627451,
              "blue": 0.20784314
            }
          }
        },
        {
          "colorType": "ACCENT3",
          "color": {
            "rgbColor": {
              "red": 0.9843137,
              "green": 0.7372549,
              "blue": 0.015686275
            }
          }
        },
        {
          "colorType": "ACCENT4",
          "color": {
            "rgbColor": {
              "red": 0.20392157,
              "green": 0.65882355,
              "blue": 0.3254902
            }
          }
        },
        {
          "colorType": "ACCENT5",
          "color": {
            "rgbColor": {
              "red": 1,
              "green": 0.42745098,
              "blue": 0.003921569
            }
          }
        },
        {
          "colorType": "ACCENT6",
          "color": {
            "rgbColor": {
              "red": 0.27450982,
              "green": 0.7411765,
              "blue": 0.7764706
            }
          }
        },
        {
          "colorType": "LINK",
          "color": {
            "rgbColor": {
              "red": 0.06666667,
              "green": 0.33333334,
              "blue": 0.8
            }
          }
        }
      ]
    }
  },
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "Sheet7",
        "index": 7,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 26
        }
      }
    }
  ],
  "spreadsheetUrl": SPREADSHEET_URL
}

Actualiza valores por metadatos

Para actualizar los valores de las celdas que coinciden con metadatos específicos, usa el spreadsheets.values.batchUpdateByDataFilter método. Debes especificar el ID de la hoja de cálculo, valueInputOption, y uno o más DataFilterValueRange valores que coincidan con los metadatos.

En este ejemplo, proporcionamos el ID de metadatos y los valores de fila actualizados en la solicitud. La respuesta muestra las propiedades y los datos actualizados para el ID de metadatos.

Solicitud

{
  "data": [
    {
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": METADATA_ID
        }
      },
      "majorDimension": "ROWS",
      "values": [
        [
          "W-24",
          "84"
        ]
      ]
    }
  ],
  "includeValuesInResponse": true,
  "valueInputOption": "USER_ENTERED"
}

Respuesta

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 1,
  "totalUpdatedColumns": 2,
  "totalUpdatedCells": 2,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "updatedRange": "Sheet7!A7:B7",
      "updatedRows": 1,
      "updatedColumns": 2,
      "updatedCells": 2,
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": METADATA_ID
        }
      },
      "updatedData": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "84"
          ]
        ]
      }
    }
  ]
}

Borra valores por metadatos

Para borrar los valores de las celdas que coinciden con metadatos específicos, usa el spreadsheets.values.batchClearByDataFilter método. Debes especificar un filtro de datos para seleccionar los metadatos que deseas borrar.

Solicitud

En este ejemplo, proporcionamos el ID de metadatos en la solicitud. La respuesta muestra el ID de la hoja de cálculo y los rangos borrados.

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    }
  ]
}

Respuesta

{
  "spreadsheetId": SPREADSHEET_ID,
  "clearedRanges": [
    "Sheet7!A7:Z7"
  ]
}

Límites de almacenamiento de metadatos

Existe un límite para la cantidad total de metadatos que puedes almacenar en una hoja de cálculo. Este límite se mide en caracteres y se compone de dos componentes:

Elemento Asignación de límite de almacenamiento
Hoja de cálculo 30,000 caracteres
Cada hoja dentro de una hoja de cálculo 30,000 caracteres

Puedes almacenar hasta 30,000 caracteres para la hoja de cálculo. Además, puedes almacenar 30,000 caracteres para cada hoja dentro de una hoja de cálculo (30,000 para la hoja uno, 30,000 para la hoja dos, etcétera). Por lo tanto, una hoja de cálculo con tres hojas podría contener hasta 120,000 caracteres de metadatos.

Cada carácter de los campos metadataKey y metadataValue del recurso spreadsheets.developerMetadata cuenta para este límite.