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

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

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

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