storage

package
v0.0.0-...-f48b261 Latest Latest
Warning

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

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

Documentation

Overview

Package storage is a Google Cloud Storage client.

Example (Auth) 
package main

import (
	"log"
	"net/http"

	"github.com/golang/oauth2/google"

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

func main() {
	// Initialize an authorized transport with Google Developers Console
	// JSON key. Read the google package examples to learn more about
	// different authorization flows you can use.
	// http://godoc.org/github.com/golang/oauth2/google
	conf, err := google.NewServiceAccountJSONConfig(
		"/path/to/json/keyfile.json",
		storage.ScopeFullControl)
	if err != nil {
		log.Fatal(err)
	}

	ctx := cloud.NewContext("project-id", &http.Client{Transport: conf.NewTransport()})
	_ = ctx // Use the context (see other examples)
}

Output:
Example (CopyObjects) 
package main

import (
	"log"
	"net/http"

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

func main() {
	// see the auth example how to initiate a context.
	ctx := cloud.NewContext("project-id", &http.Client{Transport: nil})

	o, err := storage.Copy(ctx, "bucketname", "file1", &storage.Object{
		Name:   "file2",
		Bucket: "yet-another-bucketname",
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println("copied file:", o)
}

Output:
Example (ListObjects) 
package main

import (
	"log"
	"net/http"

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

func main() {
	// see the auth example how to initiate a context.
	ctx := cloud.NewContext("project-id", &http.Client{Transport: nil})

	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.List(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:
Example (ReadObjects) 
package main

import (
	"io/ioutil"
	"log"
	"net/http"

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

func main() {
	// see the auth example how to initiate a context.
	ctx := cloud.NewContext("project-id", &http.Client{Transport: nil})

	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:
Example (TouchObjects) 
package main

import (
	"log"
	"net/http"

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

func main() {
	// see the auth example how to initiate a context.
	ctx := cloud.NewContext("project-id", &http.Client{Transport: nil})

	o, err := storage.Put(ctx, "bucketname", "filename", &storage.Object{
		ContentType: "text/plain",
	})
	if err != nil {
		log.Fatal(err)
	}
	log.Println("touched new file:", o)
}

Output:
Example (WriteObjects) 
package main

import (
	"log"
	"net/http"

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

func main() {
	// see the auth example how to initiate a context.
	ctx := cloud.NewContext("project-id", &http.Client{Transport: nil})

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

	o, err := wc.Object()
	if err != nil {
		log.Fatal(err)
	}
	log.Println("updated object:", o)
}

Output:

Index

Examples

Constants

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

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

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

Variables

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

Functions

func Delete 

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

Delete deletes the specified object.

func DeleteACLRule 

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

DeleteACLRule deletes the named ACL entity for the named object.

func DeleteBucketACLRule 

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

DeleteBucketACLRule deletes the named ACL entity for the named bucket.

func DeleteDefaultACLRule 

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

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

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.

func PutACLRule 

func PutACLRule(ctx context.Context, bucket, object, entity string, 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, entity string, 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, entity string, role ACLRole) error

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

Types

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. It could be in the form of:
	// - "user-<userId>"
	// - "user-<email>"
	// - "group-<groupId>"
	// - "group-<email>"
	// - "domain-<domain>"
	// - "project-team-<projectId>"
	// - "allUsers"
	// - "allAuthenticatedUsers"
	Entity string `json:"entity,omitempty"`

	// Role is the the access permission for the entity.
	Role ACLRole `json:"role,omitempty"`
}

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 `json:"name,omitempty"`

	// ACL is the list of access control rules on the bucket.
	ACL []*ACLRule `json:"acl,omitempty"`

	// DefaultObjectACL is the list of access controls to
	// apply to new objects when no object ACL is provided.
	DefaultObjectACL []*ACLRule `json:"defaultObjectAcl,omitempty"`

	// Location is the location of the bucket. It defaults to "US".
	Location string `json:"location,omitempty"`

	// Metageneration is the metadata generation of the bucket.
	// Read-only.
	Metageneration int64 `json:"metageneration,omitempty"`

	// 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 `json:"storageClass,omitempty"`

	// Created is the creation time of the bucket.
	// Read-only.
	Created time.Time `json:"timeCreated,omitempty"`
}

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 `json:"bucket,omitempty"`

	// Name is the name of the object.
	Name string `json:"name,omitempty"`

	// ContentType is the MIME type of the object's content.
	ContentType string `json:"contentType,omitempty"`

	// ACL is the list of access control rules for the object.
	ACL []*ACLRule `json:"acl,omitempty"`

	// Owner is the owner of the object. Owner is alway the original
	// uploader of the object.
	// Read-only.
	Owner *Owner `json:"owner,omitempty"`

	// Size is the length of the object's content.
	// Read-only.
	Size uint64 `json:"size,omitempty"`

	// ContentEncoding is the encoding of the object's content.
	// Read-only.
	ContentEncoding string `json:"contentEncoding,omitempty"`

	// MD5 is the MD5 hash of the data.
	// Read-only.
	MD5 []byte `json:"md5Hash,omitempty"`

	// CRC32C is the CRC32C checksum of the object's content.
	// Read-only.
	CRC32C []byte `json:"crc32c,omitempty"`

	// MediaLink is an URL to the object's content.
	// Read-only.
	MediaLink string `json:"mediaLink,omitempty"`

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

	// Generation is the generation version of the object's content.
	// Read-only.
	Generation int64 `json:"generation,omitempty"`

	// 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.
	// Read-only.
	MetaGeneration int64 `json:"metageneration,omitempty"`

	// StorageClass is the storage class of the object.
	StorageClass string `json:"storageClass,omitempty"`

	// Deleted is the deletion time of the object (or the zero-value time).
	// This will be non-zero if and only if this version of the object has been deleted.
	Deleted time.Time `json:"timeDeleted,omitempty"`

	// 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 `json:"updated,omitempty"`
}

Object represents a Google Cloud Storage (GCS) object.

func Copy 

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

Copy copies the source object to the destination with the new meta information provided. The destination object is inserted into the source bucket if the destination object doesn't specify another bucket name.

func Put 

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

Put inserts/updates an object with the provided meta information.

func Stat 

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

Stat returns meta information about the specified object.

type ObjectWriter 

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

ObjectWriter is an io.WriteCloser that opens a connection to update the metadata and file contents of a GCS object.

func NewWriter 

func NewWriter(ctx context.Context, bucket, name string, info *Object) *ObjectWriter

NewWriter returns a new ObjectWriter to write to the GCS object identified by the specified object name. If such object doesn't exist, it creates one. If info is not nil, write operation also modifies the meta information of the object. All read-only fields are ignored during metadata updates.

func (*ObjectWriter) Close 

func (w *ObjectWriter) Close() error

Close closes the writer and cleans up other resources used by the writer.

func (*ObjectWriter) Object 

func (w *ObjectWriter) Object() (*Object, error)

Object returns the object information. It will block until the write operation is complete.

func (*ObjectWriter) Write 

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

Write writes len(p) bytes to the object. It returns the number of the bytes written, or an error if there is a problem occured during the write. It's a blocking operation, and will not return until the bytes are written to the underlying socket.

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 List 

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

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

type Owner 

type Owner struct {
	// Entity identifies the owner, it's always in the form of "user-<userId>".
	Entity string `json:"entity,omitempty"`
}

Owner represents the owner of a GCS object.

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.

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.