القراءة الأساسية

تسمح لك 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": [
        [...],
        [...]
      ]
    }
  ]
}