نوشتن پایه

Google Sheets API به شما امکان می‌دهد مقادیر و فرمول‌ها را در سلول‌ها، محدوده‌ها، مجموعه‌هایی از محدوده‌ها و کل برگه‌ها بنویسید. مثال‌های موجود در این صفحه نشان می‌دهند که چگونه می‌توان به برخی از عملیات نوشتن رایج با منبع spreadsheets.values ​​Sheets 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 زیر نحوه نوشتن مقادیر را در یک محدوده نشان می دهد. پارامتر Query 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,
}

ورق به دست آمده به شکل زیر است:

	آ	ب	سی	D
1	مورد	هزینه	انبار شده	تاریخ ارسال
2	چرخ	20.50 دلار	4	3/1/2016
3	در، درب	15 دلار	2	1395/3/15
4	موتور	100 دلار	1	2016/3/20
5	جمع کل	135.5 دلار	7	2016/3/20

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

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

با شروع با برگه‌ای حاوی همان داده‌های تولید شده توسط مثال بالا ، نمونه کد spreadsheets.values.update زیر نحوه نوشتن مقادیر در محدوده B1:D4 را نشان می‌دهد، به‌طور انتخابی برخی سلول‌ها را بدون تغییر باقی می‌گذارد و برخی دیگر را پاک می‌کند. پارامتر Query 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,
}

ورق به دست آمده به شکل زیر است:

	آ	ب	سی	D
1	مورد	هزینه	انبار شده	تاریخ ارسال
2	چرخ	1.00 دلار	4	4/1/2016
3	در، درب	2 دلار	2	1395/4/15
4	موتور		1
5	جمع کل	3.00 دلار	7	1395/4/15

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

در چندین محدوده بنویسید

با شروع با یک صفحه خالی، نمونه کد 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,
    }
  ],
}

ورق به دست آمده به شکل زیر است:

	آ	ب	سی	D
1	مورد	هزینه	انبار شده	تاریخ ارسال
2	چرخ	20.50 دلار	4	3/1/2016
3	در، درب
4	موتور
5

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

با شروع با یک صفحه خالی، نمونه کد 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,
}

ورق به دست آمده به شکل زیر است:

	آ	ب	سی	D	E
1	داده ها	123.45	درست است، واقعی	=MAX(D2:D4)	10
2

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

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

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

	آ	ب	سی	D
1	مورد	هزینه	انبار شده	تاریخ ارسال
2	چرخ	20.50 دلار	4	3/1/2016
3

نمونه کد spreadsheets.values.append زیر نشان می‌دهد که چگونه می‌توان دو ردیف جدید از مقادیر را که با سطر 3 شروع می‌شوند، اضافه کرد. پارامتر Query 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,
  }
}

ورق به دست آمده به شکل زیر است:

	آ	ب	سی	D
1	مورد	هزینه	انبار شده	تاریخ ارسال
2	چرخ	20.50 دلار	4	3/1/2016
3	در، درب	15 دلار	2	1395/3/15
4	موتور	100 دلار	1	2016/3/20
5