تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح لك واجهة Google Sheets API قراءة القيم من الخلايا والنطاقات ومجموعات النطاقات والجداول بأكملها. توضّح الأمثلة الواردة في هذه الصفحة بعض عمليات القراءة الشائعة باستخدام مورد spreadsheets.values. يمكنك أيضًا قراءة قيم الخلايا باستخدام الطريقة spreadsheets.get، ولكن عادةً ما تكون الطريقتان spreadsheets.values.get أو spreadsheets.values.batchGet أسهل.
يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون محايدة لغويًا. للتعرّف على كيفية تنفيذ عمليات القراءة بلغات مختلفة باستخدام مكتبات برامج Google API، اطّلِع على قراءة قيم الخلايا وكتابتها.
في هذه الأمثلة، يشير العنصر النائب SPREADSHEET_ID إلى المكان الذي يجب فيه تقديم معرّف جدول البيانات، والذي يمكن العثور عليه من عنوان URL لجدول البيانات. يتم تحديد النطاقات التي سيتم القراءة منها باستخدام تدوين A1 في عنوان URL للطلب. مثال على نطاق: الورقة1!A1:D5
بيانات المصدر
بالنسبة إلى هذه الأمثلة، افترِض أنّ جدول البيانات الذي تتم قراءته يتضمّن بيانات المصدر التالية في ورقة البيانات الأولى ("Sheet1"). السلاسل في الصف الأول هي تصنيفات للأعمدة الفردية. للاطّلاع على أمثلة حول كيفية القراءة من أوراق أخرى في جدول البيانات، يُرجى الاطّلاع على نظام التسمية A1.
A
ب
C
D
1
المنتج/الخدمة
التكلفة
مخزّن
تاريخ الشحن
2
العجلة
$20.50
4
2016/3/1
3
باب
$15
2
2016/3/15
4
المحرّك
$100
1
2016/3/20
5
مجاميع
$135.5
7
2016/3/20
قراءة نطاق واحد
يوضّح نموذج الرمز التالي
spreadsheets.values.get
كيفية قراءة القيم من النطاق Sheet1!A1:D5 وعرضها
في الردّ. يتم حذف الصفوف والأعمدة الفارغة الأخيرة.
يظهر هنا بروتوكول الطلب.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5
تتألف الاستجابة من كائن
ValueRange
يصف قيم النطاق. يشير الحقل
majorDimension إلى أنّ المصفوفات هي قوائم من القيم منظَّمة حسب الصفوف.
يوضّح نموذج الرمز التالي
spreadsheets.values.batchGet
كيفية قراءة القيم من النطاقَين Sheet1!B:B وSheet1!D:D
وعرضها في الردّ. يشير الإعداد
ValueRenderOption
في UNFORMATTED_VALUE إلى أنّه يتم احتساب القيم، ولكن لا يتم تنسيقها
في الردّ. يتم حذف الصفوف والأعمدة الفارغة الأخيرة.
يظهر هنا بروتوكول الطلب.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS
تتألف الاستجابة لطلب استدعاء هذه الطريقة من عنصر يتضمّن رقم تعريف جدول البيانات ومصفوفة من عناصر ValueRange تتوافق مع كل نطاق مطلوب، ويتم إدراجها بالترتيب الذي تم طلبها به. يشير الحقل
majorDimension إلى أنّ الصفائف هي قوائم من القيم منظَّمة حسب الأعمدة. على سبيل المثال:
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS
تتألف الاستجابة لطلب استدعاء هذه الطريقة من عنصر يتضمّن رقم تعريف جدول البيانات ومصفوفة من عناصر ValueRange تتوافق مع كل نطاق مطلوب، ويتم إدراجها بالترتيب الذي تم طلبها به. يشير الحقل
majorDimension إلى أنّ الصفائف هي قوائم من القيم منظَّمة حسب الأعمدة. على سبيل المثال:
تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Basic reading\n\nThe Google Sheets API allows you to read values from cells, ranges, sets of ranges,\nand entire sheets. The examples on this page illustrate some common read\noperations with the\n[`spreadsheets.values`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values)\nresource. You can also read cell values using the\n[`spreadsheets.get`](/workspace/sheets/api/reference/rest/v4/spreadsheets/get) method, but\nusually\n[`spreadsheets.values.get`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get)\nor\n[`spreadsheets.values.batchGet`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values/batchGet)\nis easier.\n\nThese examples are presented in the form of HTTP requests to be language\nneutral. To learn how to implement reads in different languages using the Google\nAPI client libraries, see [Read \\& write cell\nvalues](/workspace/sheets/api/guides/values#read).\n\nIn these examples, the placeholder \u003cvar translate=\"no\"\u003eSPREADSHEET_ID\u003c/var\u003e indicates where you\nwould provide the [spreadsheet ID](/workspace/sheets/api/guides/concepts#spreadsheet),\nwhich can be discovered from the spreadsheet URL. The ranges to read from are\nspecified using [A1 notation](/workspace/sheets/api/guides/concepts#cell) in the request\nURL. An example range is Sheet1!A1:D5.\n\nSource data\n-----------\n\nFor these examples, assume the spreadsheet being read has the following source\ndata in its first sheet (\"Sheet1\"). The strings in the first row are labels for\nthe individual columns. To view examples of how to read from other sheets in\nyour spreadsheet, see [A1 notation](/workspace/sheets/api/guides/concepts#cell).\n\n|---|--------|--------|---------|-----------|\n| | A | B | C | D |\n| 1 | Item | Cost | Stocked | Ship Date |\n| 2 | Wheel | $20.50 | 4 | 3/1/2016 |\n| 3 | Door | $15 | 2 | 3/15/2016 |\n| 4 | Engine | $100 | 1 | 3/20/2016 |\n| 5 | Totals | $135.5 | 7 | 3/20/2016 |\n\nRead a single range\n-------------------\n\nThe following\n[`spreadsheets.values.get`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get)\ncode sample shows how to read the values from the range Sheet1!A1:D5 and returns\nthem in the response. Empty trailing rows and columns are omitted.\n\nThe request protocol is shown here. \n\n```\nGET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5\n```\n\nThe response consists of a\n[`ValueRange`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values#resource:-valuerange)\nobject that describes the range values. The\n[`majorDimension`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values) field\nindicates that the arrays are lists of values organized by rows. \n\n```text\n{\n \"range\": \"Sheet1!A1:D5\",\n \"majorDimension\": \"ROWS\",\n \"values\": [\n [\"Item\", \"Cost\", \"Stocked\", \"Ship Date\"],\n [\"Wheel\", \"$20.50\", \"4\", \"3/1/2016\"],\n [\"Door\", \"$15\", \"2\", \"3/15/2016\"],\n [\"Engine\", \"$100\", \"1\", \"30/20/2016\"],\n [\"Totals\", \"$135.5\", \"7\", \"3/20/2016\"]\n ],\n}\n```\n\nRead a single range grouped by column\n-------------------------------------\n\nThe following\n[`spreadsheets.values.get`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get)\ncode sample shows how to read the values from the range Sheet1!A1:D3 and returns\nthem in the response, but grouped by column. Empty trailing rows and columns are\nomitted.\n\nThe request protocol is shown here. \n\n```\nGET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS\n```\n\nThe response consists of a\n[`ValueRange`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values#resource:-valuerange)\nobject that describes the range values. The\n[`majorDimension`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values) field\nindicates that the arrays are lists of values organized by columns. \n\n```text\n{\n \"range\": \"Sheet1!A1:D3\",\n \"majorDimension\": \"COLUMNS\",\n \"values\": [\n [\"Item\", \"Wheel\", \"Door\"],\n [\"Cost\", \"$20.50\", \"$15\"],\n [\"Stocked\", \"4\", \"2\"],\n [\"Ship Date\", \"3/1/2016\", \"3/15/2016\"]\n ],\n}\n```\n\nRead a single range with rendering options\n------------------------------------------\n\nThe following\n[`spreadsheets.values.get`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get)\ncode sample shows how to read the values from the range Sheet1!A1:D5 and returns\nthem in the response, but uses rendering options to manage how that information\nis returned. The\n[`ValueRenderOption`](/workspace/sheets/api/reference/rest/v4/ValueRenderOption) setting\nof `FORMULA` indicates that formulas are to be returned instead of the\ncalculated value, and the\n[`DateTimeRenderOption`](/workspace/sheets/api/reference/rest/v4/DateTimeRenderOption)\nsetting of `SERIAL_NUMBER` indicates that dates are to be returned as numbers.\nOther settings are possible as well. Empty trailing rows and columns are\nomitted.\n\nThe request protocol is shown here. \n\n```\nGET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?\n valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER\n```\n\nThe response consists of a\n[`ValueRange`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values#resource:-valuerange)\nobject that describes the range values. The\n[`majorDimension`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values) field\nindicates that the arrays are lists of values organized by rows. \n\n```text\n{\n \"range\": \"Sheet1!A1:D5\",\n \"majorDimension\": \"ROWS\",\n \"values\": [\n [\"Item\", \"Cost\", \"Stocked\", \"Ship Date\"],\n [\"Wheel\", \"$20.50\", \"4\", \"42430\"],\n [\"Door\", \"$15\", \"2\", \"42444\"],\n [\"Engine\", \"$100\", \"1\", \"42449\"],\n [\"Totals\", \"=SUM(B2:B4)\", \"=SUM(C2:C4)\", \"=MAX(D2:D4)\"]\n ],\n}\n```\n\nRead multiple ranges\n--------------------\n\nThe following\n[`spreadsheets.values.batchGet`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values/batchGet)\ncode sample shows how to read values from ranges Sheet1!B:B and Sheet1!D:D and\nreturns them in the response. The\n[`ValueRenderOption`](/workspace/sheets/api/reference/rest/v4/ValueRenderOption) setting\nof `UNFORMATTED_VALUE` indicates that values are calculated, but not formatted\nin the response. Empty trailing rows and columns are omitted.\n\nThe request protocol is shown here. \n\n```\nGET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?\n ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS\n```\n\nThe response to this method call consists of an object with the spreadsheet ID\nand an array of\n[`ValueRange`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values#resource:-valuerange)\nobjects corresponding to each requested range, listed in the order they were\nrequested. The\n[`majorDimension`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values) field\nindicates that the arrays are lists of values organized by columns. For example: \n\n```scdoc\n{\n \"spreadsheetId\": SPREADSHEET_ID,\n \"valueRanges\": [\n {\n \"range\": \"Sheet1!B1:B1000\",\n \"majorDimension\": \"COLUMNS\",\n \"values\": [\n [\"Cost\",20.5,15,100,135.5]\n ]\n },\n {\n \"range\": \"Sheet1!D1:D1000\",\n \"majorDimension\": \"COLUMNS\",\n \"values\": [\n [\"Ship Date\",42430,42444,42449,42449]\n ]s\n }\n ]\n}\n```\n\nRead multiple ranges across multiple sheets\n-------------------------------------------\n\nThe following\n[`spreadsheets.values.batchGet`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values/batchGet)\ncode sample shows how to read values from ranges in sheets Sheet1!A1:D5,\nProducts!D1:D100, and Sales!E4:F6 and returns them in the response. The\n[`ValueRenderOption`](/workspace/sheets/api/reference/rest/v4/ValueRenderOption) setting\nof `UNFORMATTED_VALUE` indicates that values are calculated, but not formatted\nin the response. Empty trailing rows and columns are omitted.\n\nThe request protocol is shown here. \n\n```\nGET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?\n ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS\n```\n\nThe response to this method call consists of an object with the spreadsheet ID\nand an array of\n[`ValueRange`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values#resource:-valuerange)\nobjects corresponding to each requested range, listed in the order they were\nrequested. The\n[`majorDimension`](/workspace/sheets/api/reference/rest/v4/spreadsheets.values) field\nindicates that the arrays are lists of values organized by columns. For example: \n\n```scdoc\n{\n \"spreadsheetId\": SPREADSHEET_ID,\n \"valueRanges\": [\n {\n \"range\": \"Sheet1!A1:D5\",\n \"majorDimension\": \"COLUMNS\",\n \"values\": [\n [...],\n [...]\n ]\n },\n {\n \"range\": \"Products!D1:D100\",\n \"majorDimension\": \"COLUMNS\",\n \"values\": [\n [...]\n ]\n },\n {\n \"range\": \"Sales!E4:F6\",\n \"majorDimension\": \"COLUMNS\",\n \"values\": [\n [...],\n [...]\n ]\n }\n ]\n}\n```"]]
