storage

package
v0.0.0-...-12aa462 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2016 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package storage contains a Google Cloud Storage client.

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

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
)
View Source 
const DefaultPageSize = 1000

Variables

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

	// Done is returned by iterators in this package when they have no more items.
	Done = errors.New("storage: no more results")
)

Functions

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.

Example 
package main

import (
	"fmt"
	"io/ioutil"
	"time"

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

func main() {
	pkey, err := ioutil.ReadFile("my-private-key.pem")
	if err != nil {
		// TODO: handle error.
	}
	url, err := storage.SignedURL("my-bucket", "my-object", &storage.SignedURLOptions{
		GoogleAccessID: "xxx@developer.gserviceaccount.com",
		PrivateKey:     pkey,
		Method:         "GET",
		Expires:        time.Now().Add(48 * time.Hour),
	})
	if err != nil {
		// TODO: handle error.
	}
	fmt.Println(url)
}

Output:

Types

type ACLEntity 

type ACLEntity string

ACLEntity refers to a user or group. They are sometimes referred to as grantees.

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 ACLHandle 

type ACLHandle struct {
	// contains filtered or unexported fields
}

ACLHandle provides operations on an access control list for a Google Cloud Storage bucket or object.

func (*ACLHandle) Delete 

func (a *ACLHandle) Delete(ctx context.Context, entity ACLEntity) error

Delete permanently deletes the ACL entry for the given entity.

Example 
package main

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	// No longer grant access to the bucket to everyone on the Internet.
	if err := client.Bucket("my-bucket").ACL().Delete(ctx, storage.AllUsers); err != nil {
		// TODO: handle error.
	}
}

Output:

func (*ACLHandle) List 

func (a *ACLHandle) List(ctx context.Context) ([]ACLRule, error)

List retrieves ACL entries.

Example 
package main

import (
	"fmt"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	// List the default object ACLs for my-bucket.
	aclRules, err := client.Bucket("my-bucket").DefaultObjectACL().List(ctx)
	if err != nil {
		// TODO: handle error.
	}
	fmt.Println(aclRules)
}

Output:

func (*ACLHandle) Set 

func (a *ACLHandle) Set(ctx context.Context, entity ACLEntity, role ACLRole) error

Set sets the permission level for the given entity.

Example 
package main

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	// Let any authenticated user read my-bucket/my-object.
	obj := client.Bucket("my-bucket").Object("my-object")
	if err := obj.ACL().Set(ctx, storage.AllAuthenticatedUsers, storage.RoleReader); err != nil {
		// TODO: handle error.
	}
}

Output:

type ACLRole 

type ACLRole string

ACLRole is the level of access to grant. 

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

type ACLRule 

type ACLRule struct {
	Entity ACLEntity
	Role   ACLRole
}

ACLRule represents a grant for a role to an entity (user, group or team) for a Google Cloud Storage object or bucket.

type AdminClient deprecated 

type AdminClient struct {
	// contains filtered or unexported fields
}

AdminClient is a client type for performing admin operations on a project's buckets.

Deprecated: Client has all of AdminClient's methods.

func NewAdminClient deprecated 

func NewAdminClient(ctx context.Context, projectID string, opts ...cloud.ClientOption) (*AdminClient, error)

NewAdminClient creates a new AdminClient for a given project.

Deprecated: use NewClient instead.

func (*AdminClient) Close 

func (c *AdminClient) Close() error

Close closes the AdminClient.

func (*AdminClient) CreateBucket deprecated 

func (c *AdminClient) CreateBucket(ctx context.Context, bucketName string, attrs *BucketAttrs) error

Create creates a Bucket in the project. If attrs is nil the API defaults will be used.

Deprecated: use BucketHandle.Create instead.

func (*AdminClient) DeleteBucket deprecated 

func (c *AdminClient) DeleteBucket(ctx context.Context, bucketName string) error

Delete deletes a Bucket in the project.

Deprecated: use BucketHandle.Delete instead.

type BucketAttrs 

type BucketAttrs 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.
	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.
	Created time.Time
}

BucketAttrs represents the metadata for a Google Cloud Storage bucket.

type BucketHandle 

type BucketHandle struct {
	// contains filtered or unexported fields
}

BucketHandle provides operations on a Google Cloud Storage bucket. Use Client.Bucket to get a handle.

func (*BucketHandle) ACL 

func (c *BucketHandle) ACL() *ACLHandle

ACL returns an ACLHandle, which provides access to the bucket's access control list. This controls who can list, create or overwrite the objects in a bucket. This call does not perform any network operations.

func (*BucketHandle) Attrs 

func (b *BucketHandle) Attrs(ctx context.Context) (*BucketAttrs, error)

Attrs returns the metadata for the bucket.

Example 
package main

import (
	"fmt"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	attrs, err := client.Bucket("my-bucket").Attrs(ctx)
	if err != nil {
		// TODO: handle error.
	}
	fmt.Println(attrs)
}

Output:

func (*BucketHandle) Create 

func (b *BucketHandle) Create(ctx context.Context, projectID string, attrs *BucketAttrs) error

Create creates the Bucket in the project. If attrs is nil the API defaults will be used.

Example 
package main

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	if err := client.Bucket("my-bucket").Create(ctx, "my-project", nil); err != nil {
		// TODO: handle error.
	}
}

Output:

func (*BucketHandle) DefaultObjectACL 

func (c *BucketHandle) DefaultObjectACL() *ACLHandle

DefaultObjectACL returns an ACLHandle, which provides access to the bucket's default object ACLs. These ACLs are applied to newly created objects in this bucket that do not have a defined ACL. This call does not perform any network operations.

func (*BucketHandle) Delete 

func (b *BucketHandle) Delete(ctx context.Context) error

Delete deletes the Bucket.

Example 
package main

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	if err := client.Bucket("my-bucket").Delete(ctx); err != nil {
		// TODO: handle error.
	}
}

Output:

func (*BucketHandle) List 

func (b *BucketHandle) List(ctx context.Context, q *Query) (*ObjectList, error)

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

Deprecated. Use BucketHandle.Objects instead.

Example 
package main

import (
	"log"

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

func main() {
	ctx := context.Background()
	var client *storage.Client // See 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 := client.Bucket("bucketname").List(ctx, 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.
		if objects.Next == nil {
			break
		}
		query = objects.Next
	}

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

Output:

func (*BucketHandle) Object 

func (b *BucketHandle) Object(name string) *ObjectHandle

Object returns an ObjectHandle, which provides operations on the named object. This call does not perform any network operations.

name must consist entirely of valid UTF-8-encoded runes. The full specification for valid object names can be found at: 

https://cloud.google.com/storage/docs/bucket-naming

func (*BucketHandle) Objects 

func (b *BucketHandle) Objects(ctx context.Context, q *Query) *ObjectIterator
Example 
package main

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	it := client.Bucket("my-bucket").Objects(ctx, nil)
	_ = it // TODO: iterate using Next or NextPage.
}

Output:

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a client for interacting with Google Cloud Storage.

func NewClient 

func NewClient(ctx context.Context, opts ...cloud.ClientOption) (*Client, error)

NewClient creates a new Google Cloud Storage client. The default scope is ScopeFullControl. To use a different scope, like ScopeReadOnly, use cloud.WithScopes.

Example 
package main

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	// Use the client.

	// Close the client when finished.
	if err := client.Close(); err != nil {
		// TODO: handle error.
	}
}

Output:
Example (Auth) 
package main

