diff --git a/storage/getObjectContexts.js b/storage/getObjectContexts.js new file mode 100644 index 0000000000..613a22c2ab --- /dev/null +++ b/storage/getObjectContexts.js @@ -0,0 +1,71 @@ +// Copyright 2026 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +'use strict'; + +// sample-metadata: +// title: Get Object Contexts +// description: Retrieves the structured Object Contexts from an object. +// usage: node getObjectContexts.js + +/** + * This application demonstrates how to retrieve the 'contexts' field from a file + * in Google Cloud Storage. + */ + +function main(bucketName = 'my-bucket', fileName = 'test.txt') { + // [START storage_get_object_contexts] + /** + * TODO(developer): Uncomment the following lines before running the sample. + */ + // The ID of your GCS bucket + // const bucketName = 'your-unique-bucket-name'; + + // The ID of your GCS file + // const fileName = 'your-file-name'; + + // Imports the Google Cloud client library + const {Storage} = require('@google-cloud/storage'); + + // Creates a client + const storage = new Storage(); + + async function getObjectContexts() { + // Gets the metadata for the file + const [metadata] = await storage + .bucket(bucketName) + .file(fileName) + .getMetadata(); + + // Contexts are stored in metadata.contexts.custom + if (metadata.contexts && metadata.contexts.custom) { + console.log(`Object Contexts for ${fileName}:`); + + // Iterate through the custom contexts to show values and timestamps + for (const [key, details] of Object.entries(metadata.contexts.custom)) { + console.log(`- Key: ${key}`); + console.log(` Value: ${details.value}`); + console.log(` Created: ${details.createTime}`); + console.log(` Updated: ${details.updateTime}`); + } + } else { + console.log(`No Object Contexts found for ${fileName}.`); + } + } + + getObjectContexts().catch(console.error); + // [END storage_get_object_contexts] +} + +main(...process.argv.slice(2)); diff --git a/storage/listObjectContexts.js b/storage/listObjectContexts.js new file mode 100644 index 0000000000..3e0c0b00bf --- /dev/null +++ b/storage/listObjectContexts.js @@ -0,0 +1,104 @@ +// Copyright 2026 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +'use strict'; + +// sample-metadata: +// title: List Objects with Context Filter +// description: Lists objects in a bucket that match specific custom contexts. +// usage: node listObjectContexts.js + +/** + * This application demonstrates how to list objects in a bucket while filtering + * by their custom 'contexts' metadata. + */ + +function main(bucketName = 'my-bucket') { + // [START storage_list_object_contexts] + /** + * TODO(developer): Uncomment the following lines before running the sample. + */ + // The ID of your GCS bucket + // const bucketName = 'your-unique-bucket-name'; + + // Imports the Google Cloud client library + const {Storage} = require('@google-cloud/storage'); + + // Creates a client + const storage = new Storage(); + + async function listObjectContexts() { + // Define the filter for contexts. + const bucket = storage.bucket(bucketName); + + /** + * List any object that has a context with the specified key and value. + * Syntax: contexts.""="" + */ + const filterByValue = 'contexts."priority"="high"'; + const [filesByValue] = await bucket.getFiles({ + filter: filterByValue, + }); + + console.log(`\nFiles matching filter [${filterByValue}]:`); + filesByValue.forEach(file => console.log(` - ${file.name}`)); + + /** + * List any object that has a context with the specified key attached. + * Syntax: contexts."":* + */ + const filterByExistence = 'contexts."team-owner":*'; + const [filesWithKey] = await bucket.getFiles({ + filter: filterByExistence, + }); + + console.log( + `\nFiles with the "team-owner" context key [${filterByExistence}]:` + ); + filesWithKey.forEach(file => console.log(` - ${file.name}`)); + + /** + * List any object that does not have a context with the specified key and value attached. + * Syntax: -contexts.""="" + */ + const absenceOfValuePair = '-contexts."priority"="high"'; + const [filesNoHighPriority] = await bucket.getFiles({ + filter: absenceOfValuePair, + }); + + console.log( + `\nFiles matching absence of value pair [${absenceOfValuePair}]:` + ); + filesNoHighPriority.forEach(file => console.log(` - ${file.name}`)); + + /** + * List any object that does not have a context with the specified key attached. + * Syntax: -contexts."":* + */ + const absenceOfKey = '-contexts."team-owner":*'; + const [filesNoTeamOwner] = await bucket.getFiles({ + filter: absenceOfKey, + }); + + console.log( + `\nFiles matching absence of key regardless of value [${absenceOfKey}]:` + ); + filesNoTeamOwner.forEach(file => console.log(` - ${file.name}`)); + } + + listObjectContexts().catch(console.error); + // [END storage_list_object_contexts] +} + +main(...process.argv.slice(2)); diff --git a/storage/setObjectContexts.js b/storage/setObjectContexts.js new file mode 100644 index 0000000000..0557028133 --- /dev/null +++ b/storage/setObjectContexts.js @@ -0,0 +1,86 @@ +// Copyright 2026 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +'use strict'; + +// sample-metadata: +// title: Set Object Contexts +// description: Sets custom metadata (contexts) on an object. +// usage: node setObjectContexts.js + +/** + * This application demonstrates how to set, update, and delete object contexts (metadata) on a file + * in Google Cloud Storage. + */ + +function main(bucketName = 'my-bucket', fileName = 'test.txt') { + // [START storage_set_object_contexts] + /** + * TODO(developer): Uncomment the following lines before running the sample. + */ + // The ID of your GCS bucket + // const bucketName = 'your-unique-bucket-name'; + + // The ID of your GCS file + // const fileName = 'your-file-name'; + + // Imports the Google Cloud client library + const {Storage} = require('@google-cloud/storage'); + + // Creates a client + const storage = new Storage(); + + async function setObjectContexts() { + const file = storage.bucket(bucketName).file(fileName); + + // Create/Update Object Contexts + // Object Contexts live in the 'contexts' field, not the 'metadata' field. + const [metadata] = await file.setMetadata({ + contexts: { + custom: { + 'team-owner': {value: 'storage-team'}, + priority: {value: 'high'}, + }, + }, + }); + + console.log(`Updated Object Contexts for ${fileName}:`); + console.log(JSON.stringify(metadata.contexts, null, 2)); + + // Delete a specific key from the context: + // We send 'null' for the specific key we want to remove. + await file.setMetadata({ + contexts: { + custom: { + 'team-owner': null, + }, + }, + }); + console.log(`Deleted 'team-owner' key from contexts for ${fileName}.`); + + // Delete all keys from the context: + // We set the 'custom' property to null to wipe the entire map. + await file.setMetadata({ + contexts: { + custom: null, + }, + }); + console.log(`Cleared all custom contexts for ${fileName}.`); + } + + setObjectContexts().catch(console.error); + // [END storage_set_object_contexts] +} + +main(...process.argv.slice(2)); diff --git a/storage/system-test/files.test.js b/storage/system-test/files.test.js new file mode 100644 index 0000000000..17b1520100 --- /dev/null +++ b/storage/system-test/files.test.js @@ -0,0 +1,143 @@ +// Copyright 2019 Google LLC +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +'use strict'; + +const fs = require('fs'); +const path = require('path'); +const {Storage} = require('@google-cloud/storage'); +const {assert} = require('chai'); +const {before, after, it, describe} = require('mocha'); +const cp = require('child_process'); +const uuid = require('uuid'); +const {promisify} = require('util'); + +const execSync = cmd => cp.execSync(cmd, {encoding: 'utf-8'}); + +const storage = new Storage({ + projectId: process.env.GOOGLE_CLOUD_PROJECT, +}); +const cwd = path.join(__dirname, '..'); +const bucketName = generateName(); +const bucket = storage.bucket(bucketName); +const fileName = 'test.txt'; +const filePath = path.join(cwd, 'resources', fileName); +const downloadFilePath = path.join(cwd, 'downloaded.txt'); + +describe('file', () => { + before(async () => { + await bucket.create(); + }); + + after(async () => { + await promisify(fs.unlink)(downloadFilePath).catch(console.error); + // Try deleting all files twice, just to make sure + await bucket.deleteFiles({force: true}).catch(console.error); + await bucket.deleteFiles({force: true}).catch(console.error); + await bucket.delete().catch(console.error); + }); + + describe('Object Contexts', () => { + const contextFile = bucket.file(fileName); + + beforeEach(async () => { + await bucket.upload(filePath, {destination: fileName}); + + await contextFile.setMetadata({ + contexts: { + custom: { + 'team-owner': {value: 'storage-team'}, + priority: {value: 'high'}, + }, + }, + }); + }); + + it('should set object contexts', () => { + const output = execSync( + `node setObjectContexts.js ${bucketName} ${fileName}` + ); + // Verify Initial Creation + assert.include(output, `Updated Object Contexts for ${fileName}:`); + assert.include(output, '"team-owner":'); + assert.include(output, '"value": "storage-team"'); + assert.include(output, '"priority":'); + assert.include(output, '"value": "high"'); + assert.include(output, '"createTime":'); + assert.include(output, '"updateTime":'); + + // Verify Specific Key Deletion + assert.include( + output, + `Deleted 'team-owner' key from contexts for ${fileName}.` + ); + + // Verify Clearing All Contexts + assert.include(output, `Cleared all custom contexts for ${fileName}.`); + }); + + it('should get object contexts', () => { + const output = execSync( + `node getObjectContexts.js ${bucketName} ${fileName}` + ); + assert.include(output, `Object Contexts for ${fileName}:`); + assert.include(output, 'Key: priority'); + assert.include(output, 'Value: high'); + assert.include(output, 'Key: team-owner'); + assert.include(output, 'Value: storage-team'); + }); + + it('should list objects with context filters', async () => { + const noContextFileName = `no-context-${fileName}`; + await bucket.upload(filePath, {destination: noContextFileName}); + // Ensure it has no contexts + await bucket + .file(noContextFileName) + .setMetadata({contexts: {custom: null}}); + + const output = execSync(`node listObjectContexts.js ${bucketName}`); + + // Testing Existence of Value Pair (contexts."key"="val") + assert.include( + output, + 'Files matching filter [contexts."priority"="high"]' + ); + assert.include(output, ` - ${fileName}`); + + // Testing Existence of Key (contexts."key":*) + assert.include(output, 'Files with the "team-owner" context key'); + assert.include(output, ` - ${fileName}`); + + // Testing Absence of Value Pair (-contexts."key"="val") + assert.include( + output, + 'Files matching absence of value pair [-contexts."priority"="high"]' + ); + assert.include(output, ` - ${noContextFileName}`); + + // Testing Absence of Key (-contexts."key":*) + assert.include( + output, + 'Files matching absence of key regardless of value [-contexts."team-owner":*]' + ); + assert.include(output, ` - ${noContextFileName}`); + + await bucket.file(noContextFileName).delete(); + }); + }); +}); + +function generateName() { + return `nodejs-storage-samples-${uuid.v4()}`; +}