1# Azure SDK for Go - Previous Versions
2
3This guide is for developers who are using the old versions of Azure Go SDK. Those SDKs are located under
4[services folder](https://github.com/Azure/azure-sdk-for-go/tree/master/services).
5
6## Package Updates
7
8Most packages in the SDK are generated from [Azure API specs][azure_rest_specs]
9using [Azure/autorest.go][] and [Azure/autorest][]. These generated packages
10depend on the HTTP client implemented at [Azure/go-autorest][].
11
12[azure_rest_specs]: https://github.com/Azure/azure-rest-api-specs
13[azure/autorest]: https://github.com/Azure/autorest
14[azure/autorest.go]: https://github.com/Azure/autorest.go
15[azure/go-autorest]: https://github.com/Azure/go-autorest
16
17The SDK codebase adheres to [semantic versioning](https://semver.org) and thus
18avoids breaking changes other than at major (x.0.0) releases. Because Azure's
19APIs are updated frequently, we release a **new major version at the end of
20each month** with a full changelog. For more details and background see [SDK Update
21Practices](https://github.com/Azure/azure-sdk-for-go/wiki/SDK-Update-Practices).
22
23To more reliably manage dependencies like the Azure SDK in your applications we
24recommend [golang/dep](https://github.com/golang/dep).
25
26Packages that are still in public preview can be found under the ./services/preview
27directory. Please be aware that since these packages are in preview they are subject
28to change, including breaking changes outside of a major semver bump.
29
30# Install and Use:
31
32## Install
33
34```sh
35$ go get -u github.com/Azure/azure-sdk-for-go/...
36```
37
38and you should also make sure to include the minimum version of [`go-autorest`](https://github.com/Azure/go-autorest) that is specified in `Gopkg.toml` file.
39
40Or if you use dep, within your repo run:
41
42```sh
43$ dep ensure -add github.com/Azure/azure-sdk-for-go
44```
45
46If you need to install Go, follow [the official instructions](https://golang.org/dl/).
47
48## Use
49
50For many more scenarios and examples see
51[Azure-Samples/azure-sdk-for-go-samples][samples_repo].
52
53Apply the following general steps to use packages in this repo. For more on
54authentication and the `Authorizer` interface see [the next
55section](#authentication).
56
571. Import a package from the [services][services_dir] directory.
582. Create and authenticate a client with a `New*Client` func, e.g.
59 `c := compute.NewVirtualMachinesClient(...)`.
603. Invoke API methods using the client, e.g.
61 `res, err := c.CreateOrUpdate(...)`.
624. Handle responses and errors.
63
64[services_dir]: https://github.com/Azure/azure-sdk-for-go/tree/master/services
65
66For example, to create a new virtual network (substitute your own values for
67strings in angle brackets):
68
69```go
70package main
71
72import (
73 "context"
74
75 "github.com/Azure/azure-sdk-for-go/services/network/mgmt/2017-09-01/network"
76
77 "github.com/Azure/go-autorest/autorest/azure/auth"
78 "github.com/Azure/go-autorest/autorest/to"
79)
80
81func main() {
82 // create a VirtualNetworks client
83 vnetClient := network.NewVirtualNetworksClient("<subscriptionID>")
84
85 // create an authorizer from env vars or Azure Managed Service Idenity
86 authorizer, err := auth.NewAuthorizerFromEnvironment()
87 if err == nil {
88 vnetClient.Authorizer = authorizer
89 }
90
91 // call the VirtualNetworks CreateOrUpdate API
92 vnetClient.CreateOrUpdate(context.Background(),
93 "<resourceGroupName>",
94 "<vnetName>",
95 network.VirtualNetwork{
96 Location: to.StringPtr("<azureRegion>"),
97 VirtualNetworkPropertiesFormat: &network.VirtualNetworkPropertiesFormat{
98 AddressSpace: &network.AddressSpace{
99 AddressPrefixes: &[]string{"10.0.0.0/8"},
100 },
101 Subnets: &[]network.Subnet{
102 {
103 Name: to.StringPtr("<subnet1Name>"),
104 SubnetPropertiesFormat: &network.SubnetPropertiesFormat{
105 AddressPrefix: to.StringPtr("10.0.0.0/16"),
106 },
107 },
108 {
109 Name: to.StringPtr("<subnet2Name>"),
110 SubnetPropertiesFormat: &network.SubnetPropertiesFormat{
111 AddressPrefix: to.StringPtr("10.1.0.0/16"),
112 },
113 },
114 },
115 },
116 })
117}
118```
119
120## Authentication
121
122Typical SDK operations must be authenticated and authorized. The _Authorizer_
123interface allows use of any auth style in requests, such as inserting an OAuth2
124Authorization header and bearer token received from Azure AD.
125
126The SDK itself provides a simple way to get an authorizer which first checks
127for OAuth client credentials in environment variables and then falls back to
128Azure's [Managed Service Identity](https://github.com/Azure/azure-sdk-for-go/) when available, e.g. when on an Azure
129VM. The following snippet from [the previous section](#use) demonstrates
130this helper.
131
132```go
133import "github.com/Azure/go-autorest/autorest/azure/auth"
134
135// create a VirtualNetworks client
136vnetClient := network.NewVirtualNetworksClient("<subscriptionID>")
137
138// create an authorizer from env vars or Azure Managed Service Idenity
139authorizer, err := auth.NewAuthorizerFromEnvironment()
140if err == nil {
141 vnetClient.Authorizer = authorizer
142}
143
144// call the VirtualNetworks CreateOrUpdate API
145vnetClient.CreateOrUpdate(context.Background(),
146// ...
147```
148
149The following environment variables help determine authentication configuration:
150
151- `AZURE_ENVIRONMENT`: Specifies the Azure Environment to use. If not set, it
152 defaults to `AzurePublicCloud`. Not applicable to authentication with Managed
153 Service Identity (MSI).
154- `AZURE_AD_RESOURCE`: Specifies the AAD resource ID to use. If not set, it
155 defaults to `ResourceManagerEndpoint` for operations with Azure Resource
156 Manager. You can also choose an alternate resource programmatically with
157 `auth.NewAuthorizerFromEnvironmentWithResource(resource string)`.
158
159### More Authentication Details
160
161The previous is the first and most recommended of several authentication
162options offered by the SDK because it allows seamless use of both service
163principals and [Azure Managed Service Identity][]. Other options are listed
164below.
165
166> Note: If you need to create a new service principal, run `az ad sp create-for-rbac -n "<app_name>" --role Contributor --scopes /subscriptions/<subscription_id>` in the
167> [azure-cli](https://github.com/Azure/azure-cli). See [these
168> docs](https://docs.microsoft.com/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest)
169> for more info. Copy the new principal's ID, secret, and tenant ID for use in
170> your app, or consider the `--sdk-auth` parameter for serialized output.
171
172[azure managed service identity]: https://docs.microsoft.com/azure/active-directory/msi-overview
173
174- The `auth.NewAuthorizerFromEnvironment()` described above creates an authorizer
175 from the first available of the following configuration:
176
177 1. **Client Credentials**: Azure AD Application ID and Secret.
178
179 - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate.
180 - `AZURE_CLIENT_ID`: Specifies the app client ID to use.
181 - `AZURE_CLIENT_SECRET`: Specifies the app secret to use.
182
183 2. **Client Certificate**: Azure AD Application ID and X.509 Certificate.
184
185 - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate.
186 - `AZURE_CLIENT_ID`: Specifies the app client ID to use.
187 - `AZURE_CERTIFICATE_PATH`: Specifies the certificate Path to use.
188 - `AZURE_CERTIFICATE_PASSWORD`: Specifies the certificate password to use.
189
190 3. **Resource Owner Password**: Azure AD User and Password. This grant type is *not
191 recommended*, use device login instead if you need interactive login.
192
193 - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate.
194 - `AZURE_CLIENT_ID`: Specifies the app client ID to use.
195 - `AZURE_USERNAME`: Specifies the username to use.
196 - `AZURE_PASSWORD`: Specifies the password to use.
197
198 4. **Azure Managed Service Identity**: Delegate credential management to the
199 platform. Requires that code is running in Azure, e.g. on a VM. All
200 configuration is handled by Azure. See [Azure Managed Service
201 Identity](https://docs.microsoft.com/azure/active-directory/msi-overview)
202 for more details.
203
204- The `auth.NewAuthorizerFromFile()` method creates an authorizer using
205 credentials from an auth file created by the [Azure CLI][]. Follow these
206 steps to utilize:
207
208 1. Create a service principal and output an auth file using `az ad sp create-for-rbac --role Contributor --scopes /subscriptions/<subscription_id> --sdk-auth > client_credentials.json`.
209 2. Set environment variable `AZURE_AUTH_LOCATION` to the path of the saved
210 output file.
211 3. Use the authorizer returned by `auth.NewAuthorizerFromFile()` in your
212 client as described above.
213
214- The `auth.NewAuthorizerFromCLI()` method creates an authorizer which
215 uses [Azure CLI][] to obtain its credentials.
216
217 The default audience being requested is `https://management.azure.com` (Azure ARM API).
218 To specify your own audience, export `AZURE_AD_RESOURCE` as an evironment variable.
219 This is read by `auth.NewAuthorizerFromCLI()` and passed to Azure CLI to acquire the access token.
220
221 For example, to request an access token for Azure Key Vault, export
222 ```
223 AZURE_AD_RESOURCE="https://vault.azure.net"
224 ```
225
226- `auth.NewAuthorizerFromCLIWithResource(AUDIENCE_URL_OR_APPLICATION_ID)` - this method is self contained and does
227 not require exporting environment variables. For example, to request an access token for Azure Key Vault:
228 ```
229 auth.NewAuthorizerFromCLIWithResource("https://vault.azure.net")
230 ```
231
232 To use `NewAuthorizerFromCLI()` or `NewAuthorizerFromCLIWithResource()`, follow these steps:
233
234 1. Install [Azure CLI v2.0.12](https://docs.microsoft.com/cli/azure/install-azure-cli) or later. Upgrade earlier versions.
235 2. Use `az login` to sign in to Azure.
236
237 If you receive an error, use `az account get-access-token` to verify access.
238
239 If Azure CLI is not installed to the default directory, you may receive an error
240 reporting that `az` cannot be found.
241 Use the `AzureCLIPath` environment variable to define the Azure CLI installation folder.
242
243 If you are signed in to Azure CLI using multiple accounts or your account has
244 access to multiple subscriptions, you need to specify the specific subscription
245 to be used. To do so, use:
246
247 ```
248 az account set --subscription <subscription-id>
249 ```
250
251 To verify the current account settings, use:
252
253 ```
254 az account list
255 ```
256
257[azure cli]: https://github.com/Azure/azure-cli
258
259- Finally, you can use OAuth's [Device Flow][] by calling
260 `auth.NewDeviceFlowConfig()` and extracting the Authorizer as follows:
261
262 ```go
263 config := auth.NewDeviceFlowConfig(clientID, tenantID)
264 a, err := config.Authorizer()
265 ```
266
267[device flow]: https://oauth.net/2/device-flow/
268
269# Versioning
270
271azure-sdk-for-go provides at least a basic Go binding for every Azure API. To
272provide maximum flexibility to users, the SDK even includes previous versions of
273Azure APIs which are still in use. This enables us to support users of the
274most updated Azure datacenters, regional datacenters with earlier APIs, and
275even on-premises installations of Azure Stack.
276
277**SDK versions** apply globally and are tracked by git
278[tags](https://github.com/Azure/azure-sdk-for-go/tags). These are in x.y.z form
279and generally adhere to [semantic versioning](https://semver.org) specifications.
280
281**Service API versions** are generally represented by a date string and are
282tracked by offering separate packages for each version. For example, to choose the
283latest API versions for Compute and Network, use the following imports:
284
285```go
286import (
287 "github.com/Azure/azure-sdk-for-go/services/compute/mgmt/2017-12-01/compute"
288 "github.com/Azure/azure-sdk-for-go/services/network/mgmt/2017-09-01/network"
289)
290```
291
292Occasionally service-side changes require major changes to existing versions.
293These cases are noted in the changelog, and for this reason `Service API versions`
294cannot be used alone to ensure backwards compatibility.
295
296All available services and versions are listed under the `services/` path in
297this repo and in [GoDoc][services_godoc]. Run `find ./services -type d -mindepth 3` to list all available service packages.
298
299[services_godoc]: https://godoc.org/github.com/Azure/azure-sdk-for-go/services
300
301### Profiles
302
303Azure **API profiles** specify subsets of Azure APIs and versions. Profiles can provide:
304
305- **stability** for your application by locking to specific API versions; and/or
306- **compatibility** for your application with Azure Stack and regional Azure datacenters.
307
308In the Go SDK, profiles are available under the `profiles/` path and their
309component API versions are aliases to the true service package under
310`services/`. You can use them as follows:
311
312```go
313import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/compute/mgmt/compute"
314import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/network/mgmt/network"
315import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/storage/mgmt/storage"
316```
317
318The following profiles are available for hybrid Azure and Azure Stack environments.
319- 2017-03-09
320- 2018-03-01
321
322In addition to versioned profiles, we also provide two special profiles
323`latest` and `preview`. The `latest` profile contains the latest API version
324of each service, excluding any preview versions and/or content. The `preview`
325profile is similar to the `latest` profile but includes preview API versions.
326
327The `latest` and `preview` profiles can help you stay up to date with API
328updates as you build applications. Since they are by definition not stable,
329however, they **should not** be used in production apps. Instead, choose the
330latest specific API version (or an older one if necessary) from the `services/`
331path.
332
333As an example, to automatically use the most recent Compute APIs, use one of
334the following imports:
335
336```go
337import "github.com/Azure/azure-sdk-for-go/profiles/latest/compute/mgmt/compute"
338import "github.com/Azure/azure-sdk-for-go/profiles/preview/compute/mgmt/compute"
339```
340
341### Avoiding Breaking Changes
342
343To avoid breaking changes, when specifying imports you should specify a `Service API Version` or `Profile`, as well as lock (using [dep](https://github.com/golang/dep) and soon with [Go Modules](https://github.com/golang/go/wiki/Modules)) to a specific SDK version.
344
345For example, in your source code imports, use a `Service API Version` (`2017-12-01`):
346
347```go
348import "github.com/Azure/azure-sdk-for-go/services/compute/mgmt/2017-12-01/compute"
349```
350
351or `Profile` version (`2017-03-09`):
352
353```go
354import "github.com/Azure/azure-sdk-for-go/profiles/2017-03-09/compute/mgmt/compute"
355```
356
357As well as, for dep, a `Gopkg.toml` file with:
358
359```toml
360[[constraint]]
361 name = "github.com/Azure/azure-sdk-for-go"
362 version = "21.0.0"
363```
364
365Combined, these techniques will ensure that breaking changes should not occur. If you are extra sensitive to changes, adding an additional [version pin](https://golang.github.io/dep/docs/Gopkg.toml.html#version-rules) in your SDK Version should satisfy your needs:
366
367```toml
368[[constraint]]
369 name = "github.com/Azure/azure-sdk-for-go"
370 version = "=21.3.0"
371```
372
373## Inspecting and Debugging
374
375### Built-in Basic Request/Response Logging
376
377Starting with `go-autorest v10.15.0` you can enable basic logging of requests and responses through setting environment variables.
378Setting `AZURE_GO_SDK_LOG_LEVEL` to `INFO` will log request/response without their bodies. To include the bodies set the log level to `DEBUG`.
379
380By default the logger writes to stderr, however it can also write to stdout or a file
381if specified in `AZURE_GO_SDK_LOG_FILE`. Note that if the specified file already exists it will be truncated.
382
383**IMPORTANT:** by default the logger will redact the Authorization and Ocp-Apim-Subscription-Key
384headers. Any other secrets will _not_ be redacted.
385
386### Writing Custom Request/Response Inspectors
387
388All clients implement some handy hooks to help inspect the underlying requests being made to Azure.
389
390- `RequestInspector`: View and manipulate the go `http.Request` before it's sent
391- `ResponseInspector`: View the `http.Response` received
392
393Here is an example of how these can be used with `net/http/httputil` to see requests and responses.
394
395```go
396vnetClient := network.NewVirtualNetworksClient("<subscriptionID>")
397vnetClient.RequestInspector = LogRequest()
398vnetClient.ResponseInspector = LogResponse()
399
400// ...
401
402func LogRequest() autorest.PrepareDecorator {
403 return func(p autorest.Preparer) autorest.Preparer {
404 return autorest.PreparerFunc(func(r *http.Request) (*http.Request, error) {
405 r, err := p.Prepare(r)
406 if err != nil {
407 log.Println(err)
408 }
409 dump, _ := httputil.DumpRequestOut(r, true)
410 log.Println(string(dump))
411 return r, err
412 })
413 }
414}
415
416func LogResponse() autorest.RespondDecorator {
417 return func(p autorest.Responder) autorest.Responder {
418 return autorest.ResponderFunc(func(r *http.Response) error {
419 err := p.Respond(r)
420 if err != nil {
421 log.Println(err)
422 }
423 dump, _ := httputil.DumpResponse(r, true)
424 log.Println(string(dump))
425 return err
426 })
427 }
428}
429```
430
431## Tracing and Metrics
432
433All packages and the runtime are instrumented using [OpenCensus](https://opencensus.io/).
434
435### Enable
436
437By default, no tracing provider will be compiled into your program, and the legacy approach of setting `AZURE_SDK_TRACING_ENABLED` environment variable will no longer take effect.
438
439To enable tracing, you must now add the following include to your source file.
440
441``` go
442import _ "github.com/Azure/go-autorest/tracing/opencensus"
443```
444
445To hook up a tracer simply call `tracing.Register()` passing in a type that satisfies the `tracing.Tracer` interface.
446
447**Note**: In future major releases of the SDK, tracing may become enabled by default.
448
449### Usage
450
451Once enabled, all SDK calls will emit traces and metrics and the traces will correlate the SDK calls with the raw http calls made to Azure API's. To consume those traces, if are not doing it yet, you need to register an exporter of your choice such as [Azure App Insights](https://docs.microsoft.com/azure/application-insights/opencensus-local-forwarder) or [Zipkin](https://opencensus.io/quickstart/go/tracing/#exporting-traces).
452
453To correlate the SDK calls between them and with the rest of your code, pass in a context that has a span initiated using the [opencensus-go library](https://github.com/census-instrumentation/opencensus-go) using the `trace.Startspan(ctx context.Context, name string, o ...StartOption)` function. Here is an example:
454
455```go
456func doAzureCalls() {
457 // The resulting context will be initialized with a root span as the context passed to
458 // trace.StartSpan() has no existing span.
459 ctx, span := trace.StartSpan(context.Background(), "doAzureCalls", trace.WithSampler(trace.AlwaysSample()))
460 defer span.End()
461
462 // The traces from the SDK calls will be correlated under the span inside the context that is passed in.
463 zone, _ := zonesClient.CreateOrUpdate(ctx, rg, zoneName, dns.Zone{Location: to.StringPtr("global")}, "", "")
464 zone, _ = zonesClient.Get(ctx, rg, *zone.Name)
465 for i := 0; i < rrCount; i++ {
466 rr, _ := recordsClient.CreateOrUpdate(ctx, rg, zoneName, fmt.Sprintf("rr%d", i), dns.CNAME, rdSet{
467 RecordSetProperties: &dns.RecordSetProperties{
468 TTL: to.Int64Ptr(3600),
469 CnameRecord: &dns.CnameRecord{
470 Cname: to.StringPtr("vladdbCname"),
471 },
472 },
473 },
474 "",
475 "",
476 )
477 }
478}
479```
480
481## Request Retry Policy
482
483The SDK provides a baked in retry policy for failed requests with default values that can be configured.
484Each [client](https://godoc.org/github.com/Azure/go-autorest/autorest#Client) object contains the follow fields.
485- `RetryAttempts` - the number of times to retry a failed request
486- `RetryDuration` - the duration to wait between retries
487
488For async operations the follow values are also used.
489- `PollingDelay` - the duration to wait between polling requests
490- `PollingDuration` - the total time to poll an async request before timing out
491
492Please see the [documentation](https://godoc.org/github.com/Azure/go-autorest/autorest#pkg-constants) for the default values used.
493
494Changing one or more values will affect all subsequet API calls.
495
496The default policy is to call `autorest.DoRetryForStatusCodes()` from an API's `Sender` method. Example:
497```go
498func (client OperationsClient) ListSender(req *http.Request) (*http.Response, error) {
499 sd := autorest.GetSendDecorators(req.Context(), autorest.DoRetryForStatusCodes(client.RetryAttempts, client.RetryDuration, autorest.StatusCodesForRetry...))
500 return autorest.SendWithSender(client, req, sd...)
501}
502```
503
504Details on how `autorest.DoRetryforStatusCodes()` works can be found in the [documentation](https://godoc.org/github.com/Azure/go-autorest/autorest#DoRetryForStatusCodes).
505
506The slice of `SendDecorators` used in a `Sender` method can be customized per API call by smuggling them in the context. Here's an example.
507
508```go
509ctx := context.Background()
510autorest.WithSendDecorators(ctx, []autorest.SendDecorator{
511 autorest.DoRetryForStatusCodesWithCap(client.RetryAttempts,
512 client.RetryDuration, time.Duration(0),
513 autorest.StatusCodesForRetry...)})
514client.List(ctx)
515```
516
517This will replace the default slice of `SendDecorators` with the provided slice.
518
519The `PollingDelay` and `PollingDuration` values are used exclusively by [WaitForCompletionRef()](https://godoc.org/github.com/Azure/go-autorest/autorest/azure#Future.WaitForCompletionRef) when blocking on an async call until it completes.
520
521# Resources
522
523- SDK docs are at [godoc.org](https://godoc.org/github.com/Azure/azure-sdk-for-go/).
524- SDK samples are at [Azure-Samples/azure-sdk-for-go-samples](https://github.com/Azure-Samples/azure-sdk-for-go-samples).
525- SDK notifications are published via the [Azure update feed](https://azure.microsoft.com/updates/).
526- Azure API docs are at [docs.microsoft.com/rest/api](https://docs.microsoft.com/rest/api/).
527- General Azure docs are at [docs.microsoft.com/azure](https://docs.microsoft.com/azure).
528
529## Reporting security issues and security bugs
530
531Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) <secure@microsoft.com>. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the [Security TechCenter](https://www.microsoft.com/msrc/faqs-report-an-issue).
View as plain text