To encode or not to encode path parts in GCS?

Question

Should path parts be encoded or not encoded when it comes to Google Cloud Storage?

Encoding URI path parts says they should be encoded, but Object names talks about the possibility of naming GCS objects in a seemingly-hierarchical manner...

So if I name an object abc/xyz, is the path to my object https://www.googleapis.com/storage/v1/b/example-bucket/o/abc%2fxyz or https://www.googleapis.com/storage/v1/b/example-bucket/o/abc/xyz?

Which is it!? Somebody please help me with this confusion.

Answer 1

TL;DR

You can use nested folders when working through a GCS client library but sending GET requests to the URL itself will need you to understand how to map the folder names appropriately.

Let's all pretend that folders are real

Yes, you need to encode the object names. There's a useful description here which I partially quote below (with my emphasis) for reference:

Object names reside in a flat namespace within a bucket, [...] means that objects do not reside within subdirectories in a bucket. For example, you can name an object /europe/france/paris.jpg to make it appear that paris.jpg resides in the subdirectory /europe/france, but to Cloud Storage, the object simply exists in the bucket and has the name /europe/france/paris.jpg.

So there are no subdirectories but appropriate naming and the use of a knowledgeable UI or API will make it appear as if there is some hierarchy.

All GCS client libraries will know to encode the names correctly but if you are running raw GETs on them (with appropriate authentication), you will have to do this yourself. The relevant section is here and I quote the most relevant part here:

For example, if you send a GET request for the object named foo/?bar in the bucket example-bucket, then your request URI should be:

GET https://www.googleapis.com/storage/v1/b/example-bucket/o/foo%2f%3fbar

So you can see that the object name part as been encoded with %2f for the slash (/) character. There's a more complete description of the naming convention here.

Metadata v Content using GCS JSON API

I was slightly surprised that the default behaviour for the API was to return metadata about the object in the bucket. To get the actual content I had to append '?alt=media' as described at the end of this section:

By default, this responds with an object resource in the response body. If you provide the URL parameter alt=media, then it will respond with the object data in the response body.