Method: spreadsheets.values.batchUpdate
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تُستخدَم لضبط القيم في نطاق واحد أو أكثر من جدول بيانات. على المتصل تحديد معرّف جدول البيانات وvalueInputOption وValueRanges واحد أو أكثر.
طلب HTTP
POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values:batchUpdate
يستخدِم عنوان URL بنية تحويل ترميز gRPC.
مَعلمات المسار
| المعلمات |
spreadsheetId |
string
رقم تعريف جدول البيانات المطلوب تعديله
|
نص الطلب
يحتوي نص الطلب على بيانات بالبنية التالية:
| الحقول |
valueInputOption |
enum (ValueInputOption)
كيفية تفسير بيانات الإدخال
|
data[] |
object (ValueRange)
القيم الجديدة التي سيتم تطبيقها على جدول البيانات
|
includeValuesInResponse |
boolean
لتحديد ما إذا كان يجب أن يتضمّن ردّ التعديل قيم الخلايا التي تم تعديلها. لا تتضمّن الردود تلقائيًا القيم المعدَّلة. يحتوي الحقل updatedData ضمن كل BatchUpdateValuesResponse.responses على القيم المعدَّلة. إذا كان النطاق المطلوب كتابته أكبر من النطاق الذي تم كتابته فعليًا، يتضمّن الردّ جميع القيم في النطاق المطلوب (باستثناء الصفوف والأعمدة الفارغة في نهاية النطاق).
|
responseValueRenderOption |
enum (ValueRenderOption)
يحدِّد كيفية عرض القيم في الاستجابة. الخيار التلقائي للعرض هو FORMATTED_VALUE.
|
responseDateTimeRenderOption |
enum (DateTimeRenderOption)
لتحديد كيفية عرض التواريخ والأوقات والمدد في الاستجابة يتم تجاهل هذا الإجراء إذا كان responseValueRenderOption هو FORMATTED_VALUE. الخيار التلقائي لعرض التاريخ والوقت هو SERIAL_NUMBER.
|
نص الاستجابة
الاستجابة عند تعديل نطاق قيم في جدول بيانات
إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:
| تمثيل JSON |
{
"spreadsheetId": string,
"totalUpdatedRows": integer,
"totalUpdatedColumns": integer,
"totalUpdatedCells": integer,
"totalUpdatedSheets": integer,
"responses": [
{
object (UpdateValuesResponse)
}
]
} |
| الحقول |
spreadsheetId |
string
جدول البيانات الذي تم تطبيق التعديلات عليه
|
totalUpdatedRows |
integer
إجمالي عدد الصفوف التي تم تحديث خلية واحدة على الأقل في كل صف منها
|
totalUpdatedColumns |
integer
إجمالي عدد الأعمدة التي تم تعديل خلية واحدة على الأقل فيها
|
totalUpdatedCells |
integer
إجمالي عدد الخلايا التي تم تعديلها
|
totalUpdatedSheets |
integer
إجمالي عدد الأوراق التي تم تعديل خلية واحدة على الأقل فيها
|
responses[] |
object (UpdateValuesResponse)
عنصر UpdateValuesResponse واحد لكل نطاق مطلوب، بالترتيب نفسه الذي ظهرت به الطلبات
|
نطاقات التفويض
يتطلب أحد نطاقات OAuth التالية:
https://www.googleapis.com/auth/drivehttps://www.googleapis.com/auth/drive.filehttps://www.googleapis.com/auth/spreadsheets
لمزيد من المعلومات، يمكنك الاطّلاع على دليل التفويض.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-03-22 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-03-22 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Method: spreadsheets.values.batchUpdate\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Path parameters](#body.PATH_PARAMETERS)\n- [Request body](#body.request_body)\n - [JSON representation](#body.request_body.SCHEMA_REPRESENTATION)\n- [Response body](#body.response_body)\n - [JSON representation](#body.BatchUpdateValuesResponse.SCHEMA_REPRESENTATION)\n- [Authorization scopes](#body.aspect)\n- [Try it!](#try-it)\n\nSets values in one or more ranges of a spreadsheet. The caller must specify the spreadsheet ID, a [valueInputOption](/workspace/sheets/api/reference/rest/v4/ValueInputOption), and one or more [ValueRanges](/workspace/sheets/api/reference/rest/v4/spreadsheets.values#ValueRange).\n\n### HTTP request\n\n`POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}/values:batchUpdate`\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\n### Request body\n\nThe request body contains data with the following structure:\n\n| JSON representation |\n|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ``` { \"valueInputOption\": enum (/workspace/sheets/api/reference/rest/v4/ValueInputOption), \"data\": [ { object (/workspace/sheets/api/reference/rest/v4/spreadsheets.values#ValueRange) } ], \"includeValuesInResponse\": boolean, \"responseValueRenderOption\": enum (/workspace/sheets/api/reference/rest/v4/ValueRenderOption), \"responseDateTimeRenderOption\": enum (/workspace/sheets/api/reference/rest/v4/DateTimeRenderOption) } ``` |\n\n| Fields ||\n|--------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `valueInputOption` | `enum (`[ValueInputOption](/workspace/sheets/api/reference/rest/v4/ValueInputOption)`)` How the input data should be interpreted. |\n| `data[]` | `object (`[ValueRange](/workspace/sheets/api/reference/rest/v4/spreadsheets.values#ValueRange)`)` The new values to apply to the spreadsheet. |\n| `includeValuesInResponse` | `boolean` Determines if the update response should include the values of the cells that were updated. By default, responses do not include the updated values. The `updatedData` field within each of the [BatchUpdateValuesResponse.responses](/workspace/sheets/api/reference/rest/v4/spreadsheets.values/batchUpdate#body.BatchUpdateValuesResponse.FIELDS.responses) contains the updated values. If the range to write was larger than the range actually written, the response includes all values in the requested range (excluding trailing empty rows and columns). |\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/batchUpdate#body.request_body.FIELDS.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### 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, \"totalUpdatedRows\": integer, \"totalUpdatedColumns\": integer, \"totalUpdatedCells\": integer, \"totalUpdatedSheets\": integer, \"responses\": [ { object (/workspace/sheets/api/reference/rest/v4/UpdateValuesResponse) } ] } ``` |\n\n| Fields ||\n|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `spreadsheetId` | `string` The spreadsheet the updates were applied to. |\n| `totalUpdatedRows` | `integer` The total number of rows where at least one cell in the row was updated. |\n| `totalUpdatedColumns` | `integer` The total number of columns where at least one cell in the column was updated. |\n| `totalUpdatedCells` | `integer` The total number of cells updated. |\n| `totalUpdatedSheets` | `integer` The total number of sheets where at least one cell in the sheet was updated. |\n| `responses[]` | `object (`[UpdateValuesResponse](/workspace/sheets/api/reference/rest/v4/UpdateValuesResponse)`)` One UpdateValuesResponse per requested range, in the same order as the requests appeared. |\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)."]]
