عملیات ورق

API گوگل شیت به شما امکان می‌دهد شیت‌ها را ایجاد، پاک، کپی و حذف کنید و همچنین ویژگی‌های آنها را کنترل کنید. مثال‌های این صفحه نشان می‌دهد که چگونه می‌توانید با استفاده از API شیت، به برخی از عملیات رایج شیت‌ها دست یابید.

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

در این مثال‌ها، متغیرهای SPREADSHEET_ID و SHEET_ID نشان می‌دهند که این شناسه‌ها را کجا باید ارائه دهید. می‌توانید شناسه صفحه گسترده را در URL صفحه گسترده پیدا کنید. می‌توانید شناسه صفحه را با استفاده از متد spreadsheets.get دریافت کنید. محدوده‌ها با استفاده از نمادگذاری A1 مشخص شده‌اند. یک محدوده به عنوان مثال Sheet1!A1:D5 است.

اضافه کردن برگه

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از AddSheetRequest را برای اضافه کردن یک برگه به ​​صفحه گسترده نشان می‌دهد، ضمن اینکه عنوان، اندازه شبکه و رنگ تب را نیز تنظیم می‌کند.

پاسخ شامل یک AddSheetResponse است که شامل یک شیء با ویژگی‌های برگه ایجاد شده (مانند SHEET_ID آن) است.

پروتکل درخواست در زیر نشان داده شده است.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "addSheet": {
        "properties": {
          "title": "Deposits",
          "gridProperties": {
            "rowCount": 20,
            "columnCount": 12
          },
          "tabColor": {
            "red": 1.0,
            "green": 0.3,
            "blue": 0.4
          }
        }
      }
    }
  ]
}

پاک کردن یک برگه از تمام مقادیر با حفظ فرمت‌ها

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از UpdateCellsRequest را برای حذف تمام مقادیر از یک برگه بدون تغییر قالب‌بندی نشان می‌دهد.

مشخص کردن فیلد userEnteredValue بدون مقدار متناظر، به عنوان دستورالعملی برای پاک کردن مقادیر در محدوده تفسیر می‌شود. این تنظیم را می‌توان با فیلدهای دیگر نیز استفاده کرد. برای مثال، تغییر مقدار fields به userEnteredFormat ، تمام قالب‌بندی‌های پشتیبانی شده توسط Sheets API را از برگه حذف می‌کند، اما مقادیر سلول را بدون تغییر باقی می‌گذارد.

پروتکل درخواست در زیر نشان داده شده است.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "updateCells": {
        "range": {
          "sheetId": SHEET_ID
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

کپی کردن یک برگه از یک صفحه گسترده به صفحه گسترده دیگر

نمونه کد spreadsheet.sheets.copyTo زیر نحوه کپی کردن یک برگه مشخص شده توسط SHEET_ID از یک صفحه گسترده به صفحه گسترده دیگر را نشان می‌دهد.

متغیر TARGET_SPREADSHEET_ID در بدنه درخواست، صفحه گسترده مقصد را مشخص می‌کند. کپی، تمام مقادیر، قالب‌بندی، فرمول‌ها و سایر ویژگی‌های صفحه اصلی را حفظ می‌کند. عنوان صفحه کپی شده روی "کپی از [عنوان صفحه اصلی]" تنظیم شده است.

پاسخ شامل یک شیء SheetProperties است که ویژگی‌های برگه ایجاد شده را توصیف می‌کند.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/sheets/SHEET_ID:copyTo

{
  "destinationSpreadsheetId": "TARGET_SPREADSHEET_ID"
}

حذف یک برگه

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از DeleteSheetRequest را برای حذف یک برگه مشخص شده توسط SHEET_ID نشان می‌دهد.

پروتکل درخواست در زیر نشان داده شده است.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": SHEET_ID
      }
    }
  ]
}

خواندن داده‌های برگه

نمونه کد spreadsheets.get زیر نحوه دریافت اطلاعات مربوط به ویژگی‌های برگه را از یک صفحه گسترده که توسط SHEET_ID و SPREADSHEET_ID مشخص شده است، نشان می‌دهد. این روش اغلب برای تعیین فراداده‌های برگه‌ها در یک صفحه گسترده خاص استفاده می‌شود، بنابراین عملیات اضافی می‌توانند آن برگه‌ها را هدف قرار دهند. پارامتر جستجوی fields مشخص می‌کند که فقط داده‌های مربوط به ویژگی‌های برگه باید بازگردانده شوند (برخلاف داده‌های مقدار سلول یا داده‌های مربوط به کل صفحه گسترده).

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?&fields=sheets.properties

پاسخ شامل یک منبع Spreadsheet است که شامل یک شیء Sheet با عناصر SheetProperties است. اگر یک فیلد پاسخ داده شده روی مقدار پیش‌فرض تنظیم شود، از پاسخ حذف می‌شود.

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "Sheet1",
        "index": 0,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 100,
          "columnCount": 20,
          "frozenRowCount": 1
        }
        "tabColor": {
          "blue": 1.0
        }
      },
      ...
  ],
}