Announcing the stable release of the Azure SDK for Go

The Azure SDK for Go team at Microsoft is excited to announce the first wave of stable Azure SDK for Go client libraries. We’re releasing client libraries for Resource Management, Azure Tables, and Service Bus. The release includes azcore and azidentity modules that form the core infrastructure for client libraries. These two modules and autorest.go form the building blocks for future releases of Go client libraries.

The journey to a stable release

The Azure SDK for Go was incubated in the Go language team at Microsoft. The team grew along with the Go SDK journey and we’ve reached an important milestone today. During this journey, we focused on producing idiomatic, consistent, and diagnosable libraries for the Go community, empowering Go developers to interact with Azure. The packages evolved over time as we reacted to changes in the Go ecosystem and improved guidelines. We waited for key features such as Go’s generics and we addressed customer feedback to improve developer experience. We took the time to perfect the first version of Azure SDK for Go and hope you’ll love it as much as we do!

We want to thank everyone who helped us along this journey. Your feedback made this release possible and inspired us to design a better SDK. At Azure, we’re excited and committed to bring more languages to the Azure developer platform.

What’s next?

We’ll continue to expand the feature set in azcore, add more credential types to azidentity, add service packages, and expand upon Resource Manager packages. Client libraries for Key Vault, Cosmos DB, Storage, and App Configuration services are currently in beta. We hope to release stable versions in the coming months.

Get started

We have set up an entire section of content named Azure for Go developers. The content can help you to get started and learn core concepts of the Azure SDK for Go.

You can get the latest Azure SDK for Go libraries from pkg.go.dev or view the source code in the Azure SDK for Go repository on GitHub. A list of all Go modules with the latest versions is available on the Azure SDK Releases page. The Azure SDK for Go requires version 1.18 of Go, as it utilizes Go generics.

Common patterns

The SDK follows certain idiomatic patterns throughout its libraries. Some of those patterns are described in the following sections.

Credentials and Identity

The Azure Identity module, azidentity, provides Azure Active Directory (Azure AD) token authentication support across the Go SDK. You can import the module using its package name "github.com/Azure/azure-sdk-for-go/sdk/azidentity". After you’ve imported the azidentity module, you can use it to create a new credential to use throughout the lifecycle of your program. This module performs the authentication, obtains/renews an authentication token, and adds the token to network calls automatically. DefaultAzureCredential is the easiest way to start. This convenience credential type can read credentials from your environment. Alternatively, you can visit the Azure Identity | pkg.go.dev page for more credential types.

cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
  // handle error
}

// use cred for creating the client

Client

A client struct is the basic unit that lets you perform operations on a service. Depending on the library you choose, the client lets you perform service specific operations. For example, creating an Azure resource if you’re using a Resource Manager library or sending a message if you’re using the Service Bus library. Import the library using the package name "github.com/Azure/azure-sdk-for-go/sdk/<foo-library-group>/<foo>". For example, the package name for the Service Bus client library is "github.com/Azure/azure-sdk-for-go/sdk/messaging/azservicebus". You can choose to create the client using Azure AD credential.

serviceClient, err := foo.NewClient(<foo-identifier>, cred, <ClientOption-Struct>)
// ClientOption struct is used to define network call properties like retry etc. 
// If you want default behavior pass nil, e.g. foo.NewClient(<foo-identifier>, cred, nil)

Some of our services provide alternative methods of authentication, like connection strings or shared keys:

//Connection String
serviceClient, err := foo.NewClientFromConnectionString(connectionString, <ClientOption-Struct>)
if err != nil {
    panic(err)
}

cred, err := foo.NewSharedKeyCredential("<myAccountName>", "<myAccountKey>")
if err != nil {
    panic(err)
}
serviceClient, err := foo.NewClientWithSharedKey(<foo-identifier>, cred, <ClientOption-Struct>)
if err != nil {
    panic(err)
}

Once you’ve created a client, you can use it to perform desired operations on the service. For example, you can use the aztables library to create a table:

_, err := serviceClient.CreateTable(context.TODO(), "TableName", nil)
if err != nil {
    panic(err)
}

For more information on library-specific operations, see pkg.go.dev.

Pagers

Many Azure services return collections of items. Because the number of items can be large, the library methods return a new generic pager type runtime.Pager[T]. [T] denotes any type. This Pager allows your program to process one page of results at a time. You can use pager.More to determine if there are more result pages. Then use pager.NextPage to fetch the next result page. In this example, the Foo service returns a list of values.

serviceClient, err := foo.NewClient(<foo-identifier>, cred, nil)
ctx := context.TODO()
...

pager := serviceClient.NewListPager(<foo-specific-arguments>)
for pager.More() {
    nextResult, err := pager.NextPage(ctx)
    if err != nil {
        panic(err)
    }
    for _, v := range nextResult.Value {
        // do something with the value
        _ = v
    }
}

Long-running operations

Some operations on Azure can take a long time to complete—anywhere from a few seconds to a few days. Examples of such operations include copying data from a source URL to a storage blob or training an AI model to recognize forms. These long-running operations (LROs) don’t lend well to the standard HTTP flow of a relatively quick request and response. By convention, methods that start an LRO are prefixed with “Begin” and return a new generic poller type runtime.Poller[T]. The Poller is used to periodically poll the service until the operation finishes. You can use poller.PollUntilDone for synchronous behavior. PollUntilDone polls at a set interval until your task is finished. Alternatively, you can use poller.Poll, poller.Done, and poller.Result to implement your own logic.

serviceClient, err := foo.NewClient(<foo-identifier>, cred, nil)
ctx := context.TODO()
...

poller, err := client.BeginFooOperation(ctx, <foo-specific-arguments>)
if err != nil {
    panic(err)
}
res, err := poller.PollUntilDone(ctx, <PollUntilDoneOptions-struct>)
if err != nil {
    panic(err)
}
// PollUntilDoneOptions struct is used to define polling frequency, defaults to 30s
// If you want default behavior pass nil, e.g. poller.PollUntilDone(ctx, nil)

Logging

azcore module has an implementation of classification-based logging. To enable console logging for all SDK modules, set the environment variable AZURE_SDK_GO_LOGGING to all. Alternatively, use the azcore/log module to control log event output or to enable logs for specific events.

import (
  "fmt"
  azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
)

// print log output to stdout
azlog.SetListener(func(event azlog.Event, s string) {
    fmt.Printf("[%s] %sn", event, s)
    // or create your own format
})

// pick the set of events to log
azlog.SetEvents(
  foo.<EventConstant>,
  // EventConstant is a constant defined in the library check the library reference of available events
  foo.<EventConstant>,
)

Feedback

We would love to hear about your experiences using Azure SDK for Go. Send us your feedback on our Slack Channel or at the #golang-friends channel on Microsoft Open Source Discord Server.

For feature requests, bug reports, or general support, open an issue in the Azure SDK for Go repository on GitHub. For more information on how we triage issues, see the Azure SDK GitHub Issue Support Process.