[BUG] Misleading NIO URI format documentation #39579
Labels
Client
This issue points to a problem in the data-plane of the library.
customer-reported
Issues that are reported by GitHub users external to the Azure organization.
needs-team-attention
This issue needs attention from Azure service team or SDK team
question
The issue doesn't require a change to the product in order to be resolved. Most issues start as that
Storage
Storage Service (Queues, Blobs, Files)
Describe the bug
Not really a bug. More a documentation issue, although some additional validation of azb: URI's might help.
The README for NIO documents the URI format as azb://?endpoint=storage-account-name.blob.core.windows.net. It's very easy to think you should create a URI of the form azb://container-name:/path/to/file?endpoint=... This is technically wrong because the container name is in the host name spot and not the first element of the path. However, this works, but only if the file being referenced is in the first container in the list of containers passed to the newFileSystem call when the Azure file system is initialized. The file system will happily create azb://second-container-name:/path/to/another/file?endpoint=... as a path, but that path won't work. It only works if the URI is of the form azb:/second-container-name:/path/to/another/file?endpoint=...
Code Snippet
Add the code snippet that causes the issue.
where azure_containers is something like `"container1,container2"
Then:
but
whereas:
Expected behavior
Naively reading the docs for NIO, I'd expect both .exists tests to return true. If I use a single slash after the scheme, it works as expected, but the docs example shows 2 slashes. It does say that the container name has to be the first element of the URI path, but that's a little bit subtle. Some warning that double slashes after the azb: scheme are not needed, and could be harmful would be helpful.
Setup (please complete the following information):
I
The text was updated successfully, but these errors were encountered: