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

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

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

في هذه الأمثلة، يشير العنصران النائبان SPREADSHEET_ID وSHEET_ID إلى الموضع الذي ستُدخل فيه أرقام التعريف هذه. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL الخاص به. يمكنك الحصول على رقم تعريف ورقة البيانات باستخدام طريقة spreadsheets.get. يتم تحديد النطاقات باستخدام تدوين A1. مثال على نطاق: Sheet1!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_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
        }
      },
      ...
  ],
}