عمليات الورقة

تتيح لك Google Sheets API إنشاء جداول البيانات وحذفها ونسخها وتعديلها، بالإضافة إلى التحكّم في خصائصها. توضِّح الأمثلة الواردة في هذه الصفحة كيفية تنفيذ بعض العمليات الشائعة في "جداول بيانات Google" باستخدام واجهة برمجة التطبيقات Sheets API.

يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون متعافِية من اللغة. للتعرّف على كيفية تنفيذ تعديل مجمّع بلغات مختلفة باستخدام مكتبات برامج Google API، اطّلِع على مقالة تعديل جداول بيانات Google.

في هذين المثالَين، تشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى المكان الذي يجب فيه تقديم معرّفات التطبيقَين. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL لجدول البيانات. يمكنك الحصول على معرّف جدول البيانات باستخدام الأسلوب spreadsheets.get. يتم تحديد النطاقات باستخدام ترميز A1. أحد مثالي النطاق هو الورقة1!A1:D5.

إضافة ورقة بيانات

يوضّح نموذج الرمز التالي spreadsheets.batchUpdate كيفية استخدام AddSheetRequest لإضافة ورقة بيانات إلى جدول بيانات، مع ضبط العنوان وحجم الشبكة و لون علامة التبويب أيضًا.

تتكوّن الاستجابة من AddSheetResponse، التي تحتوي على عنصر يتضمّن سمات الورقة التي تم إنشاؤها (مثل SHEET_ID).

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "Deposits",
          "gridProperties": {
            "rowCount": 20,
            "columnCount": 12
          },
          "tabColor": {
            "red": 1.0,
            "green": 0.3,
            "blue": 0.4
          }
        }
      }
    }
  ]
}

محو جميع القيم من ورقة بيانات مع الاحتفاظ بالتنسيقات

يوضّح نموذج الرمز البرمجي التالي spreadsheets.batchUpdate كيفية استخدام الرمز UpdateCellsRequest لإزالة جميع القيم من ورقة بيانات مع إبقاء التنسيق بدون تغيير.

إنّ تحديد الحقل userEnteredValue بدون قيمة مقابلة يتم تفسيره كتعليمات لمحو القيم في النطاق. ويمكن استخدام هذا الإعداد مع حقول أخرى أيضًا. على سبيل المثال، يؤدي تغيير قيمة fields إلى userEnteredFormat إلى إزالة كل التنسيقات المتوافقة مع واجهة Sheets API من ورقة البيانات، ولكن يترك قيم الخلايا بدون تغيير.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "updateCells": {
        "range": {
          "sheetId": SHEET_ID
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

نسخ ورقة من جدول بيانات إلى آخر

يوضّح نموذج الرمز البرمجي التالي spreadsheet.sheets.copyTo كيفية نسخ ورقة واحدة محدّدة بواسطة SHEET_ID من جدول بيانات إلى جدول بيانات آخر.

يحدِّد المتغيّر TARGET_SPREADSHEET_ID في نص الطلب جدول البيانات المقصود. تحتفظ النسخة بجميع القيم والتنسيقات والصيغ وغيرها من خصائص المستند الأصلي. يتم ضبط عنوان الورقة المنسوخة على "نسخة من [عنوان الورقة الأصلي]".

تتألف الاستجابة من كائن SheetProperties يصف سمات ورقة البيانات التي تم إنشاؤها.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/sheets/SHEET_ID:copyTo

{
  "destinationSpreadsheetId": "TARGET_SPREADSHEET_ID"
}

حذف ورقة بيانات

يوضّح نموذج الرمز التالي spreadsheets.batchUpdate كيفية استخدام الإجراء DeleteSheetRequest لحذف ورقة بيانات محدّدة بواسطة SHEET_ID.

يظهر بروتوكول الطلب أدناه.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": SHEET_ID
      }
    }
  ]
}

قراءة بيانات ورقة البيانات

يوضّح نموذج الرمز التالي spreadsheets.get كيفية الحصول على معلومات sheet من جدول بيانات، المحدّد من خلال SHEET_ID وSPREADSHEET_ID. غالبًا ما تُستخدَم هذه الطريقة لتحديد المحتوى الوصفي للجداول ضمن جدول بيانات معيّن، حتى تتمكّن العمليات الإضافية من استهداف تلك الجداول. تُحدِّد مَعلمة طلب البحث fields أنّه يجب عرض بيانات خاصية ورقة البيانات فقط (بدلاً من بيانات قيمة الخلية أو البيانات ذات الصلة بجدول البيانات بأكمله).

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?&fields=sheets.properties

تتألف الاستجابة من موارد Spreadsheet التي تحتوي على كائن Sheet يتضمّن عناصر SheetProperties. إذا تم ضبط حقل استجابة معيّن على القيمة التلقائية، سيتم حذفه من الاستجابة.

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "Sheet1",
        "index": 0,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 100,
          "columnCount": 20,
          "frozenRowCount": 1
        }
        "tabColor": {
          "blue": 1.0
        }
      },
      ...
  ],
}