Lectura básica

La API de Google Sheets te permite leer valores de celdas, rangos, conjuntos de rangos y hojas completas. En los ejemplos de esta página, se ilustran algunas operaciones de lectura comunes con el recurso.spreadsheets.values También puedes leer valores de celdas con el spreadsheets.get método, pero por lo general, spreadsheets.values.get o spreadsheets.values.batchGet es más fácil.

Estos ejemplos se presentan en forma de solicitudes HTTP para que sean independientes del lenguaje. Para obtener información sobre cómo implementar lecturas en diferentes lenguajes con las bibliotecas cliente de la API de Google, consulta Lee y escribe valores de celdas.

En estos ejemplos, el marcador de posición SPREADSHEET_ID indica dónde proporcionarías el ID de la hoja de cálculo, que se puede descubrir desde la URL de la hoja de cálculo. Los rangos de los que se leerán se especifican con la notación A1 en la URL de la solicitud. Un ejemplo de rango es Sheet1!A1:D5.

Datos de origen

Para estos ejemplos, supongamos que la hoja de cálculo que se lee tiene los siguientes datos de origen en su primera hoja ("Sheet1"). Las cadenas de la primera fila son etiquetas para las columnas individuales. Para ver ejemplos de cómo leer desde otras hojas de tu hoja de cálculo, consulta Notación A1.

A B C D
1 Elemento Costo En stock Fecha de envío
2 Rueda de la fortuna $20.50 4 1/3/2016
3 Puerta $15 2 15/3/2016
4 Motor $100 1 20/3/2016
5 Totales $135.5 7 20/3/2016

Lee un solo rango

En el siguiente spreadsheets.values.get ejemplo de código, se muestra cómo leer los valores del rango Sheet1!A1:D5 y devolver los en la respuesta. Se omiten las filas y columnas finales vacías.

Aquí se muestra el protocolo de solicitud.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5

La respuesta consta de un ValueRange objeto que describe los valores del rango. El majorDimension campo indica que los arrays son listas de valores organizados por filas.

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "30/20/2016"],
    ["Totals", "$135.5", "7", "3/20/2016"]
  ],
}

Lee un solo rango agrupado por columna

En el siguiente spreadsheets.values.get ejemplo de código, se muestra cómo leer los valores del rango Sheet1!A1:D3 y devolver los en la respuesta, pero agrupados por columna. Se omiten las filas y columnas finales vacías.

Aquí se muestra el protocolo de solicitud.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS

La respuesta consta de un ValueRange objeto que describe los valores del rango. El majorDimension campo indica que los arrays son listas de valores organizados por columnas.

{
  "range": "Sheet1!A1:D3",
  "majorDimension": "COLUMNS",
  "values": [
    ["Item", "Wheel", "Door"],
    ["Cost", "$20.50", "$15"],
    ["Stocked", "4", "2"],
    ["Ship Date", "3/1/2016", "3/15/2016"]
  ],
}

Lee un solo rango con opciones de renderización

En el siguiente spreadsheets.values.get ejemplo de código, se muestra cómo leer los valores del rango Sheet1!A1:D5 y devolverlos en la respuesta, pero se usan opciones de renderización para administrar cómo se muestra esa información. El ValueRenderOption parámetro de configuración de FORMULA indica que se deben mostrar las fórmulas en lugar del valor calculado, y el DateTimeRenderOption parámetro de configuración de SERIAL_NUMBER indica que las fechas se deben mostrar como números. También son posibles otros parámetros de configuración. Se omiten las filas y columnas finales vacías.

Aquí se muestra el protocolo de solicitud.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?
            valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER

La respuesta consta de un ValueRange objeto que describe los valores del rango. El majorDimension campo indica que los arrays son listas de valores organizados por filas.

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "42430"],
    ["Door", "$15", "2", "42444"],
    ["Engine", "$100", "1", "42449"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

Lee varios rangos

En el siguiente spreadsheets.values.batchGet ejemplo de código, se muestra cómo leer valores de los rangos Sheet1!B:B y Sheet1!D:D y devolverlos en la respuesta. El ValueRenderOption parámetro de configuración de UNFORMATTED_VALUE indica que los valores se calculan, pero no se formatean en la respuesta. Se omiten las filas y columnas finales vacías.

Aquí se muestra el protocolo de solicitud.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

La respuesta a esta llamada de método consta de un objeto con el ID de la hoja de cálculo y un array de ValueRange objetos correspondiente a cada rango solicitado, que se muestra en el orden en que se solicitaron. El majorDimension campo indica que los arrays son listas de valores organizados por columnas. Por ejemplo:

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!B1:B1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Cost",20.5,15,100,135.5]
      ]
    },
    {
      "range": "Sheet1!D1:D1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Ship Date",42430,42444,42449,42449]
      ]s
    }
  ]
}

Lee varios rangos en varias hojas

En el siguiente spreadsheets.values.batchGet ejemplo de código, se muestra cómo leer valores de los rangos en las hojas Sheet1!A1:D5, Products!D1:D100 y Sales!E4:F6 y devolverlos en la respuesta. El ValueRenderOption parámetro de configuración de UNFORMATTED_VALUE indica que los valores se calculan, pero no se formatean en la respuesta. Se omiten las filas y columnas finales vacías.

Aquí se muestra el protocolo de solicitud.

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

La respuesta a esta llamada de método consta de un objeto con el ID de la hoja de cálculo y un array de ValueRange objetos correspondiente a cada rango solicitado, que se muestra en el orden en que se solicitaron. El majorDimension campo indica que los arrays son listas de valores organizados por columnas. Por ejemplo:

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!A1:D5",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    },
    {
      "range": "Products!D1:D100",
      "majorDimension": "COLUMNS",
      "values": [
        [...]
      ]
    },
    {
      "range": "Sales!E4:F6",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    }
  ]
}