Method: spreadsheets.values.append
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
إلحاق القيم بجدول بيانات يُستخدَم نطاق الإدخال للبحث عن البيانات الحالية والعثور على "جدول" ضمن هذا النطاق. ستتم إضافة القيم إلى الصف التالي من الجدول، بدءًا من أول عمود في الجدول. اطّلِع على الدليل ونموذج الرمز البرمجي للحصول على تفاصيل محدّدة عن كيفية رصد الجداول وإلحاق البيانات بها.
على المتصل تحديد معرّف جدول البيانات والنطاق وvalueInputOption. لا يتحكّم العنصر valueInputOption إلا في كيفية إضافة بيانات الإدخال إلى ورقة البيانات (حسب العمود أو الصف)، ولا يؤثّر في الخلية التي تبدأ فيها كتابة البيانات.
طلب HTTP
POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values/{range}:append
يستخدِم عنوان URL بنية تحويل ترميز 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. الخيار التلقائي لعرض التاريخ والوقت هو 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
يحدِّد كيفية تغيير البيانات الحالية عند إدخال بيانات جديدة.
| عمليات التعداد |
OVERWRITE |
تستبدل البيانات الجديدة البيانات الحالية في المناطق التي يتم فيها كتابتها. (ملاحظة: ستؤدي إضافة بيانات إلى نهاية الورقة إلى إدراج صفوف أو أعمدة جديدة حتى يمكن كتابة البيانات). |
INSERT_ROWS |
يتم إدراج صفوف للبيانات الجديدة. |
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-03-22 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-03-22 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],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. |"]]
