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