import (
	"io/ioutil"
	"log"

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

func main() {
	// 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 := context.Background()
	client, err := storage.NewClient(ctx, cloud.WithTokenSource(conf.TokenSource(ctx)))
	if err != nil {
		log.Fatal(err)
	}

	// Use the client.

	// Close the client when finished.
	if err := client.Close(); err != nil {
		// TODO: handle error.
	}
}

Output:

func (*Client) Bucket 

func (c *Client) Bucket(name string) *BucketHandle

Bucket returns a BucketHandle, which provides operations on the named bucket. This call does not perform any network operations.

name must contain only lowercase letters, numbers, dashes, underscores, and dots. The full specification for valid bucket names can be found at: 

https://cloud.google.com/storage/docs/bucket-naming

func (*Client) Close 

func (c *Client) Close() error

Close closes the Client.

type Condition 

type Condition interface {
	// contains filtered or unexported methods
}

A Condition constrains methods to act on specific generations of resources.

Not all conditions or combinations of conditions are applicable to all methods.

func Generation 

func Generation(gen int64) Condition

func IfGenerationMatch 

func IfGenerationMatch(gen int64) Condition

func IfGenerationNotMatch 

func IfGenerationNotMatch(gen int64) Condition

func IfMetaGenerationMatch 

func IfMetaGenerationMatch(gen int64) Condition

func IfMetaGenerationNotMatch 

func IfMetaGenerationNotMatch(gen int64) Condition

type ObjectAttrs 

type ObjectAttrs struct {
	// Bucket is the name of the bucket containing this GCS object.
	// This field is read-only.
	Bucket string

	// Name is the name of the object within the bucket.
	// This field is read-only.
	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. This field is read-only.
	//
	// If non-zero, it is in the form of "user-<userId>".
	Owner string

	// Size is the length of the object's content. This field is read-only.
	Size int64

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

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

	// MD5 is the MD5 hash of the object's content. This field is read-only.
	MD5 []byte

	// CRC32C is the CRC32 checksum of the object's content using
	// the Castagnoli93 polynomial. This field is read-only.
	CRC32C uint32

	// MediaLink is an URL to the object's content. This field is read-only.
	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.
	// This field is read-only.
	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. This field is read-only.
	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". This field is read-only.
	StorageClass string

	// Created is the time the object was created. This field is read-only.
	Created time.Time

	// Deleted is the time the object was deleted.
	// If not deleted, it is the zero value. This field is read-only.
	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. This field is read-only.
	Updated time.Time
}

ObjectAttrs represents the metadata for a Google Cloud Storage (GCS) object.

type ObjectHandle 

type ObjectHandle struct {
	// contains filtered or unexported fields
}

ObjectHandle provides operations on an object in a Google Cloud Storage bucket. Use BucketHandle.Object to get a handle.

func (*ObjectHandle) ACL 

func (o *ObjectHandle) ACL() *ACLHandle

ACL provides access to the object's access control list. This controls who can read and write this object. This call does not perform any network operations.

func (*ObjectHandle) Attrs 

func (o *ObjectHandle) Attrs(ctx context.Context) (*ObjectAttrs, error)

Attrs returns meta information about the object. ErrObjectNotExist will be returned if the object is not found.

Example 
package main

import (
	"fmt"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	objAttrs, err := client.Bucket("my-bucket").Object("my-object").Attrs(ctx)
	if err != nil {
		// TODO: handle error.
	}
	fmt.Println(objAttrs)
}

Output:
Example (WithConditions) 
package main

import (
	"fmt"
	"time"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	obj := client.Bucket("my-bucket").Object("my-object")
	// Read the object.
	objAttrs1, err := obj.Attrs(ctx)
	if err != nil {
		// TODO: handle error.
	}
	// Do something else for a while.
	time.Sleep(5 * time.Minute)
	// Now read the same contents, even if the object has been written since the last read.
	objAttrs2, err := obj.WithConditions(storage.Generation(objAttrs1.Generation)).Attrs(ctx)
	if err != nil {
		// TODO: handle error.
	}
	fmt.Println(objAttrs1, objAttrs2)
}

Output:

func (*ObjectHandle) CopyTo 

func (o *ObjectHandle) CopyTo(ctx context.Context, dst *ObjectHandle, attrs *ObjectAttrs) (*ObjectAttrs, error)

CopyTo copies the object to the given dst. The copied object's attributes are overwritten by attrs if non-nil.

Example 
package main

import (
	"fmt"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	src := client.Bucket("bucketname").Object("file1")
	dst := client.Bucket("another-bucketname").Object("file2")

	o, err := src.CopyTo(ctx, dst, nil)
	if err != nil {
		// TODO: handle error.
	}
	fmt.Println("copied file:", o)
}

Output:

func (*ObjectHandle) Delete 

func (o *ObjectHandle) Delete(ctx context.Context) error

Delete deletes the single specified object.

Example 
package main

import (
	"fmt"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	// To delete multiple objects in a bucket, list them with an
	// ObjectIterator, then Delete them.

	// 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.
	bucket := client.Bucket("my-bucket")
	it := bucket.Objects(ctx, nil)
	for {
		objAttrs, err := it.Next()
		if err != nil && err != storage.Done {
			// TODO: Handle error.
		}
		if err == storage.Done {
			break
		}
		if err := bucket.Object(objAttrs.Name).Delete(ctx); err != nil {
			// TODO: Handle error.
		}
	}
	fmt.Println("deleted all object items in the bucket specified.")
}

Output:

func (*ObjectHandle) NewRangeReader 

func (o *ObjectHandle) NewRangeReader(ctx context.Context, offset, length int64) (*Reader, error)

NewRangeReader reads part of an object, reading at most length bytes starting at the given offset. If length is negative, the object is read until the end.

Example 
package main

import (
	"fmt"
	"io/ioutil"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	// Read only the first 64K.
	rc, err := client.Bucket("bucketname").Object("filename1").NewRangeReader(ctx, 0, 64*1024)
	if err != nil {
		// TODO: handle error.
	}
	slurp, err := ioutil.ReadAll(rc)
	rc.Close()
	if err != nil {
		// TODO: handle error.
	}
	fmt.Println("first 64K of file contents:", slurp)
}

Output:

func (*ObjectHandle) NewReader 

func (o *ObjectHandle) NewReader(ctx context.Context) (*Reader, error)

NewReader creates a new Reader to read the contents of the object. ErrObjectNotExist will be returned if the object is not found.

Example 
package main

import (
	"fmt"
	"io/ioutil"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	rc, err := client.Bucket("my-bucket").Object("my-object").NewReader(ctx)
	if err != nil {
		// TODO: handle error.
	}
	slurp, err := ioutil.ReadAll(rc)
	rc.Close()
	if err != nil {
		// TODO: handle error.
	}
	fmt.Println("file contents:", slurp)
}

Output:

func (*ObjectHandle) NewWriter 

func (o *ObjectHandle) NewWriter(ctx context.Context) *Writer

NewWriter returns a storage Writer that writes to the GCS object associated with this ObjectHandle.

A new object will be created if an object with this name already exists. Otherwise any previous object with the same name will be replaced. The object will not be available (and any previous object will remain) until Close has been called.

Attributes can be set on the object by modifying the returned Writer's ObjectAttrs field before the first call to Write. If no ContentType attribute is specified, the content type will be automatically sniffed using net/http.DetectContentType.

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

Example 
package main

import (
	"fmt"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	wc := client.Bucket("bucketname").Object("filename1").NewWriter(ctx)
	wc.ContentType = "text/plain"
	wc.ACL = []storage.ACLRule{{storage.AllUsers, storage.RoleReader}}
	if _, err := wc.Write([]byte("hello world")); err != nil {
		// TODO: handle error.
	}
	if err := wc.Close(); err != nil {
		// TODO: handle error.
	}
	fmt.Println("updated object:", wc.Attrs())
}

Output:

func (*ObjectHandle) Update 

func (o *ObjectHandle) Update(ctx context.Context, attrs ObjectAttrs) (*ObjectAttrs, error)

Update updates an object with the provided attributes. All zero-value attributes are ignored. ErrObjectNotExist will be returned if the object is not found.

Example 
package main

import (
	"fmt"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	// Change only the content type of the object.
	objAttrs, err := client.Bucket("my-bucket").Object("my-object").Update(ctx, storage.ObjectAttrs{
		ContentType: "text/html",
	})
	if err != nil {
		// TODO: handle error.
	}
	fmt.Println(objAttrs)
}

Output:

func (*ObjectHandle) WithConditions 

func (o *ObjectHandle) WithConditions(conds ...Condition) *ObjectHandle

WithConditions returns a copy of o using the provided conditions.

type ObjectIterator 

type ObjectIterator struct {
	// contains filtered or unexported fields
}

func (*ObjectIterator) Next 

func (it *ObjectIterator) Next() (*ObjectAttrs, error)

Next returns the next result. Its second return value is Done if there are no more results. Once Next returns Done, all subsequent calls will return Done.

Internally, Next retrieves results in bulk. You can call SetPageSize as a performance hint to affect how many results are retrieved in a single RPC.

SetPageToken should not be called when using Next.

Next and NextPage should not be used with the same iterator.

If Query.Delimiter is non-empty, Next returns an error. Use NextPage when using delimiters.

Example 
package main

import (
	"fmt"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	it := client.Bucket("my-bucket").Objects(ctx, nil)
	for {
		objAttrs, err := it.Next()
		if err != nil && err != storage.Done {
			// TODO: Handle error.
		}
		if err == storage.Done {
			break
		}
		fmt.Println(objAttrs)
	}
}

Output:

func (*ObjectIterator) NextPage 

func (it *ObjectIterator) NextPage() (objs []*ObjectAttrs, prefixes []string, err error)

NextPage returns the next page of results, both objects (as *ObjectAttrs) and prefixes. Prefixes will be nil if query.Delimiter is empty.

NextPage will return exactly the number of results (the total of objects and prefixes) specified by the last call to SetPageSize, unless there are not enough results available. If no page size was specified, it uses DefaultPageSize.

NextPage may return a second return value of Done along with the last page of results.

After NextPage returns Done, all subsequent calls to NextPage will return (nil, Done).

Next and NextPage should not be used with the same iterator.

Example 
package main

import (
	"fmt"

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

func main() {
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		// TODO: handle error.
	}
	it := client.Bucket("my-bucket").Objects(ctx, nil)
	it.SetPageSize(50)
	for {
		objAttrs, prefixes, err := it.NextPage()
		if err != nil && err != storage.Done {
			// TODO: Handle error.
		}
		fmt.Println(objAttrs, prefixes)
		if err == storage.Done {
			break
		}
	}
}

Output:

func (*ObjectIterator) NextPageToken 

func (it *ObjectIterator) NextPageToken() string

NextPageToken returns a page token that can be used with SetPageToken to resume iteration from the next page. It returns the empty string if there are no more pages. For an example, see SetPageToken.

func (*ObjectIterator) SetPageSize 

func (it *ObjectIterator) SetPageSize(pageSize int32)

SetPageSize sets the page size for all subsequent calls to NextPage. NextPage will return exactly this many items if they are present.

func (*ObjectIterator) SetPageToken 

func (it *ObjectIterator) SetPageToken(t string)

SetPageToken sets the page token for the next call to NextPage, to resume the iteration from a previous point.

type ObjectList 

type ObjectList struct {
	// Results represent a list of object results.
	Results []*ObjectAttrs

	// 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
}

ObjectList represents a list of objects returned from a bucket List call.

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.
	//
	// Deprecated. Use ObjectIterator.SetPageSize.
	MaxResults int
}

Query represents a query to filter objects from a bucket.

type Reader 

type Reader struct {
	// contains filtered or unexported fields
}

Reader reads a Cloud Storage object.

func (*Reader) Close 

func (r *Reader) Close() error

func (*Reader) ContentType 

func (r *Reader) ContentType() string

ContentType returns the content type of the object.

func (*Reader) Read 

func (r *Reader) Read(p []byte) (int, error)

func (*Reader) Remain 

func (r *Reader) Remain() int64

Remain returns the number of bytes left to read, or -1 if unknown.

func (*Reader) Size 

func (r *Reader) Size() int64

Size returns the size of the object in bytes. The returned value is always the same and is not affected by calls to Read or Close.

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.
	// Exactly one of PrivateKey or SignBytes must be non-nil.
	PrivateKey []byte

	// SignBytes is a function for implementing custom signing.
	// If your application is running on Google App Engine, you can use appengine's internal signing function:
	//     ctx := appengine.NewContext(request)
	//     acc, _ := appengine.ServiceAccount(ctx)
	//     url, err := SignedURL("bucket", "object", &SignedURLOptions{
	//     	GoogleAccessID: acc,
	//     	SignBytes: func(b []byte) ([]byte, error) {
	//     		_, signedBytes, err := appengine.SignBytes(ctx, b)
	//     		return signedBytes, err
	//     	},
	//     	// etc.
	//     })
	//
	// Exactly one of PrivateKey or SignBytes must be non-nil.
	SignBytes func([]byte) ([]byte, error)

	// 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 (*Writer) Attrs 

func (w *Writer) Attrs() *ObjectAttrs

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

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) 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.