إنشاء جداول بيانات وإدارتها

يوضّح هذا المستند كيفية إنشاء جداول بيانات وإدارتها في "جداول بيانات Google" باستخدام Google Sheets API.

إنشاء جدول بيانات

لإنشاء ملف في "جداول بيانات Google"، استخدِم الطريقة create في المورد spreadsheets بدون مَعلمات.

عند إنشاء الملف، تعرض الطريقة مورد spreadsheets. يحتوي المرجع الذي تم عرضه على spreadsheetId وproperties وقائمة sheets وspreadsheetUrl.

توضح عينة التعليمات البرمجية التالية كيفية إنشاء جدول بيانات فارغ بعنوان محدد.

برمجة التطبيقات

sheets/api/spreadsheet_snippets.gs

عرض على GitHub

/**
 * 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

عرض على 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 Drive

يتم تلقائيًا حفظ جدول البيانات الذي تم إنشاؤه في المجلد الجذر الخاص بالمستخدم على Google Drive.

إذا أردت حفظ جدول بيانات في مجلد محدّد في Drive، استخدِم إحدى الطريقتَين التاليتَين:

• بعد إنشاء ملف جدول البيانات، يمكنك نقله إلى مجلد معيّن باستخدام طريقة update في مورد files من Google Drive API. لمزيد من المعلومات، يُرجى الاطّلاع على نقل الملفات بين المجلدات.

• أضِف جدول بيانات فارغًا إلى مجلد باستخدام طريقة create في مورد files في Drive API، مع تحديد application/vnd.google-apps.spreadsheet كـ mimeType. لمزيد من المعلومات حول إنشاء الملفات، يُرجى الاطّلاع على إنشاء ملف في مجلد معيّن. لمزيد من المعلومات عن أنواع MIME، يُرجى الاطّلاع على أنواع MIME المتوافقة في Google Workspace وGoogle Drive.

في كلتا الحالتين، عليك إضافة نطاقات Drive API المناسبة للسماح بإجراء المكالمة.

إذا كان تطبيقك يستخدم حساب خدمة، سيكون حساب الخدمة هو مالك جدول البيانات الذي تم إنشاؤه. بعد ذلك، يتم تخزين هذا الملف في مساحة تخزين في Drive المخصّصة لحساب الخدمة. لا تظهر الملفات ضمن حسابات مساحة تخزين في Drive أخرى إلا إذا تمت مشاركتها بشكلٍ صريح. لمزيد من المعلومات، يُرجى الاطّلاع على ملكية الملف.

لنقل ملف أو إنشائه داخل مجلد في مساحة تخزين سحابي مشتركة، يُرجى الرجوع إلى تنفيذ إمكانية استخدام مساحة التخزين السحابي المشتركة.

لمزيد من المعلومات حول الحدود القصوى للخلايا والصفوف في "جداول بيانات Google"، يُرجى الاطّلاع على الملفات التي يمكنك تخزينها في Google Drive.

الحصول على جدول بيانات

للحصول على جدول بيانات، استخدِم طريقة get في مورد spreadsheets مع مَعلمة المسار spreadsheetId.

تعرض الطريقة الملف كمثيل لمورد spreadsheets. بشكل تلقائي، لا يتم عرض البيانات داخل جدول البيانات. يحتوي المورد الذي يتم عرضه على بنية جدول البيانات وبياناته الوصفية، بما في ذلك خصائص جدول البيانات (مثل العنوان واللغة والمنطقة الزمنية) وبعض المعلومات التفصيلية عن ورقة البيانات (مثل التنسيق والنطاقات المحمية).

لتضمين بيانات ضمن مورد spreadsheets، استخدِم الطريقتَين التاليتَين:

• حدِّد قناع حقل يتضمّن الحقول التي اخترتها من خلال ضبط المَعلمة fields system.

• اضبط قيمة المَعلمة المنطقية includeGridData لطلب البحث على true. في حال ضبط قناع الحقل، يتم تجاهل المَعلمة includeGridData.

عند العمل على جداول بيانات كبيرة، ننصحك بالبحث عن حقول جدول البيانات المحدّدة التي تحتاج إليها فقط. تعرض الطريقة get جميع البيانات المرتبطة بجدول البيانات، لذا قد تكون طلبات البحث العامة عن جداول البيانات الكبيرة بطيئة. على سبيل المثال، لقراءة الرقم 100 من خلية، تعرض الدالة spreadsheets.get قيمة الخلية بالإضافة إلى البيانات الوصفية (مثل اسم الخط وحجمه وما إلى ذلك)، ما يؤدي إلى إنشاء حمولات JSON كبيرة يستغرق تحليلها وقتًا طويلاً. في المقابل، لا يعرض طلب مشابه إلى values.get سوى قيمة الخلية المحدّدة، ما يؤدي إلى استجابة أسرع وأقل حجمًا.

لمزيد من المعلومات حول المرجع spreadsheets.values، بما في ذلك spreadsheets.values.get و spreadsheets.values.batchGet، يُرجى الاطّلاع على المستندات التالية:

• قراءة قيم الخلايا وكتابتها
• القراءة الأساسية

سرد جداول البيانات

لا يوفّر Sheets API طريقة لإدراج جداول البيانات للمستخدمين الذين تمّت المصادقة عليهم.

لاسترداد قائمة بجداول البيانات، يمكنك استخدام طريقة list في Drive API على المرجع files، مع تحديد 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 برمز الدخول الذي يمنح إذن الوصول إلى واجهة برمجة التطبيقات.

يتطلّب استخدام الطريقة files.list لإدراج جداول بيانات المستخدم نطاقًا محظورًا في Drive API.

مواضيع ذات صلة

في ما يلي بعض الخطوات التالية التي يمكنك تجربتها:

• لتعديل جدول بيانات، يُرجى الاطّلاع على مقالة تعديل جداول البيانات.

• للتعرّف على كيفية استخدام الشرائح الذكية، يُرجى الاطّلاع على مقالة الشرائح الذكية.

• للحصول على معلومات حول استخدام البيانات الوصفية للمطوّرين، يُرجى الاطّلاع على قراءة البيانات الوصفية وكتابتها والبحث فيها.