Azure-docs: Blob Storage APIs sections sounds contradictory and confusing

[shraboin]

This section: https://docs.microsoft.com/en-us/azure/storage/blobs/data-lake-storage-known-issues#blob-storage-apis
Specifically this:
You cannot use both Blob APIs and Data Lake Storage APIs to write to the same instance of a file. If you write to a file by using Data Lake Storage Gen2 APIs, then that file's blocks won't be visible to calls to the Get Block List blob API. _You can overwrite a file by using either Data Lake Storage Gen2 APIs or Blob APIs_. This won't affect file properties.

Could be inferred multiple ways and confusing. Both bolded portions of text above contradict each other. Is the bold & italicized portion saying you can use either api for to overwrite a file regardless if it was made originally with Blob or Data Lake? Or is saying that you can overwrite using either api as long as api matches the api used when initially created e.g: if written via blob api then overwrite can be done via blob api & vice-versa. If it is the latter then it should be a seperate bullet or omitted entirely. If the former it should be clarified better. One example:

You cannot use both API & Data Lake Storage APIs to write to the same instance of a file. If you write to a file by using Data Lake Storage Gen2 APIs, then that file's blocks won't be visible to calls to the Get Block List blob API. The only exception is when using you are overwriting. You can overwrite a file/blob using either API.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 46d15a48-4780-edbb-4485-121f901cbac9
• Version Independent ID: fc65764c-2d2a-4901-5c31-82b4566bf3bc
• Content: Known issues with Azure Data Lake Storage Gen2
• Content Source: articles/storage/blobs/data-lake-storage-known-issues.md
• Service: storage
• Sub-service: data-lake-storage-gen2
• GitHub Login: @normesta
• Microsoft Alias: normesta

[KranthiPakala-MSFT]

@shraboin
Thank you for reaching out. At this time we are reviewing the ask and will provide an update as appropriate

[MartinJaffer-MSFT]

@shraboin sorry for the delay, I wanted to do a few tests to be sure my answer is current. The service has changed since I last tried.

In a gen2 account (with Heirarchical namespace), I created a container, and inside it I placed a pair of files in root, and a pair of files in a folder. Each pair consisted of an item uploaded via Set-AzStorageBlobContent and an item uploaded via New-AzDataLakeGen2Item.
Then I did a rest call (using Postman) https://XXXXX.blob.core.windows.net/XXXX?res=container&comp=list
I was able to see all items and the folder. Next I will test overwriting.

[MartinJaffer-MSFT]

Next I pointed at an item created as a gen2 item in the previous step. Except this time I use a call to https://xxxxx.blob.core.windows.net/xxxx/fol1/subGen2.txt. When I do a GET the file is read, but when I do a PUT to overwrite it, I get 404 not found.

Next I do similar, but pointing at an item created as blob in the previous step, and calling the dfs.core.windows.net endpoint for it. I am able to read with a GET. PUT overwrites (makes into an empty file). This is not to be confused with append operation.

After all this I can still list all the items.

[MartinJaffer-MSFT]

Thank you for asking me to look into this, @shraboin . Given the difference between my experience, and the document I highlighted, I will assign this to author for updating as appropriate.

[MartinJaffer-MSFT]

@normesta Could you please review this document for accuracy with respect to current behavior? The behaviors I have experienced do not match up with the documented behaviors. See above comments for my tests.

[shraboin]

@MartinJaffer-MSFT thanks for looking at this.

[MartinJaffer-MSFT]

Sorry for taking so long @shraboin . The service seems to have changed quite significantly since I last did a deep dive (maybe a couple months ago).

[normesta]

Thank you @shraboin. Yes, you're suggested text looks clearer. I've incorporated that into the content and it should appear live in the doc by tomorrow 10 AM. @MartinJaffer-MSFT - tested overwrite with both ADLSG2 and Blob APIs against both types of accounts (ADLSG2 and flat namespace). Overwrite works across APIs. Therefore, the content is correct. It's just not phrased optimally. @shraboin's phrasing is much clearer.

[normesta]

please-close