storage

package
v2.3.0-rc.2+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 28, 2016 License: Apache-2.0, Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package storage contains a Google Cloud Storage client.

This package is experimental and may make backwards-incompatible changes.

Example (Auth) 
package main

import (
	"io/ioutil"
	"log"

	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
	"google.golang.org/cloud"
	"google.golang.org/cloud/storage"
)

func main() context.Context {
	// Initialize an authorized context with Google Developers Console
	// JSON key. Read the google package examples to learn more about
	// different authorization flows you can use.
	// http://godoc.org/golang.org/x/oauth2/google
	jsonKey, err := ioutil.ReadFile("/path/to/json/keyfile.json")
	if err != nil {
		log.Fatal(err)
	}
	conf, err := google.JWTConfigFromJSON(
		jsonKey,
		storage.ScopeFullControl,
	)
	if err != nil {
		log.Fatal(err)
	}
	ctx := cloud.NewContext("project-id", conf.Client(oauth2.NoContext))
	// Use the context (see other examples)
	return ctx
}

Output:

Index

Examples

Constants

View Source 
const (
	// ScopeFullControl grants permissions to manage your
	// data and permissions in Google Cloud Storage.
	ScopeFullControl = raw.DevstorageFullControlScope

	// ScopeReadOnly grants permissions to
	// view your data in Google Cloud Storage.
	ScopeReadOnly = raw.DevstorageReadOnlyScope

	// ScopeReadWrite grants permissions to manage your
	// data in Google Cloud Storage.
	ScopeReadWrite = raw.DevstorageReadWriteScope
)

Variables

View Source 
var (
	ErrBucketNotExist = errors.New("storage: bucket doesn't exist")
	ErrObjectNotExist = errors.New("storage: object doesn't exist")
)

Functions

func DeleteACLRule 

func DeleteACLRule(ctx context.Context, bucket, object string, entity ACLEntity) error

DeleteACLRule deletes the named ACL entity for the named object.

func DeleteBucketACLRule 

func DeleteBucketACLRule(ctx context.Context, bucket string, entity ACLEntity) error

DeleteBucketACLRule deletes the named ACL entity for the named bucket.

func DeleteDefaultACLRule 

func DeleteDefaultACLRule(ctx context.Context, bucket string, entity ACLEntity) error

DeleteDefaultACLRule deletes the named default ACL entity for the named bucket.

func DeleteObject 

func DeleteObject(ctx context.Context, bucket, name string) error

DeleteObject deletes the single specified object.

Example 
package main

import (
	"io/ioutil"
	"log"

	"golang.org/x/net/context"
	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
	"google.golang.org/cloud"
	"google.golang.org/cloud/storage"
)

func Example_auth() context.Context {

	jsonKey, err := ioutil.ReadFile("/path/to/json/keyfile.json")
	if err != nil {
		log.Fatal(err)
	}
	conf, err := google.JWTConfigFromJSON(
		jsonKey,
		storage.ScopeFullControl,
	)
	if err != nil {
		log.Fatal(err)
	}
	ctx := cloud.NewContext("project-id", conf.Client(oauth2.NoContext))

	return ctx
}

func main() {
	// To delete multiple objects in a bucket, first ListObjects then delete them.
	ctx := Example_auth()

	// If you are using this package on App Engine Managed VMs runtime,
	// you can init a bucket client with your app's default bucket name.
	// See http://godoc.org/google.golang.org/appengine/file#DefaultBucketName.
	const bucket = "bucketname"

	var query *storage.Query // Set up query as desired.
	for {
		objects, err := storage.ListObjects(ctx, bucket, query)
		if err != nil {
			log.Fatal(err)
		}
		for _, obj := range objects.Results {
			log.Printf("deleting object name: %q, size: %v", obj.Name, obj.Size)
			if err := storage.DeleteObject(ctx, bucket, obj.Name); err != nil {
				log.Fatalf("unable to delete %q: %v", obj.Name, err)
			}
		}
		// if there are more results, objects.Next will be non-nil.
		query = objects.Next
		if query == nil {
			break
		}
	}

	log.Println("deleted all object items in the bucket you specified.")
}

Output:

func NewReader 

func NewReader(ctx context.Context, bucket, name string) (io.ReadCloser, error)

NewReader creates a new io.ReadCloser to read the contents of the object.

Example 
package main

import (
	"io/ioutil"
	"log"

	"golang.org/x/net/context"
	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
	"google.golang.org/cloud"
	"google.golang.org/cloud/storage"
)

func Example_auth() context.Context {

	jsonKey, err := ioutil.ReadFile("/path/to/json/keyfile.json")
	if err != nil {
		log.Fatal(err)
	}
	conf, err := google.JWTConfigFromJSON(
		jsonKey,
		storage.ScopeFullControl,
	)
	if err != nil {
		log.Fatal(err)
	}
	ctx := cloud.NewContext("project-id", conf.Client(oauth2.NoContext))

	return ctx
}

func main() {
	ctx := Example_auth()

	rc, err := storage.NewReader(ctx, "bucketname", "filename1")
	if err != nil {
		log.Fatal(err)
	}
	slurp, err := ioutil.ReadAll(rc)
	rc.Close()
	if err != nil {
		log.Fatal(err)
	}

	log.Println("file contents:", slurp)
}

Output:

func PutACLRule 

func PutACLRule(ctx context.Context, bucket, object string, entity ACLEntity, role ACLRole) error

PutACLRule saves the named ACL entity with the provided role for the named object.

func PutBucketACLRule 

func PutBucketACLRule(ctx context.Context, bucket string, entity ACLEntity, role ACLRole) error

PutBucketACLRule saves the named ACL entity with the provided role for the named bucket.

func PutDefaultACLRule 

func PutDefaultACLRule(ctx context.Context, bucket string, entity ACLEntity, role ACLRole) error

PutDefaultACLRule saves the named default object ACL entity with the provided role for the named bucket.

func SignedURL 

func SignedURL(bucket, name string, opts *SignedURLOptions) (string, error)

SignedURL returns a URL for the specified object. Signed URLs allow the users access to a restricted resource for a limited time without having a Google account or signing in. For more information about the signed URLs, see https://cloud.google.com/storage/docs/accesscontrol#Signed-URLs.

Types

type ACLEntity 

type ACLEntity string

ACLEntity is an entity holding an ACL permission.

It could be in the form of: "user-<userId>", "user-<email>","group-<groupId>", "group-<email>", "domain-<domain>" and "project-team-<projectId>".

Or one of the predefined constants: AllUsers, AllAuthenticatedUsers. 

const (
	AllUsers              ACLEntity = "allUsers"
	AllAuthenticatedUsers ACLEntity = "allAuthenticatedUsers"
)

type ACLRole 

type ACLRole string

ACLRole is the the access permission for the entity. 

const (
	RoleOwner  ACLRole = "OWNER"
	RoleReader ACLRole = "READER"
)

type ACLRule 

type ACLRule struct {
	// Entity identifies the entity holding the current rule's permissions.
	Entity ACLEntity

	// Role is the the access permission for the entity.
	Role ACLRole
}

ACLRule represents an access control list rule entry for a Google Cloud Storage object or bucket. A bucket is a Google Cloud Storage container whose name is globally unique and contains zero or more objects. An object is a blob of data that is stored in a bucket.

func ACL 

func ACL(ctx context.Context, bucket, object string) ([]ACLRule, error)

ACL returns the ACL entries for the named object.

func BucketACL 

func BucketACL(ctx context.Context, bucket string) ([]ACLRule, error)

BucketACL returns the ACL entries for the named bucket.

func DefaultACL 

func DefaultACL(ctx context.Context, bucket string) ([]ACLRule, error)

DefaultACL returns the default object ACL entries for the named bucket.

type Bucket 

type Bucket struct {
	// Name is the name of the bucket.
	Name string

	// ACL is the list of access control rules on the bucket.
	ACL []ACLRule

	// DefaultObjectACL is the list of access controls to
	// apply to new objects when no object ACL is provided.
	DefaultObjectACL []ACLRule

	// Location is the location of the bucket. It defaults to "US".
	Location string

	// Metageneration is the metadata generation of the bucket.
	// Read-only.
	Metageneration int64

	// StorageClass is the storage class of the bucket. This defines
	// how objects in the bucket are stored and determines the SLA
	// and the cost of storage. Typical values are "STANDARD" and
	// "DURABLE_REDUCED_AVAILABILITY". Defaults to "STANDARD".
	StorageClass string

	// Created is the creation time of the bucket.
	// Read-only.
	Created time.Time
}

