Operações de dados

Com a API Google Sheets, você pode manipular os dados de uma planilha de várias maneiras. A maioria das funcionalidades disponíveis para usuários que trabalham com a interface das Planilhas também é possível com a API Sheets. Os exemplos nesta página ilustram como realizar algumas operações comuns de planilha com a API Sheets.

Esses exemplos são apresentados na forma de solicitações HTTP para serem neutros em termos de linguagem. Para saber como implementar uma atualização em lote em diferentes idiomas usando as bibliotecas do cliente da Google API, consulte Atualizar planilhas.

Nesses exemplos, os marcadores de posição SPREADSHEET_ID e SHEET_ID indicam onde você deve fornecer esses IDs. Você pode encontrar o ID da planilha no URL dela. Você pode conferir o ID da planilha usando o método spreadsheets.get. Os intervalos são especificados usando a notação A1. Um exemplo de intervalo é Sheet1!A1:D5.

Aplicar a validação de dados a um intervalo

O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar o SetDataValidationRequest para aplicar uma regra de validação de dados, em que "value > 5", a cada célula no intervalo A1:D10.

Confira o protocolo da solicitação abaixo.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "setDataValidation": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "rule": {
          "condition": {
            "type": "NUMBER_GREATER",
            "values": [
              {
                "userEnteredValue": "5"
              }
            ]
          },
          "inputMessage": "Value must be > 5",
          "strict": true
        }
      }
    }
  ]
}

Copiar e colar a formatação de células

O exemplo de código spreadsheets.batchUpdate a seguir mostra como usar CopyPasteRequest para copiar a formatação apenas no intervalo A1:D10 e colá-la no intervalo F1:I10 na mesma página. O método usa o tipo enumerado PasteType com PASTE_FORMAT para colar apenas a formatação e a validação de dados. Os valores originais em A1:D10 não são alterados.

Confira o protocolo da solicitação abaixo.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "copyPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 5,
          "endColumnIndex": 9
        },
        "pasteType": "PASTE_FORMAT",
        "pasteOrientation": "NORMAL"
      }
    }
  ]
}

Recortar e colar células

O exemplo de código spreadsheets.batchUpdate abaixo mostra como usar o CutPasteRequest. Ele corta o intervalo A1:D10 e usa a enumeração PasteType com PASTE_NORMAL para colar os valores, fórmulas, formatações e mesclagens no intervalo F1:I10 na mesma página. O conteúdo original das células do intervalo de origem é removido.

Confira o protocolo da solicitação abaixo.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "cutPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "rowIndex": 0,
          "columnIndex": 5
        },
        "pasteType": "PASTE_NORMAL"
      }
    }
  ]
}

Repita uma fórmula em um intervalo

O exemplo de código spreadsheets.batchUpdate abaixo mostra como usar o RepeatCellRequest para copiar a fórmula =FLOOR(A1*PI()) para o intervalo B1:D10. O intervalo da fórmula é incrementado automaticamente para cada linha e coluna do intervalo, começando pela célula do canto superior esquerdo. Por exemplo, a célula B1 tem a fórmula =FLOOR(A1*PI()), enquanto a célula D6 tem a fórmula =FLOOR(C6*PI()).

Confira o protocolo da solicitação abaixo.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 1,
          "endColumnIndex": 4
        },
        "cell": {
          "userEnteredValue": {
              "formulaValue": "=FLOOR(A1*PI())"
          }
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

Classificar um intervalo com várias especificações de classificação

O exemplo de código spreadsheets.batchUpdate abaixo mostra como usar a função SortRangeRequest para classificar o intervalo A1:D10, primeiro pela coluna B em ordem crescente, depois pela coluna C em ordem decrescente e, por fim, pela coluna D em ordem decrescente.

Confira o protocolo da solicitação abaixo.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "sortRange": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "sortSpecs": [
          {
            "dimensionIndex": 1,
            "sortOrder": "ASCENDING"
          },
          {
            "dimensionIndex": 2,
            "sortOrder": "DESCENDING"
          },
          {
            "dimensionIndex": 3,
            "sortOrder": "DESCENDING"
          }
        ]
      }
    }
  ]
}