ایجاد و مدیریت صفحات گسترده

این سند نحوه ایجاد و مدیریت صفحات گسترده در Google Sheets با استفاده از API Google Sheets را توضیح می‌دهد.

ایجاد یک صفحه گسترده

برای ایجاد یک فایل در Sheets، از متد create روی منبع spreadsheets بدون پارامتر استفاده کنید.

وقتی فایل را ایجاد می‌کنید، این متد یک منبع spreadsheets را برمی‌گرداند. منبع برگردانده شده شامل یک spreadsheetId ، properties ، لیستی از sheets و یک spreadsheetUrl است.

نمونه کد زیر نحوه ایجاد یک صفحه گسترده خالی با عنوان مشخص شده را نشان می‌دهد.

اسکریپت برنامه‌ها

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);
  }
};

جاوا

sheets/snippets/src/main/java/Create.java
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();
  }
}

جاوا اسکریپت

sheets/snippets/sheets_create.js
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;
  }
}

نود جی اس

sheets/snippets/sheets_create.js
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;
}

پی اچ پی

sheets/snippets/src/SpreadsheetCreate.php
<?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();
          }
    }

پایتون

sheets/snippets/sheets_create.py
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")

روبی

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

صفحات گسترده را در پوشه‌های گوگل درایو سازماندهی کنید

به طور پیش‌فرض، صفحه‌گسترده ایجاد شده در پوشه ریشه کاربر در گوگل درایو ذخیره می‌شود.

اگر می‌خواهید یک صفحه‌گسترده را در پوشه‌ی مشخص‌شده‌ای از درایو ذخیره کنید، از این روش‌ها استفاده کنید:

برای هر یک از گزینه‌های جایگزین، باید محدوده‌های مناسب Drive API را برای تأیید فراخوانی اضافه کنید.

اگر برنامه شما از یک حساب سرویس استفاده می‌کند، حساب سرویس مالک صفحه گسترده ایجاد شده است. سپس این فایل در فضای ذخیره‌سازی اختصاصی Drive حساب سرویس قرار می‌گیرد. فایل‌ها در سایر حساب‌های ذخیره‌سازی Drive نمایش داده نمی‌شوند، مگر اینکه صریحاً به اشتراک گذاشته شوند. برای اطلاعات بیشتر، به بخش مالکیت فایل مراجعه کنید.

برای جابجایی یا ایجاد فایل در پوشه درایو مشترک، به «پیاده‌سازی پشتیبانی از درایو مشترک» مراجعه کنید.

برای کسب اطلاعات بیشتر در مورد محدودیت‌های سلول و ردیف در Google Sheets، به فایل‌هایی که می‌توانید در Google Drive ذخیره کنید مراجعه کنید.

یک جدول دریافت کنید

برای دریافت یک صفحه گسترده، از متد get روی منبع spreadsheets به همراه پارامتر مسیر spreadsheetId استفاده کنید.

این متد، فایل را به عنوان نمونه‌ای از یک منبع spreadsheets برمی‌گرداند. به طور پیش‌فرض، داده‌های درون صفحه گسترده برگردانده نمی‌شوند. منبع برگردانده شده شامل ساختار و فراداده‌های صفحه گسترده، از جمله ویژگی‌های صفحه گسترده (مانند عنوان، منطقه و منطقه زمانی) و برخی اطلاعات دقیق صفحه (مانند قالب‌بندی و محدوده‌های محافظت‌شده) است.

برای گنجاندن داده‌ها در یک منبع spreadsheets ، از این دو روش استفاده کنید:

  • با تنظیم پارامتر سیستم fields ، یک ماسک فیلد مشخص کنید که فیلدهای انتخابی شما را فهرست می‌کند.

  • پارامتر کوئری boolean includeGridData را روی true تنظیم کنید. اگر یک ماسک فیلد تنظیم شده باشد، پارامتر includeGridData نادیده گرفته می‌شود.

وقتی با صفحات گسترده بزرگ کار می‌کنید، توصیه می‌کنیم فقط برای فیلدهای خاص صفحه گسترده که نیاز دارید، کوئری بزنید. متد get تمام داده‌های مرتبط با صفحه گسترده را برمی‌گرداند، بنابراین کوئری‌های عمومی برای صفحات گسترده بزرگ می‌توانند کند باشند. برای مثال، برای خواندن عدد ۱۰۰ از یک سلول، spreadsheets.get مقدار سلول به علاوه فراداده (مانند نام فونت، اندازه و غیره) را برمی‌گرداند که منجر به حجم زیادی از داده‌های JSON می‌شود که تجزیه آنها کند است. در مقایسه، فراخوانی مشابه values.get فقط مقدار خاص سلول را برمی‌گرداند که منجر به پاسخ بسیار سبک‌تر و سریع‌تر می‌شود.

برای اطلاعات بیشتر در مورد منبع spreadsheets.values ، شامل spreadsheets.values.get و spreadsheets.values.batchGet ، به اسناد زیر مراجعه کنید:

فهرست صفحات گسترده

API مربوط به Sheets روشی برای فهرست کردن صفحات گسترده برای کاربران احراز هویت شده ارائه نمی‌دهد.

برای بازیابی لیستی از صفحات گسترده، می‌توانید از متد list در Drive API روی منبع files استفاده کنید و application/vnd.google-apps.spreadsheet را به عنوان mimeType مشخص کنید:

اچ‌تی‌پی 

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

حلقه 

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 است.

در اینجا چند مرحله بعدی وجود دارد که می‌توانید امتحان کنید: