Merge pull request #273864 from pauljewellmsft/devguide-go

Add blob developer guide content for Go

Author: v-dirichards

articles/storage/blobs/TOC.yml

@@ -559,7 +559,7 @@ items:
         href: storage-blob-dotnet-get-started.md
       - name: Authorize access from your application
         items:
-        - name: Azure Active Directory
+        - name: Microsoft Entra ID
           items:
           - name: Overview
             href: /dotnet/azure/sdk/authentication?toc=/azure/storage/blobs/toc.json&bc=/azure/storage/blobs/breadcrumb/toc.json
@@ -653,7 +653,7 @@ items:
         href: storage-blob-java-get-started.md
       - name: Authorize access from your application
         items:
-        - name: Azure Active Directory
+        - name: Microsoft Entra ID
           items:
           - name: Overview
             href: /azure/developer/java/sdk/identity?toc=/azure/storage/blobs/toc.json&bc=/azure/storage/blobs/breadcrumb/toc.json
@@ -733,7 +733,7 @@ items:
         href: storage-blob-javascript-get-started.md
       - name: Authorize access from your application
         items:
-        - name: Azure Active Directory
+        - name: Microsoft Entra ID
           items:
           - name: Overview
             href: /azure/developer/javascript/sdk/authentication/overview?toc=/azure/storage/blobs/toc.json&bc=/azure/storage/blobs/breadcrumb/toc.json
@@ -803,7 +803,7 @@ items:
         href: storage-blob-typescript-get-started.md
       - name: Authorize access from your application
         items:
-        - name: Azure Active Directory
+        - name: Microsoft Entra ID
           items:
           - name: Overview
             href: /azure/developer/javascript/sdk/authentication/overview?toc=/azure/storage/blobs/toc.json&bc=/azure/storage/blobs/breadcrumb/toc.json
@@ -871,7 +871,7 @@ items:
         href: storage-blob-python-get-started.md
       - name: Authorize access from your application
         items:
-        - name: Azure Active Directory
+        - name: Microsoft Entra ID
           items:
           - name: Overview
             href: /azure/developer/python/sdk/authentication-overview?toc=/azure/storage/blobs/toc.json&bc=/azure/storage/blobs/breadcrumb/toc.json
@@ -945,6 +945,42 @@ items:
           href: storage-retry-policy-python.md
         - name: Configure logging
           href: /azure/developer/python/sdk/azure-sdk-logging?toc=/azure/storage/blobs/toc.json&bc=/azure/storage/blobs/breadcrumb/toc.json
+    - name: Go
+      items:
+      - name: Get started
+        href: storage-blob-go-get-started.md
+      - name: Authorize access from your application
+        items:
+        - name: Microsoft Entra ID
+          items:
+          - name: Authentication in development environments
+            href: /azure/developer/go/azure-sdk-authentication?toc=/azure/storage/blobs/toc.json&bc=/azure/storage/blobs/breadcrumb/toc.json
+          - name: Authentication in Azure-hosted apps
+            href: /azure/developer/go/azure-sdk-authentication-managed-identity?toc=/azure/storage/blobs/toc.json&bc=/azure/storage/blobs/breadcrumb/toc.json
+          - name: Authentication with a service principal
+            href: /azure/developer/go/azure-sdk-authentication-service-principal?toc=/azure/storage/blobs/toc.json&bc=/azure/storage/blobs/breadcrumb/toc.json
+      - name: Container actions
+        items:
+        - name: Create a container
+          href: storage-blob-container-create-go.md
+        - name: Delete and restore containers
+          href: storage-blob-container-delete-go.md
+        - name: List containers
+          href: storage-blob-containers-list-go.md
+        - name: Manage properties and metadata
+          href: storage-blob-container-properties-metadata-go.md
+      - name: Blob actions
+        items:
+        - name: Upload blobs
+          href: storage-blob-upload-go.md
+        - name: Download blobs
+          href: storage-blob-download-go.md
+        - name: List blobs
+          href: storage-blobs-list-go.md
+        - name: Delete and restore blobs
+          href: storage-blob-delete-go.md
+        - name: Manage blob properties and metadata
+          href: storage-blob-properties-metadata-go.md
     - name: Test with a storage emulator
       items:
       - name: Use the Azurite open-source emulator

articles/storage/blobs/breadcrumb/toc.yml

@@ -23,4 +23,7 @@
       topicHref: /azure/storage/blobs/storage-blobs-introduction
     - name: Blobs
       tocHref: /azure/developer/java/sdk/
+      topicHref: /azure/storage/blobs/storage-blobs-introduction
+    - name: Blobs
+      tocHref: /azure/developer/go/
       topicHref: /azure/storage/blobs/storage-blobs-introduction

articles/storage/blobs/storage-blob-container-create-go.md

@@ -0,0 +1,74 @@
+---
+title: Create a blob container with Go
+titleSuffix: Azure Storage
+description: Learn how to create a blob container in your Azure Storage account using the Go client library.
+services: storage
+author: pauljewellmsft
+
+ms.service: azure-blob-storage
+ms.topic: how-to
+ms.date: 05/22/2024
+ms.author: pauljewell
+ms.devlang: golang
+ms.custom: devx-track-go, devguide-go
+---
+
+# Create a blob container with Go
+
+[!INCLUDE [storage-dev-guide-selector-create-container](../../../includes/storage-dev-guides/storage-dev-guide-selector-create-container.md)]
+
+This article shows how to create containers with the [Azure Storage client module for Go](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azblob#section-readme). Blobs in Azure Storage are organized into containers. Before you can upload a blob, you must first create a container.
+
+[!INCLUDE [storage-dev-guide-prereqs-go](../../../includes/storage-dev-guides/storage-dev-guide-prereqs-go.md)]
+
+## Set up your environment
+
+[!INCLUDE [storage-dev-guide-project-setup-go](../../../includes/storage-dev-guides/storage-dev-guide-project-setup-go.md)]
+
+#### Authorization
+
+The authorization mechanism must have the necessary permissions to create a container. For authorization with Microsoft Entra ID (recommended), you need Azure RBAC built-in role **Storage Blob Data Contributor** or higher. To learn more, see the authorization guidance for [Create Container (REST API)](/rest/api/storageservices/create-container#authorization).
+
+[!INCLUDE [storage-dev-guide-about-container-naming](../../../includes/storage-dev-guides/storage-dev-guide-about-container-naming.md)]
+
+## Create a container
+
+To create a container, call the following method:
+
+- [CreateContainer](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azblob#Client.CreateContainer)
+
+Containers are created immediately beneath the storage account. It's not possible to nest one container beneath another. An exception is thrown if a container with the same name already exists. 
+
+The following example shows how to create a container:
+
+:::code language="go" source="~/blob-devguide-go/cmd/create-container/create_container.go" id="snippet_create_container":::
+
+## Create the root container
+
+A root container serves as a default container for your storage account. Each storage account can have one root container, which must be named *$root*. The root container must be explicitly created or deleted.
+
+You can reference a blob stored in the root container without including the root container name. The root container enables you to reference a blob at the top level of the storage account hierarchy. For example, you can reference a blob in the root container as follows:
+
+`https://<storage-account-name>.blob.core.windows.net/default.html`
+
+The following example creates the container if it doesn't already exist in the storage account:
+
+:::code language="go" source="~/blob-devguide-go/cmd/create-container/create_container.go" id="snippet_create_root_container":::
+
+[!INCLUDE [storage-dev-guide-code-samples-note-go](../../../includes/storage-dev-guides/storage-dev-guide-code-samples-note-go.md)]
+
+## Resources
+
+To learn more about creating a container using the Azure Blob Storage client module for Go, see the following resources.
+
+### Code samples
+
+- View [code samples](https://github.com/Azure-Samples/blob-storage-devguide-go/blob/main/cmd/create-container/create_container.go) from this article (GitHub)
+
+### REST API operations
+
+The Azure SDK for Go contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar Go paradigms. The client library methods for creating a container use the following REST API operation:
+
+- [Create Container](/rest/api/storageservices/create-container) (REST API)
+
+[!INCLUDE [storage-dev-guide-resources-go](../../../includes/storage-dev-guides/storage-dev-guide-resources-go.md)]

articles/storage/blobs/storage-blob-container-delete-go.md

@@ -0,0 +1,76 @@
+---
+title: Delete and restore a blob container with Go
+titleSuffix: Azure Storage
+description: Learn how to delete and restore a blob container in your Azure Storage account using the Go client library.
+services: storage
+author: pauljewellmsft
+
+ms.service: azure-blob-storage
+ms.topic: how-to
+ms.date: 05/22/2024
+ms.author: pauljewell
+ms.devlang: golang
+ms.custom: devx-track-go, devguide-go
+---
+
+# Delete and restore a blob container with Go
+
+[!INCLUDE [storage-dev-guide-selector-delete-container](../../../includes/storage-dev-guides/storage-dev-guide-selector-delete-container.md)]
+
+This article shows how to delete containers with the [Azure Storage client module for Go](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azblob#section-readme). If you've enabled [container soft delete](soft-delete-container-overview.md), you can restore deleted containers.
+
+[!INCLUDE [storage-dev-guide-prereqs-go](../../../includes/storage-dev-guides/storage-dev-guide-prereqs-go.md)]
+
+## Set up your environment
+
+[!INCLUDE [storage-dev-guide-project-setup-go](../../../includes/storage-dev-guides/storage-dev-guide-project-setup-go.md)]
+
+#### Authorization
+
+The authorization mechanism must have the necessary permissions to delete or restore a container. For authorization with Microsoft Entra ID (recommended), you need Azure RBAC built-in role **Storage Blob Data Contributor** or higher. To learn more, see the authorization guidance for [Delete Container (REST API)](/rest/api/storageservices/delete-container#authorization) and [Restore Container (REST API)](/rest/api/storageservices/restore-container#authorization).
+
+## Delete a container
+
+To delete a container, call the following method:
+
+- [DeleteContainer](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azblob#Client.DeleteContainer)
+
+After you delete a container, you can't create a container with the same name for *at least* 30 seconds. Attempting to create a container with the same name fails with HTTP error code `409 (Conflict)`. Any other operations on the container or the blobs it contains fail with HTTP error code `404 (Not Found)`.
+
+The following example shows how to delete a specified container:
+
+:::code language="go" source="~/blob-devguide-go/cmd/delete-container/delete_container.go" id="snippet_delete_container":::
+
+## Restore a deleted container
+
+When container soft delete is enabled for a storage account, a deleted container and its contents can be recovered within a specified retention period. To learn more about container soft delete, see [Enable and manage soft delete for containers](soft-delete-container-enable.md). You can restore a soft-deleted container by calling the following method from the embedded [ServiceClient](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azblob#Client.ServiceClient) for the client object:
+
+- [RestoreContainer](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/service#Client.RestoreContainer)
+
+The following example lists containers, including soft-deleted containers, and iterates over the list to restore the specified soft-deleted container:
+
+:::code language="go" source="~/blob-devguide-go/cmd/delete-container/delete_container.go" id="snippet_restore_container":::
+
+[!INCLUDE [storage-dev-guide-code-samples-note-go](../../../includes/storage-dev-guides/storage-dev-guide-code-samples-note-go.md)]
+
+## Resources
+
+To learn more about deleting a container using the Azure Blob Storage client module for Go, see the following resources.
+
+### Code samples
+
+- View [code samples](https://github.com/Azure-Samples/blob-storage-devguide-go/blob/main/cmd/delete-container/delete_container.go) from this article (GitHub)
+
+### REST API operations
+
+The Azure SDK for Go contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar Go paradigms. The client library methods for deleting or restoring a container use the following REST API operations:
+
+- [Delete Container](/rest/api/storageservices/delete-container) (REST API)
+- [Restore Container](/rest/api/storageservices/restore-container) (REST API)
+
+[!INCLUDE [storage-dev-guide-resources-go](../../../includes/storage-dev-guides/storage-dev-guide-resources-go.md)]
+
+### See also
+
+- [Soft delete for containers](soft-delete-container-overview.md)
+- [Enable and manage soft delete for containers](soft-delete-container-enable.md)

articles/storage/blobs/storage-blob-container-properties-metadata-go.md

@@ -0,0 +1,90 @@
+---
+title: Use Go to manage properties and metadata for a blob container
+titleSuffix: Azure Storage
+description: Learn how to set and retrieve system properties and store custom metadata on blob containers in your Azure Storage account using the Go client library.
+services: storage
+author: pauljewellmsft
+
+ms.service: azure-blob-storage
+ms.topic: how-to
+ms.date: 05/22/2024
+ms.author: pauljewell
+ms.devlang: golang
+ms.custom: devx-track-go, devguide-go
+---
+
+# Manage container properties and metadata with Go
+
+[!INCLUDE [storage-dev-guide-selector-manage-properties-container](../../../includes/storage-dev-guides/storage-dev-guide-selector-manage-properties-container.md)]
+
+Blob containers support system properties and user-defined metadata, in addition to the data they contain. This article shows how to manage system properties and user-defined metadata with the [Azure Storage client module for Go](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azblob#section-readme).
+
+[!INCLUDE [storage-dev-guide-prereqs-go](../../../includes/storage-dev-guides/storage-dev-guide-prereqs-go.md)]
+
+## Set up your environment
+
+[!INCLUDE [storage-dev-guide-project-setup-go](../../../includes/storage-dev-guides/storage-dev-guide-project-setup-go.md)]
+
+#### Authorization
+
+The authorization mechanism must have the necessary permissions to work with container properties or metadata. For authorization with Microsoft Entra ID (recommended), you need Azure RBAC built-in role **Storage Blob Data Reader** or higher for the *get* operations, and **Storage Blob Data Contributor** or higher for the *set* operations. To learn more, see the authorization guidance for [Get Container Properties](/rest/api/storageservices/get-container-properties#authorization), [Set Container Metadata](/rest/api/storageservices/set-container-metadata#authorization), or [Get Container Metadata](/rest/api/storageservices/get-container-metadata#authorization).
+
+## About properties and metadata
+
+- **System properties**: System properties exist on each Blob Storage resource. Some of them can be read or set, while others are read-only. Behind the scenes, some system properties correspond to certain standard HTTP headers. The Azure Storage client library for Go maintains these properties for you.
+
+- **User-defined metadata**: User-defined metadata consists of one or more name-value pairs that you specify for a Blob storage resource. You can use metadata to store additional values with the resource. Metadata values are for your own purposes only, and don't affect how the resource behaves.
+
+    Metadata name/value pairs are valid HTTP headers and should adhere to all restrictions governing HTTP headers. For more information about metadata naming requirements, see [Metadata names](/rest/api/storageservices/naming-and-referencing-containers--blobs--and-metadata#metadata-names).
+
+## Retrieve container properties
+
+To retrieve container properties, call the following method from a container client object:
+
+- [GetProperties](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/container#Client.GetProperties)
+
+The following code example fetches a container's system properties and writes some of the property values to a console window:
+
+:::code language="go" source="~/blob-devguide-go/cmd/container-properties-metadata/container_properties_metadata.go" id="snippet_get_container_properties":::
+
+## Set and retrieve metadata
+
+You can specify metadata as one or more name-value pairs on a blob or container resource. To set metadata, call the following method from a container client object:
+
+- [SetMetadata](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/container#Client.SetMetadata)
+
+Setting container metadata overwrites all existing metadata associated with the container. It's not possible to modify an individual name-value pair.
+
+The following code example sets metadata on a container:
+
+:::code language="go" source="~/blob-devguide-go/cmd/container-properties-metadata/container_properties_metadata.go" id="snippet_set_container_metadata":::
+
+To retrieve metadata, call the following method from a container client object:
+
+- [GetProperties](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/storage/azblob/container#Client.GetProperties)
+
+Metadata is included in the response from `GetProperties`. The following example reads in metadata values and writes them to a console window: 
+
+:::code language="go" source="~/blob-devguide-go/cmd/container-properties-metadata/container_properties_metadata.go" id="snippet_get_container_metadata":::
+
+[!INCLUDE [storage-dev-guide-code-samples-note-go](../../../includes/storage-dev-guides/storage-dev-guide-code-samples-note-go.md)]
+
+## Resources
+
+To learn more about setting and retrieving container properties and metadata using the Azure Blob Storage client module for Go, see the following resources.
+
+### Code samples
+
+- View [code samples](https://github.com/Azure-Samples/blob-storage-devguide-go/blob/main/cmd/container-properties-metadata/container_properties_metadata.go) from this article (GitHub)
+
+### REST API operations
+
+The Azure SDK for Go contains libraries that build on top of the Azure REST API, allowing you to interact with REST API operations through familiar Go paradigms. The client library methods for setting and retrieving properties and metadata use the following REST API operations:
+
+- [Get Container Properties](/rest/api/storageservices/get-container-properties) (REST API)
+- [Set Container Metadata](/rest/api/storageservices/set-container-metadata) (REST API)
+- [Get Container Metadata](/rest/api/storageservices/get-container-metadata) (REST API)
+
+The `get_container_properties` method retrieves container properties and metadata by calling both the [Get Container Properties](/rest/api/storageservices/get-container-properties) operation and the [Get Container Metadata](/rest/api/storageservices/get-container-metadata) operation.
+
+[!INCLUDE [storage-dev-guide-resources-go](../../../includes/storage-dev-guides/storage-dev-guide-resources-go.md)]