Bucket represents a Google Cloud Storage bucket.

func BucketInfo 

func BucketInfo(ctx context.Context, name string) (*Bucket, error)

BucketInfo returns the metadata for the specified bucket.

type Object 

type Object struct {
	// Bucket is the name of the bucket containing this GCS object.
	Bucket string

	// Name is the name of the object within the bucket.
	Name string

	// ContentType is the MIME type of the object's content.
	ContentType string

	// ContentLanguage is the content language of the object's content.
	ContentLanguage string

	// CacheControl is the Cache-Control header to be sent in the response
	// headers when serving the object data.
	CacheControl string

	// ACL is the list of access control rules for the object.
	ACL []ACLRule

	// Owner is the owner of the object.
	//
	// If non-zero, it is in the form of "user-<userId>".
	Owner string

	// Size is the length of the object's content.
	Size int64

	// ContentEncoding is the encoding of the object's content.
	ContentEncoding string

	// MD5 is the MD5 hash of the object's content.
	MD5 []byte

	// CRC32C is the CRC32 checksum of the object's content using
	// the Castagnoli93 polynomial.
	CRC32C uint32

	// MediaLink is an URL to the object's content.
	MediaLink string

	// Metadata represents user-provided metadata, in key/value pairs.
	// It can be nil if no metadata is provided.
	Metadata map[string]string

	// Generation is the generation number of the object's content.
	Generation int64

	// MetaGeneration is the version of the metadata for this
	// object at this generation. This field is used for preconditions
	// and for detecting changes in metadata. A metageneration number
	// is only meaningful in the context of a particular generation
	// of a particular object.
	MetaGeneration int64

	// StorageClass is the storage class of the bucket.
	// This value defines how objects in the bucket are stored and
	// determines the SLA and the cost of storage. Typical values are
	// "STANDARD" and "DURABLE_REDUCED_AVAILABILITY".
	// It defaults to "STANDARD".
	StorageClass string

	// Deleted is the time the object was deleted.
	// If not deleted, it is the zero value.
	Deleted time.Time

	// Updated is the creation or modification time of the object.
	// For buckets with versioning enabled, changing an object's
	// metadata does not change this property.
	Updated time.Time
}

Object represents a Google Cloud Storage (GCS) object.

func CopyObject 

func CopyObject(ctx context.Context, srcBucket, srcName string, destBucket, destName string, attrs *ObjectAttrs) (*Object, error)

CopyObject copies the source object to the destination. The copied object's attributes are overwritten by attrs if non-nil.

Example 
package main

import (
	"io/ioutil"
	"log"

	"golang.org/x/net/context"
	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
	"google.golang.org/cloud"
	"google.golang.org/cloud/storage"
)

func Example_auth() context.Context {

	jsonKey, err := ioutil.ReadFile("/path/to/json/keyfile.json")
	if err != nil {
		log.Fatal(err)
	}
	conf, err := google.JWTConfigFromJSON(
		jsonKey,
		storage.ScopeFullControl,
	)
	if err != nil {
		log.Fatal(err)
	}
	ctx := cloud.NewContext("project-id", conf.Client(oauth2.NoContext))

	return ctx
}

func main() {
	ctx := Example_auth()

	o, err := storage.CopyObject(ctx, "bucketname", "file1", "another-bucketname", "file2", nil)
	if err != nil {
		log.Fatal(err)
	}
	log.Println("copied file:", o)
}

Output:

func StatObject 

func StatObject(ctx context.Context, bucket, name string) (*Object, error)

StatObject returns meta information about the specified object.

func UpdateAttrs 

func UpdateAttrs(ctx context.Context, bucket, name string, attrs ObjectAttrs) (*Object, error)

UpdateAttrs updates an object with the provided attributes. All zero-value attributes are ignored.

type ObjectAttrs 

type ObjectAttrs struct {
	// Name is the name of the object.
	Name string

	// ContentType is the MIME type of the object's content.
	// Optional.
	ContentType string

	// ContentLanguage is the optional RFC 1766 Content-Language of
	// the object's content sent in response headers.
	ContentLanguage string

	// ContentEncoding is the optional Content-Encoding of the object
	// sent it the response headers.
	ContentEncoding string

	// CacheControl is the optional Cache-Control header of the object
	// sent in the response headers.
	CacheControl string

	// ContentDisposition is the optional Content-Disposition header of the object
	// sent in the response headers.
	ContentDisposition string

	// ACL is the list of access control rules for the object.
	// Optional. If nil or empty, existing ACL rules are preserved.
	ACL []ACLRule

	// Metadata represents user-provided metadata, in key/value pairs.
	// It can be nil if the current metadata values needs to preserved.
	Metadata map[string]string
}

ObjectAttrs is the user-editable object attributes.

type Objects 

type Objects struct {
	// Results represent a list of object results.
	Results []*Object

	// Next is the continuation query to retrieve more
	// results with the same filtering criteria. If there
	// are no more results to retrieve, it is nil.
	Next *Query

	// Prefixes represents prefixes of objects
	// matching-but-not-listed up to and including
	// the requested delimiter.
	Prefixes []string
}

Objects represents a list of objects returned from a bucket look-p request and a query to retrieve more objects from the next pages.

func ListObjects 

func ListObjects(ctx context.Context, bucket string, q *Query) (*Objects, error)

ListObjects lists objects from the bucket. You can specify a query to filter the results. If q is nil, no filtering is applied.

Example 
package main

import (
	"io/ioutil"
	"log"

	"golang.org/x/net/context"
	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
	"google.golang.org/cloud"
	"google.golang.org/cloud/storage"
)

func Example_auth() context.Context {

	jsonKey, err := ioutil.ReadFile("/path/to/json/keyfile.json")
	if err != nil {
		log.Fatal(err)
	}
	conf, err := google.JWTConfigFromJSON(
		jsonKey,
		storage.ScopeFullControl,
	)
	if err != nil {
		log.Fatal(err)
	}
	ctx := cloud.NewContext("project-id", conf.Client(oauth2.NoContext))

	return ctx
}

func main() {
	ctx := Example_auth()

	var query *storage.Query
	for {
		// If you are using this package on App Engine Managed VMs runtime,
		// you can init a bucket client with your app's default bucket name.
		// See http://godoc.org/google.golang.org/appengine/file#DefaultBucketName.
		objects, err := storage.ListObjects(ctx, "bucketname", query)
		if err != nil {
			log.Fatal(err)
		}
		for _, obj := range objects.Results {
			log.Printf("object name: %s, size: %v", obj.Name, obj.Size)
		}
		// if there are more results, objects.Next
		// will be non-nil.
		query = objects.Next
		if query == nil {
			break
		}
	}

	log.Println("paginated through all object items in the bucket you specified.")
}

Output:

type Query 

type Query struct {
	// Delimiter returns results in a directory-like fashion.
	// Results will contain only objects whose names, aside from the
	// prefix, do not contain delimiter. Objects whose names,
	// aside from the prefix, contain delimiter will have their name,
	// truncated after the delimiter, returned in prefixes.
	// Duplicate prefixes are omitted.
	// Optional.
	Delimiter string

	// Prefix is the prefix filter to query objects
	// whose names begin with this prefix.
	// Optional.
	Prefix string

	// Versions indicates whether multiple versions of the same
	// object will be included in the results.
	Versions bool

	// Cursor is a previously-returned page token
	// representing part of the larger set of results to view.
	// Optional.
	Cursor string

	// MaxResults is the maximum number of items plus prefixes
	// to return. As duplicate prefixes are omitted,
	// fewer total results may be returned than requested.
	// The default page limit is used if it is negative or zero.
	MaxResults int
}

Query represents a query to filter objects from a bucket.

type SignedURLOptions 

