تتيح لك Google Sheets API قراءة القيم من الخلايا والنطاقات ومجموعات النطاقات
والأوراق بأكملها. توضّح الأمثلة في هذه الصفحة بعض عمليات القراءة الشائعة باستخدام مورد spreadsheets.values
. يمكنك أيضًا قراءة قيم الخلايا باستخدام الطريقة
spreadsheets.get
، ولكن عادةً ما يكون استخدام
spreadsheets.values.get
أو
spreadsheets.values.batchGet
أسهل.
يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون متعافِية من اللغة. للتعرّف على كيفية تنفيذ عمليات القراءة بلغات مختلفة باستخدام مكتبات عملاء Google API، اطّلِع على قراءة قيم الخلايا وكتابتها.
في هذه الأمثلة، يشير العنصر النائب SPREADSHEET_ID إلى المكان الذي يجب فيه تقديم رقم تعريف جدول البيانات، الذي يمكن العثور عليه من عنوان URL لجدول البيانات. يتم تحديد النطاقات المطلوب القراءة منها باستخدام علامة A1 في عنوان URL للطلب. على سبيل المثال، الورقة1!A1:D5.
بيانات المصدر
في هذه الأمثلة، نفترض أنّ جدول البيانات الذي تتم قراءته يحتوي على بيانات المصدر التالية في الورقة الأولى ("الورقة1"). السلاسل في الصف الأول هي تصنيفات للأعمدة الفردية. للاطّلاع على أمثلة عن كيفية القراءة من أوراق بيانات أخرى في جدول البيانات، اطّلِع على ترميز A1.
A | ب | C | D | |
1 | المنتج/الخدمة | التكلفة | متوفّر | تاريخ الشحن |
2 | العجلة | 20.50 دولار أمريكي | 4 | 1/3/2016 |
3 | باب | $15 | 2 | 2016/3/15 |
4 | المحرك | $100 | 1 | 3/20/2016 |
5 | مجاميع | 135.5 دولار أمريكي | 7 | 3/20/2016 |
قراءة نطاق واحد
يوضِّح نموذج الرمز التالي
spreadsheets.values.get
كيفية قراءة القيم من النطاق ورقة البيانات1!A1:D5 وعرضها
في الاستجابة. يتم حذف الصفوف والأعمدة اللاحقة الفارغة.
يظهر هنا بروتوكول الطلب.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5
تتألف الاستجابة من كائن
ValueRange
يصف قيم النطاق. يشير الحقل
majorDimension
إلى أنّ المصفوفات هي قوائم بالقيم منظَّمة حسب الصفوف.
{ "range": "Sheet1!A1:D5", "majorDimension": "ROWS", "values": [ ["Item", "Cost", "Stocked", "Ship Date"], ["Wheel", "$20.50", "4", "3/1/2016"], ["Door", "$15", "2", "3/15/2016"], ["Engine", "$100", "1", "30/20/2016"], ["Totals", "$135.5", "7", "3/20/2016"] ], }
قراءة نطاق واحد مجمَّعة حسب العمود
يوضّح نموذج الرمز التالي
spreadsheets.values.get
كيفية قراءة القيم من النطاق ورقة البيانات1!A1:D3 وإعادتها
في الاستجابة، ولكن مجمّعة حسب العمود. تتم إزالة الصفوف والأعمدة الفارغة في نهاية التقرير.
يظهر هنا بروتوكول الطلب.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS
تتكون الاستجابة من كائن
ValueRange
يصف قيم النطاق. يشير الحقل
majorDimension
إلى أنّ الصفائف هي قوائم بالقيم منظَّمة حسب الأعمدة.
{ "range": "Sheet1!A1:D3", "majorDimension": "COLUMNS", "values": [ ["Item", "Wheel", "Door"], ["Cost", "$20.50", "$15"], ["Stocked", "4", "2"], ["Ship Date", "3/1/2016", "3/15/2016"] ], }
قراءة نطاق واحد باستخدام خيارات العرض
يوضّح نموذج الرمز البرمجي
spreadsheets.values.get
التالي كيفية قراءة القيم من النطاق Sheet1!A1:D5 وعرضها
في الردّ، ولكنّه يستخدم خيارات العرض لإدارة طريقة عرض هذه المعلومات. يشير الإعداد
ValueRenderOption
للعمود FORMULA
إلى أنّه يجب عرض الصيغ بدلاً من
القيمة المحسوبة، ويشير الإعداد
DateTimeRenderOption
للعمود SERIAL_NUMBER
إلى أنّه يجب عرض التواريخ كأرقام.
من الممكن أيضًا ضبط إعدادات أخرى. تتم إزالة الصفوف والأعمدة الفارغة في نهاية التقرير.
يظهر هنا بروتوكول الطلب.
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5? valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER
تتكون الاستجابة من كائن
ValueRange
يصف قيم النطاق. يشير حقل
majorDimension
إلى أنّ المصفوفات هي قوائم قيم منظَّمة حسب الصفوف.
{ "range": "Sheet1!A1:D5", "majorDimension": "ROWS", "values": [ ["Item", "Cost", "Stocked", "Ship Date"], ["Wheel", "$20.50", "4", "42430"], ["Door", "$15", "2", "42444"], ["Engine", "$100", "1", "42449"], ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"] ], }
قراءة نطاقات متعددة
يوضِّح نموذج الرمز التالي
spreadsheets.values.batchGet
كيفية قراءة القيم من النطاقَين ورقة البيانات1!B:B وورقة البيانات1!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
إلى أنّ الصفائف هي قوائم بالقيم منظَّمة حسب الأعمدة. على سبيل المثال:
{ "spreadsheetId": SPREADSHEET_ID, "valueRanges": [ { "range": "Sheet1!B1:B1000", "majorDimension": "COLUMNS", "values": [ ["Cost",20.5,15,100,135.5] ] }, { "range": "Sheet1!D1:D1000", "majorDimension": "COLUMNS", "values": [ ["Ship Date",42430,42444,42449,42449] ]s } ] }
قراءة نطاقات متعددة في أوراق بيانات متعددة
يوضّح رمز المعالجة التالي
spreadsheets.values.batchGet
كيفية قراءة القيم من النطاقات في الأوراق "الورقة1"!A1:D5 و
"المنتجات"!D1:D100 و"المبيعات"!E4:F6 وإعادتها في الاستجابة. يشير الإعداد ValueRenderOption
في UNFORMATTED_VALUE
إلى أنّه قد تم احتساب القيم، ولكن لم يتم تنسيقها في الردّ. يتم حذف الصفوف والأعمدة الفارغة في نهاية النطاق.
يتم عرض بروتوكول الطلب هنا.
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
إلى أنّ الصفائف هي قوائم بالقيم منظَّمة حسب الأعمدة. على سبيل المثال:
{ "spreadsheetId": SPREADSHEET_ID, "valueRanges": [ { "range": "Sheet1!A1:D5", "majorDimension": "COLUMNS", "values": [ [...], [...] ] }, { "range": "Products!D1:D100", "majorDimension": "COLUMNS", "values": [ [...] ] }, { "range": "Sales!E4:F6", "majorDimension": "COLUMNS", "values": [ [...], [...] ] } ] }