عملیات داده

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

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

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

اعتبارسنجی داده ها را برای یک محدوده اعمال کنید

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از SetDataValidationRequest را برای اعمال یک قانون اعتبارسنجی داده، که در آن "مقدار > 5"، برای هر سلول در محدوده A1:D10 استفاده می شود، نشان می دهد.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "setDataValidation": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "rule": {
          "condition": {
            "type": "NUMBER_GREATER",
            "values": [
              {
                "userEnteredValue": "5"
              }
            ]
          },
          "inputMessage": "Value must be > 5",
          "strict": true
        }
      }
    }
  ]
}

قالب بندی سلول را کپی و جایگذاری کنید

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از CopyPasteRequest را برای کپی کردن قالب‌بندی فقط در محدوده A1:D10 و چسباندن آن در محدوده F1:I10 در همان صفحه نشان می‌دهد. این روش از شماره PasteType با PASTE_FORMAT برای چسباندن قالب‌بندی و اعتبارسنجی داده‌ها استفاده می‌کند. مقادیر اصلی در A1:D10 بدون تغییر باقی می مانند.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "copyPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 5,
          "endColumnIndex": 9
        },
        "pasteType": "PASTE_FORMAT",
        "pasteOrientation": "NORMAL"
      }
    }
  ]
}

برش و چسباندن سلول ها

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از CutPasteRequest را نشان می دهد. محدوده A1:D10 را برش می‌دهد و از PasteType enum با PASTE_NORMAL برای چسباندن مقادیر، فرمول‌ها، قالب‌بندی و ادغام در محدوده F1:I10 در همان برگه استفاده می‌کند. محتویات سلول محدوده منبع اصلی حذف می شوند.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "cutPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "rowIndex": 0,
          "columnIndex": 5
        },
        "pasteType": "PASTE_NORMAL"
      }
    }
  ]
}

یک فرمول را در یک محدوده تکرار کنید

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از RepeatCellRequest را برای کپی فرمول =FLOOR(A1*PI()) در محدوده B1:D10 نشان می دهد. محدوده فرمول به طور خودکار برای هر سطر و ستون در محدوده افزایش می یابد و از سلول بالا سمت چپ شروع می شود. به عنوان مثال، سلول B1 دارای فرمول =FLOOR(A1*PI()) است، در حالی که سلول D6 دارای فرمول =FLOOR(C6*PI()) است.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 1,
          "endColumnIndex": 4
        },
        "cell": {
          "userEnteredValue": {
              "formulaValue": "=FLOOR(A1*PI())"
          }
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

مرتب سازی یک محدوده با مشخصات مرتب سازی متعدد

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از SortRangeRequest را برای مرتب‌سازی محدوده A1:D10، ابتدا بر اساس ستون B به ترتیب صعودی، سپس بر اساس ستون C به ترتیب نزولی، سپس بر اساس ستون D به ترتیب نزولی نشان می‌دهد.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "sortRange": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "sortSpecs": [
          {
            "dimensionIndex": 1,
            "sortOrder": "ASCENDING"
          },
          {
            "dimensionIndex": 2,
            "sortOrder": "DESCENDING"
          },
          {
            "dimensionIndex": 3,
            "sortOrder": "DESCENDING"
          }
        ]
      }
    }
  ]
}
 ،

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

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

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

اعتبارسنجی داده ها را برای یک محدوده اعمال کنید

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از SetDataValidationRequest را برای اعمال یک قانون اعتبارسنجی داده، که در آن "مقدار > 5"، برای هر سلول در محدوده A1:D10 استفاده می شود، نشان می دهد.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "setDataValidation": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "rule": {
          "condition": {
            "type": "NUMBER_GREATER",
            "values": [
              {
                "userEnteredValue": "5"
              }
            ]
          },
          "inputMessage": "Value must be > 5",
          "strict": true
        }
      }
    }
  ]
}

قالب بندی سلول را کپی و جایگذاری کنید

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از CopyPasteRequest را برای کپی کردن قالب‌بندی فقط در محدوده A1:D10 و چسباندن آن در محدوده F1:I10 در همان صفحه نشان می‌دهد. این روش از شماره PasteType با PASTE_FORMAT برای چسباندن قالب‌بندی و اعتبارسنجی داده‌ها استفاده می‌کند. مقادیر اصلی در A1:D10 بدون تغییر باقی می مانند.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "copyPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 5,
          "endColumnIndex": 9
        },
        "pasteType": "PASTE_FORMAT",
        "pasteOrientation": "NORMAL"
      }
    }
  ]
}

برش و چسباندن سلول ها

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از CutPasteRequest را نشان می دهد. محدوده A1:D10 را برش می‌دهد و از PasteType enum با PASTE_NORMAL برای چسباندن مقادیر، فرمول‌ها، قالب‌بندی و ادغام در محدوده F1:I10 در همان برگه استفاده می‌کند. محتویات سلول محدوده منبع اصلی حذف می شوند.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "cutPaste": {
        "source": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "destination": {
          "sheetId": SHEET_ID,
          "rowIndex": 0,
          "columnIndex": 5
        },
        "pasteType": "PASTE_NORMAL"
      }
    }
  ]
}

یک فرمول را در یک محدوده تکرار کنید

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از RepeatCellRequest را برای کپی فرمول =FLOOR(A1*PI()) در محدوده B1:D10 نشان می دهد. محدوده فرمول به طور خودکار برای هر سطر و ستون در محدوده افزایش می یابد و از سلول بالا سمت چپ شروع می شود. به عنوان مثال، سلول B1 دارای فرمول =FLOOR(A1*PI()) است، در حالی که سلول D6 دارای فرمول =FLOOR(C6*PI()) است.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "repeatCell": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 1,
          "endColumnIndex": 4
        },
        "cell": {
          "userEnteredValue": {
              "formulaValue": "=FLOOR(A1*PI())"
          }
        },
        "fields": "userEnteredValue"
      }
    }
  ]
}

مرتب سازی یک محدوده با مشخصات مرتب سازی متعدد

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از SortRangeRequest را برای مرتب‌سازی محدوده A1:D10، ابتدا بر اساس ستون B به ترتیب صعودی، سپس بر اساس ستون C به ترتیب نزولی، سپس بر اساس ستون D به ترتیب نزولی نشان می‌دهد.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
  "requests": [
    {
      "sortRange": {
        "range": {
          "sheetId": SHEET_ID,
          "startRowIndex": 0,
          "endRowIndex": 10,
          "startColumnIndex": 0,
          "endColumnIndex": 4
        },
        "sortSpecs": [
          {
            "dimensionIndex": 1,
            "sortOrder": "ASCENDING"
          },
          {
            "dimensionIndex": 2,
            "sortOrder": "DESCENDING"
          },
          {
            "dimensionIndex": 3,
            "sortOrder": "DESCENDING"
          }
        ]
      }
    }
  ]
}