type SignedURLOptions struct {
	// GoogleAccessID represents the authorizer of the signed URL generation.
	// It is typically the Google service account client email address from
	// the Google Developers Console in the form of "xxx@developer.gserviceaccount.com".
	// Required.
	GoogleAccessID string

	// PrivateKey is the Google service account private key. It is obtainable
	// from the Google Developers Console.
	// At https://console.developers.google.com/project/<your-project-id>/apiui/credential,
	// create a service account client ID or reuse one of your existing service account
	// credentials. Click on the "Generate new P12 key" to generate and download
	// a new private key. Once you download the P12 file, use the following command
	// to convert it into a PEM file.
	//
	//    $ openssl pkcs12 -in key.p12 -passin pass:notasecret -out key.pem -nodes
	//
	// Provide the contents of the PEM file as a byte slice.
	// Required.
	PrivateKey []byte

	// Method is the HTTP method to be used with the signed URL.
	// Signed URLs can be used with GET, HEAD, PUT, and DELETE requests.
	// Required.
	Method string

	// Expires is the expiration time on the signed URL. It must be
	// a datetime in the future.
	// Required.
	Expires time.Time

	// ContentType is the content type header the client must provide
	// to use the generated signed URL.
	// Optional.
	ContentType string

	// Headers is a list of extention headers the client must provide
	// in order to use the generated signed URL.
	// Optional.
	Headers []string

	// MD5 is the base64 encoded MD5 checksum of the file.
	// If provided, the client should provide the exact value on the request
	// header in order to use the signed URL.
	// Optional.
	MD5 []byte
}

SignedURLOptions allows you to restrict the access to the signed URL.

type Writer 

type Writer struct {
	// ObjectAttrs are optional attributes to set on the object. Any attributes
	// must be initialized before the first Write call. Nil or zero-valued
	// attributes are ignored.
	ObjectAttrs
	// contains filtered or unexported fields
}

A Writer writes a Cloud Storage object.

func NewWriter 

func NewWriter(ctx context.Context, bucket, name string) *Writer

NewWriter returns a storage Writer that writes to the GCS object identified by the specified name. If such an object doesn't exist, it creates one. Attributes can be set on the object by modifying the returned Writer's ObjectAttrs field before the first call to Write. The name parameter to this function is ignored if the Name field of the ObjectAttrs field is set to a non-empty string.

It is the caller's responsibility to call Close when writing is done.

The object is not available and any previous object with the same name is not replaced on Cloud Storage until Close is called.

Example 
package main

import (
	"io/ioutil"
	"log"

	"golang.org/x/net/context"
	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
	"google.golang.org/cloud"
	"google.golang.org/cloud/storage"
)

func Example_auth() context.Context {

	jsonKey, err := ioutil.ReadFile("/path/to/json/keyfile.json")
	if err != nil {
		log.Fatal(err)
	}
	conf, err := google.JWTConfigFromJSON(
		jsonKey,
		storage.ScopeFullControl,
	)
	if err != nil {
		log.Fatal(err)
	}
	ctx := cloud.NewContext("project-id", conf.Client(oauth2.NoContext))

	return ctx
}

func main() {
	ctx := Example_auth()

	wc := storage.NewWriter(ctx, "bucketname", "filename1")
	wc.ContentType = "text/plain"
	wc.ACL = []storage.ACLRule{{storage.AllUsers, storage.RoleReader}}
	if _, err := wc.Write([]byte("hello world")); err != nil {
		log.Fatal(err)
	}
	if err := wc.Close(); err != nil {
		log.Fatal(err)
	}
	log.Println("updated object:", wc.Object())
}

Output:

func (*Writer) Close 

func (w *Writer) Close() error

Close completes the write operation and flushes any buffered data. If Close doesn't return an error, metadata about the written object can be retrieved by calling Object.

func (*Writer) CloseWithError 

func (w *Writer) CloseWithError(err error) error

CloseWithError aborts the write operation with the provided error. CloseWithError always returns nil.

func (*Writer) Object 

func (w *Writer) Object() *Object

Object returns metadata about a successfully-written object. It's only valid to call it after Close returns nil.

func (*Writer) Write 

func (w *Writer) Write(p []byte) (n int, err error)

Write appends to w.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.