建立及管理試算表

本文說明如何使用 Google Sheets API，在 Google 試算表中建立及管理試算表。

建立試算表

如要在 Google 試算表中建立檔案，請使用 spreadsheets 資源的 create 方法，且不含任何參數。

建立檔案時，這個方法會傳回 spreadsheets 資源。傳回的資源包含 spreadsheetId、properties、sheets 清單和 spreadsheetUrl。

下列程式碼範例說明如何建立空白試算表，並指定標題。

Apps Script

sheets/api/spreadsheet_snippets.gs

/**
 * Creates a new sheet using the sheets advanced services
 * @param {string} title the name of the sheet to be created
 * @returns {string} the spreadsheet ID
 */
Snippets.prototype.create = (title) => {
  // This code uses the Sheets Advanced Service, but for most use cases
  // the built-in method SpreadsheetApp.create() is more appropriate.
  try {
    const sheet = Sheets.newSpreadsheet();
    sheet.properties = Sheets.newSpreadsheetProperties();
    sheet.properties.title = title;
    const spreadsheet = Sheets.Spreadsheets.create(sheet);

    return spreadsheet.spreadsheetId;
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
};

Java

sheets/snippets/src/main/java/Create.java

前往 GitHub 查看

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.Spreadsheet;
import com.google.api.services.sheets.v4.model.SpreadsheetProperties;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Collections;

/* Class to demonstrate the use of Spreadsheet Create API */
public class Create {
  /**
   * Create a new spreadsheet.
   *
   * @param title - the name of the sheet to be created.
   * @return newly created spreadsheet id
   * @throws IOException - if credentials file not found.
   */
  public static String createSpreadsheet(String title) throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Create the sheets API client
    Sheets service = new Sheets.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Sheets samples")
        .build();

    // Create new spreadsheet with a title
    Spreadsheet spreadsheet = new Spreadsheet()
        .setProperties(new SpreadsheetProperties()
            .setTitle(title));
    spreadsheet = service.spreadsheets().create(spreadsheet)
        .setFields("spreadsheetId")
        .execute();
    // Prints the new spreadsheet id
    System.out.println("Spreadsheet ID: " + spreadsheet.getSpreadsheetId());
    return spreadsheet.getSpreadsheetId();
  }
}

JavaScript

sheets/snippets/sheets_create.js

前往 GitHub 查看

function create(title, callback) {
  try {
    gapi.client.sheets.spreadsheets.create({
      properties: {
        title: title,
      },
    }).then((response) => {
      if (callback) callback(response);
      console.log('Spreadsheet ID: ' + response.result.spreadsheetId);
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }
}

Node.js

sheets/snippets/sheets_create.js

前往 GitHub 查看

import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Creates a new Google Spreadsheet.
 * @param {string} title The title of the new spreadsheet.
 * @return {string} The ID of the created spreadsheet.
 */
async function create(title) {
  // Authenticate with Google and get an authorized client.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/spreadsheets',
  });

  // Create a new Sheets API client.
  const service = google.sheets({version: 'v4', auth});

  // The resource body for creating a new spreadsheet.
  const resource = {
    properties: {
      title,
    },
  };

  // Create the new spreadsheet.
  const spreadsheet = await service.spreadsheets.create({
    resource,
    fields: 'spreadsheetId',
  });

  // Log the ID of the new spreadsheet.
  console.log(`Spreadsheet ID: ${spreadsheet.data.spreadsheetId}`);
  return spreadsheet.data.spreadsheetId;
}

PHP

sheets/snippets/src/SpreadsheetCreate.php

前往 GitHub 查看

<?php
use Google\Client;
use Google\Service\Drive;
use Google\Service\Sheets\SpreadSheet;

/**
* create an empty spreadsheet
* 
*/

 function create($title)
    {   
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
        $client = new Google\Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Google\Service\Drive::DRIVE);
        $service = new Google_Service_Sheets($client);
        try{

            $spreadsheet = new Google_Service_Sheets_Spreadsheet([
                'properties' => [
                    'title' => $title
                    ]
                ]);
                $spreadsheet = $service->spreadsheets->create($spreadsheet, [
                    'fields' => 'spreadsheetId'
                ]);
                printf("Spreadsheet ID: %s\n", $spreadsheet->spreadsheetId);
                return $spreadsheet->spreadsheetId;
        }
        catch(Exception $e) {
            // TODO(developer) - handle error appropriately
            echo 'Message: ' .$e->getMessage();
          }
    }

Python

sheets/snippets/sheets_create.py

前往 GitHub 查看

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def create(title):
  """
  Creates the Sheet the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)
    spreadsheet = {"properties": {"title": title}}
    spreadsheet = (
        service.spreadsheets()
        .create(body=spreadsheet, fields="spreadsheetId")
        .execute()
    )
    print(f"Spreadsheet ID: {(spreadsheet.get('spreadsheetId'))}")
    return spreadsheet.get("spreadsheetId")
  except HttpError as error:
    print(f"An error occurred: {error}")
    return error


if __name__ == "__main__":
  # Pass: title
  create("mysheet1")

Ruby

sheets/snippets/lib/spreadsheet_snippets.rb

前往 GitHub 查看

spreadsheet = {
  properties: {
    title: 'Sales Report'
  }
}
spreadsheet = service.create_spreadsheet(spreadsheet,
                                         fields: 'spreadsheetId')
puts "Spreadsheet ID: #{spreadsheet.spreadsheet_id}"

將試算表整理到 Google 雲端硬碟資料夾

根據預設，建立的試算表會儲存在 Google 雲端硬碟的使用者根資料夾中。

如要將試算表儲存至特定雲端硬碟資料夾，請使用下列方法：

建立試算表檔案後，請使用 Google Drive API 的 files 資源中的 update 方法，將檔案移至特定資料夾。詳情請參閱「在資料夾之間移動檔案」。
使用 Drive API 的 files 資源中的 create 方法，在資料夾中新增空白試算表，並將 application/vnd.google-apps.spreadsheet 指定為 mimeType。如要進一步瞭解如何建立檔案，請參閱「在特定資料夾中建立檔案」。如要進一步瞭解 MIME 類型，請參閱「Google Workspace 和 Google 雲端硬碟支援的 MIME 類型」。

無論選擇哪種替代方案，您都需要新增適當的 Drive API 範圍，授權進行呼叫。

如果應用程式使用服務帳戶，則建立的試算表會歸服務帳戶所有。這個檔案會儲存在服務帳戶專屬的雲端硬碟儲存空間中。除非您明確共用檔案，否則檔案不會顯示在其他雲端硬碟儲存空間帳戶中。詳情請參閱「檔案擁有權」。

如要在共用雲端硬碟資料夾中移動或建立檔案，請參閱「實作共用雲端硬碟支援功能」。

如要進一步瞭解 Google 試算表的儲存格和列數上限，請參閱「Google 雲端硬碟可存放的檔案」。

取得試算表

如要取得試算表，請在 spreadsheets 資源上使用 get 方法，並搭配 spreadsheetId 路徑參數。

這個方法會以 spreadsheets 資源的執行個體形式傳回檔案。根據預設，系統不會傳回試算表中的資料。傳回的資源包含試算表的結構和中繼資料，包括試算表屬性 (例如標題、語言代碼和時區)，以及一些詳細的工作表資訊 (例如格式和受保護的範圍)。

如要在 spreadsheets 資源中納入資料，請使用下列兩種方法：

設定 fields 系統參數，指定列出所選欄位的欄位遮罩。
將布林值 includeGridData 查詢參數設為 true。如果已設定欄位遮罩，系統會忽略 includeGridData 參數。

處理大型試算表時，建議您只查詢所需的特定試算表欄位。get 方法會傳回與試算表相關聯的所有資料，因此對大型試算表的一般查詢可能會很慢。舉例來說，如要從儲存格讀取數字 100，spreadsheets.get 會傳回儲存格值和中繼資料 (例如字型名稱、大小等)，導致 JSON 酬載過大，剖析速度緩慢。相較之下，對 values.get 的類似呼叫只會傳回特定儲存格值，因此回應速度更快，負擔也輕得多。

如要進一步瞭解 spreadsheets.values 資源，包括 spreadsheets.values.get 和 spreadsheets.values.batchGet，請參閱下列文件：

列出試算表

Sheets API 不提供列出通過驗證使用者可存取試算表的方法。

如要擷取試算表清單，請在 files 資源上使用 Drive API 的 list 方法，並將 application/vnd.google-apps.spreadsheet 指定為 mimeType：

HTTP

GET https://www.googleapis.com/drive/v3/files?q=mimeType='application/vnd.google-apps.spreadsheet'

cURL

curl -X GET "https://www.googleapis.com/drive/v3/files?q=mimeType='application/vnd.google-apps.spreadsheet'" \
 -H "Authorization: Bearer ACCESS_TOKEN" \
 -H "Accept: application/json"

將 ACCESS_TOKEN 替換為可授權存取 API 的存取權杖。

如要使用 files.list 方法列出使用者的試算表，必須使用受限的 Drive API 範圍。

建議您採取下列後續步驟：

如要更新試算表，請參閱「更新試算表」。
如要使用智慧型方塊，請參閱「智慧型方塊」。
如要使用開發人員中繼資料，請參閱「讀取、寫入及搜尋中繼資料」。

建立及管理試算表 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

建立試算表

Apps Script

Java

JavaScript

Node.js

PHP

Python

Ruby

將試算表整理到 Google 雲端硬碟資料夾

取得試算表

列出試算表

HTTP

cURL

相關主題

建立及管理試算表