نوشتن پایه

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

توجه داشته باشید که نوشتن مقادیر سلول با استفاده از متد spreadsheet.batchUpdate نیز امکان‌پذیر است، که اگر می‌خواهید قالب‌بندی سلول یا سایر ویژگی‌هایی را که منبع spreadsheets.values ​​روی آنها تأثیری ندارد، به‌طور همزمان به‌روزرسانی کنید، می‌تواند مفید باشد. برای مثال، اگر می‌خواهید طیفی از سلول‌ها را از یک برگه به ​​برگه دیگر کپی کنید و در عین حال فرمول سلول و قالب‌بندی سلول را بازنویسی کنید، می‌توانید از متد UpdateCellsRequest با spreadsheet.batchUpdate استفاده کنید.

با این حال، برای نوشتن مقادیر ساده، استفاده از متد spreadsheets.values.update یا متد spreadsheets.values.batchUpdate آسان‌تر است.

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

در این مثال‌ها، عبارت SPREADSHEET_ID نشان می‌دهد که شناسه صفحه‌گسترده را کجا باید وارد کنید، که از طریق URL صفحه‌گسترده قابل دسترسی است. محدوده‌هایی که باید در آن‌ها نوشته شود با استفاده از نمادگذاری A1 مشخص شده‌اند. یک محدوده به عنوان مثال Sheet1!A1:D5 است.

یک محدوده واحد بنویسید

با شروع از یک صفحه گسترده جدید و خالی، نمونه کد spreadsheets.values.update زیر نحوه نوشتن مقادیر در یک محدوده را نشان می‌دهد. پارامتر پرس و جوی ValueInputOption الزامی است و تعیین می‌کند که آیا مقادیر نوشته شده تجزیه می‌شوند یا خیر (برای مثال، آیا یک رشته به تاریخ تبدیل می‌شود یا خیر).

بدنه درخواست یک شیء ValueRange است که مقادیر محدوده‌ای که باید نوشته شوند را توصیف می‌کند. فیلد majorDimension نشان می‌دهد که آرایه‌ها لیست‌هایی از مقادیر هستند که بر اساس ردیف‌ها سازماندهی شده‌اند. مقادیر موجود در محدوده هدف رونویسی می‌شوند.

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

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "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", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

پاسخ شامل یک شیء UpdateValuesResponse است، مانند این:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

برگه حاصل به شکل زیر است:

به صورت انتخابی در یک محدوده بنویسید

هنگام نوشتن مقادیر در یک محدوده، می‌توان با تنظیم عناصر آرایه مربوطه به null از تغییر برخی از سلول‌های موجود جلوگیری کرد. همچنین می‌توان با نوشتن یک رشته خالی ( "" ) در یک سلول، آن را پاک کرد.

با شروع از یک برگه حاوی همان داده‌های تولید شده توسط مثال بالا ، نمونه کد spreadsheets.values.update زیر نحوه نوشتن مقادیر در محدوده B1:D4 را نشان می‌دهد، به طور انتخابی برخی از سلول‌ها بدون تغییر باقی می‌مانند و بقیه پاک می‌شوند. پارامتر پرس و جوی ValueInputOption الزامی است و تعیین می‌کند که آیا مقادیر نوشته شده تجزیه می‌شوند یا خیر (به عنوان مثال، آیا یک رشته به تاریخ تبدیل می‌شود یا خیر).

بدنه درخواست یک شیء ValueRange است که مقادیر محدوده‌ای را که باید نوشته شوند، توصیف می‌کند. فیلد majorDimension نشان می‌دهد که آرایه‌ها، فهرست‌هایی از مقادیر هستند که بر اساس ستون سازماندهی شده‌اند.

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

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

فیلد values در اینجا تغییرات ایجاد شده در هر ستون در محدوده را فهرست می‌کند. آرایه اول نشان می‌دهد که B1 باید بدون تغییر باقی بماند (به دلیل عنصر آرایه null )، در حالی که B4 باید پاک شود (رشته خالی). مقادیر B2 و B3 به‌روزرسانی می‌شوند. آرایه سوم عملیات مشابهی را روی ستون D انجام می‌دهد، در حالی که آرایه خالی دوم نشان می‌دهد که ستون C باید بدون تغییر باقی بماند.

