创建和管理电子表格

本文档介绍了如何使用 Google Sheets API 在 Google 表格中创建和管理电子表格。

创建电子表格

如需在 Google 表格中创建文件，请对 spreadsheets 资源使用不带任何参数的 create 方法。

创建文件时，该方法会返回 spreadsheets 资源。返回的资源包含 spreadsheetId、properties、sheets 列表和 spreadsheetUrl。

以下代码示例展示了如何创建具有指定标题的空白电子表格。

Apps 脚本

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 资源使用 spreadsheetId 路径参数调用 get 方法。

该方法会以 spreadsheets 资源实例的形式返回文件。默认情况下，系统不会返回电子表格中的数据。返回的资源包含电子表格的结构和元数据，包括电子表格属性（例如标题、语言区域和时区）以及一些详细的工作表信息（例如格式和受保护的范围）。

如需在 spreadsheets 资源中包含数据，请使用以下两种方法：

通过设置 fields 系统参数，指定列出所选字段的字段掩码。
将布尔值 includeGridData 查询参数设置为 true。如果设置了字段掩码，系统会忽略 includeGridData 参数。

处理大型电子表格时，建议您仅查询所需的特定电子表格字段。get 方法会返回与电子表格关联的所有数据，因此针对大型电子表格的一般查询可能会很慢。例如，若要从单元格中读取数字 100，spreadsheets.get 会返回单元格值以及元数据（例如字体名称、大小等），从而生成难以解析的大型 JSON 载荷。相比之下，对 values.get 的类似调用仅返回特定的单元格值，从而获得更轻量、更快速的响应。

如需详细了解 spreadsheets.values 资源（包括 spreadsheets.values.get 和 spreadsheets.values.batchGet），请参阅以下文档：

列出电子表格

Sheets API 不提供列出通过身份验证的用户可访问的电子表格的方法。

如需检索电子表格列表，您可以使用 Drive API 的 files 资源中的 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 脚本

Java

JavaScript

Node.js

PHP

Python

Ruby

在 Google 云端硬盘文件夹中整理电子表格

获取电子表格

列出电子表格

HTTP

cURL

相关主题

创建和管理电子表格