تتيح لك 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
}
},
...
],
}