عملیات ورق

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

این نمونه ها در قالب درخواست های HTTP برای خنثی بودن زبان ارائه شده اند. برای یادگیری نحوه اجرای یک به‌روزرسانی دسته‌ای به زبان‌های مختلف با استفاده از کتابخانه‌های سرویس گیرنده Google 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
        }
      },
      ...
  ],
}