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

تتيح لك واجهة Google Sheets API قراءة القيم من الخلايا والنطاقات ومجموعات النطاقات والجداول بأكملها. توضّح الأمثلة الواردة في هذه الصفحة بعض عمليات القراءة الشائعة باستخدام مورد spreadsheets.values. يمكنك أيضًا قراءة قيم الخلايا باستخدام الطريقة spreadsheets.get، ولكن عادةً ما تكون الطريقتان spreadsheets.values.get أو spreadsheets.values.batchGet أسهل.

يتم تقديم هذه الأمثلة في شكل طلبات HTTP لتكون محايدة لغويًا. للتعرّف على كيفية تنفيذ عمليات القراءة بلغات مختلفة باستخدام مكتبات برامج Google API، اطّلِع على قراءة قيم الخلايا وكتابتها.

في هذه الأمثلة، يشير العنصر النائب SPREADSHEET_ID إلى المكان الذي يجب فيه تقديم معرّف جدول البيانات، والذي يمكن العثور عليه من عنوان URL لجدول البيانات. يتم تحديد النطاقات التي سيتم القراءة منها باستخدام تدوين A1 في عنوان URL للطلب. مثال على نطاق: الورقة1!A1:D5

بيانات المصدر

بالنسبة إلى هذه الأمثلة، افترِض أنّ جدول البيانات الذي تتم قراءته يتضمّن بيانات المصدر التالية في ورقة البيانات الأولى ("Sheet1"). السلاسل في الصف الأول هي تصنيفات للأعمدة الفردية. للاطّلاع على أمثلة حول كيفية القراءة من أوراق أخرى في جدول البيانات، يُرجى الاطّلاع على نظام التسمية A1.

قراءة نطاق واحد

يوضّح نموذج الرمز التالي 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"]
  ],
}

قراءة نطاق واحد مجمّع حسب العمود

يوضّح نموذج الرمز التالي كيفية قراءة القيم من النطاق Sheet1!A1:D3 وعرضها في الرد، ولكن مع تجميعها حسب العمود.spreadsheets.values.get يتم حذف الصفوف والأعمدة الفارغة في نهاية الجدول.

يظهر هنا بروتوكول الطلب.

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"]
  ],
}

قراءة نطاق واحد مع خيارات العرض

يوضّح نموذج الرمز التالي كيفية قراءة القيم من النطاق Sheet1!A1:D5 وعرضها في الرد، ولكنّه يستخدم خيارات العرض لإدارة طريقة عرض هذه المعلومات.spreadsheets.values.get يشير الإعداد 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
    }
  ]
}

قراءة نطاقات متعددة في أوراق متعددة

يوضّح نموذج الرمز التالي كيفية قراءة القيم من النطاقات في الأوراق Sheet1!A1:D5 وProducts!D1:D100 وSales!E4:F6 وعرضها في الردّ.spreadsheets.values.batchGet يشير الإعداد 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": [
        [...],
        [...]
      ]
    }
  ]
}