1// Copyright 2017 Microsoft Corporation. All rights reserved.
2// Use of this source code is governed by an MIT
3// license that can be found in the LICENSE file.
4
5/*
6Package azblob allows you to manipulate Azure Storage containers and blobs objects.
7
8URL Types
9
10The most common types you'll work with are the XxxURL types. The methods of these types make requests
11against the Azure Storage Service.
12
13 - ServiceURL's          methods perform operations on a storage account.
14    - ContainerURL's     methods perform operations on an account's container.
15       - BlockBlobURL's  methods perform operations on a container's block blob.
16       - AppendBlobURL's methods perform operations on a container's append blob.
17       - PageBlobURL's   methods perform operations on a container's page blob.
18       - BlobURL's       methods perform operations on a container's blob regardless of the blob's type.
19
20Internally, each XxxURL object contains a URL and a request pipeline. The URL indicates the endpoint where each HTTP
21request is sent and the pipeline indicates how the outgoing HTTP request and incoming HTTP response is processed.
22The pipeline specifies things like retry policies, logging, deserialization of HTTP response payloads, and more.
23
24Pipelines are threadsafe and may be shared by multiple XxxURL objects. When you create a ServiceURL, you pass
25an initial pipeline. When you call ServiceURL's NewContainerURL method, the new ContainerURL object has its own
26URL but it shares the same pipeline as the parent ServiceURL object.
27
28To work with a blob, call one of ContainerURL's 4 NewXxxBlobURL methods depending on how you want to treat the blob.
29To treat the blob as a block blob, append blob, or page blob, call NewBlockBlobURL, NewAppendBlobURL, or NewPageBlobURL
30respectively. These three types are all identical except for the methods they expose; each type exposes the methods
31relevant to the type of blob represented. If you're not sure how you want to treat a blob, you can call NewBlobURL;
32this returns an object whose methods are relevant to any kind of blob. When you call ContainerURL's NewXxxBlobURL,
33the new XxxBlobURL object has its own URL but it shares the same pipeline as the parent ContainerURL object. You
34can easily switch between blob types (method sets) by calling a ToXxxBlobURL method.
35
36If you'd like to use a different pipeline with a ServiceURL, ContainerURL, or XxxBlobURL object, then call the XxxURL
37object's WithPipeline method passing in the desired pipeline. The WithPipeline methods create a new XxxURL object
38with the same URL as the original but with the specified pipeline.
39
40Note that XxxURL objects use little memory, are goroutine-safe, and many objects share the same pipeline. This means that
41XxxURL objects share a lot of system resources making them very efficient.
42
43All of XxxURL's methods that make HTTP requests return rich error handling information so you can discern network failures,
44transient failures, timeout failures, service failures, etc. See the StorageError interface for more information and an
45example of how to do deal with errors.
46
47URL and Shared Access Signature Manipulation
48
49The library includes a BlobURLParts type for deconstructing and reconstructing URLs. And you can use the following types
50for generating and parsing Shared Access Signature (SAS)
51 - Use the AccountSASSignatureValues type to create a SAS for a storage account.
52 - Use the BlobSASSignatureValues type to create a SAS for a container or blob.
53 - Use the SASQueryParameters type to turn signature values in to query parameres or to parse query parameters.
54
55To generate a SAS, you must use the SharedKeyCredential type.
56
57Credentials
58
59When creating a request pipeline, you must specify one of this package's credential types.
60 - Call the NewAnonymousCredential function for requests that contain a Shared Access Signature (SAS).
61 - Call the NewSharedKeyCredential function (with an account name & key) to access any account resources. You must also use this
62   to generate Shared Access Signatures.
63
64HTTP Request Policy Factories
65
66This package defines several request policy factories for use with the pipeline package.
67Most applications will not use these factories directly; instead, the NewPipeline
68function creates these factories, initializes them (via the PipelineOptions type)
69and returns a pipeline object for use by the XxxURL objects.
70
71However, for advanced scenarios, developers can access these policy factories directly
72and even create their own and then construct their own pipeline in order to affect HTTP
73requests and responses performed by the XxxURL objects. For example, developers can
74introduce their own logging, random failures, request recording & playback for fast
75testing, HTTP request pacing, alternate retry mechanisms, metering, metrics, etc. The
76possibilities are endless!
77
78Below are the request pipeline policy factory functions that are provided with this
79package:
80 - NewRetryPolicyFactory           Enables rich retry semantics for failed HTTP requests.
81 - NewRequestLogPolicyFactory      Enables rich logging support for HTTP requests/responses & failures.
82 - NewTelemetryPolicyFactory       Enables simple modification of the HTTP request's User-Agent header so each request reports the SDK version & language/runtime making the requests.
83 - NewUniqueRequestIDPolicyFactory Adds a x-ms-client-request-id header with a unique UUID value to an HTTP request to help with diagnosing failures.
84
85Also, note that all the NewXxxCredential functions return request policy factory objects which get injected into the pipeline.
86*/
87package azblob
88
89// 	TokenCredential     Use this to access resources using Role-Based Access Control (RBAC).
90