نظرة عامة على Google Sheets API
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
واجهة برمجة تطبيقات "جداول بيانات Google" هي واجهة RESTful تتيح لك قراءة بيانات جداول البيانات وتعديلها. تتيح لك واجهة Sheets API إجراء ما يلي:
- إنشاء جداول بيانات
- قراءة قيم خلايا جداول البيانات وكتابتها
- تعديل تنسيق جدول البيانات
- إدارة "أوراق البيانات المرتبطة"
في ما يلي قائمة بالمصطلحات الشائعة المستخدَمة في Sheets API:
- جدول بيانات
تمثّل هذه السمة الكائن الأساسي في "جداول بيانات Google". يمكن أن يحتوي على عدة عناصر Sheets، كل منها يتضمّن معلومات منظَّمة في Cells. يمثّل المورد
spreadsheets
جدول بيانات. يحتوي على قيمة spreadsheetId فريدة.
- معرّف جدول البيانات
- المعرّف الفريد لجدول بيانات. وهي سلسلة معيّنة تحتوي على أحرف وأرقام وبعض الرموز الخاصة التي تشير إلى جدول بيانات، ويمكن استخراجها من عنوان URL الخاص بجدول البيانات. تكون أرقام تعريف جداول البيانات ثابتة، حتى إذا تغيّر اسم جدول البيانات.
https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit?gid=SHEET_ID#gid=SHEET_ID
- ورقة
صفحة أو علامة تبويب ضمن جدول بيانات يمثّل المرجع
Sheets ورقة. يحتوي على قيمة رقمية فريدة sheetId وورقة title كجزء من عنصر SheetProperties.
- رقم تعريف ورقة البيانات
- المعرّف الفريد لورقة محدّدة ضمن جدول بيانات وهو عدد صحيح معيّن يتضمّن أرقامًا تشير إلى ورقة، ويمكن استخراجه من عنوان URL الخاص بجدول البيانات. تكون أرقام تعريف جداول البيانات ثابتة، حتى إذا تغيّر اسم الجدول. للاطّلاع على مثال، راجِع معرّف جدول البيانات.
- الخلية
حقل فردي من النص أو البيانات داخل ورقة يتم ترتيب الخلايا في صفوف وأعمدة، ويمكن تجميعها كنطاق من الخلايا. يمثّل المرجع
Cells
كل خلية، ولكن ليس لديه قيمة معرّف فريدة.
بدلاً من ذلك، تحدّد إحداثيات الصف والعمود الخلايا.
- ترميز A1
- بنية تُستخدَم لتحديد خلية أو نطاق من الخلايا باستخدام سلسلة تحتوي على اسم الورقة بالإضافة إلى إحداثيات الخلية البادئة والخلية المنتهية باستخدام أحرف الأعمدة وأرقام الصفوف. هذه الطريقة هي الأكثر شيوعًا وفائدة
عند الإشارة إلى نطاق مطلق من الخلايا.
- تشير
Sheet1!A1:B2 إلى جميع الخلايا في الصفين والعمودين الأولين من Sheet1.
- تشير
Sheet1!A:A إلى جميع الخلايا في العمود الأول من Sheet1.
- تشير
Sheet1!1:2 إلى جميع الخلايا في الصفين الأول والثاني من "ورقة1".
- يشير
Sheet1!A5:A إلى جميع خلايا العمود الأول من "ورقة 1"، بدءًا من الصف 5.
- يشير
A1:B2 إلى جميع الخلايا في الصفين والعمودين الأولين من ورقة البيانات الأولى المرئية.
- يشير
Sheet1 إلى جميع الخلايا في Sheet1.
- تشير
'Jon's_Data'!A1:D5 إلى جميع الخلايا في الصفوف الخمسة الأولى والأعمدة الأربعة الأولى من ورقة باسم "Jon's_Data".
- تشير
'My Custom Sheet'!A:A إلى جميع الخلايا في العمود الأول من ورقة باسم "My Custom Sheet".
- تشير
'My Custom Sheet' إلى جميع الخلايا في "جدول البيانات المخصّص".
يجب استخدام علامات اقتباس فردية لأسماء الجداول التي تتضمّن مسافات أو رموزًا خاصة.
ملاحظة: استخدِم أسماء مختلفة للعناصر في جداول البيانات حيثما أمكن ذلك. على سبيل المثال، يشير A1 (بدون علامات اقتباس) إلى الخلية A1 في ورقة البيانات الأولى المرئية. تشير 'A1' إلى ورقة تحمل الاسم A1. وبالمثل، تشير Sheet1 إلى ورقة تحمل الاسم Sheet1. ومع ذلك، إذا كان هناك نطاق مسمّى بعنوان "Sheet1"، ستشير Sheet1 إلى النطاق المسمّى وستشير 'Sheet1' إلى ورقة البيانات.
- ترميز R1C1
- بنية تُستخدَم لتحديد خلية أو نطاق من الخلايا باستخدام سلسلة تحتوي على اسم الورقة بالإضافة إلى إحداثيات الخلية البادئة والمنتهية باستخدام أرقام الصفوف وأرقام الأعمدة هذه الطريقة أقل شيوعًا من نظام التسمية A1، ولكنّها قد تكون مفيدة عند الإشارة إلى نطاق من الخلايا بالنسبة إلى موضع خلية معيّنة.
- تشير
Sheet1!R1C1:R2C2 إلى أول خليتين في أول صفين من "ورقة 1".
- يشير
R1C1:R2C2 إلى أول خليتين في أول صفين من ورقة البيانات الأولى الظاهرة.
- يشير
Sheet1!R[3]C[1] إلى الخلية التي تقع على بعد ثلاثة صفوف إلى الأسفل وعمود واحد إلى يسار الخلية الحالية.
- النطاق المُعنوَن
- خلية أو نطاق خلايا محدّد باسم مخصّص لتسهيل المراجع
في جميع أنحاء التطبيق يمثّل المورد
FilterView
نطاقًا مسمّى.
- النطاق المحمي
- خلية أو نطاق محدّد من الخلايا لا يمكن تعديله. يمثّل مورد
ProtectedRange
نطاقًا محميًا.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Google Sheets API Overview\n\nThe Google Sheets API is a RESTful interface that lets you read and modify a\nspreadsheet's data. The Sheets API lets you:\n\n- Create spreadsheets\n- Read and write spreadsheet cell values\n- Update spreadsheet formatting\n- Manage Connected Sheets\n\nThe following is a list of common terms used in the Sheets API:\n\n*Spreadsheet*\n\n: The primary object in Google Sheets. It can contain multiple `Sheets`, each\n with structured information contained in `Cells`. The\n [`spreadsheets`](/workspace/sheets/api/reference/rest/v4/spreadsheets)\n resource represents a spreadsheet. It contains a unique `spreadsheetId`\n value.\n\n *Spreadsheet ID*\n : The unique identifier for a spreadsheet. It's a particular string\n containing letters, numbers, and some special characters that reference a\n spreadsheet and it can be derived from the spreadsheet's URL. Spreadsheet\n IDs are stable, even if the spreadsheet name changes. \n\n https://docs.google.com/spreadsheets/d/\u003cvar translate=\"no\"\u003eSPREADSHEET_ID\u003c/var\u003e/edit?gid=\u003cvar translate=\"no\"\u003eSHEET_ID\u003c/var\u003e#gid=\u003cvar translate=\"no\"\u003eSHEET_ID\u003c/var\u003e\n\n*Sheet*\n\n: A page or tab within a spreadsheet. The\n [`Sheets`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets) resource\n represents a sheet. It contains a unique numeric `sheetId` value and sheet\n `title` as part of the\n [`SheetProperties`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#sheetproperties)\n object.\n\n *Sheet ID*\n : The unique identifier for a specific sheet within a spreadsheet. It's a\n particular integer containing numbers that reference a sheet and it can be\n derived from the spreadsheet's URL. Sheet IDs are stable, even if the sheet\n name changes. For an example, see [Spreadsheet ID](#spreadsheet-id).\n\n*Cell*\n\n: An individual field of text or data within a sheet. Cells are arranged in rows\n and columns, and can be grouped as a range of cells. The\n [`Cells`](/workspace/sheets/api/reference/rest/v4/spreadsheets/cells)\n resource represents each cell, but it doesn't have a unique ID value.\n Instead, row and column coordinates identify the cells.\n\n *A1 notation*\n : A syntax used to define a cell or range of cells with a string that\n contains the sheet name plus the starting and ending cell coordinates using\n column letters and row numbers. This method is the most common and useful\n when referencing an absolute range of cells.\n - `Sheet1!A1:B2` refers to all the cells in the first two rows and columns of Sheet1.\n - `Sheet1!A:A` refers to all the cells in the first column of Sheet1.\n - `Sheet1!1:2` refers to all the cells in the first two rows of Sheet1.\n - `Sheet1!A5:A` refers to all the cells of the first column of Sheet 1, from row 5 onward.\n - `A1:B2` refers to all the cells in the first two rows and columns of the first visible sheet.\n - `Sheet1` refers to all the cells in Sheet1.\n - `'Jon's_Data'!A1:D5` refers to all the cells in the first five rows and four columns of a sheet named \"Jon's_Data.\"\n - `'My Custom Sheet'!A:A` refers to all the cells in the first column of a sheet named \"My Custom Sheet.\"\n - `'My Custom Sheet'` refers to all the cells in \"My Custom Sheet\".\n\n Single quotes are required for sheet names with spaces or special characters.\n\n **Tip** : Where possible, use distinct names for objects in your spreadsheets. For example, A1 (without quotes) refers to cell A1 in the first visible sheet. `'A1'` refers to a sheet with the name A1. Similarly, Sheet1 refers to a sheet with the name Sheet1. However, if there's a named range titled \"Sheet1\", then Sheet1 refers to the named range and `'Sheet1'` refers to the sheet.\n\n *R1C1 notation*\n : A syntax used to define a cell or range of cells with a string that\n contains the sheet name plus the starting and ending cell coordinates using\n row numbers and column numbers. This method is less common than A1 notation,\n but can be useful when referencing a range of cells relative to a given\n cell's position.\n - `Sheet1!R1C1:R2C2` refers to the first two cells in the top two rows of Sheet1.\n - `R1C1:R2C2` refers to the first two cells in the top two rows of the first visible sheet.\n - `Sheet1!R[3]C[1]` refers to the cell that is three rows below and one column to the right of the current cell.\n\n *Named range*\n : A defined cell or range of cells with a custom name to simplify references\n throughout an application. A\n [`FilterView`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#filterview)\n resource represents a named range.\n\n *Protected range*\n : A defined cell or range of cells that cannot be modified. A\n [`ProtectedRange`](/workspace/sheets/api/reference/rest/v4/spreadsheets/sheets#protectedrange)\n resource represents a protected range.\n\nRelated topics\n--------------\n\n- To learn about developing with Google Workspace APIs, including handling\n authentication and authorization, refer to [Develop on\n Google Workspace](/workspace/guides/get-started).\n\n- To learn how to configure and run a Sheets API app, try the\n [JavaScript quickstart](/workspace/sheets/api/quickstart/js)."]]
