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