mirror of
https://github.com/rclone/rclone.git
synced 2024-12-12 10:12:41 +01:00
90 lines
5.6 KiB
Go
90 lines
5.6 KiB
Go
// Copyright 2017 Microsoft Corporation. All rights reserved.
|
|
// Use of this source code is governed by an MIT
|
|
// license that can be found in the LICENSE file.
|
|
|
|
/*
|
|
Package azblob allows you to manipulate Azure Storage containers and blobs objects.
|
|
|
|
URL Types
|
|
|
|
The most common types you'll work with are the XxxURL types. The methods of these types make requests
|
|
against the Azure Storage Service.
|
|
|
|
- ServiceURL's methods perform operations on a storage account.
|
|
- ContainerURL's methods perform operations on an account's container.
|
|
- BlockBlobURL's methods perform operations on a container's block blob.
|
|
- AppendBlobURL's methods perform operations on a container's append blob.
|
|
- PageBlobURL's methods perform operations on a container's page blob.
|
|
- BlobURL's methods perform operations on a container's blob regardless of the blob's type.
|
|
|
|
Internally, each XxxURL object contains a URL and a request pipeline. The URL indicates the endpoint where each HTTP
|
|
request is sent and the pipeline indicates how the outgoing HTTP request and incoming HTTP response is processed.
|
|
The pipeline specifies things like retry policies, logging, deserialization of HTTP response payloads, and more.
|
|
|
|
Pipelines are threadsafe and may be shared by multiple XxxURL objects. When you create a ServiceURL, you pass
|
|
an initial pipeline. When you call ServiceURL's NewContainerURL method, the new ContainerURL object has its own
|
|
URL but it shares the same pipeline as the parent ServiceURL object.
|
|
|
|
To work with a blob, call one of ContainerURL's 4 NewXxxBlobURL methods depending on how you want to treat the blob.
|
|
To treat the blob as a block blob, append blob, or page blob, call NewBlockBlobURL, NewAppendBlobURL, or NewPageBlobURL
|
|
respectively. These three types are all identical except for the methods they expose; each type exposes the methods
|
|
relevant to the type of blob represented. If you're not sure how you want to treat a blob, you can call NewBlobURL;
|
|
this returns an object whose methods are relevant to any kind of blob. When you call ContainerURL's NewXxxBlobURL,
|
|
the new XxxBlobURL object has its own URL but it shares the same pipeline as the parent ContainerURL object. You
|
|
can easily switch between blob types (method sets) by calling a ToXxxBlobURL method.
|
|
|
|
If you'd like to use a different pipeline with a ServiceURL, ContainerURL, or XxxBlobURL object, then call the XxxURL
|
|
object's WithPipeline method passing in the desired pipeline. The WithPipeline methods create a new XxxURL object
|
|
with the same URL as the original but with the specified pipeline.
|
|
|
|
Note that XxxURL objects use little memory, are goroutine-safe, and many objects share the same pipeline. This means that
|
|
XxxURL objects share a lot of system resources making them very efficient.
|
|
|
|
All of XxxURL's methods that make HTTP requests return rich error handling information so you can discern network failures,
|
|
transient failures, timeout failures, service failures, etc. See the StorageError interface for more information and an
|
|
example of how to do deal with errors.
|
|
|
|
URL and Shared Access Signature Manipulation
|
|
|
|
The library includes a BlobURLParts type for deconstructing and reconstructing URLs. And you can use the following types
|
|
for generating and parsing Shared Access Signature (SAS)
|
|
- Use the AccountSASSignatureValues type to create a SAS for a storage account.
|
|
- Use the BlobSASSignatureValues type to create a SAS for a container or blob.
|
|
- Use the SASQueryParameters type to turn signature values in to query parameres or to parse query parameters.
|
|
|
|
To generate a SAS, you must use the SharedKeyCredential type.
|
|
|
|
Credentials
|
|
|
|
When creating a request pipeline, you must specify one of this package's credential types.
|
|
- Call the NewAnonymousCredential function for requests that contain a Shared Access Signature (SAS).
|
|
- Call the NewSharedKeyCredential function (with an account name & key) to access any account resources. You must also use this
|
|
to generate Shared Access Signatures.
|
|
|
|
HTTP Request Policy Factories
|
|
|
|
This package defines several request policy factories for use with the pipeline package.
|
|
Most applications will not use these factories directly; instead, the NewPipeline
|
|
function creates these factories, initializes them (via the PipelineOptions type)
|
|
and returns a pipeline object for use by the XxxURL objects.
|
|
|
|
However, for advanced scenarios, developers can access these policy factories directly
|
|
and even create their own and then construct their own pipeline in order to affect HTTP
|
|
requests and responses performed by the XxxURL objects. For example, developers can
|
|
introduce their own logging, random failures, request recording & playback for fast
|
|
testing, HTTP request pacing, alternate retry mechanisms, metering, metrics, etc. The
|
|
possibilities are endless!
|
|
|
|
Below are the request pipeline policy factory functions that are provided with this
|
|
package:
|
|
- NewRetryPolicyFactory Enables rich retry semantics for failed HTTP requests.
|
|
- NewRequestLogPolicyFactory Enables rich logging support for HTTP requests/responses & failures.
|
|
- NewTelemetryPolicyFactory Enables simple modification of the HTTP request's User-Agent header so each request reports the SDK version & language/runtime making the requests.
|
|
- NewUniqueRequestIDPolicyFactory Adds a x-ms-client-request-id header with a unique UUID value to an HTTP request to help with diagnosing failures.
|
|
|
|
Also, note that all the NewXxxCredential functions return request policy factory objects which get injected into the pipeline.
|
|
*/
|
|
package azblob
|
|
|
|
// TokenCredential Use this to access resources using Role-Based Access Control (RBAC).
|