docs: Clarify whether setMetadata is replacing existing metadata or updating only specified fields

From the NodeJS documentation, it is not clear enough whether calling file.setMetadata({contentType: 'image/png'}) would remove existing metadata fields on the field (as they are not specified) or would only change the content type.

To understand this, one must dig deeply into the NodeJS SDK to understand the exact behaviour and cross-reference it with the Cloud Storage API.

From my understanding, setMetadata is using PATCH, so any existing metadata would stay the same, correct?

--

Could we please update the documentation to make this clearer?

e.g. Set the metadata of the object. Uses PATCH method, meaning it only modifies passed fields and leaves unspecified fields unchanged.

nodejs-storage/src/nodejs-common/service-object.ts

Lines 477 to 485 in 57b28f1

    
             /** 
        
              * Set the metadata for this object. 
        
              * 
        
              * @param {object} metadata - The metadata to set on this object. 
        
              * @param {object=} options - Configuration options. 
        
              * @param {function=} callback - The callback function. 
        
              * @param {?error} callback.err - An error returned while making this request. 
        
              * @param {object} callback.apiResponse - The full API response. 
        
              */

And also mirror those function documentation to the File class method (as otherwise, the documentation will not be surfaced on the SDK API documentation page)
See: https://cloud.google.com/nodejs/docs/reference/storage/latest/storage/file#_google_cloud_storage_File_setMetadata_member_1_

Thanks for opening an issue. We are aware of a current documentation problem for some functions such as setMetadata where the full documentation is not being displayed. For example, what you are requesting is already present at:

nodejs-storage/src/file.ts

Lines 943 to 949 in 57b28f1

    
                  * Merge the given metadata with the current remote file's metadata. This 
        
                  * will set metadata if it was previously unset or update previously set 
        
                  * metadata. To unset previously set metadata, set its value to null. 
        
                  * 
        
                  * You can set custom key/value pairs in the metadata key of the given 
        
                  * object, however the other properties outside of this object must adhere 
        
                  * to the {@link https://goo.gl/BOnnCK| official API documentation}.

We are working to resolve the issue.

Navigation Menu

Repository navigation

docs: Clarify whether setMetadata is replacing existing metadata or updating only specified fields #2513

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	/**
	* Set the metadata for this object.
	*
	* @param {object} metadata - The metadata to set on this object.
	* @param {object=} options - Configuration options.
	* @param {function=} callback - The callback function.
	* @param {?error} callback.err - An error returned while making this request.
	* @param {object} callback.apiResponse - The full API response.
	*/

	* Merge the given metadata with the current remote file's metadata. This
	* will set metadata if it was previously unset or update previously set
	* metadata. To unset previously set metadata, set its value to null.
	*
	* You can set custom key/value pairs in the metadata key of the given
	* object, however the other properties outside of this object must adhere
	* to the {@link https://goo.gl/BOnnCK\| official API documentation}.

docs: Clarify whether setMetadata is replacing existing metadata or updating only specified fields #2513

Description

Activity

ddelgrosso1 commented on Aug 26, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions