From ec8bcc488403479d688d1ae225da3b86eee88e6c Mon Sep 17 00:00:00 2001 From: Darragh Mc Kay Date: Thu, 2 Dec 2021 17:56:16 +0000 Subject: [PATCH 1/3] Fetch developer metadata by Id and create for columns, rows and sheets --- lib/GoogleSpreadsheet.js | 46 +++++++++++++++++++++++++++++++ lib/GoogleSpreadsheetCell.js | 15 ++++++++++ lib/GoogleSpreadsheetRow.js | 15 ++++++++++ lib/GoogleSpreadsheetWorksheet.js | 5 +++- 4 files changed, 80 insertions(+), 1 deletion(-) diff --git a/lib/GoogleSpreadsheet.js b/lib/GoogleSpreadsheet.js index 98d3a19d..ef2be364 100644 --- a/lib/GoogleSpreadsheet.js +++ b/lib/GoogleSpreadsheet.js @@ -332,6 +332,52 @@ 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 deleteNamedRange(namedRangeId) { return this._makeSingleUpdateRequest('deleteNamedRange', { namedRangeId }); } diff --git a/lib/GoogleSpreadsheetCell.js b/lib/GoogleSpreadsheetCell.js index 7d7f318b..1e2ae39d 100644 --- a/lib/GoogleSpreadsheetCell.js +++ b/lib/GoogleSpreadsheetCell.js @@ -174,6 +174,21 @@ 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 + ); + } + // 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..8015347d 100644 --- a/lib/GoogleSpreadsheetRow.js +++ b/lib/GoogleSpreadsheetRow.js @@ -67,6 +67,21 @@ 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 + ); + } } 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() { From 6978343d449766f08493076a37b9500b4ccea3bc Mon Sep 17 00:00:00 2001 From: Darragh Mc Kay Date: Thu, 2 Dec 2021 18:20:13 +0000 Subject: [PATCH 2/3] Add docs --- docs/classes/google-spreadsheet-cell.md | 13 +++++++++ docs/classes/google-spreadsheet-row.md | 12 ++++++++ docs/classes/google-spreadsheet-worksheet.md | 14 +++++++++ docs/classes/google-spreadsheet.md | 30 ++++++++++++++++++++ 4 files changed, 69 insertions(+) diff --git a/docs/classes/google-spreadsheet-cell.md b/docs/classes/google-spreadsheet-cell.md index e7d13011..91d2323d 100644 --- a/docs/classes/google-spreadsheet-cell.md +++ b/docs/classes/google-spreadsheet-cell.md @@ -111,3 +111,16 @@ Property|Type|Description ?> Usually makes more sense to use `sheet.saveUpdatedCells()` to save many cell updates at once + + +### Developer Metadata + +#### `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..73ba6634 100644 --- a/docs/classes/google-spreadsheet-row.md +++ b/docs/classes/google-spreadsheet-row.md @@ -94,3 +94,15 @@ Param|Type|Required|Description _also available as `row.del()`_ + +### Developer Metadata + +#### `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..681219f7 100644 --- a/docs/classes/google-spreadsheet.md +++ b/docs/classes/google-spreadsheet.md @@ -210,3 +210,33 @@ 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 + +Param|Type|Required|Description +---|---|---|--- +`metadataId`|Number|✅|The ID of the developer metadata object + +#### `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_ From 12853bffb8a66319635cfab2386d52b9b38f4840 Mon Sep 17 00:00:00 2001 From: Darragh Mc Kay Date: Fri, 3 Dec 2021 12:37:20 +0000 Subject: [PATCH 3/3] Get developer metadata by grid range and A1 range --- docs/classes/google-spreadsheet-cell.md | 3 +++ docs/classes/google-spreadsheet-row.md | 3 +++ docs/classes/google-spreadsheet.md | 12 +++++++++++- lib/GoogleSpreadsheet.js | 18 ++++++++++++++++++ lib/GoogleSpreadsheetCell.js | 10 ++++++++++ lib/GoogleSpreadsheetRow.js | 10 ++++++++++ 6 files changed, 55 insertions(+), 1 deletion(-) diff --git a/docs/classes/google-spreadsheet-cell.md b/docs/classes/google-spreadsheet-cell.md index 91d2323d..2dfd4025 100644 --- a/docs/classes/google-spreadsheet-cell.md +++ b/docs/classes/google-spreadsheet-cell.md @@ -115,6 +115,9 @@ Property|Type|Description ### 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 diff --git a/docs/classes/google-spreadsheet-row.md b/docs/classes/google-spreadsheet-row.md index 73ba6634..8f6aa05d 100644 --- a/docs/classes/google-spreadsheet-row.md +++ b/docs/classes/google-spreadsheet-row.md @@ -97,6 +97,9 @@ _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 diff --git a/docs/classes/google-spreadsheet.md b/docs/classes/google-spreadsheet.md index 681219f7..15dfae77 100644 --- a/docs/classes/google-spreadsheet.md +++ b/docs/classes/google-spreadsheet.md @@ -215,9 +215,19 @@ Param|Type|Required|Description ### `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 ---|---|---|--- -`metadataId`|Number|✅|The ID of the developer metadata object +`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 diff --git a/lib/GoogleSpreadsheet.js b/lib/GoogleSpreadsheet.js index ef2be364..9796436f 100644 --- a/lib/GoogleSpreadsheet.js +++ b/lib/GoogleSpreadsheet.js @@ -378,6 +378,24 @@ class GoogleSpreadsheet { ); } + 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 1e2ae39d..cc225d10 100644 --- a/lib/GoogleSpreadsheetCell.js +++ b/lib/GoogleSpreadsheetCell.js @@ -189,6 +189,16 @@ class GoogleSpreadsheetCell { ); } + 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 8015347d..deea11d7 100644 --- a/lib/GoogleSpreadsheetRow.js +++ b/lib/GoogleSpreadsheetRow.js @@ -82,6 +82,16 @@ class GoogleSpreadsheetRow { metadataId ); } + + async getDeveloperMetadata() { + return this._sheet._spreadsheet.getDeveloperMetadataByGridRange( + { + sheetId: this._sheet.sheetId, + startRowIndex: this._rowNumber, + endRowIndex: this._rowNumber + 1, + } + ); + } } module.exports = GoogleSpreadsheetRow;