تتيح لك 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
من جدول بيانات محدّد في 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
}
},
...
],
}