عملیات داده

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

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

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

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

نمونه کد spreadsheets.batchUpdate زیر نحوه استفاده از SetDataValidationRequest را برای اعمال یک قانون اعتبارسنجی داده‌ها، که در آن "value > 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 به همراه 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"
          }
        ]
      }
    }
  ]
}