{"id":2038,"date":"2022-05-20T13:11:27","date_gmt":"2022-05-20T20:11:27","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/azure-sdk\/?p=2038"},"modified":"2022-05-25T16:24:32","modified_gmt":"2022-05-25T23:24:32","slug":"announcing-the-stable-release-of-the-azure-sdk-for-go","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/azure-sdk\/announcing-the-stable-release-of-the-azure-sdk-for-go\/","title":{"rendered":"Announcing the stable release of the Azure SDK for Go"},"content":{"rendered":"

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<\/code> and azidentity<\/code> modules that form the core infrastructure for client libraries. These two modules and autorest.go<\/a> form the building blocks for future releases of Go client libraries.<\/p>\n

The journey to a stable release<\/h2>\n

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.\nThe 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!<\/p>\n

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.<\/p>\n

What’s next?<\/h2>\n

We’ll continue to expand the feature set in azcore<\/code>, add more credential types to azidentity<\/code>, 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.<\/p>\n

Get started<\/h2>\n

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

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

Common patterns<\/h2>\n

The SDK follows certain idiomatic patterns throughout its libraries. Some of those patterns are described in the following sections.<\/p>\n

Credentials and Identity<\/h3>\n

The Azure Identity module, azidentity<\/code>, 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\"<\/code>. After you’ve imported the azidentity<\/code> 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<\/code> 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<\/a> page for more credential types.<\/p>\n

cred, err := azidentity.NewDefaultAzureCredential(nil)\r\nif err != nil {\r\n  \/\/ handle error\r\n}\r\n\r\n\/\/ use cred for creating the client<\/code><\/pre>\n
Client<\/h3>\n
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>\"<\/code>. For example, the package name for the Service Bus client library is \"github.com\/Azure\/azure-sdk-for-go\/sdk\/messaging\/azservicebus\"<\/code>. You can choose to create the client using Azure AD credential.<\/p>\n
serviceClient, err := foo.NewClient(<foo-identifier>, cred, <ClientOption-Struct>)\r\n\/\/ ClientOption struct is used to define network call properties like retry etc. \r\n\/\/ If you want default behavior pass nil, e.g. foo.NewClient(<foo-identifier>, cred, nil)<\/code><\/pre>\n
Some of our services provide alternative methods of authentication, like connection strings or shared keys:<\/p>\n
\/\/Connection String\r\nserviceClient, err := foo.NewClientFromConnectionString(connectionString, <ClientOption-Struct>)\r\nif err != nil {\r\n    panic(err)\r\n}<\/code><\/pre>\n
cred, err := foo.NewSharedKeyCredential(\"<myAccountName>\", \"<myAccountKey>\")\r\nif err != nil {\r\n    panic(err)\r\n}\r\nserviceClient, err := foo.NewClientWithSharedKey(<foo-identifier>, cred, <ClientOption-Struct>)\r\nif err != nil {\r\n    panic(err)\r\n}<\/code><\/pre>\n
Once you’ve created a client, you can use it to perform desired operations on the service. For example, you can use the aztables<\/code> library to create a table:<\/p>\n
_, err := serviceClient.CreateTable(context.TODO(), \"TableName\", nil)\r\nif err != nil {\r\n    panic(err)\r\n}<\/code><\/pre>\n
For more information on library-specific operations, see pkg.go.dev<\/a>.<\/p>\n
Pagers<\/h3>\n
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]<\/code>. [T]<\/code> denotes any type. This Pager<\/code> allows your program to process one page of results at a time. You can use pager.More<\/code> to determine if there are more result pages. Then use pager.NextPage<\/code> to fetch the next result page. In this example, the Foo<\/code> service returns a list of values.<\/p>\n
serviceClient, err := foo.NewClient(<foo-identifier>, cred, nil)\r\nctx := context.TODO()\r\n...\r\n\r\npager := serviceClient.NewListPager(<foo-specific-arguments>)\r\nfor pager.More() {\r\n    nextResult, err := pager.NextPage(ctx)\r\n    if err != nil {\r\n        panic(err)\r\n    }\r\n    for _, v := range nextResult.Value {\r\n        \/\/ do something with the value\r\n        _ = v\r\n    }\r\n}<\/code><\/pre>\n
Long-running operations<\/h3>\n
Some operations on Azure can take a long time to complete\u2014anywhere 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.\nBy convention, methods that start an LRO are prefixed with “Begin” and return a new generic poller type runtime.Poller[T]<\/code>. The Poller is used to periodically poll the service until the operation finishes. You can use poller.PollUntilDone<\/code> for synchronous behavior. PollUntilDone<\/code> polls at a set interval until your task is finished. Alternatively, you can use poller.Poll<\/code>, poller.Done<\/code>, and poller.Result<\/code> to implement your own logic.<\/p>\n
serviceClient, err := foo.NewClient(<foo-identifier>, cred, nil)\r\nctx := context.TODO()\r\n...\r\n\r\npoller, err := client.BeginFooOperation(ctx, <foo-specific-arguments>)\r\nif err != nil {\r\n    panic(err)\r\n}\r\nres, err := poller.PollUntilDone(ctx, <PollUntilDoneOptions-struct>)\r\nif err != nil {\r\n    panic(err)\r\n}\r\n\/\/ PollUntilDoneOptions struct is used to define polling frequency, defaults to 30s\r\n\/\/ If you want default behavior pass nil, e.g. poller.PollUntilDone(ctx, nil)<\/code><\/pre>\n
Logging<\/h3>\n
azcore<\/code> module has an implementation of classification-based logging. To enable console logging for all SDK modules, set the environment variable AZURE_SDK_GO_LOGGING<\/code> to all<\/code>.\nAlternatively, use the azcore\/log<\/code> module to control log event output or to enable logs for specific events.<\/p>\n
import (\r\n  \"fmt\"\r\n  azlog \"github.com\/Azure\/azure-sdk-for-go\/sdk\/azcore\/log\"\r\n)\r\n\r\n\/\/ print log output to stdout\r\nazlog.SetListener(func(event azlog.Event, s string) {\r\n    fmt.Printf(\"[%s] %sn\", event, s)\r\n    \/\/ or create your own format\r\n})\r\n\r\n\/\/ pick the set of events to log\r\nazlog.SetEvents(\r\n  foo.<EventConstant>,\r\n  \/\/ EventConstant is a constant defined in the library check the library reference of available events\r\n  foo.<EventConstant>,\r\n)<\/code><\/pre>\n
Feedback<\/h2>\n
We would love to hear about your experiences using Azure SDK for Go. Send us your feedback on our Slack Channel<\/a> or at the #golang-friends<\/a> channel on Microsoft Open Source Discord Server.<\/p>\n
For feature requests, bug reports, or general support, open an issue<\/a> 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<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"
This post announces the stable release of the Azure SDK for Go.<\/p>\n","protected":false},"author":91679,"featured_media":2047,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[706,810,811,705],"class_list":["post-2038","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-azure-sdk","tag-azuresdk","tag-go","tag-golang","tag-sdk"],"acf":[],"blog_post_summary":"
This post announces the stable release of the Azure SDK for Go.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts\/2038","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/users\/91679"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/comments?post=2038"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/posts\/2038\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/media\/2047"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/media?parent=2038"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/categories?post=2038"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-json\/wp\/v2\/tags?post=2038"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}