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

تتيح لك 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	3/15/2016
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 كيفية قراءة القيم من النطاق ورقة البيانات1!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": [
        [...],
        [...]
      ]
    }
  ]
}