Setting metadata seems really difficult to reason with.

I was just trying to set the metadata to files and frankly couldn’t figure out what was going on. I’m still not 100% but I think this invalid:

file.setMetadata({
  'example-key': 'example-value',
});

Instead it’s meant to be:

file.setMetadata({
  metadata: {
    'example-key': 'example-value',
  }
});

Reason being that custom metadata has to moved out of the top level set of metadata values.

If this is the case, I would love two changes made to the API to make this easy to reason with:

1. Enforce a strict check on the metadata value such that custom values cannot be used on the top level metadata object.
2. Bit of a stretch but I would like it Add a setCustomMetadata() method to avoid this weirdness around wrapping metadata with a metadata key.

[repentsinner]

I ran into this recently, and would suggest that rather than changing the APIs maybe just add an explicit user metadata sample for any of the contexts that support it? It’s very loosely hinted at in some of the existing samples such as https://github.com/googleapis/nodejs-storage/blob/master/samples/files.js#L257

The docs do touch on this as well (https://googleapis.dev/nodejs/storage/latest/File.html#setMetadata), but don’t explicitly call out that the nested nature of the term ‘metadata’ might be a gotcha for those unfamiliar with this. Perhaps some clearer wording to suggest that metadata.metadata can be considered as metadata.user_metadata or metadata.context_metadata, rather than GCS-specific metadata would help?

I’d also suggest that this file.js example that is embedded in the docs could be included in the samples directory for those of us who read docs as a last resort 😃 This code most clearly illustrates the difference between reserved GCS properties and custom properties.

[stephenplusplus]

It’s rare a complaint for this comes up, and since we’re stuck for ideas, maybe it’s just an uncommon, short-lived pain point?