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