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

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

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

في هذه الأمثلة، العنصران النائبان SPREADSHEET_ID وSHEET_ID يشير إلى مكان تقديم أرقام التعريف هذه. يمكنك العثور على جدول البيانات 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
        }
      },
      ...
  ],
}