Method: spreadsheets.values.append
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
הוספת ערכים לגיליון אלקטרוני. טווח הקלט משמש לחיפוש נתונים קיימים ולמציאת 'טבלה' בטווח הזה. הערכים יתווספו לשורה הבאה בטבלה, החל מהעמודה הראשונה בטבלה. במדריך ובקוד לדוגמה מוסבר בפירוט איך הטבלאות מזוהות ואיך הנתונים מצורפים.
מבצע הקריאה החוזרת צריך לציין את מזהה הגיליון האלקטרוני, את הטווח ואת valueInputOption. הפרמטר valueInputOption קובע רק איך נתוני הקלט יתווספו לגיליון (לפי עמודות או לפי שורות), אבל הוא לא משפיע על התא שבו הנתונים יתחילו להיכתב.
בקשת HTTP
POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}:append
כתובת ה-URL משתמשת בתחביר של Transcoding של gRPC.
פרמטרים של נתיב
| פרמטרים |
spreadsheetId |
string
המזהה של הגיליון האלקטרוני שרוצים לעדכן.
|
range |
string
סימון A1 של טווח לחיפוש טבלה לוגית של נתונים. הערכים מצורפים אחרי השורה האחרונה בטבלה.
|
פרמטרים של שאילתה
| פרמטרים |
valueInputOption |
enum (ValueInputOption)
איך צריך לפרש את נתוני הקלט.
|
insertDataOption |
enum (InsertDataOption)
איך להוסיף את נתוני הקלט.
|
includeValuesInResponse |
boolean
קובע אם תגובת העדכון צריכה לכלול את הערכים של התאים שנוספו. כברירת מחדל, התשובות לא כוללות את הערכים המעודכנים.
|
responseValueRenderOption |
enum (ValueRenderOption)
קובעת את האופן שבו יש להציג את הערכים בתגובה. אפשרות העיבוד שמוגדרת כברירת מחדל היא FORMATTED_VALUE.
|
responseDateTimeRenderOption |
enum (DateTimeRenderOption)
קובע איך יתבצע העיבוד של תאריכים, שעות ומרווחי זמן בתגובה. המערכת מתעלמת מהערך הזה אם responseValueRenderOption הוא FORMATTED_VALUE. אפשרות ברירת המחדל של עיבוד dateTime היא SERIAL_NUMBER.
|
גוף הבקשה
גוף הבקשה מכיל מופע של ValueRange.
גוף התשובה
התגובה שמתקבלת כשמעדכנים טווח ערכים בגיליון אלקטרוני.
אם הפעולה מצליחה, גוף התגובה מכיל נתונים במבנה הבא:
| ייצוג ב-JSON |
{
"spreadsheetId": string,
"tableRange": string,
"updates": {
object (UpdateValuesResponse)
}
} |
| שדות |
spreadsheetId |
string
גיליון האלקטרוני שבו הוחלו העדכונים.
|
tableRange |
string
הטווח (בסימן A1) של הטבלה שאליה מצורפים הערכים (לפני הוספת הערכים). הערך יהיה ריק אם לא נמצאה טבלה.
|
updates |
object (UpdateValuesResponse)
מידע על העדכונים שהוחלו.
|
היקפי הרשאה
נדרש אחד מהיקפי ההרשאות הבאים של OAuth:
https://www.googleapis.com/auth/drivehttps://www.googleapis.com/auth/drive.filehttps://www.googleapis.com/auth/spreadsheets
מידע נוסף זמין במדריך ההרשאות.
InsertDataOption
קובעת איך הנתונים הקיימים משתנים כשמזינים נתונים חדשים.
| טיפוסים בני מנייה (enum) |
OVERWRITE |
הנתונים החדשים מחליפים את הנתונים הקיימים באזורים שבהם הם נכתבים. (הערה: הוספת נתונים לסוף הגיליון עדיין תוסיף שורות או עמודות חדשות כדי שניתן יהיה לכתוב את הנתונים). |
INSERT_ROWS |
המערכת תוסיף שורות לנתונים החדשים. |
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-03-22 (שעון UTC).
[null,null,["עדכון אחרון: 2025-03-22 (שעון UTC)."],[],[],null,["# Method: spreadsheets.values.append\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Path parameters](#body.PATH_PARAMETERS)\n- [Query parameters](#body.QUERY_PARAMETERS)\n- [Request body](#body.request_body)\n- [Response body](#body.response_body)\n - [JSON representation](#body.AppendValuesResponse.SCHEMA_REPRESENTATION)\n- [Authorization scopes](#body.aspect)\n- [InsertDataOption](#InsertDataOption)\n- [Try it!](#try-it)\n\nAppends values to a spreadsheet. The input range is used to search for existing data and find a \"table\" within that range. Values will be appended to the next row of the table, starting with the first column of the table. See the [guide](https://developers.google.com/workspace/sheets/api/guides/values#appending_values) and [sample code](https://developers.google.com/workspace/sheets/api/samples/writing#append_values) for specific details of how tables are detected and data is appended.\n\nThe caller must specify the spreadsheet ID, range, and a [valueInputOption](/workspace/sheets/api/reference/rest/v4/ValueInputOption). The `valueInputOption` only controls how the input data will be added to the sheet (column-wise or row-wise), it does not influence what cell the data starts being written to.\n\n### HTTP request\n\n`POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}:append`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Path parameters\n\n| Parameters ||\n|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `spreadsheetId` | `string` The ID of the spreadsheet to update. |\n| `range` | `string` The [A1 notation](https://developers.google.com/workspace/sheets/api/guides/concepts#cell) of a range to search for a logical table of data. Values are appended after the last row of the table. |\n\n### Query parameters\n\n| Parameters ||\n|--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `valueInputOption` | `enum (`[ValueInputOption](/workspace/sheets/api/reference/rest/v4/ValueInputOption)`)` How the input data should be interpreted. |\n| `insertDataOption` | `enum (`[InsertDataOption](/workspace/sheets/api/reference/rest/v4/spreadsheets.values/append#InsertDataOption)`)` How the input data should be inserted. |\n| `includeValuesInResponse` | `boolean` Determines if the update response should include the values of the cells that were appended. By default, responses do not include the updated values. |\n| `responseValueRenderOption` | `enum (`[ValueRenderOption](/workspace/sheets/api/reference/rest/v4/ValueRenderOption)`)` Determines how values in the response should be rendered. The default render option is [FORMATTED_VALUE](/workspace/sheets/api/reference/rest/v4/ValueRenderOption). |\n| `responseDateTimeRenderOption` | `enum (`[DateTimeRenderOption](/workspace/sheets/api/reference/rest/v4/DateTimeRenderOption)`)` Determines how dates, times, and durations in the response should be rendered. This is ignored if [responseValueRenderOption](/workspace/sheets/api/reference/rest/v4/spreadsheets.values/append#body.QUERY_PARAMETERS.response_value_render_option) is [FORMATTED_VALUE](/workspace/sheets/api/reference/rest/v4/ValueRenderOption). The default dateTime render option is [SERIAL_NUMBER](/workspace/sheets/api/reference/rest/v4/DateTimeRenderOption). |\n\n### Request body\n\nThe request body contains an instance of [ValueRange](/workspace/sheets/api/reference/rest/v4/spreadsheets.values#ValueRange).\n\n### Response body\n\nThe response when updating a range of values in a spreadsheet.\n\nIf successful, the response body contains data with the following structure:\n\n| JSON representation |\n|-------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"spreadsheetId\": string, \"tableRange\": string, \"updates\": { object (/workspace/sheets/api/reference/rest/v4/UpdateValuesResponse) } } ``` |\n\n| Fields ||\n|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------|\n| `spreadsheetId` | `string` The spreadsheet the updates were applied to. |\n| `tableRange` | `string` The range (in A1 notation) of the table that values are being appended to (before the values were appended). Empty if no table was found. |\n| `updates` | `object (`[UpdateValuesResponse](/workspace/sheets/api/reference/rest/v4/UpdateValuesResponse)`)` Information about the updates that were applied. |\n\n### Authorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://www.googleapis.com/auth/drive`\n- `https://www.googleapis.com/auth/drive.file`\n- `https://www.googleapis.com/auth/spreadsheets`\n\nFor more information, see the [Authorization guide](/workspace/guides/configure-oauth-consent).\n\nInsertDataOption\n----------------\n\nDetermines how existing data is changed when new data is input.\n\n| Enums ||\n|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `OVERWRITE` | The new data overwrites existing data in the areas it is written. (Note: adding data to the end of the sheet will still insert new rows or columns so the data can be written.) |\n| `INSERT_ROWS` | Rows are inserted for the new data. |"]]
