خواندن پایه

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 مراجعه کنید.

الف ب سی D
1 مورد هزینه انبار شده تاریخ ارسال
2 چرخ 20.50 دلار 4 3/1/2016
3 درب 15 دلار 2 1395/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 زیر نحوه خواندن مقادیر از محدوده‌ها را در sheets 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": [
        [...],
        [...]
      ]
    }
  ]
}
 ،

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 مراجعه کنید.

الف ب سی D
1 مورد هزینه انبار شده تاریخ ارسال
2 چرخ 20.50 دلار 4 3/1/2016
3 درب 15 دلار 2 1395/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 زیر نحوه خواندن مقادیر از محدوده‌ها را در sheets 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": [
        [...],
        [...]
      ]
    }
  ]
}