خواندن پایه

API گوگل شیت به شما امکان می‌دهد مقادیر را از سلول‌ها، محدوده‌ها، مجموعه‌هایی از محدوده‌ها و کل شیت‌ها بخوانید. مثال‌های این صفحه برخی از عملیات خواندن رایج را با منبع spreadsheets.values ​​نشان می‌دهند. همچنین می‌توانید مقادیر سلول را با استفاده از متد spreadsheets.get بخوانید، اما معمولاً spreadsheets.values.get یا spreadsheets.values.batchGet آسان‌تر هستند.

این مثال‌ها به صورت درخواست‌های HTTP ارائه شده‌اند تا از نظر زبانی بی‌طرف باشند. برای یادگیری نحوه‌ی پیاده‌سازی خواندن در زبان‌های مختلف با استفاده از کتابخانه‌های کلاینت Google API، به بخش «خواندن و نوشتن مقادیر سلول» مراجعه کنید.

در این مثال‌ها، عبارت SPREADSHEET_ID نشان می‌دهد که شناسه صفحه‌گسترده را کجا باید وارد کنید، که از طریق URL صفحه‌گسترده قابل دسترسی است. محدوده‌هایی که باید از آنها خوانده شوند با استفاده از نمادگذاری A1 در URL درخواست مشخص شده‌اند. یک محدوده به عنوان مثال Sheet1!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"]
  ],
}

خواندن یک محدوده واحد که بر اساس ستون گروه‌بندی شده است

نمونه کد 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": [
        [...],
        [...]
      ]
    }
  ]
}