Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / dc6c1efea8e6c89afa94df984d9291359cb04797 / . / docs / dyn / sheets_v4.spreadsheets.values.html
blob: 6e051eb7939b761508e7189f8e568b24ecf656aa [file] [log] [blame]
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]1<html><body>
2<style>
3
4body, h1, h2, h3, div, span, p, pre, a {
5 margin: 0;
6 padding: 0;
7 border: 0;
8 font-weight: inherit;
9 font-style: inherit;
10 font-size: 100%;
11 font-family: inherit;
12 vertical-align: baseline;
13}
14
15body {
16 font-size: 13px;
17 padding: 1em;
18}
19
20h1 {
21 font-size: 26px;
22 margin-bottom: 1em;
23}
24
25h2 {
26 font-size: 24px;
27 margin-bottom: 1em;
28}
29
30h3 {
31 font-size: 20px;
32 margin-bottom: 1em;
33 margin-top: 1em;
34}
35
36pre, code {
37 line-height: 1.5;
38 font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
39}
40
41pre {
42 margin-top: 0.5em;
43}
44
45h1, h2, h3, p {
46 font-family: Arial, sans serif;
47}
48
49h1, h2, h3 {
50 border-bottom: solid #CCC 1px;
51}
52
53.toc_element {
54 margin-top: 0.5em;
55}
56
57.firstline {
58 margin-left: 2 em;
59}
60
61.method {
62 margin-top: 1em;
63 border: solid 1px #CCC;
64 padding: 1em;
65 background: #EEE;
66}
67
68.details {
69 font-weight: bold;
70 font-size: 14px;
71}
72
73</style>
74
75<h1><a href="sheets_v4.html">Google Sheets API</a> . <a href="sheets_v4.spreadsheets.html">spreadsheets</a> . <a href="sheets_v4.spreadsheets.values.html">values</a></h1>
76<h2>Instance Methods</h2>
77<p class="toc_element">
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]78 <code><a href="#append">append(spreadsheetId, range=None, body, insertDataOption=None, valueInputOption=None, x__xgafv=None)</a></code></p>
79<p class="firstline">Appends values to a spreadsheet. The input range is used to search for</p>
80<p class="toc_element">
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]81 <code><a href="#batchGet">batchGet(spreadsheetId, valueRenderOption=None, majorDimension=None, ranges=None, dateTimeRenderOption=None, x__xgafv=None)</a></code></p>
82<p class="firstline">Returns one or more ranges of values from a spreadsheet.</p>
83<p class="toc_element">
84 <code><a href="#batchUpdate">batchUpdate(spreadsheetId, body, x__xgafv=None)</a></code></p>
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]85<p class="firstline">Sets values in one or more ranges of a spreadsheet.</p>
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]86<p class="toc_element">
87 <code><a href="#get">get(spreadsheetId, range, valueRenderOption=None, majorDimension=None, dateTimeRenderOption=None, x__xgafv=None)</a></code></p>
88<p class="firstline">Returns a range of values from a spreadsheet.</p>
89<p class="toc_element">
90 <code><a href="#update">update(spreadsheetId, range, body, valueInputOption=None, x__xgafv=None)</a></code></p>
91<p class="firstline">Sets values in a range of a spreadsheet.</p>
92<h3>Method Details</h3>
93<div class="method">
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]94 <code class="details" id="append">append(spreadsheetId, range=None, body, insertDataOption=None, valueInputOption=None, x__xgafv=None)</code>
95 <pre>Appends values to a spreadsheet. The input range is used to search for
96existing data and find a "table" within that range. Values will be
97appended to the next row of the table, starting with the first column of
98the table. See the
99[guide](/sheets/guides/values#appending_values)
100and
101[sample code](/sheets/samples/writing#append_values)
102for specific details of how tables are detected and data is appended.
103
104The caller must specify the spreadsheet ID, range, and
105a valueInputOption. The `valueInputOption` only
106controls how the input data will be added to the sheet (column-wise or
107row-wise), it does not influence what cell the data starts being written
108to.
109
110Args:
111 spreadsheetId: string, The ID of the spreadsheet to update. (required)
112 range: string, The A1 notation of a range to search for a logical table of data.
113Values will be appended after the last row of the table. (required)
114 body: object, The request body. (required)
115 The object takes the form of:
116
117{ # Data within a range of the spreadsheet.
118 "range": "A String", # The range the values cover, in A1 notation.
119 # For output, this range indicates the entire requested range,
120 # even though the values will exclude trailing rows and columns.
121 # When appending values, this field represents the range to search for a
122 # table, after which values will be appended.
123 "values": [ # The data that was read or to be written. This is an array of arrays,
124 # the outer array representing all the data and each inner array
125 # representing a major dimension. Each item in the inner array
126 # corresponds with one cell.
127 #
128 # For output, empty trailing rows and columns will not be included.
129 #
130 # For input, supported value types are: bool, string, and double.
131 # Null values will be skipped.
132 # To set a cell to an empty value, set the string value to an empty string.
133 [
134 "",
135 ],
136 ],
137 "majorDimension": "A String", # The major dimension of the values.
138 #
139 # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
140 # then requesting `range=A1:B2,majorDimension=ROWS` will return
141 # `[[1,2],[3,4]]`,
142 # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
143 # `[[1,3],[2,4]]`.
144 #
145 # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
146 # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
147 # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
148 #
149 # When writing, if this field is not set, it defaults to ROWS.
150}
151
152 insertDataOption: string, How the input data should be inserted.
153 valueInputOption: string, How the input data should be interpreted.
154 x__xgafv: string, V1 error format.
155 Allowed values
156 1 - v1 error format
157 2 - v2 error format
158
159Returns:
160 An object of the form:
161
162 { # The response when updating a range of values in a spreadsheet.
163 "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
164 "tableRange": "A String", # The range (in A1 notation) of the table that values are being appended to
165 # (before the values were appended).
166 # Empty if no table was found.
167 "updates": { # The response when updating a range of values in a spreadsheet. # Information about the updates that were applied.
168 "updatedRange": "A String", # The range (in A1 notation) that updates were applied to.
169 "updatedColumns": 42, # The number of columns where at least one cell in the column was updated.
170 "updatedCells": 42, # The number of cells updated.
171 "updatedRows": 42, # The number of rows where at least one cell in the row was updated.
172 "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
173 },
174 }</pre>
175</div>
176
177<div class="method">
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]178 <code class="details" id="batchGet">batchGet(spreadsheetId, valueRenderOption=None, majorDimension=None, ranges=None, dateTimeRenderOption=None, x__xgafv=None)</code>
179 <pre>Returns one or more ranges of values from a spreadsheet.
180The caller must specify the spreadsheet ID and one or more ranges.
181
182Args:
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]183 spreadsheetId: string, The ID of the spreadsheet to retrieve data from. (required)
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]184 valueRenderOption: string, How values should be represented in the output.
185 majorDimension: string, The major dimension that results should use.
186
187For example, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
188then requesting `range=A1:B2,majorDimension=ROWS` will return
189`[[1,2],[3,4]]`,
190whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
191`[[1,3],[2,4]]`.
192 ranges: string, The A1 notation of the values to retrieve. (repeated)
193 dateTimeRenderOption: string, How dates, times, and durations should be represented in the output.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]194This is ignored if value_render_option is
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]195FORMATTED_VALUE.
196 x__xgafv: string, V1 error format.
197 Allowed values
198 1 - v1 error format
199 2 - v2 error format
200
201Returns:
202 An object of the form:
203
204 { # The response when retrieving more than one range of values in a spreadsheet.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]205 "spreadsheetId": "A String", # The ID of the spreadsheet the data was retrieved from.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]206 "valueRanges": [ # The requested values. The order of the ValueRanges is the same as the
207 # order of the requested ranges.
208 { # Data within a range of the spreadsheet.
209 "range": "A String", # The range the values cover, in A1 notation.
210 # For output, this range indicates the entire requested range,
211 # even though the values will exclude trailing rows and columns.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]212 # When appending values, this field represents the range to search for a
213 # table, after which values will be appended.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]214 "values": [ # The data that was read or to be written. This is an array of arrays,
215 # the outer array representing all the data and each inner array
216 # representing a major dimension. Each item in the inner array
217 # corresponds with one cell.
218 #
219 # For output, empty trailing rows and columns will not be included.
220 #
221 # For input, supported value types are: bool, string, and double.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]222 # Null values will be skipped.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]223 # To set a cell to an empty value, set the string value to an empty string.
224 [
225 "",
226 ],
227 ],
228 "majorDimension": "A String", # The major dimension of the values.
229 #
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]230 # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
231 # then requesting `range=A1:B2,majorDimension=ROWS` will return
232 # `[[1,2],[3,4]]`,
233 # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
234 # `[[1,3],[2,4]]`.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]235 #
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]236 # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
237 # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
238 # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]239 #
240 # When writing, if this field is not set, it defaults to ROWS.
241 },
242 ],
243 }</pre>
244</div>
245
246<div class="method">
247 <code class="details" id="batchUpdate">batchUpdate(spreadsheetId, body, x__xgafv=None)</code>
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]248 <pre>Sets values in one or more ranges of a spreadsheet.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]249The caller must specify the spreadsheet ID,
250a valueInputOption, and one or more
251ValueRanges.
252
253Args:
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]254 spreadsheetId: string, The ID of the spreadsheet to update. (required)
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]255 body: object, The request body. (required)
256 The object takes the form of:
257
258{ # The request for updating more than one range of values in a spreadsheet.
259 "data": [ # The new values to apply to the spreadsheet.
260 { # Data within a range of the spreadsheet.
261 "range": "A String", # The range the values cover, in A1 notation.
262 # For output, this range indicates the entire requested range,
263 # even though the values will exclude trailing rows and columns.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]264 # When appending values, this field represents the range to search for a
265 # table, after which values will be appended.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]266 "values": [ # The data that was read or to be written. This is an array of arrays,
267 # the outer array representing all the data and each inner array
268 # representing a major dimension. Each item in the inner array
269 # corresponds with one cell.
270 #
271 # For output, empty trailing rows and columns will not be included.
272 #
273 # For input, supported value types are: bool, string, and double.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]274 # Null values will be skipped.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]275 # To set a cell to an empty value, set the string value to an empty string.
276 [
277 "",
278 ],
279 ],
280 "majorDimension": "A String", # The major dimension of the values.
281 #
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]282 # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
283 # then requesting `range=A1:B2,majorDimension=ROWS` will return
284 # `[[1,2],[3,4]]`,
285 # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
286 # `[[1,3],[2,4]]`.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]287 #
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]288 # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
289 # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
290 # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]291 #
292 # When writing, if this field is not set, it defaults to ROWS.
293 },
294 ],
295 "valueInputOption": "A String", # How the input data should be interpreted.
296 }
297
298 x__xgafv: string, V1 error format.
299 Allowed values
300 1 - v1 error format
301 2 - v2 error format
302
303Returns:
304 An object of the form:
305
306 { # The response when updating a range of values in a spreadsheet.
307 "responses": [ # One UpdateValuesResponse per requested range, in the same order as
308 # the requests appeared.
309 { # The response when updating a range of values in a spreadsheet.
310 "updatedRange": "A String", # The range (in A1 notation) that updates were applied to.
311 "updatedColumns": 42, # The number of columns where at least one cell in the column was updated.
312 "updatedCells": 42, # The number of cells updated.
313 "updatedRows": 42, # The number of rows where at least one cell in the row was updated.
314 "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
315 },
316 ],
317 "totalUpdatedCells": 42, # The total number of cells updated.
318 "totalUpdatedColumns": 42, # The total number of columns where at least one cell in the column was
319 # updated.
320 "totalUpdatedRows": 42, # The total number of rows where at least one cell in the row was updated.
321 "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
322 "totalUpdatedSheets": 42, # The total number of sheets where at least one cell in the sheet was
323 # updated.
324 }</pre>
325</div>
326
327<div class="method">
328 <code class="details" id="get">get(spreadsheetId, range, valueRenderOption=None, majorDimension=None, dateTimeRenderOption=None, x__xgafv=None)</code>
329 <pre>Returns a range of values from a spreadsheet.
330The caller must specify the spreadsheet ID and a range.
331
332Args:
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]333 spreadsheetId: string, The ID of the spreadsheet to retrieve data from. (required)
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]334 range: string, The A1 notation of the values to retrieve. (required)
335 valueRenderOption: string, How values should be represented in the output.
336 majorDimension: string, The major dimension that results should use.
337
338For example, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
339then requesting `range=A1:B2,majorDimension=ROWS` will return
340`[[1,2],[3,4]]`,
341whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
342`[[1,3],[2,4]]`.
343 dateTimeRenderOption: string, How dates, times, and durations should be represented in the output.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]344This is ignored if value_render_option is
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]345FORMATTED_VALUE.
346 x__xgafv: string, V1 error format.
347 Allowed values
348 1 - v1 error format
349 2 - v2 error format
350
351Returns:
352 An object of the form:
353
354 { # Data within a range of the spreadsheet.
355 "range": "A String", # The range the values cover, in A1 notation.
356 # For output, this range indicates the entire requested range,
357 # even though the values will exclude trailing rows and columns.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]358 # When appending values, this field represents the range to search for a
359 # table, after which values will be appended.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]360 "values": [ # The data that was read or to be written. This is an array of arrays,
361 # the outer array representing all the data and each inner array
362 # representing a major dimension. Each item in the inner array
363 # corresponds with one cell.
364 #
365 # For output, empty trailing rows and columns will not be included.
366 #
367 # For input, supported value types are: bool, string, and double.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]368 # Null values will be skipped.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]369 # To set a cell to an empty value, set the string value to an empty string.
370 [
371 "",
372 ],
373 ],
374 "majorDimension": "A String", # The major dimension of the values.
375 #
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]376 # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
377 # then requesting `range=A1:B2,majorDimension=ROWS` will return
378 # `[[1,2],[3,4]]`,
379 # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
380 # `[[1,3],[2,4]]`.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]381 #
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]382 # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
383 # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
384 # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]385 #
386 # When writing, if this field is not set, it defaults to ROWS.
387 }</pre>
388</div>
389
390<div class="method">
391 <code class="details" id="update">update(spreadsheetId, range, body, valueInputOption=None, x__xgafv=None)</code>
392 <pre>Sets values in a range of a spreadsheet.
393The caller must specify the spreadsheet ID, range, and
394a valueInputOption.
395
396Args:
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]397 spreadsheetId: string, The ID of the spreadsheet to update. (required)
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]398 range: string, The A1 notation of the values to update. (required)
399 body: object, The request body. (required)
400 The object takes the form of:
401
402{ # Data within a range of the spreadsheet.
403 "range": "A String", # The range the values cover, in A1 notation.
404 # For output, this range indicates the entire requested range,
405 # even though the values will exclude trailing rows and columns.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]406 # When appending values, this field represents the range to search for a
407 # table, after which values will be appended.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]408 "values": [ # The data that was read or to be written. This is an array of arrays,
409 # the outer array representing all the data and each inner array
410 # representing a major dimension. Each item in the inner array
411 # corresponds with one cell.
412 #
413 # For output, empty trailing rows and columns will not be included.
414 #
415 # For input, supported value types are: bool, string, and double.
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]416 # Null values will be skipped.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]417 # To set a cell to an empty value, set the string value to an empty string.
418 [
419 "",
420 ],
421 ],
422 "majorDimension": "A String", # The major dimension of the values.
423 #
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]424 # For output, if the spreadsheet data is: `A1=1,B1=2,A2=3,B2=4`,
425 # then requesting `range=A1:B2,majorDimension=ROWS` will return
426 # `[[1,2],[3,4]]`,
427 # whereas requesting `range=A1:B2,majorDimension=COLUMNS` will return
428 # `[[1,3],[2,4]]`.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]429 #
Jon Wayne Parrott7d5badb2016-08-16 12:44:29 -0700[diff] [blame]430 # For input, with `range=A1:B2,majorDimension=ROWS` then `[[1,2],[3,4]]`
431 # will set `A1=1,B1=2,A2=3,B2=4`. With `range=A1:B2,majorDimension=COLUMNS`
432 # then `[[1,2],[3,4]]` will set `A1=1,B1=3,A2=2,B2=4`.
Jon Wayne Parrott0a471d32016-05-19 10:54:38 -0700[diff] [blame]433 #
434 # When writing, if this field is not set, it defaults to ROWS.
435}
436
437 valueInputOption: string, How the input data should be interpreted.
438 x__xgafv: string, V1 error format.
439 Allowed values
440 1 - v1 error format
441 2 - v2 error format
442
443Returns:
444 An object of the form:
445
446 { # The response when updating a range of values in a spreadsheet.
447 "updatedRange": "A String", # The range (in A1 notation) that updates were applied to.
448 "updatedColumns": 42, # The number of columns where at least one cell in the column was updated.
449 "updatedCells": 42, # The number of cells updated.
450 "updatedRows": 42, # The number of rows where at least one cell in the row was updated.
451 "spreadsheetId": "A String", # The spreadsheet the updates were applied to.
452 }</pre>
453</div>
454
455</body></html>