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

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