تسمح لك 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.
A | B | C | D | |
1 | المنتج/الخدمة | التكلفة | المخزون | تاريخ الشحن |
2 | العجلة | SAR 20.50 | 4 | 1/3/2016 |
3 | باب | دولار هونغ كونغ | 2 | 2016/3/15 |
4 | المحرك | $100 | 1 | 20/3/2016 |
5 | مجاميع | 135.5 دولار نيوزيلندي | 7 | 20/3/2016 |
قراءة نطاق واحد
يوضح نموذج التعليمات البرمجية 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": [ [...], [...] ] } ] }