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

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

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

في هذه الأمثلة، يشير العنصران النائبان 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
        }
      },
      ...
  ],
}