پاسخ شامل یک شیء UpdateValuesResponse مانند این است:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

برگه حاصل به شکل زیر است:

توجه داشته باشید که ردیف "مجموع" اگرچه مستقیماً توسط این درخواست تغییر نکرده است، اما تغییر می‌کند زیرا سلول‌های آن حاوی فرمول‌هایی هستند که به سلول‌های تغییر یافته بستگی دارند.

نوشتن در چندین محدوده

با شروع از یک برگه خالی، نمونه کد spreadsheets.values.batchUpdate زیر نحوه نوشتن مقادیر در محدوده‌های Sheet1!A1:A4 و Sheet1!B1:D2 را نشان می‌دهد. مقادیر موجود در محدوده هدف رونویسی می‌شوند. بدنه درخواست شامل یک شیء ValueInputOption است که نحوه تفسیر داده‌های ورودی و آرایه‌ای از اشیاء ValueRange مربوط به هر محدوده نوشته شده را نشان می‌دهد. فیلد majorDimension تعیین می‌کند که آیا آرایه‌های موجود به عنوان آرایه‌های ستونی یا ردیفی تفسیر می‌شوند.

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

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

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

پاسخ شامل یک شیء است که آمار به‌روزرسانی‌شده‌ی سلول‌ها و آرایه‌ای از اشیاء UpdateValuesResponse را فهرست می‌کند، که هر کدام برای یک محدوده‌ی به‌روزرسانی‌شده است. برای مثال:

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

برگه حاصل به شکل زیر است:

نوشتن مقادیر بدون تجزیه

با شروع از یک صفحه خالی، نمونه کد spreadsheets.values.update زیر نحوه نوشتن مقادیر در محدوده Sheet1!A1:E1 را نشان می‌دهد، اما از پارامتر پرس و جوی RAW ValueInputOption برای جلوگیری از تجزیه رشته‌های نوشته شده به عنوان فرمول، مقادیر بولی یا اعداد استفاده می‌کند. آنها به صورت رشته ظاهر می‌شوند و ترازبندی متن در صفحه ترازبندی می‌شود.

بدنه درخواست یک شیء ValueRange است که مقادیر محدوده‌ای که باید نوشته شوند را توصیف می‌کند. فیلد majorDimension نشان می‌دهد که آرایه‌ها لیست‌هایی از مقادیر هستند که بر اساس ردیف‌ها سازماندهی شده‌اند. مقادیر موجود در محدوده هدف رونویسی می‌شوند.

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

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

پاسخ شامل یک شیء UpdateValuesResponse مانند این است:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

برگه حاصل به شکل زیر است:

توجه داشته باشید که "TRUE" در مرکز قرار گرفته و یک مقدار بولی است، در حالی که "123.45" به دلیل عدد بودن، از راست تراز شده است و "10" به دلیل رشته بودن، از چپ تراز شده است. فرمول تجزیه نشده و به صورت رشته نیز نمایش داده می‌شود.

مقادیر را اضافه کنید

با یک برگه مانند جدول زیر شروع کنید:

نمونه کد spreadsheets.values.append زیر نحوه اضافه کردن دو ردیف جدید از مقادیر را که از ردیف ۳ شروع می‌شوند، نشان می‌دهد. پارامتر پرس‌وجوی ValueInputOption الزامی است و تعیین می‌کند که آیا مقادیر نوشته شده تجزیه می‌شوند یا خیر (برای مثال، آیا یک رشته به تاریخ تبدیل می‌شود یا خیر).

بدنه درخواست یک شیء ValueRange است که مقادیر محدوده‌ای را که باید نوشته شوند توصیف می‌کند. فیلد majorDimension نشان می‌دهد که آرایه‌ها، فهرست‌هایی از مقادیر هستند که بر اساس ردیف‌ها سازماندهی شده‌اند.

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

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

پاسخ شامل یک شیء AppendValuesResponse مانند این است:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

برگه حاصل به شکل زیر است: