# README

Azure SDK for Go

azure-sdk-for-go provides Go packages for using Azure services. It has been tested with Go 1.8 and 1.9. To be notified about updates and changes, subscribe to the Azure update feed.

:exclamation: NOTE: This project is in preview and breaking changes are introduced frequently. Therefore, vendoring dependencies is even more important than usual. We use dep.

Install:

$ go get -u github.com/Azure/azure-sdk-for-go/...

or if you use dep (recommended), within your project run:

$ dep ensure -add github.com/Azure/azure-sdk-for-go

If you need to install Go, follow the official instructions.

Use:

For complete examples see Azure-Samples/azure-sdk-for-go-samples.

Import a package from the services directory.
Create and authenticate a client with a New*Client func, e.g. c := compute.NewVirtualMachinesClient(...).
Invoke API methods using the client, e.g. c.CreateOrUpdate(...).
Handle responses.

For example, to create a new virtual network (substitute your own values for strings in angle brackets):

import (
	"github.com/Azure/azure-sdk-for-go/services/network/mgmt/2017-09-01/network"
	"github.com/Azure/go-autorest/autorest"
	"github.com/Azure/go-autorest/autorest/to"
)

vnetClient := network.NewVirtualNetworksClient("<subscriptionID>")
vnetClient.Authorizer = autorest.NewBearerAuthorizer("<OAuthTokenProvider>")

vnetClient.CreateOrUpdate(
  "<resourceGroupName>",
  "<vnetName>",
  network.VirtualNetwork{
    Location: to.StringPtr("<azureRegion>"),
    VirtualNetworkPropertiesFormat: &network.VirtualNetworkPropertiesFormat{
      AddressSpace: &network.AddressSpace{
        AddressPrefixes: &[]string{"10.0.0.0/8"},
      },
      Subnets: &[]network.Subnet{
        {
          Name: to.StringPtr("<subnet1Name>"),
          SubnetPropertiesFormat: &network.SubnetPropertiesFormat{
            AddressPrefix: to.StringPtr("10.0.0.0/16"),
          },
        },
        {
          Name: to.StringPtr("<subnet2Name>"),
          SubnetPropertiesFormat: &network.SubnetPropertiesFormat{
            AddressPrefix: to.StringPtr("10.1.0.0/16"),
          },
        },
      },
    },
  },
  nil)

Authentication

Most operations require an OAuth token for authentication and authorization. You can get one from Azure AD using the adal package and a service principal as shown in the following example.

If you need to create a service principal (aka Client, App), run az ad sp create-for-rbac -n "<app_name>" in the azure-cli, see these docs for more info.

Copy the new principal's ID, secret, and tenant ID for use in your app, e.g. as follows:

import (
	"github.com/Azure/go-autorest/autorest/adal"
	"github.com/Azure/go-autorest/autorest/azure"
)

var (
	clientID =        "<service_principal_ID>"
	subscriptionID =  "<subscription_ID>"
	tenantID =        "<tenant_ID>"
	clientSecret =    "<service_principal_secret>"
)

func getServicePrincipalToken() (adal.OAuthTokenProvider, error) {
	config, err := adal.NewOAuthConfig(azure.PublicCloud.ActiveDirectoryEndpoint, tenantID)
	return adal.NewServicePrincipalToken(
		*oauthConfig,
		clientID,
		clientSecret,
		azure.PublicCloud.ResourceManagerEndpoint)
}

Background

Most packages in the SDK are generated from Azure API specs with Azure/autorest and Azure/autorest.go.

A list of available services and package import paths is in [SERVICES.md][].

Versioning

More info in the wiki

You'll need to consider both SDK and API versions when selecting your targets. The following will describe them one by one.

SDK versions are set with repository-wide tags. We try to adhere to semver, so although we've long moved past version zero, we continue to add -beta to versions because this package is still in preview.

Azure API versions are typically a date string of form yyyy-mm-dd[-preview|-beta]. Whatever SDK version you use, you must also specify an API version in your import path, for example:

import "github.com/Azure/azure-sdk-for-go/services/compute/mgmt/2016-03-01/compute"
import "github.com/Azure/azure-sdk-for-go/services/network/mgmt/2017-09-01/network"

For a list of all available services and versions see godoc or start with find ./services -type d -mindepth 3 within this repo.

Azure API profiles specify a subset of APIs and versions offered in specific Azure regions and Azure Stack. The 2017-03-09 profile is intended for use with Azure Stack and includes compatible Compute, Network, Storage and Group management APIs. You can use it as follows:

import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/compute/mgmt/compute"
import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/network/mgmt/network"
import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/resources/mgmt/..."
import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/storage/mgmt/storage"

We also provide two special profiles: latest and preview. These will always refer to the most recent stable or preview API versions for each service. For example, to automatically use the most recent Compute APIs, use one of the following imports:

import "github.com/Azure/azure-sdk-for-go/profiles/latest/compute/mgmt/compute"
import "github.com/Azure/azure-sdk-for-go/profiles/preview/compute/mgmt/compute"