diff --git a/docs/classes/google-spreadsheet-cell.md b/docs/classes/google-spreadsheet-cell.md index e7d13011..2dfd4025 100644 --- a/docs/classes/google-spreadsheet-cell.md +++ b/docs/classes/google-spreadsheet-cell.md @@ -111,3 +111,19 @@ Property|Type|Description ?> Usually makes more sense to use `sheet.saveUpdatedCells()` to save many cell updates at once + + +### Developer Metadata + +### `getDeveloperMetadata()` (async) :id=fn-getDeveloperMetadata +> Get developer metadata for the current cell's column + +#### `createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId)` (async) :id=fn-createSheetDeveloperMetadata +> Add a new developer metadata object to the column of the cell + +Param|Type|Required|Description +---|---|---|--- +`metadataKey`|String|✅|The metadata key +`metadataValue`|String|✅|Data associated with the metadata's key +`visibility`|String|-|Limits the visibility selected developer metadata
_One of (PROJECT or DOCUMENT) - defaults to unspecified_ +`metadataId`|Integer|-|Spreadsheet-scoped unique ID that identifies the metadata
_autogenerated by google if empty_ diff --git a/docs/classes/google-spreadsheet-row.md b/docs/classes/google-spreadsheet-row.md index c4564cc3..8f6aa05d 100644 --- a/docs/classes/google-spreadsheet-row.md +++ b/docs/classes/google-spreadsheet-row.md @@ -94,3 +94,18 @@ Param|Type|Required|Description _also available as `row.del()`_ + +### Developer Metadata + +### `getDeveloperMetadata()` (async) :id=fn-getDeveloperMetadata +> Get developer metadata for the current row + +#### `createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId)` (async) :id=fn-createSheetDeveloperMetadata +> Add a new developer metadata object to the row + +Param|Type|Required|Description +---|---|---|--- +`metadataKey`|String|✅|The metadata key +`metadataValue`|String|✅|Data associated with the metadata's key +`visibility`|String|-|Limits the visibility selected developer metadata
_One of (PROJECT or DOCUMENT) - defaults to unspecified_ +`metadataId`|Integer|-|Spreadsheet-scoped unique ID that identifies the metadata
_autogenerated by google if empty_ diff --git a/docs/classes/google-spreadsheet-worksheet.md b/docs/classes/google-spreadsheet-worksheet.md index a336bd2e..3c7ac76b 100644 --- a/docs/classes/google-spreadsheet-worksheet.md +++ b/docs/classes/google-spreadsheet-worksheet.md @@ -272,6 +272,20 @@ Param|Type|Required|Description - ✨ **Side effects** - new row(s) or column(s) are inserted into the sheet - 🚨 **Warning** - Does not update cached rows/cells, so be sure to reload rows/cells before trying to make any updates to sheet contents + +### Developer Metadata + +#### `createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId)` (async) :id=fn-createSheetDeveloperMetadata +> Add a new developer metadata object to the sheet + +Param|Type|Required|Description +---|---|---|--- +`metadataKey`|String|✅|The metadata key +`metadataValue`|String|✅|Data associated with the metadata's key +`visibility`|String|-|Limits the visibility selected developer metadata
_One of (PROJECT or DOCUMENT) - defaults to unspecified_ +`metadataId`|Integer|-|Spreadsheet-scoped unique ID that identifies the metadata
_autogenerated by google if empty_ + + ### Other #### `clear()` (async) :id=fn-clear diff --git a/docs/classes/google-spreadsheet.md b/docs/classes/google-spreadsheet.md index 55553fb1..15dfae77 100644 --- a/docs/classes/google-spreadsheet.md +++ b/docs/classes/google-spreadsheet.md @@ -210,3 +210,43 @@ Param|Type|Required|Description `rangeId`|String|✅|ID of the range to remove +### Developer Metadata + +### `getMetadataById(metadataId)` (async) :id=fn-getMetadataById +> Get the developer metadata by ID + +### `getDeveloperMetadataByA1Range(a1Range)` (async) :id=fn-getDeveloperMetadataByA1Range +> Get a range of developer metadata by A1Range + +Param|Type|Required|Description +---|---|---|--- +`a1Range`|String|✅|The A1 range to find developer metadata
_Must be a single column or a single row_ + +### `getDeveloperMetadataByGridRange(gridRange)` (async) :id=fn-getDeveloperMetadataByA1Range +> Get a range of developer metadata by Grid Range + +Param|Type|Required|Description +---|---|---|--- +`gridRange`|Object|✅|The Grid Range to find developer metadata
_Must represent a single column or a single row_ + +#### `createSheetDeveloperMetadata(metadataKey, metadataValue, sheetId, visibility, metadataId)` (async) :id=fn-createSheetDeveloperMetadata +> Add a new developer metadata object to a specific sheet + +Param|Type|Required|Description +---|---|---|--- +`metadataKey`|String|✅|The metadata key +`metadataValue`|String|✅|Data associated with the metadata's key +`sheetId`|String|-|The ID of the sheet to associate the metadata with +`visibility`|String|-|Limits the visibility selected developer metadata
_One of (PROJECT or DOCUMENT) - defaults to unspecified_ +`metadataId`|Integer|-|Spreadsheet-scoped unique ID that identifies the metadata
_autogenerated by google if empty_ + +#### `createRangeDeveloperMetadata(metadataKey, metadataValue, range, visibility, metadataId)` (async) :id=fn-createRangeDeveloperMetadata +> Add a new developer metadata object to a specific range (COLUMNS or ROWS) + +Param|Type|Required|Description +---|---|---|--- +`metadataKey`|String|✅|The metadata key +`metadataValue`|String|✅|Data associated with the metadata's key +`range`|String|✅||The dimensionRange object to associate the metadata with +`visibility`|String|-|Limits the visibility selected developer metadata
_One of (PROJECT or DOCUMENT) - defaults to unspecified_ +`metadataId`|Integer|-|Spreadsheet-scoped unique ID that identifies the metadata
_autogenerated by google if empty_ diff --git a/lib/GoogleSpreadsheet.js b/lib/GoogleSpreadsheet.js index 98d3a19d..9796436f 100644 --- a/lib/GoogleSpreadsheet.js +++ b/lib/GoogleSpreadsheet.js @@ -332,6 +332,70 @@ class GoogleSpreadsheet { }); } + async getMetadataById(metadataId) { + // Request type = `developerMetadata` + // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.developerMetadata/get + return this.axios + .get(`/developerMetadata/${metadataId}`) + .then((response) => response.data); + } + + async _createDeveloperMetadata(metadataKey, metadataValue, location, visibility, metadataId) { + // Request type = `createDeveloperMetadata` + // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.developerMetadata#DeveloperMetadata + return this._makeSingleUpdateRequest('createDeveloperMetadata', { + developerMetadata: { + metadataKey, + metadataValue, + location, + visibility: visibility || 'PROJECT', + metadataId, + }, + }).then((data) => data.developerMetadata); + } + + async createSheetDeveloperMetadata(metadataKey, metadataValue, sheetId, visibility, metadataId) { + return this._createDeveloperMetadata( + metadataKey, + metadataValue, + { + sheetId: sheetId || 0, + }, + visibility, + metadataId + ); + } + + async createRangeDeveloperMetadata(metadataKey, metadataValue, range, visibility, metadataId) { + return this._createDeveloperMetadata( + metadataKey, + metadataValue, + { + dimensionRange: range, + }, + visibility, + metadataId + ); + } + + async _getDeveloperMetadata(dataFilter) { + // Request type = `developerMetadata:search` + // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.developerMetadata/search + return this.axios + .post('/developerMetadata:search', { + dataFilters: [dataFilter], + }) + .then((response) => response.data.matchedDeveloperMetadata); + } + + async getDeveloperMetadataByA1Range(a1Range) { + return this._getDeveloperMetadata({ a1Range }); + } + + async getDeveloperMetadataByGridRange(gridRange) { + return this._getDeveloperMetadata({ gridRange }); + } + async deleteNamedRange(namedRangeId) { return this._makeSingleUpdateRequest('deleteNamedRange', { namedRangeId }); } diff --git a/lib/GoogleSpreadsheetCell.js b/lib/GoogleSpreadsheetCell.js index 7d7f318b..cc225d10 100644 --- a/lib/GoogleSpreadsheetCell.js +++ b/lib/GoogleSpreadsheetCell.js @@ -174,6 +174,31 @@ class GoogleSpreadsheetCell { await this._sheet.saveUpdatedCells([this]); } + async createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId) { + return this._sheet._spreadsheet.createRangeDeveloperMetadata( + metadataKey, + metadataValue, + { + dimension: 'COLUMNS', + sheetId: this._sheet.sheetId, + startIndex: this._column, + endIndex: this._column + 1, + }, + visibility, + metadataId + ); + } + + async getDeveloperMetadata() { + return this._sheet._spreadsheet.getDeveloperMetadataByGridRange( + { + sheetId: this._sheet.sheetId, + startColumnIndex: this._column, + endColumnIndex: this._column + 1, + } + ); + } + // used by worksheet when saving cells // returns an individual batchUpdate request to update the cell _getUpdateRequest() { diff --git a/lib/GoogleSpreadsheetRow.js b/lib/GoogleSpreadsheetRow.js index a1ff7603..deea11d7 100644 --- a/lib/GoogleSpreadsheetRow.js +++ b/lib/GoogleSpreadsheetRow.js @@ -67,6 +67,31 @@ class GoogleSpreadsheetRow { return result; } async del() { return this.delete(); } // alias to mimic old version of this module + + async createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId) { + return this._sheet._spreadsheet.createRangeDeveloperMetadata( + metadataKey, + metadataValue, + { + dimension: 'ROWS', + sheetId: this._sheet.sheetId, + startIndex: this._rowNumber, + endIndex: this._rowNumber + 1, + }, + visibility, + metadataId + ); + } + + async getDeveloperMetadata() { + return this._sheet._spreadsheet.getDeveloperMetadataByGridRange( + { + sheetId: this._sheet.sheetId, + startRowIndex: this._rowNumber, + endRowIndex: this._rowNumber + 1, + } + ); + } } module.exports = GoogleSpreadsheetRow; diff --git a/lib/GoogleSpreadsheetWorksheet.js b/lib/GoogleSpreadsheetWorksheet.js index 324e77c7..345b5631 100644 --- a/lib/GoogleSpreadsheetWorksheet.js +++ b/lib/GoogleSpreadsheetWorksheet.js @@ -782,9 +782,12 @@ class GoogleSpreadsheetWorksheet { // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#DeleteBandingRequest } - async createDeveloperMetadata() { + async createDeveloperMetadata(metadataKey, metadataValue, visibility, metadataId) { // Request type = `createDeveloperMetadata` // https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/request#CreateDeveloperMetadataRequest + return this._spreadsheet.createSheetDeveloperMetadata( + metadataKey, metadataValue, this.sheetId, visibility, metadataId + ); } async updateDeveloperMetadata() {