تسمح لك Google Sheets API بقراءة القيم من الخلايا والنطاقات ومجموعات النطاقات
وأوراق البيانات بالكامل. توضّح الأمثلة في هذه الصفحة بعض عمليات القراءة الشائعة باستخدام مورد spreadsheets.values
. يمكنك أيضًا قراءة قيم الخلايا باستخدام طريقة
spreadsheets.get
، ولكن
عادةً ما تكون
spreadsheets.values.get
أو
spreadsheets.values.batchGet
أسهل.
يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون محايدة اللغة. لمعرفة كيفية تنفيذ عمليات القراءة بلغات مختلفة باستخدام مكتبات برامج Google API، يمكنك الاطّلاع على قراءة قيم الخلايا وكتابتها.
في هذه الأمثلة، يشير العنصر النائب SPREADSHEET_ID إلى المكان الذي ستقدّم فيه رقم تعريف جدول البيانات، الذي يمكن اكتشافه من عنوان URL لجدول البيانات. يتم تحديد النطاقات المطلوب القراءة منها باستخدام رمز A1 في عنوان URL للطلب. مثال على النطاق هو Sheet1!A1:D5.
البيانات المصدر
بالنسبة لهذه الأمثلة، افترض أن جدول البيانات الذي تتم قراءته يحتوي على بيانات المصدر التالية في الورقة الأولى ("Sheet1"). السلاسل الموجودة في الصف الأول هي تسميات للأعمدة الفردية. لعرض أمثلة حول كيفية القراءة من أوراق البيانات الأخرى في جدول البيانات، راجع ترميز A1.
جيم | B | 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
إلى أن الصفائف هي قوائم قيم منظَّمة حسب الصفوف.
{ "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
التالي كيفية قراءة القيم من النطاق Sheet1!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
التالي كيفية قراءة القيم من النطاقات 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
إلى أنّ المصفوفات هي قوائم قيم منظَّمة حسب الأعمدة. مثلاً:
{ "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
التالي كيفية قراءة القيم من النطاقات في الأوراق Sheet1!A1:D5
وProducts!D1:D100 وSales!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": [ [...], [...] ] } ] }