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

تسمح لك 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.

	جيم	B	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 و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": [
        [...],
        [...]
      ]
    }
  ]
}