資料作業

Google Sheets API 可讓您以各種方式操控試算表中的資料。使用者透過 Google 試算表使用者介面可執行的多數功能，也能透過 Google 試算表 API 達成。本頁的範例說明如何透過 Google Sheets API 執行一些常見的試算表作業。

這些範例會以 HTTP 要求的形式呈現，不限於特定語言。如要瞭解如何使用 Google API 用戶端程式庫，以不同語言實作批次更新，請參閱「更新試算表」。

在這些範例中，預留位置 SPREADSHEET_ID 和 SHEET_ID 表示您提供這些 ID 的位置。您可以在試算表網址中找到試算表 ID。您可以使用 spreadsheets.get 方法取得工作表 ID。範圍是使用 A1 標記法指定的。例如：Sheet1!A1:D5。

對範圍套用資料驗證

下列 spreadsheets.batchUpdate 程式碼範例說明如何使用 SetDataValidationRequest 套用資料驗證規則 (「值 > 5」)，至 A1:D10 範圍內的每個儲存格。

要求通訊協定如下所示。

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

複製及貼上儲存格格式

下列spreadsheets.batchUpdate程式碼範例說明如何使用 CopyPasteRequest，只複製 A1:D10 範圍的格式，並貼到同一工作表的 F1:I10 範圍。這個方法會使用 PasteType 列舉，搭配 PASTE_FORMAT 僅貼上格式和資料驗證規則。A1:D10 中的原始值維持不變。

要求通訊協定如下所示。

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

剪下並貼上儲存格

以下 spreadsheets.batchUpdate 程式碼範例說明如何使用 CutPasteRequest。這個函式會剪下 A1:D10 範圍，並使用 PasteType 列舉和 PASTE_NORMAL，將值、公式、格式和合併儲存格貼到同一工作表的 F1:I10 範圍。原始來源範圍的儲存格內容會移除。

要求通訊協定如下所示。

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

在範圍內重複套用公式

下列程式碼範例說明如何使用 RepeatCellRequest 將公式 =FLOOR(A1*PI()) 複製到 B1:D10 範圍。spreadsheets.batchUpdate公式的範圍會自動遞增，從範圍左上方的儲存格開始，逐列和逐欄遞增。舉例來說，儲存格 B1 含有公式 =FLOOR(A1*PI())，而儲存格 D6 含有公式 =FLOOR(C6*PI())。

要求通訊協定如下所示。

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

使用多個排序規格排序範圍

下列程式碼範例說明如何使用 SortRangeRequest，先依遞增順序依 B 欄排序 A1:D10 範圍，再依遞減順序依 C 欄排序，最後依遞減順序依 D 欄排序。spreadsheets.batchUpdate

要求通訊協定如下所示。

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