storage

packagemodule

v1.60.0Latest Latest

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

Go to latest Published: Feb 10, 2026 License:Apache-2.0Imports:85Imported by:6,400

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/googleapis/google-cloud-go

README ¶

Cloud Storage

Example Usage

First create astorage.Client to use throughout your application:

client, err := storage.NewClient(ctx)if err != nil {log.Fatal(err)}

// Read the object1 from bucket.rc, err := client.Bucket("bucket").Object("object1").NewReader(ctx)if err != nil {log.Fatal(err)}defer rc.Close()body, err := io.ReadAll(rc)if err != nil {log.Fatal(err)}

Documentation¶

Overview¶

Package storage provides an easy way to work with Google Cloud Storage.Google Cloud Storage stores data in named objects, which are grouped into buckets.

More information about Google Cloud Storage is available athttps://cloud.google.com/storage/docs.

Seehttps://pkg.go.dev/cloud.google.com/go for authentication, timeouts,connection pooling and similar aspects of this package.

Creating a Client¶

To start working with this package, create aClient:

ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {    // TODO: Handle error.}

The client will use your default application credentials. Clients should bereused instead of created as needed. The methods ofClient are safe forconcurrent use by multiple goroutines.

You may configure the client by passing in options from thegoogle.golang.org/api/optionpackage. You may also use options defined in this package, such asWithJSONReads.

If you only wish to access public data, you can createan unauthenticated client with

client, err := storage.NewClient(ctx, option.WithoutAuthentication())

To use an emulator with this library, you can set the STORAGE_EMULATOR_HOSTenvironment variable to the address at which your emulator is running. This willsend requests to that address instead of to Cloud Storage. You can then createand use a client as usual:

// Set STORAGE_EMULATOR_HOST environment variable.err := os.Setenv("STORAGE_EMULATOR_HOST", "localhost:9000")if err != nil {    // TODO: Handle error.}// Create client as usual.client, err := storage.NewClient(ctx)if err != nil {    // TODO: Handle error.}// This request is now directed to http://localhost:9000/storage/v1/b// instead of https://storage.googleapis.com/storage/v1/bif err := client.Bucket("my-bucket").Create(ctx, projectID, nil); err != nil {    // TODO: Handle error.}

Please note that there is no official emulator for Cloud Storage.

Buckets¶

A Google Cloud Storage bucket is a collection of objects. To work with abucket, make a bucket handle:

bkt := client.Bucket(bucketName)

A handle is a reference to a bucket. You can have a handle even if thebucket doesn't exist yet. To create a bucket in Google Cloud Storage,callBucketHandle.Create:

if err := bkt.Create(ctx, projectID, nil); err != nil {    // TODO: Handle error.}

Note that although buckets are associated with projects, bucket names areglobal across all projects.

Each bucket has associated metadata, represented in this package byBucketAttrs. The third argument toBucketHandle.Create allows you to setthe initialBucketAttrs of a bucket. To retrieve a bucket's attributes, useBucketHandle.Attrs:

attrs, err := bkt.Attrs(ctx)if err != nil {    // TODO: Handle error.}fmt.Printf("bucket %s, created at %s, is located in %s with storage class %s\n",    attrs.Name, attrs.Created, attrs.Location, attrs.StorageClass)

Objects¶

An object holds arbitrary data as a sequence of bytes, like a file. Yourefer to objects using a handle, just as with buckets, but unlike bucketsyou don't explicitly create an object. Instead, the first time you writeto an object it will be created. You can use the standard Goio.Readerandio.Writer interfaces to read and write object data:

obj := bkt.Object("data")// Write something to obj.// w implements io.Writer.w := obj.NewWriter(ctx)// Write some text to obj. This will either create the object or overwrite whatever is there already.if _, err := fmt.Fprintf(w, "This object contains text.\n"); err != nil {    // TODO: Handle error.}// Close, just like writing a file.if err := w.Close(); err != nil {    // TODO: Handle error.}// Read it back.r, err := obj.NewReader(ctx)if err != nil {    // TODO: Handle error.}defer r.Close()if _, err := io.Copy(os.Stdout, r); err != nil {    // TODO: Handle error.}// Prints "This object contains text."

Objects also have attributes, which you can fetch withObjectHandle.Attrs:

objAttrs, err := obj.Attrs(ctx)if err != nil {    // TODO: Handle error.}fmt.Printf("object %s has size %d and can be read using %s\n",    objAttrs.Name, objAttrs.Size, objAttrs.MediaLink)

Listing objects¶

Listing objects in a bucket is done with theBucketHandle.Objects method:

query := &storage.Query{Prefix: ""}var names []stringit := bkt.Objects(ctx, query)for {    attrs, err := it.Next()    if err == iterator.Done {        break    }    if err != nil {        log.Fatal(err)    }    names = append(names, attrs.Name)}

Objects are listed lexicographically by name. To filter objectslexicographically, [Query.StartOffset] and/or [Query.EndOffset] can be used:

query := &storage.Query{    Prefix: "",    StartOffset: "bar/",  // Only list objects lexicographically >= "bar/"    EndOffset: "foo/",    // Only list objects lexicographically < "foo/"}// ... as before

If only a subset of object attributes is needed when listing, specifying thissubset usingQuery.SetAttrSelection may speed up the listing process:

query := &storage.Query{Prefix: ""}query.SetAttrSelection([]string{"Name"})// ... as before

ACLs¶

Both objects and buckets have ACLs (Access Control Lists). An ACL is a list ofACLRules, each of which specifies the role of a user, group or project. ACLsare suitable for fine-grained control, but you may prefer using IAM to controlaccess at the project level (seeCloud Storage IAM docs.

To list the ACLs of a bucket or object, obtain anACLHandle and callACLHandle.List:

acls, err := obj.ACL().List(ctx)if err != nil {    // TODO: Handle error.}for _, rule := range acls {    fmt.Printf("%s has role %s\n", rule.Entity, rule.Role)}

You can also set and delete ACLs.

Conditions¶

Every object has a generation and a metageneration. The generation changeswhenever the content changes, and the metageneration changes whenever themetadata changes.Conditions let you check these values before an operation;the operation only executes if the conditions match. You can use conditions toprevent race conditions in read-modify-write operations.

For example, say you've read an object's metadata into objAttrs. Nowyou want to write to that object, but only if its contents haven't changedsince you read it. Here is how to express that:

w = obj.If(storage.Conditions{GenerationMatch: objAttrs.Generation}).NewWriter(ctx)// Proceed with writing as above.

Signed URLs¶

You can obtain a URL that lets anyone read or write an object for a limited time.Signing a URL requires credentials authorized to sign a URL. To use the sameauthentication that was used when instantiating the Storage client, useBucketHandle.SignedURL.

url, err := client.Bucket(bucketName).SignedURL(objectName, opts)if err != nil {    // TODO: Handle error.}fmt.Println(url)

You can also sign a URL without creating a client. See the documentation ofSignedURL for details.

url, err := storage.SignedURL(bucketName, "shared-object", opts)if err != nil {    // TODO: Handle error.}fmt.Println(url)

Post Policy V4 Signed Request¶

A type of signed request that allows uploads through HTML forms directly to Cloud Storage withtemporary permission. Conditions can be applied to restrict how the HTML form is used and exercisedby a user.

For more information, please see theXML POST Object docs as wellas the documentation ofBucketHandle.GenerateSignedPostPolicyV4.

pv4, err := client.Bucket(bucketName).GenerateSignedPostPolicyV4(objectName, opts)if err != nil {    // TODO: Handle error.}fmt.Printf("URL: %s\nFields; %v\n", pv4.URL, pv4.Fields)

Credential requirements for signing¶

If the GoogleAccessID and PrivateKey option fields are not provided, they willbe automatically detected byBucketHandle.SignedURL andBucketHandle.GenerateSignedPostPolicyV4 if any of the following are true:

you are authenticated to the Storage Client with a service account'sdownloaded private key, either directly in code or by setting theGOOGLE_APPLICATION_CREDENTIALS environment variable (seeOther Environments),
your application is running on Google Compute Engine (GCE), or
you are logged intogcloud using application default credentialswithimpersonation enabled.

Detecting GoogleAccessID may not be possible if you are authenticated using atoken source or usingoption.WithHTTPClient. In this case, you can provide aservice account email for GoogleAccessID and the client will attempt to signthe URL or Post Policy using that service account.

To generate the signature, you must have:

iam.serviceAccounts.signBlob permissions on the GoogleAccessID serviceaccount, and
theIAM Service Account Credentials API enabled (unless authenticatingwith a downloaded private key).

Errors¶

Errors returned by this client are often of the typegithub.com/googleapis/gax-go/v2/apierror.The [apierror.APIError] type can wrap agoogle.golang.org/grpc/status.Statusif gRPC was used, or agoogle.golang.org/api/googleapi.Error if HTTP/REST was used.You might also encountergoogleapi.Error directly from HTTP operations.These types of errors can be inspected for more information by usingerrors.Asto access the specific underlying error types and retrieve detailed information,including HTTP or gRPC status codes. For example:

// APIErrors often wrap a googleapi.Error (for JSON and XML calls) or a status.Status (for gRPC calls)var ae *apierror.APIErrorif ok := errors.As(err, &ae); ok {// ae.HTTPCode() is the HTTP status code.// ae.GRPCStatus().Code() is the gRPC status codelog.Printf("APIError: HTTPCode: %d, GRPCStatusCode: %s", ae.HTTPCode(), ae.GRPCStatus().Code())if ae.GRPCStatus().Code() == codes.Unavailable {// ... handle gRPC unavailable ...}}// This allows a user to get more information directly from googleapi.Errors (for JSON/XML calls)var e *googleapi.Errorif ok := errors.As(err, &e); ok {// e.Code is the HTTP status code.// e.Message is the error message.// e.Body is the raw response body.// e.Header contains the HTTP response headers.log.Printf("HTTP Code: %d, Message: %s", e.Code, e.Message)if e.Code == 409 {// ... handle conflict ...}}

This library may also return other errors that are not wrapped as [apierror.APIError]. Forexample, errors with authentication may returncloud.google.com/go/auth.Error.

Retrying failed requests¶

Methods in this package may retry calls that fail with transient errors.Retrying continues indefinitely unless the controlling context is canceled, theclient is closed, or a non-transient error is received. To stop retries fromcontinuing, use context timeouts or cancellation.

The retry strategy in this library follows best practices for Cloud Storage. Bydefault, operations are retried only if they are idempotent, and exponentialbackoff with jitter is employed. In addition, errors are only retried if theyare defined as transient by the service. See theCloud Storage retry docsfor more information.

Users can configure non-default retry behavior for a single library call (usingBucketHandle.Retryer andObjectHandle.Retryer) or for all calls made by aclient (usingClient.SetRetry). For example:

o := client.Bucket(bucket).Object(object).Retryer(// Use WithBackoff to change the timing of the exponential backoff.storage.WithBackoff(gax.Backoff{Initial:    2 * time.Second,}),// Use WithPolicy to configure the idempotency policy. RetryAlways will// retry the operation even if it is non-idempotent.storage.WithPolicy(storage.RetryAlways),)// Use a context timeout to set an overall deadline on the call, including all// potential retries.ctx, cancel := context.WithTimeout(ctx, 5*time.Second)defer cancel()// Delete an object using the specified strategy and timeout.if err := o.Delete(ctx); err != nil {// Handle err.}

Sending Custom Headers¶

You can add custom headers to any API call made by this package by usingcallctx.SetHeaders on the context which is passed to the method. For example,to add acustom audit logging header:

ctx := context.Background()ctx = callctx.SetHeaders(ctx, "x-goog-custom-audit-<key>", "<value>")// Use client as usual with the context and the additional headers will be sent.client.Bucket("my-bucket").Attrs(ctx)

gRPC API¶

This package includes support for theCloud Storage gRPC API. Thisimplementation uses gRPC rather than the default JSON & XML APIsto make requests to Cloud Storage. All methods on theClient supportthe gRPC API, with the exception of theClient.ServiceAccount,Notification,andHMACKey methods.

The Cloud Storage gRPC API is generally available.

To create a client which will use gRPC, use the alternate constructor:

ctx := context.Background()client, err := storage.NewGRPCClient(ctx)if err != nil {// TODO: Handle error.}// Use client as usual.

One major advantage of the gRPC API is that it can useDirect Connectivity,enabling requests to skip some proxy steps and reducing response latency.Requirements to use Direct Connectivity include:

Your application must be running inside Google Cloud.
Your Cloud Storagebucket location must overlap with your VM or computeenvironment zone. For example, if your VM is in us-east1a, your bucketmust be located in either us-east1 (single region), nam4 (dual region),or us (multi-region).
Your client must use service account authentication.

Additional requirements for Direct Connectivity are documented in theCloud Storage gRPC docs. If all requirements are met, the client willuse Direct Connectivity by default without requiring any client optionsor environment variables. To disable Direct Connectivity, you can setthe environment variable GOOGLE_CLOUD_DISABLE_DIRECT_PATH=true.

Dependencies for the gRPC API may slightly increase the size of binaries forapplications depending on this package. If you are not using gRPC, you can usethe build tag `disable_grpc_modules` to opt out of these dependencies andreduce the binary size.

The gRPC client is instrumented with Open Telemetry metrics which export toCloud Monitoring by default. More information is available in thegRPC client-side metrics documentation, including information aboutroles which must be enabled in order to do the export successfully. Todisable this export, you can use theWithDisabledClientMetrics clientoption.

The client automatically computes and sends CRC32C checksums for uploads usingWriter,providing an additional layer of data integrity validation with a slight CPU overhead.

Note: With a chunk size of 0 (no buffering) in JSON uploads, an auto-calculated checksum mismatchreturns an error but may leave corrupt data on the server, requiring manual cleanup. This risk does notapply to single-shot uploads when user-provided checksum is provided.

Automatic checksumming can be disabled using [Writer.DisableAutoChecksum].

Storage Control API¶

Certain control plane and long-running operations for Cloud Storage (including Folderand Managed Folder operations) are supported via the autogenerated Storage Controlclient, which is available as a subpackage in this module. See package docs atcloud.google.com/go/storage/control/apiv2 or reference theStorage Control API docs.

Index¶

Examples¶

Constants¶

View Source

const (// DeleteAction is a lifecycle action that deletes a live and/or archived// objects. Takes precedence over SetStorageClass actions.DeleteAction = "Delete"// SetStorageClassAction changes the storage class of live and/or archived// objects.SetStorageClassAction = "SetStorageClass"// AbortIncompleteMPUAction is a lifecycle action that aborts an incomplete// multipart upload when the multipart upload meets the conditions specified// in the lifecycle rule. The AgeInDays condition is the only allowed// condition for this action. AgeInDays is measured from the time the// multipart upload was created.AbortIncompleteMPUAction = "AbortIncompleteMultipartUpload")

View Source

const (// Send no payload with notification messages.NoPayload = "NONE"// Send object metadata as JSON with notification messages.JSONPayload = "JSON_API_V1")

Values for Notification.PayloadFormat.

View Source

const (// Event that occurs when an object is successfully created.ObjectFinalizeEvent = "OBJECT_FINALIZE"// Event that occurs when the metadata of an existing object changes.ObjectMetadataUpdateEvent = "OBJECT_METADATA_UPDATE"// Event that occurs when an object is permanently deleted.ObjectDeleteEvent = "OBJECT_DELETE"// Event that occurs when the live version of an object becomes an// archived version.ObjectArchiveEvent = "OBJECT_ARCHIVE")

Values for Notification.EventTypes.

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 indicates that the bucket does not exist. It should be// checked for using [errors.Is] instead of direct equality.ErrBucketNotExist =errors.New("storage: bucket doesn't exist")// ErrObjectNotExist indicates that the object does not exist. It should be// checked for using [errors.Is] instead of direct equality.ErrObjectNotExist =errors.New("storage: object doesn't exist"))

Functions¶

funcCheckDirectConnectivitySupported ¶added inv1.47.0

func CheckDirectConnectivitySupported(ctxcontext.Context, bucketstring, opts ...option.ClientOption)error

CheckDirectConnectivitySupported checks if gRPC direct connectivityis available for a specific bucket from the environment where the clientis running. A `nil` error represents Direct Connectivity was detected.Direct connectivity is expected to be available when running from insideGCP and connecting to a bucket in the same region.

Experimental helper that's subject to change.

You can pass inoption.ClientOption you plan on passing toNewGRPCClient

funcShouldRetry ¶added inv1.26.0

func ShouldRetry(errerror)bool

ShouldRetry returns true if an error is retryable, based on best practiceguidance from GCS. Seehttps://cloud.google.com/storage/docs/retry-strategy#go for more informationon what errors are considered retryable.

If you would like to customize retryable errors, use the WithErrorFunc tosupply a RetryOption to your library calls. For example, to retry additionalerrors, you can write a custom func that wraps ShouldRetry and also specifiesadditional errors that should return true.

funcSignedURL ¶

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

SignedURL returns a URL for the specified object. Signed URLs allow anyoneaccess to a restricted resource for a limited time without needing aGoogle account or signing in. For more information about signed URLs, seehttps://cloud.google.com/storage/docs/accesscontrol#signed_urls_query_string_authenticationIf initializing a Storage Client, instead use the Bucket.SignedURL methodwhich uses the Client's credentials to handle authentication.

Example¶

package mainimport ("fmt""os""time""cloud.google.com/go/storage")func main() {pkey, err := os.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)}

funcWithDisabledClientMetrics ¶added inv1.44.0

func WithDisabledClientMetrics()option.ClientOption

WithDisabledClientMetrics is an option that may be passed toNewClient.gRPC metrics are enabled by default in the GCS client and will export thegRPC telemetry discussed ingRFC/66 andgRFC/78 toGoogle Cloud Monitoring. The option is used to disable metrics.Google Cloud Support can use this information to more quickly diagnoseproblems related to GCS and gRPC.Sending this data does not incur any billing charges, and requires minimalCPU (a single RPC every few minutes) or memory (a few KiB to batch thetelemetry).

The default is to enable client metrics. To opt-out of metrics collected usethis option.

funcWithJSONReads ¶added inv1.30.0

func WithJSONReads()option.ClientOption

WithJSONReads is an option that may be passed toNewClient.It sets the client to use the Cloud Storage JSON API for objectreads. Currently, the default API used for reads is XML, but JSON willbecome the default in a future release.

Setting this option is required to use the GenerationNotMatch condition. Wealso recommend using JSON reads to ensure consistency with other clientoperations (all of which use JSON by default).

Note that when this option is set, reads will return a zero date forReaderObjectAttrs.LastModified and may return a different value forReaderObjectAttrs.CacheControl.

funcWithXMLReads ¶added inv1.30.0

func WithXMLReads()option.ClientOption

WithXMLReads is an option that may be passed toNewClient.It sets the client to use the Cloud Storage XML API for object reads.

This is the current default, but the default will switch to JSON in a futurerelease.

Types¶

typeACLEntity ¶

type ACLEntitystring

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 (AllUsersACLEntity = "allUsers"AllAuthenticatedUsersACLEntity = "allAuthenticatedUsers")

typeACLHandle ¶

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

ACLHandle provides operations on an access control list for a Google Cloud Storage bucket or object.ACLHandle on an object operates on the latest generation of that object by default.Selecting a specific generation of an object is not currently supported by the client.

func (*ACLHandle)Delete ¶

func (a *ACLHandle) Delete(ctxcontext.Context, entityACLEntity) (errerror)

Delete permanently deletes the ACL entry for the given entity.

Example¶

package mainimport ("context""cloud.google.com/go/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.}}

func (*ACLHandle)List ¶

func (a *ACLHandle) List(ctxcontext.Context) (rules []ACLRule, errerror)

List retrieves ACL entries.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/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)}

func (*ACLHandle)Set ¶

func (a *ACLHandle) Set(ctxcontext.Context, entityACLEntity, roleACLRole) (errerror)

Set sets the role for the given entity.

Example¶

package mainimport ("context""cloud.google.com/go/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.}}

typeACLRole ¶

type ACLRolestring

ACLRole is the level of access to grant.

const (RoleOwnerACLRole = "OWNER"RoleReaderACLRole = "READER"RoleWriterACLRole = "WRITER")

typeACLRule ¶

type ACLRule struct {EntityACLEntityEntityIDstringRoleACLRoleDomainstringEmailstringProjectTeam *ProjectTeam}

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

typeAppendableWriterOpts ¶added inv1.52.0

type AppendableWriterOpts struct {// ChunkSize: See Writer.ChunkSize.ChunkSizeint// ChunkRetryDeadline: See Writer.ChunkRetryDeadline.ChunkRetryDeadlinetime.Duration// ProgressFunc: See Writer.ProgressFunc.ProgressFunc func(int64)// FinalizeOnClose: See Writer.FinalizeOnClose.FinalizeOnClosebool}

AppendableWriterOpts provides options to set on a Writer initializedby [NewWriterFromAppendableObject]. Writer options must be set via thisstruct rather than being modified on the returned Writer. All Writerfields not present in this struct cannot be set when taking over anappendable object.

AppendableWriterOpts is supported only for gRPC clients and only forobjects which were created append semantics and not finalized.This feature is in preview and is not yet available for general use.

typeAutoclass ¶added inv1.28.0

type Autoclass struct {// Enabled specifies whether the autoclass feature is enabled// on the bucket.Enabledbool// ToggleTime is the time from which Autoclass was last toggled.// If Autoclass is enabled when the bucket is created, the ToggleTime// is set to the bucket creation time. This field is read-only.ToggleTimetime.Time// TerminalStorageClass: The storage class that objects in the bucket// eventually transition to if they are not read for a certain length of// time. Valid values are NEARLINE and ARCHIVE.// To modify TerminalStorageClass, Enabled must be set to true.TerminalStorageClassstring// TerminalStorageClassUpdateTime represents the time of the most recent// update to "TerminalStorageClass".TerminalStorageClassUpdateTimetime.Time}

Autoclass holds the bucket's autoclass configuration. If enabled,allows for the automatic selection of the best storage classbased on object access patterns. Seehttps://cloud.google.com/storage/docs/using-autoclass for more information.

typeBucketAttrs ¶

type BucketAttrs struct {// Name is the name of the bucket.// This field is read-only.Namestring// ACL is the list of access control rules on the bucket.ACL []ACLRule// BucketPolicyOnly is an alias for UniformBucketLevelAccess. Use of// UniformBucketLevelAccess is recommended above the use of this field.// Setting BucketPolicyOnly.Enabled OR UniformBucketLevelAccess.Enabled to// true, will enable UniformBucketLevelAccess.BucketPolicyOnlyBucketPolicyOnly// UniformBucketLevelAccess configures access checks to use only bucket-level IAM// policies and ignore any ACL rules for the bucket.// Seehttps://cloud.google.com/storage/docs/uniform-bucket-level-access// for more information.UniformBucketLevelAccessUniformBucketLevelAccess// PublicAccessPrevention is the setting for the bucket's// PublicAccessPrevention policy, which can be used to prevent public access// of data in the bucket. See//https://cloud.google.com/storage/docs/public-access-prevention for more// information.PublicAccessPreventionPublicAccessPrevention// DefaultObjectACL is the list of access controls to// apply to new objects when no object ACL is provided.DefaultObjectACL []ACLRule// DefaultEventBasedHold is the default value for event-based hold on// newly created objects in this bucket. It defaults to false.DefaultEventBasedHoldbool// If not empty, applies a predefined set of access controls. It should be set// only when creating a bucket.// It is always empty for BucketAttrs returned from the service.// Seehttps://cloud.google.com/storage/docs/json_api/v1/buckets/insert// for valid values.PredefinedACLstring// If not empty, applies a predefined set of default object access controls.// It should be set only when creating a bucket.// It is always empty for BucketAttrs returned from the service.// Seehttps://cloud.google.com/storage/docs/json_api/v1/buckets/insert// for valid values.PredefinedDefaultObjectACLstring// Location is the location of the bucket. It defaults to "US".// If specifying a dual-region, CustomPlacementConfig should be set in conjunction.Locationstring// The bucket's custom placement configuration that holds a list of// regional locations for custom dual regions.CustomPlacementConfig *CustomPlacementConfig// MetaGeneration is the metadata generation of the bucket.// This field is read-only.MetaGenerationint64// StorageClass is the default 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", "NEARLINE",// "COLDLINE" and "ARCHIVE". Defaults to "STANDARD".// Seehttps://cloud.google.com/storage/docs/storage-classes for all// valid values.StorageClassstring// Created is the creation time of the bucket.// This field is read-only.Createdtime.Time// Updated is the time at which the bucket was last modified.// This field is read-only.Updatedtime.Time// VersioningEnabled reports whether this bucket has versioning enabled.VersioningEnabledbool// Labels are the bucket's labels.Labels map[string]string// RequesterPays reports whether the bucket is a Requester Pays bucket.// Clients performing operations on Requester Pays buckets must provide// a user project (see BucketHandle.UserProject), which will be billed// for the operations.RequesterPaysbool// Lifecycle is the lifecycle configuration for objects in the bucket.LifecycleLifecycle// Retention policy enforces a minimum retention time for all objects// contained in the bucket. A RetentionPolicy of nil implies the bucket// has no minimum data retention.//// This feature is in private alpha release. It is not currently available to// most customers. It might be changed in backwards-incompatible ways and is not// subject to any SLA or deprecation policy.RetentionPolicy *RetentionPolicy// The bucket's Cross-Origin Resource Sharing (CORS) configuration.CORS []CORS// The encryption configuration used by default for newly inserted objects.Encryption *BucketEncryption// The logging configuration.Logging *BucketLogging// The website configuration.Website *BucketWebsite// Etag is the HTTP/1.1 Entity tag for the bucket.// This field is read-only.Etagstring// LocationType describes how data is stored and replicated.// Typical values are "multi-region", "region" and "dual-region".// This field is read-only.LocationTypestring// The project number of the project the bucket belongs to.// This field is read-only.ProjectNumberuint64// RPO configures the Recovery Point Objective (RPO) policy of the bucket.// Set to RPOAsyncTurbo to turn on Turbo Replication for a bucket.// Seehttps://cloud.google.com/storage/docs/managing-turbo-replication for// more information.RPORPO// Autoclass holds the bucket's autoclass configuration. If enabled,// allows for the automatic selection of the best storage class// based on object access patterns.Autoclass *Autoclass// ObjectRetentionMode reports whether individual objects in the bucket can// be configured with a retention policy. An empty value means that object// retention is disabled.// This field is read-only. Object retention can be enabled only by creating// a bucket with SetObjectRetention set to true on the BucketHandle. It// cannot be modified once the bucket is created.// ObjectRetention cannot be configured or reported through the gRPC API.ObjectRetentionModestring// SoftDeletePolicy contains the bucket's soft delete policy, which defines// the period of time that soft-deleted objects will be retained, and cannot// be permanently deleted. By default, new buckets will be created with a// 7 day retention duration. In order to fully disable soft delete, you need// to set a policy with a RetentionDuration of 0.SoftDeletePolicy *SoftDeletePolicy// HierarchicalNamespace contains the bucket's hierarchical namespace// configuration. Hierarchical namespace enabled buckets can contain// [cloud.google.com/go/storage/control/apiv2/controlpb.Folder] resources.// It cannot be modified after bucket creation time.// UniformBucketLevelAccess must also also be enabled on the bucket.HierarchicalNamespace *HierarchicalNamespace// OwnerEntity contains entity information in the form "project-owner-projectId".OwnerEntitystring}

BucketAttrs represents the metadata for a Google Cloud Storage bucket.Read-only fields are ignored by BucketHandle.Create.

typeBucketAttrsToUpdate ¶

type BucketAttrsToUpdate struct {// If set, updates whether the bucket uses versioning.VersioningEnabledoptional.Bool// If set, updates whether the bucket is a Requester Pays bucket.RequesterPaysoptional.Bool// DefaultEventBasedHold is the default value for event-based hold on// newly created objects in this bucket.DefaultEventBasedHoldoptional.Bool// BucketPolicyOnly is an alias for UniformBucketLevelAccess. Use of// UniformBucketLevelAccess is recommended above the use of this field.// Setting BucketPolicyOnly.Enabled OR UniformBucketLevelAccess.Enabled to// true, will enable UniformBucketLevelAccess. If both BucketPolicyOnly and// UniformBucketLevelAccess are set, the value of UniformBucketLevelAccess// will take precedence.BucketPolicyOnly *BucketPolicyOnly// UniformBucketLevelAccess configures access checks to use only bucket-level IAM// policies and ignore any ACL rules for the bucket.// Seehttps://cloud.google.com/storage/docs/uniform-bucket-level-access// for more information.UniformBucketLevelAccess *UniformBucketLevelAccess// PublicAccessPrevention is the setting for the bucket's// PublicAccessPrevention policy, which can be used to prevent public access// of data in the bucket. See//https://cloud.google.com/storage/docs/public-access-prevention for more// information.PublicAccessPreventionPublicAccessPrevention// StorageClass is the default 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", "NEARLINE",// "COLDLINE" and "ARCHIVE". Defaults to "STANDARD".// Seehttps://cloud.google.com/storage/docs/storage-classes for all// valid values.StorageClassstring// If set, updates the retention policy of the bucket. Using// RetentionPolicy.RetentionPeriod = 0 will delete the existing policy.//// This feature is in private alpha release. It is not currently available to// most customers. It might be changed in backwards-incompatible ways and is not// subject to any SLA or deprecation policy.RetentionPolicy *RetentionPolicy// If set, replaces the CORS configuration with a new configuration.// An empty (rather than nil) slice causes all CORS policies to be removed.CORS []CORS// If set, replaces the encryption configuration of the bucket. Using// BucketEncryption.DefaultKMSKeyName = "" will delete the existing// configuration.Encryption *BucketEncryption// If set, replaces the lifecycle configuration of the bucket.Lifecycle *Lifecycle// If set, replaces the logging configuration of the bucket.Logging *BucketLogging// If set, replaces the website configuration of the bucket.Website *BucketWebsite// If not empty, applies a predefined set of access controls.// Seehttps://cloud.google.com/storage/docs/json_api/v1/buckets/patch.PredefinedACLstring// If not empty, applies a predefined set of default object access controls.// Seehttps://cloud.google.com/storage/docs/json_api/v1/buckets/patch.PredefinedDefaultObjectACLstring// RPO configures the Recovery Point Objective (RPO) policy of the bucket.// Set to RPOAsyncTurbo to turn on Turbo Replication for a bucket.// Seehttps://cloud.google.com/storage/docs/managing-turbo-replication for// more information.RPORPO// If set, updates the autoclass configuration of the bucket.// To disable autoclass on the bucket, set to an empty &Autoclass{}.// To update the configuration for Autoclass.TerminalStorageClass,// Autoclass.Enabled must also be set to true.// Seehttps://cloud.google.com/storage/docs/using-autoclass for more information.Autoclass *Autoclass// If set, updates the soft delete policy of the bucket.SoftDeletePolicy *SoftDeletePolicy// contains filtered or unexported fields}

BucketAttrsToUpdate define the attributes to update during an Update call.

func (*BucketAttrsToUpdate)DeleteLabel ¶

func (ua *BucketAttrsToUpdate) DeleteLabel(namestring)

DeleteLabel causes a label to be deleted when ua is used in acall to Bucket.Update.

func (*BucketAttrsToUpdate)SetLabel ¶

func (ua *BucketAttrsToUpdate) SetLabel(name, valuestring)

SetLabel causes a label to be added or modified when ua is usedin a call to Bucket.Update.

typeBucketConditions ¶

type BucketConditions struct {// MetagenerationMatch specifies that the bucket must have the given// metageneration for the operation to occur.// If MetagenerationMatch is zero, it has no effect.MetagenerationMatchint64// MetagenerationNotMatch specifies that the bucket must not have the given// metageneration for the operation to occur.// If MetagenerationNotMatch is zero, it has no effect.MetagenerationNotMatchint64}

BucketConditions constrain bucket methods to act on specific metagenerations.

The zero value is an empty set of constraints.

typeBucketEncryption ¶

type BucketEncryption struct {// A Cloud KMS key name, in the form// projects/P/locations/L/keyRings/R/cryptoKeys/K, that will be used to encrypt// objects inserted into this bucket, if no encryption method is specified.// The key's location must be the same as the bucket's.DefaultKMSKeyNamestring}

BucketEncryption is a bucket's encryption configuration.

typeBucketHandle ¶

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

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

Example (Exists)¶

package mainimport ("context""errors""fmt""cloud.google.com/go/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 errors.Is(err, storage.ErrBucketNotExist) {fmt.Println("The bucket does not exist")return}if err != nil {// TODO: handle error.}fmt.Printf("The bucket exists and has attributes: %#v\n", attrs)}

func (*BucketHandle)ACL ¶

func (b *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)AddNotification ¶

func (b *BucketHandle) AddNotification(ctxcontext.Context, n *Notification) (ret *Notification, errerror)

AddNotification adds a notification to b. You must set n's TopicProjectID, TopicIDand PayloadFormat, and must not set its ID. The other fields are all optional. Thereturned Notification's ID can be used to refer to it.Note: gRPC is not supported.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}b := client.Bucket("my-bucket")n, err := b.AddNotification(ctx, &storage.Notification{TopicProjectID: "my-project",TopicID:        "my-topic",PayloadFormat:  storage.JSONPayload,})if err != nil {// TODO: handle error.}fmt.Println(n.ID)}

func (*BucketHandle)Attrs ¶

func (b *BucketHandle) Attrs(ctxcontext.Context) (attrs *BucketAttrs, errerror)

Attrs returns the metadata for the bucket.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/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)}

func (*BucketHandle)BucketName ¶added inv1.42.0

func (b *BucketHandle) BucketName()string

BucketName returns the name of the bucket.

func (*BucketHandle)Create ¶

func (b *BucketHandle) Create(ctxcontext.Context, projectIDstring, attrs *BucketAttrs) (errerror)

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

Example¶

package mainimport ("context""cloud.google.com/go/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.}}

func (*BucketHandle)DefaultObjectACL ¶

func (b *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(ctxcontext.Context) (errerror)

Delete deletes the Bucket.

Example¶

package mainimport ("context""cloud.google.com/go/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.}}

func (*BucketHandle)DeleteNotification ¶

func (b *BucketHandle) DeleteNotification(ctxcontext.Context, idstring) (errerror)

DeleteNotification deletes the notification with the given ID.Note: gRPC is not supported.

Example¶

package mainimport ("context""cloud.google.com/go/storage")var notificationID stringfunc main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}b := client.Bucket("my-bucket")// TODO: Obtain notificationID from BucketHandle.AddNotification// or BucketHandle.Notifications.err = b.DeleteNotification(ctx, notificationID)if err != nil {// TODO: handle error.}}

func (*BucketHandle)GenerateSignedPostPolicyV4 ¶added inv1.19.0

func (b *BucketHandle) GenerateSignedPostPolicyV4(objectstring, opts *PostPolicyV4Options) (*PostPolicyV4,error)

GenerateSignedPostPolicyV4 generates a PostPolicyV4 value from bucket, object and opts.The generated URL and fields will then allow an unauthenticated client to perform multipart uploads.

This method requires the Expires field in the specified PostPolicyV4Optionsto be non-nil. You may need to set the GoogleAccessID and PrivateKey fieldsin some cases. Read more on theautomatic detection of credentials for this method.

To allow the unauthenticated client to upload to any object name in thebucket with a given prefix rather than a specific object name, you can passan empty string for object and setPostPolicyV4Options.Conditions toincludeConditionStartsWith("$key", "prefix").

func (*BucketHandle)IAM ¶

func (b *BucketHandle) IAM() *iam.Handle

IAM provides access to IAM access control for the bucket.

func (*BucketHandle)If ¶

func (b *BucketHandle) If(condsBucketConditions) *BucketHandle

If returns a new BucketHandle that applies a set of preconditions.Preconditions already set on the BucketHandle are ignored. The suppliedBucketConditions must have exactly one field set to a non-zero value;otherwise an error will be returned from any operation on the BucketHandle.Operations on the new handle will return an error if the preconditions are notsatisfied. The only valid preconditions for buckets are MetagenerationMatchand MetagenerationNotMatch.

func (*BucketHandle)LockRetentionPolicy ¶

func (b *BucketHandle) LockRetentionPolicy(ctxcontext.Context)error

LockRetentionPolicy locks a bucket's retention policy until a previously-configuredRetentionPeriod past the EffectiveTime. Note that if RetentionPeriod is set to lessthan a day, the retention policy is treated as a development configuration and lockingwill have no effect. The BucketHandle must have a metageneration condition thatmatches the bucket's metageneration. See BucketHandle.If.

This feature is in private alpha release. It is not currently available tomost customers. It might be changed in backwards-incompatible ways and is notsubject to any SLA or deprecation policy.

Example¶

package mainimport ("context""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}b := client.Bucket("my-bucket")attrs, err := b.Attrs(ctx)if err != nil {// TODO: handle error.}// Note that locking the bucket without first attaching a RetentionPolicy// that's at least 1 day is a no-operr = b.If(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).LockRetentionPolicy(ctx)if err != nil {// TODO: handle err}}

func (*BucketHandle)Notifications ¶

func (b *BucketHandle) Notifications(ctxcontext.Context) (n map[string]*Notification, errerror)

Notifications returns all the Notifications configured for this bucket, as a mapindexed by notification ID.Note: gRPC is not supported.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}b := client.Bucket("my-bucket")ns, err := b.Notifications(ctx)if err != nil {// TODO: handle error.}for id, n := range ns {fmt.Printf("%s: %+v\n", id, n)}}

func (*BucketHandle)Object ¶

func (b *BucketHandle) Object(namestring) *ObjectHandle

Object returns an ObjectHandle, which provides operations on the named object.This call does not perform any network operations such as fetching the object or verifying its existence.Use methods on ObjectHandle to perform network operations.

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

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

func (*BucketHandle)Objects ¶

func (b *BucketHandle) Objects(ctxcontext.Context, q *Query) *ObjectIterator

Objects returns an iterator over the objects in the bucket that match theQuery q. If q is nil, no filtering is done. Objects will be iterated overlexicographically by name.

Note: The returned iterator is not safe for concurrent operations without explicit synchronization.

Example¶

package mainimport ("context""cloud.google.com/go/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 iterator.Pager.}

func (*BucketHandle)Retryer ¶added inv1.19.0

func (b *BucketHandle) Retryer(opts ...RetryOption) *BucketHandle

Retryer returns a bucket handle that is configured with custom retrybehavior as specified by the options that are passed to it. All operationson the new handle will use the customized retry configuration.Retry options set on a object handle will take precedence over options set onthe bucket handle.These retry options will merge with the client's retry configuration (if set)for the returned handle. Options passed into this method will take precedenceover retry options on the client. Note that you must explicitly pass in eachoption you want to override.

func (*BucketHandle)SetObjectRetention ¶added inv1.36.0

func (b *BucketHandle) SetObjectRetention(enablebool) *BucketHandle

SetObjectRetention returns a new BucketHandle that will enable object retentionon bucket creation. To enable object retention, you must use the returnedhandle to create the bucket. This has no effect on an already existing bucket.ObjectRetention is not enabled by default.ObjectRetention cannot be configured through the gRPC API.

func (*BucketHandle)SignedURL ¶added inv1.18.0

func (b *BucketHandle) SignedURL(objectstring, opts *SignedURLOptions) (string,error)

This method requires the Method and Expires fields in the specifiedSignedURLOptions to be non-nil. You may need to set the GoogleAccessID andPrivateKey fields in some cases. Read more on theautomatic detection of credentialsfor this method.

func (*BucketHandle)Update ¶

func (b *BucketHandle) Update(ctxcontext.Context, uattrsBucketAttrsToUpdate) (attrs *BucketAttrs, errerror)

Update updates a bucket's attributes.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}// Enable versioning in the bucket, regardless of its previous value.attrs, err := client.Bucket("my-bucket").Update(ctx,storage.BucketAttrsToUpdate{VersioningEnabled: true})if err != nil {// TODO: handle error.}fmt.Println(attrs)}

Example (ReadModifyWrite)¶

If your update is based on the bucket's previous attributes, match themetageneration number to make sure the bucket hasn't changed since you read it.

package mainimport ("context""fmt""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}b := client.Bucket("my-bucket")attrs, err := b.Attrs(ctx)if err != nil {// TODO: handle error.}var au storage.BucketAttrsToUpdateau.SetLabel("lab", attrs.Labels["lab"]+"-more")if attrs.Labels["delete-me"] == "yes" {au.DeleteLabel("delete-me")}attrs, err = b.If(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).Update(ctx, au)if err != nil {// TODO: handle error.}fmt.Println(attrs)}

func (*BucketHandle)UserProject ¶

func (b *BucketHandle) UserProject(projectIDstring) *BucketHandle

UserProject returns a new BucketHandle that passes the project ID as the userproject for all subsequent calls. Calls with a user project will be billed to thatproject rather than to the bucket's owning project.

A user project is required for all operations on Requester Pays buckets.

typeBucketIterator ¶

type BucketIterator struct {// Prefix restricts the iterator to buckets whose names begin with it.Prefixstring// If true, the iterator will return a partial result of buckets even if// some buckets are unreachable. Call the Unreachable() method to retrieve the// list of unreachable buckets. By default (false), the iterator will return// an error if any buckets are unreachable.ReturnPartialSuccessbool// contains filtered or unexported fields}

A BucketIterator is an iterator over BucketAttrs.

Note: This iterator is not safe for concurrent operations without explicit synchronization.

func (*BucketIterator)Next ¶

func (it *BucketIterator) Next() (*BucketAttrs,error)

Next returns the next result. Its second return value is iterator.Done ifthere are no more results. Once Next returns iterator.Done, all subsequentcalls will return iterator.Done.

Note: This method is not safe for concurrent operations without explicit synchronization.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/storage""google.golang.org/api/iterator")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}it := client.Buckets(ctx, "my-project")for {bucketAttrs, err := it.Next()if err == iterator.Done {break}if err != nil {// TODO: Handle error.}fmt.Println(bucketAttrs)}}

func (*BucketIterator)PageInfo ¶

func (it *BucketIterator) PageInfo() *iterator.PageInfo

PageInfo supports pagination. See the google.golang.org/api/iterator package for details.

Note: This method is not safe for concurrent operations without explicit synchronization.

func (*BucketIterator)Unreachable ¶added inv1.58.0

func (it *BucketIterator) Unreachable() []string

Unreachable returns a list of bucket names that could not be reachedduring the iteration if ReturnPartialSuccess was set to true.

typeBucketLogging ¶

type BucketLogging struct {// The destination bucket where the current bucket's logs// should be placed.LogBucketstring// A prefix for log object names.LogObjectPrefixstring}

BucketLogging holds the bucket's logging configuration, which defines thedestination bucket and optional name prefix for the current bucket'slogs.

typeBucketPolicyOnly ¶

type BucketPolicyOnly struct {// Enabled specifies whether access checks use only bucket-level IAM// policies. Enabled may be disabled until the locked time.Enabledbool// LockedTime specifies the deadline for changing Enabled from true to// false.LockedTimetime.Time}

BucketPolicyOnly is an alias for UniformBucketLevelAccess.Use of UniformBucketLevelAccess is preferred above BucketPolicyOnly.

typeBucketWebsite ¶

type BucketWebsite struct {// If the requested object path is missing, the service will ensure the path has// a trailing '/', append this suffix, and attempt to retrieve the resulting// object. This allows the creation of index.html objects to represent directory// pages.MainPageSuffixstring// If the requested object path is missing, and any mainPageSuffix object is// missing, if applicable, the service will return the named object from this// bucket as the content for a 404 Not Found result.NotFoundPagestring}

BucketWebsite holds the bucket's website configuration, controlling how theservice behaves when accessing bucket contents as a web site. Seehttps://cloud.google.com/storage/docs/static-website for more information.

typeCORS ¶

type CORS struct {// MaxAge is the value to return in the Access-Control-Max-Age// header used in preflight responses.MaxAgetime.Duration// Methods is the list of HTTP methods on which to include CORS response// headers, (GET, OPTIONS, POST, etc) Note: "*" is permitted in the list// of methods, and means "any method".Methods []string// Origins is the list of Origins eligible to receive CORS response// headers. Note: "*" is permitted in the list of origins, and means// "any Origin".Origins []string// ResponseHeaders is the list of HTTP headers other than the simple// response headers to give permission for the user-agent to share// across domains.ResponseHeaders []string}

CORS is the bucket's Cross-Origin Resource Sharing (CORS) configuration.

typeClient ¶

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

Client is a client for interacting with Google Cloud Storage.

Clients should be reused instead of created as needed.The methods of Client are safe for concurrent use by multiple goroutines.

funcNewClient ¶

func NewClient(ctxcontext.Context, opts ...option.ClientOption) (*Client,error)

NewClient creates a new Google Cloud Storage client using the HTTP transport.The default scope is ScopeFullControl. To use a different scope, likeScopeReadOnly, use option.WithScopes.

Clients should be reused instead of created as needed. The methods of Clientare safe for concurrent use by multiple goroutines.

You may configure the client by passing in options from thegoogle.golang.org/api/optionpackage. You may also use options defined in this package, such asWithJSONReads.

Example¶

package mainimport ("context""cloud.google.com/go/storage")func main() {ctx := context.Background()// Use Google Application Default Credentials to authorize and authenticate the client.// More information about Application Default Credentials and how to enable is at// https://developers.google.com/identity/protocols/application-default-credentials.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.}}

Example (Unauthenticated)¶

This example shows how to create an unauthenticated client, whichcan be used to access public data.

package mainimport ("context""cloud.google.com/go/storage""google.golang.org/api/option")func main() {ctx := context.Background()client, err := storage.NewClient(ctx, option.WithoutAuthentication())if err != nil {// TODO: handle error.}// Use the client.// Close the client when finished.if err := client.Close(); err != nil {// TODO: handle error.}}

funcNewGRPCClient ¶added inv1.33.0

func NewGRPCClient(ctxcontext.Context, opts ...option.ClientOption) (*Client,error)

NewGRPCClient creates a new Storage client using the gRPC transport and API.Client methods which have not been implemented in gRPC will return an error.In particular, methods for Cloud Pub/Sub notifications, Service Account HMACkeys, and ServiceAccount are not supported.Using a non-default universe domain is also not supported with the StoragegRPC client.

Clients should be reused instead of created as needed. The methods of Clientare safe for concurrent use by multiple goroutines.

You may configure the client by passing in options from thegoogle.golang.org/api/optionpackage.

func (*Client)Bucket ¶

func (c *Client) Bucket(namestring) *BucketHandle

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

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

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

func (*Client)Buckets ¶

func (c *Client) Buckets(ctxcontext.Context, projectIDstring) *BucketIterator

Buckets returns an iterator over the buckets in the project. You mayoptionally set the iterator's Prefix field to restrict the list to bucketswhose names begin with the prefix. By default, all buckets in the projectare returned.

To receive a partial list of buckets when some are unavailable, set theiterator's ReturnPartialSuccess field to true. You can then call theiterator's Unreachable method to retrieve the names of the unreachablebuckets.

Note: The returned iterator is not safe for concurrent operations without explicit synchronization.

Example¶

package mainimport ("context""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}it := client.Buckets(ctx, "my-project")_ = it // TODO: iterate using Next or iterator.Pager.}

func (*Client)Close ¶

func (c *Client) Close()error

Close closes the Client.

Close need not be called at program exit.

func (*Client)CreateHMACKey ¶

func (c *Client) CreateHMACKey(ctxcontext.Context, projectID, serviceAccountEmailstring, opts ...HMACKeyOption) (*HMACKey,error)

CreateHMACKey invokes an RPC for Google Cloud Storage to create a new HMACKey.Note: gRPC is not supported.

Example¶

package mainimport ("context""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}hkey, err := client.CreateHMACKey(ctx, "project-id", "service-account-email")if err != nil {// TODO: handle error.}_ = hkey // TODO: Use the HMAC Key.}

func (*Client)HMACKeyHandle ¶

func (c *Client) HMACKeyHandle(projectID, accessIDstring) *HMACKeyHandle

HMACKeyHandle creates a handle that will be used for HMACKey operations.

func (*Client)ListHMACKeys ¶

func (c *Client) ListHMACKeys(ctxcontext.Context, projectIDstring, opts ...HMACKeyOption) *HMACKeysIterator

ListHMACKeys returns an iterator for listing HMACKeys.

Note: This iterator is not safe for concurrent operations without explicit synchronization.Note: gRPC is not supported.

Example¶

package mainimport ("context""cloud.google.com/go/storage""google.golang.org/api/iterator")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}iter := client.ListHMACKeys(ctx, "project-id")for {key, err := iter.Next()if err == iterator.Done {break}if err != nil {// TODO: handle error.}_ = key // TODO: Use the key.}}

Example (ForServiceAccountEmail)¶

package mainimport ("context""cloud.google.com/go/storage""google.golang.org/api/iterator")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}iter := client.ListHMACKeys(ctx, "project-id", storage.ForHMACKeyServiceAccountEmail("service@account.email"))for {key, err := iter.Next()if err == iterator.Done {break}if err != nil {// TODO: handle error.}_ = key // TODO: Use the key.}}

Example (ShowDeletedKeys)¶

package mainimport ("context""cloud.google.com/go/storage""google.golang.org/api/iterator")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}iter := client.ListHMACKeys(ctx, "project-id", storage.ShowDeletedHMACKeys())for {key, err := iter.Next()if err == iterator.Done {break}if err != nil {// TODO: handle error.}_ = key // TODO: Use the key.}}

func (*Client)ServiceAccount ¶

func (c *Client) ServiceAccount(ctxcontext.Context, projectIDstring) (string,error)

ServiceAccount fetches the email address of the given project's Google Cloud Storage service account.Note: gRPC is not supported.

func (*Client)SetRetry ¶added inv1.19.0

func (c *Client) SetRetry(opts ...RetryOption)

SetRetry configures the client with custom retry behavior as specified by theoptions that are passed to it. All operations using this client will use thecustomized retry configuration.This should be called once before using the client for network operations, asthere could be indeterminate behaviour with operations in progress.Retry options set on a bucket or object handle will take precedence overthese options.

typeComposer ¶

type Composer struct {// ObjectAttrs are optional attributes to set on the destination object.// Any attributes must be initialized before any calls on the Composer. Nil// or zero-valued attributes are ignored.ObjectAttrs// SendCRC specifies whether to transmit a CRC32C field. It should be set// to true in addition to setting the Composer's CRC32C field, because zero// is a valid CRC and normally a zero would not be transmitted.// If a CRC32C is sent, and the data in the destination object does not match// the checksum, the compose will be rejected.SendCRC32Cbool// contains filtered or unexported fields}

A Composer composes source objects into a destination object.

For Requester Pays buckets, the user project of dst is billed.

func (*Composer)Run ¶

func (c *Composer) Run(ctxcontext.Context) (attrs *ObjectAttrs, errerror)

Run performs the compose operation.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}bkt := client.Bucket("bucketname")src1 := bkt.Object("o1")src2 := bkt.Object("o2")dst := bkt.Object("o3")// Compose and modify metadata.c := dst.ComposerFrom(src1, src2)c.ContentType = "text/plain"// Set the expected checksum for the destination object to be validated by// the backend (if desired).c.CRC32C = 42c.SendCRC32C = trueattrs, err := c.Run(ctx)if err != nil {// TODO: Handle error.}fmt.Println(attrs)// Just compose.attrs, err = dst.ComposerFrom(src1, src2).Run(ctx)if err != nil {// TODO: Handle error.}fmt.Println(attrs)}

typeConditions ¶

type Conditions struct {// GenerationMatch specifies that the object must have the given generation// for the operation to occur.// If GenerationMatch is zero, it has no effect.// Use DoesNotExist to specify that the object does not exist in the bucket.GenerationMatchint64// GenerationNotMatch specifies that the object must not have the given// generation for the operation to occur.// If GenerationNotMatch is zero, it has no effect.// This condition only works for object reads if the WithJSONReads client// option is set.GenerationNotMatchint64// DoesNotExist specifies that the object must not exist in the bucket for// the operation to occur.// If DoesNotExist is false, it has no effect.DoesNotExistbool// MetagenerationMatch specifies that the object must have the given// metageneration for the operation to occur.// If MetagenerationMatch is zero, it has no effect.MetagenerationMatchint64// MetagenerationNotMatch specifies that the object must not have the given// metageneration for the operation to occur.// If MetagenerationNotMatch is zero, it has no effect.// This condition only works for object reads if the WithJSONReads client// option is set.MetagenerationNotMatchint64}

Conditions constrain methods to act on specific generations ofobjects.

The zero value is an empty set of constraints. Not all conditions orcombinations of conditions are applicable to all methods.Seehttps://cloud.google.com/storage/docs/generations-preconditionsfor details on how these operate.

typeCopier ¶

type Copier struct {// ObjectAttrs are optional attributes to set on the destination object.// Any attributes must be initialized before any calls on the Copier. Nil// or zero-valued attributes are ignored.ObjectAttrs// RewriteToken can be set before calling Run to resume a copy// operation. After Run returns a non-nil error, RewriteToken will// have been updated to contain the value needed to resume the copy.RewriteTokenstring// ProgressFunc can be used to monitor the progress of a multi-RPC copy// operation. If ProgressFunc is not nil and copying requires multiple// calls to the underlying service (see//https://cloud.google.com/storage/docs/json_api/v1/objects/rewrite), then// ProgressFunc will be invoked after each call with the number of bytes of// content copied so far and the total size in bytes of the source object.//// ProgressFunc is intended to make upload progress available to the// application. For example, the implementation of ProgressFunc may update// a progress bar in the application's UI, or log the result of// float64(copiedBytes)/float64(totalBytes).//// ProgressFunc should return quickly without blocking.ProgressFunc func(copiedBytes, totalBytesuint64)// The Cloud KMS key, in the form projects/P/locations/L/keyRings/R/cryptoKeys/K,// that will be used to encrypt the object. Overrides the object's KMSKeyName, if// any.//// Providing both a DestinationKMSKeyName and a customer-supplied encryption key// (via ObjectHandle.Key) on the destination object will result in an error when// Run is called.DestinationKMSKeyNamestring// contains filtered or unexported fields}

A Copier copies a source object to a destination.

func (*Copier)Run ¶

func (c *Copier) Run(ctxcontext.Context) (attrs *ObjectAttrs, errerror)

Run performs the copy.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/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")// Copy content and modify metadata.copier := dst.CopierFrom(src)copier.ContentType = "text/plain"attrs, err := copier.Run(ctx)if err != nil {// TODO: Handle error, possibly resuming with copier.RewriteToken.}fmt.Println(attrs)// Just copy content.attrs, err = dst.CopierFrom(src).Run(ctx)if err != nil {// TODO: Handle error. No way to resume.}fmt.Println(attrs)}

Example (Progress)¶

package mainimport ("context""log""cloud.google.com/go/storage")func main() {// Display progress across multiple rewrite RPCs.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")copier := dst.CopierFrom(src)copier.ProgressFunc = func(copiedBytes, totalBytes uint64) {log.Printf("copy %.1f%% done", float64(copiedBytes)/float64(totalBytes)*100)}if _, err := copier.Run(ctx); err != nil {// TODO: handle error.}}

typeCustomPlacementConfig ¶added inv1.24.0

type CustomPlacementConfig struct {// The list of regional locations in which data is placed.// Custom Dual Regions require exactly 2 regional locations.DataLocations []string}

CustomPlacementConfig holds the bucket's custom placementconfiguration for Custom Dual Regions. Seehttps://cloud.google.com/storage/docs/locations#location-dr for more information.

typeHMACKey ¶

type HMACKey struct {// The HMAC's secret key.Secretstring// AccessID is the ID of the HMAC key.AccessIDstring// Etag is the HTTP/1.1 Entity tag.Etagstring// ID is the ID of the HMAC key, including the ProjectID and AccessID.IDstring// ProjectID is the ID of the project that owns the// service account to which the key authenticates.ProjectIDstring// ServiceAccountEmail is the email address// of the key's associated service account.ServiceAccountEmailstring// CreatedTime is the creation time of the HMAC key.CreatedTimetime.Time// UpdatedTime is the last modification time of the HMAC key metadata.UpdatedTimetime.Time// State is the state of the HMAC key.// It can be one of StateActive, StateInactive or StateDeleted.StateHMACState}

HMACKey is the representation of a Google Cloud Storage HMAC key.

HMAC keys are used to authenticate signed access to objects. To enable HMAC keyauthentication, please visithttps://cloud.google.com/storage/docs/migrating.

typeHMACKeyAttrsToUpdate ¶

type HMACKeyAttrsToUpdate struct {// State is required and must be either StateActive or StateInactive.StateHMACState// Etag is an optional field and it is the HTTP/1.1 Entity tag.Etagstring}

HMACKeyAttrsToUpdate defines the attributes of an HMACKey that will be updated.

typeHMACKeyHandle ¶

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

HMACKeyHandle helps provide access and management for HMAC keys.

func (*HMACKeyHandle)Delete ¶

func (hkh *HMACKeyHandle) Delete(ctxcontext.Context, opts ...HMACKeyOption)error

Delete invokes an RPC to delete the key referenced by accessID, on Google Cloud Storage.Only inactive HMAC keys can be deleted.After deletion, a key cannot be used to authenticate requests.Note: gRPC is not supported.

Example¶

package mainimport ("context""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}hkh := client.HMACKeyHandle("project-id", "access-key-id")// Make sure that the HMACKey being deleted has a status of inactive.if err := hkh.Delete(ctx); err != nil {// TODO: handle error.}}

func (*HMACKeyHandle)Get ¶

func (hkh *HMACKeyHandle) Get(ctxcontext.Context, opts ...HMACKeyOption) (*HMACKey,error)

Get invokes an RPC to retrieve the HMAC key referenced by theHMACKeyHandle's accessID.

Options such as UserProjectForHMACKeys can be used to set theuserProject to be billed against for operations.Note: gRPC is not supported.

Example¶

package mainimport ("context""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}hkh := client.HMACKeyHandle("project-id", "access-key-id")hkey, err := hkh.Get(ctx)if err != nil {// TODO: handle error.}_ = hkey // TODO: Use the HMAC Key.}

func (*HMACKeyHandle)Update ¶

func (h *HMACKeyHandle) Update(ctxcontext.Context, auHMACKeyAttrsToUpdate, opts ...HMACKeyOption) (*HMACKey,error)

Update mutates the HMACKey referred to by accessID.Note: gRPC is not supported.

Example¶

package mainimport ("context""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}hkh := client.HMACKeyHandle("project-id", "access-key-id")ukey, err := hkh.Update(ctx, storage.HMACKeyAttrsToUpdate{State: storage.Inactive,})if err != nil {// TODO: handle error.}_ = ukey // TODO: Use the HMAC Key.}

typeHMACKeyOption ¶

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

HMACKeyOption configures the behavior of HMACKey related methods and actions.

funcForHMACKeyServiceAccountEmail ¶

func ForHMACKeyServiceAccountEmail(serviceAccountEmailstring)HMACKeyOption

ForHMACKeyServiceAccountEmail returns HMAC Keys that areassociated with the email address of a service account in the project.

Only one service account email can be used as a filter, so if multipleof these options are applied, the last email to be set will be used.

funcShowDeletedHMACKeys ¶

func ShowDeletedHMACKeys()HMACKeyOption

ShowDeletedHMACKeys will also list keys whose state is "DELETED".

funcUserProjectForHMACKeys ¶added inv1.1.0

func UserProjectForHMACKeys(userProjectIDstring)HMACKeyOption

UserProjectForHMACKeys will bill the request against userProjectIDif userProjectID is non-empty.

Note: This is a noop right now and only provided for API compatibility.

typeHMACKeysIterator ¶

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

An HMACKeysIterator is an iterator over HMACKeys.

Note: This iterator is not safe for concurrent operations without explicit synchronization.

func (*HMACKeysIterator)Next ¶

func (it *HMACKeysIterator) Next() (*HMACKey,error)

Next returns the next result. Its second return value is iterator.Done ifthere are no more results. Once Next returns iterator.Done, all subsequentcalls will return iterator.Done.

Note: This iterator is not safe for concurrent operations without explicit synchronization.

func (*HMACKeysIterator)PageInfo ¶

func (it *HMACKeysIterator) PageInfo() *iterator.PageInfo

PageInfo supports pagination. See the google.golang.org/api/iterator package for details.

Note: This iterator is not safe for concurrent operations without explicit synchronization.

typeHMACState ¶

type HMACStatestring

HMACState is the state of the HMAC key.

const (// Active is the status for an active key that can be used to sign// requests.ActiveHMACState = "ACTIVE"// Inactive is the status for an inactive key thus requests signed by// this key will be denied.InactiveHMACState = "INACTIVE"// Deleted is the status for a key that is deleted.// Once in this state the key cannot key cannot be recovered// and does not count towards key limits. Deleted keys will be cleaned// up later.DeletedHMACState = "DELETED")

typeHierarchicalNamespace ¶added inv1.42.0

type HierarchicalNamespace struct {// Enabled indicates whether hierarchical namespace features are enabled on// the bucket. This can only be set at bucket creation time currently.Enabledbool}

HierarchicalNamespace contains the bucket's hierarchical namespaceconfiguration. Hierarchical namespace enabled buckets can containcloud.google.com/go/storage/control/apiv2/controlpb.Folder resources.

typeLifecycle ¶

type Lifecycle struct {Rules []LifecycleRule}

Lifecycle is the lifecycle configuration for objects in the bucket.

typeLifecycleAction ¶

type LifecycleAction struct {// Type is the type of action to take on matching objects.//// Acceptable values are storage.DeleteAction, storage.SetStorageClassAction,// and storage.AbortIncompleteMPUAction.Typestring// StorageClass is the storage class to set on matching objects if the Action// is "SetStorageClass".StorageClassstring}

LifecycleAction is a lifecycle configuration action.

typeLifecycleCondition ¶

type LifecycleCondition struct {// AllObjects is used to select all objects in a bucket by// setting AgeInDays to 0.AllObjectsbool// AgeInDays is the age of the object in days.// If you want to set AgeInDays to `0` use AllObjects set to `true`.AgeInDaysint64// CreatedBefore is the time the object was created.//// This condition is satisfied when an object is created before midnight of// the specified date in UTC.CreatedBeforetime.Time// CustomTimeBefore is the CustomTime metadata field of the object. This// condition is satisfied when an object's CustomTime timestamp is before// midnight of the specified date in UTC.//// This condition can only be satisfied if CustomTime has been set.CustomTimeBeforetime.Time// DaysSinceCustomTime is the days elapsed since the CustomTime date of the// object. This condition can only be satisfied if CustomTime has been set.// Note: Using `0` as the value will be ignored by the library and not sent to the API.DaysSinceCustomTimeint64// DaysSinceNoncurrentTime is the days elapsed since the noncurrent timestamp// of the object. This condition is relevant only for versioned objects.// Note: Using `0` as the value will be ignored by the library and not sent to the API.DaysSinceNoncurrentTimeint64// Liveness specifies the object's liveness. Relevant only for versioned objectsLivenessLiveness// MatchesPrefix is the condition matching an object if any of the// matches_prefix strings are an exact prefix of the object's name.MatchesPrefix []string// MatchesStorageClasses is the condition matching the object's storage// class.//// Values include "STANDARD", "NEARLINE", "COLDLINE" and "ARCHIVE".MatchesStorageClasses []string// MatchesSuffix is the condition matching an object if any of the// matches_suffix strings are an exact suffix of the object's name.MatchesSuffix []string// NoncurrentTimeBefore is the noncurrent timestamp of the object. This// condition is satisfied when an object's noncurrent timestamp is before// midnight of the specified date in UTC.//// This condition is relevant only for versioned objects.NoncurrentTimeBeforetime.Time// NumNewerVersions is the condition matching objects with a number of newer versions.//// If the value is N, this condition is satisfied when there are at least N// versions (including the live version) newer than this version of the// object.// Note: Using `0` as the value will be ignored by the library and not sent to the API.NumNewerVersionsint64}

LifecycleCondition is a set of conditions used to match objects and take anaction automatically.

All configured conditions must be met for the associated action to be taken.

typeLifecycleRule ¶

type LifecycleRule struct {// Action is the action to take when all of the associated conditions are// met.ActionLifecycleAction// Condition is the set of conditions that must be met for the associated// action to be taken.ConditionLifecycleCondition}

LifecycleRule is a lifecycle configuration rule.

When all the configured conditions are met by an object in the bucket, theconfigured action will automatically be taken on that object.

typeLiveness ¶

type Livenessint

Liveness specifies whether the object is live or not.

const (// LiveAndArchived includes both live and archived objects.LiveAndArchivedLiveness =iota// Live specifies that the object is still live.Live// Archived specifies that the object is archived.Archived)

typeMoveObjectDestination ¶added inv1.49.0

type MoveObjectDestination struct {ObjectstringConditions *Conditions}

MoveObjectDestination provides the destination object name and (optional) preconditionsforObjectHandle.Move.

typeMultiRangeDownloader ¶added inv1.50.0

type MultiRangeDownloader struct {// Attrs is populated when NewMultiRangeDownloader returns.AttrsReaderObjectAttrs// contains filtered or unexported fields}

MultiRangeDownloader reads a Cloud Storage object.

Typically, a MultiRangeDownloader opens a stream to which we can adddifferent ranges to read from the object.

This API is currently in preview and is not yet available for general use.

Example¶

package mainimport ("bytes""context""errors""fmt""log""sync""cloud.google.com/go/storage""cloud.google.com/go/storage/experimental")func main() {ctx := context.Background()// NewMultiRangeDownloader is only available on gRPC.client, err := storage.NewGRPCClient(ctx, experimental.WithGRPCBidiReads())if err != nil {// TODO: handle error.}defer client.Close()obj := client.Bucket("my-bucket").Object("my-object")// The MultiRangeDownloader is the most asynchronous method for downloading// ranges. A callback is invoked for each downloaded range.mrd, err := obj.NewMultiRangeDownloader(ctx)if err != nil {// TODO: handle error.}// Use a WaitGroup to wait for the error collector goroutine.var wg sync.WaitGroupwg.Add(1)var rangeErrs []errorerrChan := make(chan error)// Goroutine to collect errors from the channel.go func() {defer wg.Done()for err := range errChan {rangeErrs = append(rangeErrs, err)}}()// Callback registered by user to be called upon completion of a range.callback := func(offset, length int64, err error) {if err != nil {errChan <- err}}// User creates an io.Writer (e.g. a buffer) and adds it to the// MultiRangeDownloader with a particular range. Data will be downloaded// into the buffer.b1 := new(bytes.Buffer)mrd.Add(b1, 0, 100, callback)b2 := new(bytes.Buffer)mrd.Add(b2, 200, 100, callback)// Wait for all downloads to complete.mrd.Wait()if err := mrd.Close(); err != nil {// TODO: handle error on close.}// Close the channel to signal the collector to stop.close(errChan)// Wait for the collector to finish draining the channel.wg.Wait()if len(rangeErrs) > 0 {// TODO: handle error from the range download.log.Printf("received errors: %s", errors.Join(rangeErrs...))}fmt.Printf("Downloaded %d bytes to first buffer: %s\n", b1.Len(), b1.String())fmt.Printf("Downloaded %d bytes to second buffer: %s\n", b2.Len(), b2.String())}

func (*MultiRangeDownloader)Add ¶added inv1.50.0

func (mrd *MultiRangeDownloader) Add(outputio.Writer, offset, lengthint64, callback func(int64,int64,error))

Add adds a new range to MultiRangeDownloader.

The offset for the first byte to return in the read, relative to the startof the object.

A negative offset value will be interpreted as the number of bytes from theend of the object to be returned. Requesting a negative offset with magnitudelarger than the size of the object will return the entire object.

An offset larger than the size of the object returns an OutOfRange error viathe callback and enters a permanent error state. All subsequent calls to Closewill return this same error.

A limit of zero indicates that there is no limit, and a negative limit willcause an error.

This will initiate the read range but is non-blocking; call callback toprocess the result. Add is thread-safe and can be called simultaneouslyfrom different goroutines.

Callback will be called with the offset, length of data read, and errorof the read. Note that the length of the data read may be less than therequested length if the end of the object is reached.

func (*MultiRangeDownloader)Close ¶added inv1.50.0

func (mrd *MultiRangeDownloader) Close()error

Close the MultiRangeDownloader. It must be called when done reading.Adding new ranges after this has been called will cause an error.

This will immediately close the stream and can result in a"stream closed early" error if a response for a range is still not processed.CallMultiRangeDownloader.Wait to avoid this error.

If the downloader is in a permanent error state, this will return an error.

func (*MultiRangeDownloader)Error ¶added inv1.52.0

func (mrd *MultiRangeDownloader) Error()error

Error returns an error if the MultiRangeDownloader is in a permanent failurestate. It returns a nil error if the MultiRangeDownloader is open and can beused.

func (*MultiRangeDownloader)GetHandle ¶added inv1.50.0

func (mrd *MultiRangeDownloader) GetHandle() []byte

GetHandle returns the read handle. This can be used to further speed up thefollow up read if the same object is read through a different stream.

func (*MultiRangeDownloader)Wait ¶added inv1.50.0

func (mrd *MultiRangeDownloader) Wait()

Wait for all the responses to process on the stream.Adding new ranges after this has been called will cause an error.Wait will wait for all callbacks to finish.

typeNotification ¶

type Notification struct {//The ID of the notification.IDstring// The ID of the topic to which this subscription publishes.TopicIDstring// The ID of the project to which the topic belongs.TopicProjectIDstring// Only send notifications about listed event types. If empty, send notifications// for all event types.// Seehttps://cloud.google.com/storage/docs/pubsub-notifications#events.EventTypes []string// If present, only apply this notification configuration to object names that// begin with this prefix.ObjectNamePrefixstring// An optional list of additional attributes to attach to each Cloud PubSub// message published for this notification subscription.CustomAttributes map[string]string// The contents of the message payload.// Seehttps://cloud.google.com/storage/docs/pubsub-notifications#payload.PayloadFormatstring}

A Notification describes how to send Cloud PubSub messages when certainevents occur in a bucket.

typeObjectAttrs ¶

type ObjectAttrs struct {// Bucket is the name of the bucket containing this GCS object.// This field is read-only.Bucketstring// Name is the name of the object within the bucket.// This field is read-only.Namestring// ContentType is the MIME type of the object's content.ContentTypestring// ContentLanguage is the content language of the object's content.ContentLanguagestring// CacheControl is the Cache-Control header to be sent in the response// headers when serving the object data.CacheControlstring// EventBasedHold specifies whether an object is under event-based hold. New// objects created in a bucket whose DefaultEventBasedHold is set will// default to that value.EventBasedHoldbool// TemporaryHold specifies whether an object is under temporary hold. While// this flag is set to true, the object is protected against deletion and// overwrites.TemporaryHoldbool// RetentionExpirationTime is a server-determined value that specifies the// earliest time that the object's retention period expires.// This is a read-only field.RetentionExpirationTimetime.Time// ACL is the list of access control rules for the object.ACL []ACLRule// If not empty, applies a predefined set of access controls. It should be set// only when writing, copying or composing an object. When copying or composing,// it acts as the destinationPredefinedAcl parameter.// PredefinedACL is always empty for ObjectAttrs returned from the service.// Seehttps://cloud.google.com/storage/docs/json_api/v1/objects/insert// for valid values.PredefinedACLstring// Owner is the owner of the object. This field is read-only.//// If non-zero, it is in the form of "user-<userId>".Ownerstring// Size is the length of the object's content. This field is read-only.Sizeint64// ContentEncoding is the encoding of the object's content.ContentEncodingstring// ContentDisposition is the optional Content-Disposition header of the object// sent in the response headers.ContentDispositionstring// MD5 is the MD5 hash of the object's content. This field is read-only,// except when used from a Writer. If set on a Writer, the uploaded// data is rejected if its MD5 hash does not match this field.MD5 []byte// CRC32C is the CRC32 checksum of the object's content using the Castagnoli93// polynomial. This field is read-only, except when used from a Writer or// Composer. In those cases, if the SendCRC32C field in the Writer or Composer// is set to is true, the uploaded data is rejected if its CRC32C hash does// not match this field.//// Note: For a Writer, SendCRC32C must be set to true BEFORE the first call to// Writer.Write() in order to send the checksum.CRC32Cuint32// MediaLink is an URL to the object's content. This field is read-only.MediaLinkstring// Metadata represents user-provided metadata, in key/value pairs.// It can be nil if no metadata is provided.//// For object downloads using Reader, metadata keys are sent as headers.// Therefore, avoid setting metadata keys using characters that are not valid// for headers. Seehttps://www.rfc-editor.org/rfc/rfc7230#section-3.2.6.Metadata map[string]string// Generation is the generation number of the object's content.// This field is read-only.Generationint64// 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.Metagenerationint64// StorageClass is the storage class of the object. This defines// how objects are stored and determines the SLA and the cost of storage.// Typical values are "STANDARD", "NEARLINE", "COLDLINE" and "ARCHIVE".// Defaults to "STANDARD".// Seehttps://cloud.google.com/storage/docs/storage-classes for all// valid values.StorageClassstring// Created is the time the object was created. This field is read-only.Createdtime.Time// Finalized is the time the object contents were finalized. This may differ// from Created for appendable objects. This field is read-only.Finalizedtime.Time// Deleted is the time the object was deleted.// If not deleted, it is the zero value. This field is read-only.Deletedtime.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.Updatedtime.Time// CustomerKeySHA256 is the base64-encoded SHA-256 hash of the// customer-supplied encryption key for the object. It is empty if there is// no customer-supplied encryption key.// See //https://cloud.google.com/storage/docs/encryption for more about// encryption in Google Cloud Storage.CustomerKeySHA256string// Cloud KMS key name, in the form// projects/P/locations/L/keyRings/R/cryptoKeys/K, used to encrypt this object,// if the object is encrypted by such a key.//// Providing both a KMSKeyName and a customer-supplied encryption key (via// ObjectHandle.Key) will result in an error when writing an object.KMSKeyNamestring// Prefix is set only for ObjectAttrs which represent synthetic "directory// entries" when iterating over buckets using Query.Delimiter. See// ObjectIterator.Next. When set, no other fields in ObjectAttrs will be// populated.Prefixstring// Etag is the HTTP/1.1 Entity tag for the object.// This field is read-only.Etagstring// A user-specified timestamp which can be applied to an object. This is// typically set in order to use the CustomTimeBefore and DaysSinceCustomTime// LifecycleConditions to manage object lifecycles.//// CustomTime cannot be removed once set on an object. It can be updated to a// later value but not to an earlier one. For more information see//https://cloud.google.com/storage/docs/metadata#custom-time .CustomTimetime.Time// ComponentCount is the number of objects contained within a composite object.// For non-composite objects, the value will be zero.// This field is read-only.ComponentCountint64// Retention contains the retention configuration for this object.// ObjectRetention cannot be configured or reported through the gRPC API.Retention *ObjectRetention// SoftDeleteTime is the time when the object became soft-deleted.// Soft-deleted objects are only accessible on an object handle returned by// ObjectHandle.SoftDeleted; if ObjectHandle.SoftDeleted has not been set,// ObjectHandle.Attrs will return ErrObjectNotExist if the object is soft-deleted.// This field is read-only.SoftDeleteTimetime.Time// HardDeleteTime is the time when the object will be permanently deleted.// Only set when an object becomes soft-deleted with a soft delete policy.// Soft-deleted objects are only accessible on an object handle returned by// ObjectHandle.SoftDeleted; if ObjectHandle.SoftDeleted has not been set,// ObjectHandle.Attrs will return ErrObjectNotExist if the object is soft-deleted.// This field is read-only.HardDeleteTimetime.Time// Contexts store custom key-value metadata that the user could// annotate object with. These key-value pairs can be used to filter objects// during list calls. Seehttps://cloud.google.com/storage/docs/object-contexts// for more details.Contexts *ObjectContexts}

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

typeObjectAttrsToUpdate ¶

type ObjectAttrsToUpdate struct {EventBasedHoldoptional.BoolTemporaryHoldoptional.BoolContentTypeoptional.StringContentLanguageoptional.StringContentEncodingoptional.StringContentDispositionoptional.StringCacheControloptional.StringCustomTimetime.Time// Cannot be deleted or backdated from its current value.Metadata           map[string]string// Set to map[string]string{} to delete.ACL                []ACLRule// If not empty, applies a predefined set of access controls. ACL must be nil.// Seehttps://cloud.google.com/storage/docs/json_api/v1/objects/patch.PredefinedACLstring// Retention contains the retention configuration for this object.// Operations other than setting the retention for the first time or// extending the RetainUntil time on the object retention must be done// on an ObjectHandle with OverrideUnlockedRetention set to true.Retention *ObjectRetention// Contexts allows adding, modifying, or deleting individual object contexts.// To add or modify a context, set the value field in ObjectCustomContextPayload.// To delete a context, set the Delete field in ObjectCustomContextPayload to true.// To remove all contexts, pass Custom as an empty map in Contexts. Passing nil Custom// map will be no-op.Contexts *ObjectContexts}

ObjectAttrsToUpdate is used to update the attributes of an object.Only fields set to non-nil values will be updated.For all fields except CustomTime and Retention, set the field to its zerovalue to delete it. CustomTime cannot be deleted or changed to an earliertime once set. Retention can be deleted (only if the Mode is Unlocked) bysetting it to an empty value (not nil).

For example, to change ContentType and delete ContentEncoding, Metadata andRetention, use:

ObjectAttrsToUpdate{    ContentType: "text/html",    ContentEncoding: "",    Metadata: map[string]string{},    Retention: &ObjectRetention{},}

typeObjectContexts ¶added inv1.58.0

type ObjectContexts struct {Custom map[string]ObjectCustomContextPayload}

ObjectContexts is a container for custom object contexts.

typeObjectCustomContextPayload ¶added inv1.58.0

type ObjectCustomContextPayload struct {ValuestringDeletebool// Read-only fields. Any updates to CreateTime and UpdateTime will be ignored.// These fields are handled by the server.CreateTimetime.TimeUpdateTimetime.Time}

ObjectCustomContextPayload holds the value of a user-defined object context andother metadata. To delete a key from Custom object contexts, set Delete as true.

typeObjectHandle ¶

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.

Example (Exists)¶

package mainimport ("context""errors""fmt""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}attrs, err := client.Bucket("my-bucket").Object("my-object").Attrs(ctx)if errors.Is(err, storage.ErrObjectNotExist) {fmt.Println("The object does not exist")return}if err != nil {// TODO: handle error.}fmt.Printf("The object exists and has attributes: %#v\n", attrs)}

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(ctxcontext.Context) (attrs *ObjectAttrs, errerror)

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

Example¶

package mainimport ("context""fmt""cloud.google.com/go/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)}

Example (WithConditions)¶

package mainimport ("context""fmt""time""cloud.google.com/go/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.Generation(objAttrs1.Generation).Attrs(ctx)if err != nil {// TODO: handle error.}fmt.Println(objAttrs1, objAttrs2)}

func (*ObjectHandle)BucketName ¶

func (o *ObjectHandle) BucketName()string

BucketName returns the name of the bucket.

func (*ObjectHandle)ComposerFrom ¶

func (dst *ObjectHandle) ComposerFrom(srcs ...*ObjectHandle) *Composer

ComposerFrom creates a Composer that can compose srcs into dst.You can immediately call Run on the returned Composer, or you canconfigure it first.

The encryption key for the destination object will be used to decrypt allsource objects and encrypt the destination object. It is an errorto specify an encryption key for any of the source objects.

func (*ObjectHandle)CopierFrom ¶

func (dst *ObjectHandle) CopierFrom(src *ObjectHandle) *Copier

CopierFrom creates a Copier that can copy src to dst.You can immediately call Run on the returned Copier, oryou can configure it first.

For Requester Pays buckets, the user project of dst is billed, unless it is empty,in which case the user project of src is billed.

Example (RotateEncryptionKeys)¶

package mainimport ("context""cloud.google.com/go/storage")var key1, key2 []bytefunc main() {// To rotate the encryption key on an object, copy it onto itself.ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}obj := client.Bucket("bucketname").Object("obj")// Assume obj is encrypted with key1, and we want to change to key2._, err = obj.Key(key2).CopierFrom(obj.Key(key1)).Run(ctx)if err != nil {// TODO: handle error.}}

func (*ObjectHandle)Delete ¶

func (o *ObjectHandle) Delete(ctxcontext.Context) (errerror)

Delete deletes the single specified object.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/storage""google.golang.org/api/iterator")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 the App Engine Flex 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 != iterator.Done {// TODO: Handle error.}if err == iterator.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.")}

func (*ObjectHandle)Generation ¶

func (o *ObjectHandle) Generation(genint64) *ObjectHandle

Generation returns a new ObjectHandle that operates on a specific generationof the object.By default, the handle operates on the latest generation. Notall operations work when given a specific generation; check the APIendpoints athttps://cloud.google.com/storage/docs/json_api/ for details.

Example¶

package mainimport ("context""io""os""cloud.google.com/go/storage")var gen int64func main() {// Read an object's contents from generation gen, regardless of the// current generation of the object.ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}obj := client.Bucket("my-bucket").Object("my-object")rc, err := obj.Generation(gen).NewReader(ctx)if err != nil {// TODO: handle error.}defer rc.Close()if _, err := io.Copy(os.Stdout, rc); err != nil {// TODO: handle error.}}

func (*ObjectHandle)If ¶

func (o *ObjectHandle) If(condsConditions) *ObjectHandle

If returns a new ObjectHandle that applies a set of preconditions.Preconditions already set on the ObjectHandle are ignored. The suppliedConditions must have at least one field set to a non-default value;otherwise an error will be returned from any operation on the ObjectHandle.Operations on the new handle will return an error if the preconditions are notsatisfied. Seehttps://cloud.google.com/storage/docs/generations-preconditionsfor more details.

Example¶

package mainimport ("context""io""net/http""os""cloud.google.com/go/storage""google.golang.org/api/googleapi")var gen int64func main() {// Read from an object only if the current generation is gen.ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}obj := client.Bucket("my-bucket").Object("my-object")rc, err := obj.If(storage.Conditions{GenerationMatch: gen}).NewReader(ctx)if err != nil {// TODO: handle error.}if _, err := io.Copy(os.Stdout, rc); err != nil {// TODO: handle error.}if err := rc.Close(); err != nil {switch ee := err.(type) {case *googleapi.Error:if ee.Code == http.StatusPreconditionFailed {// The condition presented in the If failed.// TODO: handle error.}// TODO: handle other status codes here.default:// TODO: handle error.}}}

func (*ObjectHandle)Key ¶

func (o *ObjectHandle) Key(encryptionKey []byte) *ObjectHandle

Key returns a new ObjectHandle that uses the supplied encryptionkey to encrypt and decrypt the object's contents.

Encryption key must be a 32-byte AES-256 key.Seehttps://cloud.google.com/storage/docs/encryption for details.

Example¶

package mainimport ("context""cloud.google.com/go/storage")var secretKey []bytefunc main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}obj := client.Bucket("my-bucket").Object("my-object")// Encrypt the object's contents.w := obj.Key(secretKey).NewWriter(ctx)if _, err := w.Write([]byte("top secret")); err != nil {// TODO: handle error.}if err := w.Close(); err != nil {// TODO: handle error.}}

func (*ObjectHandle)Move ¶added inv1.49.0

func (o *ObjectHandle) Move(ctxcontext.Context, destinationMoveObjectDestination) (*ObjectAttrs,error)

Move changes the name of the object to the destination name.It can only be used to rename an object within the same bucket.

Any preconditions set on the ObjectHandle will be applied for the sourceobject. Set preconditions on the destination object using[MoveObjectDestination.Conditions].

func (*ObjectHandle)NewMultiRangeDownloader ¶added inv1.50.0

func (o *ObjectHandle) NewMultiRangeDownloader(ctxcontext.Context) (mrd *MultiRangeDownloader, errerror)

NewMultiRangeDownloader creates a multi-range reader for an object.Must be called on a gRPC client created usingNewGRPCClient.

func (*ObjectHandle)NewRangeReader ¶

func (o *ObjectHandle) NewRangeReader(ctxcontext.Context, offset, lengthint64) (r *Reader, errerror)

NewRangeReader reads part of an object, reading at most length bytesstarting at the given offset. If length is negative, the object is readuntil the end. If offset is negative, the object is read abs(offset) bytesfrom the end, and length must also be negative to indicate all remainingbytes will be read.

If the object's metadata property "Content-Encoding" is set to "gzip" or satisfiesdecompressive transcoding perhttps://cloud.google.com/storage/docs/transcodingthat file will be served back whole, regardless of the requested range asGoogle Cloud Storage dictates. If decompressive transcoding occurs,[Reader.Attrs.Decompressed] will be true.

By default, reads are made using the Cloud Storage XML API. We recommendusing the JSON API instead, which can be done by settingWithJSONReadswhen callingNewClient. This ensures consistency with other clientoperations, which all use JSON. JSON will become the default in a futurerelease.

Example¶

package mainimport ("context""fmt""io""cloud.google.com/go/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.}defer rc.Close()slurp, err := io.ReadAll(rc)if err != nil {// TODO: handle error.}fmt.Printf("first 64K of file contents:\n%s\n", slurp)}

Example (LastNBytes)¶

package mainimport ("context""fmt""io""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}// Read only the last 10 bytes until the end of the file.rc, err := client.Bucket("bucketname").Object("filename1").NewRangeReader(ctx, -10, -1)if err != nil {// TODO: handle error.}defer rc.Close()slurp, err := io.ReadAll(rc)if err != nil {// TODO: handle error.}fmt.Printf("Last 10 bytes from the end of the file:\n%s\n", slurp)}

Example (UntilEnd)¶

package mainimport ("context""fmt""io""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}// Read from the 101st byte until the end of the file.rc, err := client.Bucket("bucketname").Object("filename1").NewRangeReader(ctx, 100, -1)if err != nil {// TODO: handle error.}defer rc.Close()slurp, err := io.ReadAll(rc)if err != nil {// TODO: handle error.}fmt.Printf("From 101st byte until the end:\n%s\n", slurp)}

func (*ObjectHandle)NewReader ¶

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

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

The caller must call Close on the returned Reader when done reading.

Example¶

package mainimport ("context""fmt""io""cloud.google.com/go/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 := io.ReadAll(rc)rc.Close()if err != nil {// TODO: handle error.}fmt.Println("file contents:", slurp)}

func (*ObjectHandle)NewWriter ¶

func (o *ObjectHandle) NewWriter(ctxcontext.Context) *Writer

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

A new object will be created unless 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'sObjectAttrs field before the first call to Write. If no ContentTypeattribute is specified, the content type will be automatically sniffedusing net/http.DetectContentType.

Note that each Writer allocates an internal buffer of size Writer.ChunkSize.See the ChunkSize docs for more information.

It is the caller's responsibility to call Close when writing is done. Tostop writing without saving the data, cancel the context.

Example¶

package mainimport ("context""cloud.google.com/go/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 // TODO: Use the Writer.}

func (*ObjectHandle)NewWriterFromAppendableObject ¶added inv1.52.0

func (o *ObjectHandle) NewWriterFromAppendableObject(ctxcontext.Context, opts *AppendableWriterOpts) (*Writer,int64,error)

NewWriterFromAppendableObject opens a new Writer to an object which has beenpartially flushed to GCS, but not finalized. It returns the Writer as wellas the current end offset of the object. All bytes written will be appendedcontinuing from the offset.

Generation must be set on the ObjectHandle or an error will be returned.

Writer fields such as ChunkSize or ChunkRetryDuration can be set onlyby setting the equivalent field inAppendableWriterOpts. Attributes seton the returned Writer will not be honored since the stream to GCS hasalready been opened. Some fields such as ObjectAttrs and checksums cannotbe set on a takeover for append.

It is the caller's responsibility to call Close when writing is complete toclose the stream.Calling Close or Flush is necessary to sync any data in the pipe to GCS.

The returned Writer is not safe to use across multiple go routines. Inaddition, if you attempt to append to the same object from multipleWriters at the same time, an error will be returned on Flush or Close.

NewWriterFromAppendableObject is supported only for gRPC clients and only forobjects which were created append semantics and not finalized.This feature is in preview and is not yet available for general use.

Example¶

package mainimport ("context""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewGRPCClient(ctx)if err != nil {// TODO: handle error.}bucketName := "my-rapid-bucket"objectName := "appendable-obj"obj := client.Bucket(bucketName).Object(objectName)// First get the object's generation. This is required to append to an// existing object.attrs, err := obj.Attrs(ctx)if err != nil {// TODO: handle error.}// Create a writer for appending to the object.// Set Writer fields such as ChunkSize and FinalizeOnClose here.w, offset, err := obj.Generation(attrs.Generation).NewWriterFromAppendableObject(ctx, &storage.AppendableWriterOpts{ChunkSize:       8 * 1024 * 1024, // 8 MiBFinalizeOnClose: true,            // finalize the object; default is unfinalized.})if err != nil {// TODO: handle error}// TODO: Start writing data from object offset using Writer.Write()._ = offsetif err := w.Close(); err != nil {// TODO: handle error.}}

func (*ObjectHandle)ObjectName ¶

func (o *ObjectHandle) ObjectName()string

ObjectName returns the name of the object.

func (*ObjectHandle)OverrideUnlockedRetention ¶added inv1.36.0

func (o *ObjectHandle) OverrideUnlockedRetention(overridebool) *ObjectHandle

OverrideUnlockedRetention provides an option for overriding an UnlockedRetention policy. This must be set to true in order to change a policyfrom Unlocked to Locked, to set it to null, or to reduce itsRetainUntil attribute. It is not required for setting the ObjectRetention forthe first time nor for extending the RetainUntil time.

Example¶

package mainimport ("context""time""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}// Overriding the retention policy is required to shorten the retention period// for an object.retainUntilDate := time.Now().Add(24 * time.Hour)uattrs := storage.ObjectAttrsToUpdate{Retention: &storage.ObjectRetention{Mode:        "Unlocked",RetainUntil: retainUntilDate,},}if _, err := client.Bucket("bucketname").Object("filename1").OverrideUnlockedRetention(true).Update(ctx, uattrs); err != nil {// TODO: handle error.}}

func (*ObjectHandle)ReadCompressed ¶

func (o *ObjectHandle) ReadCompressed(compressedbool) *ObjectHandle

ReadCompressed when true causes the read to happen without decompressing.

func (*ObjectHandle)ReadHandle ¶added inv1.50.0

func (o *ObjectHandle) ReadHandle(rReadHandle) *ObjectHandle

ReadHandle returns a new ObjectHandle that uses the ReadHandle to open the objects.

Objects that have already been opened can be opened an additional time,using a read handle returned in the response, at lower latency.This produces the exact same object and generation and does not check ifthe generation is still the newest one.Note that this will be a noop unless it's set on a gRPC client on buckets withbi-directional read API access.Also note that you can get a ReadHandle only via calling reader.ReadHandle() on aprevious read of the same object.

func (*ObjectHandle)Restore ¶added inv1.41.0

func (o *ObjectHandle) Restore(ctxcontext.Context, opts *RestoreOptions) (*ObjectAttrs,error)

Restore will restore a soft-deleted object to a live object.Note that you must specify a generation to use this method.

func (*ObjectHandle)Retryer ¶added inv1.19.0

func (o *ObjectHandle) Retryer(opts ...RetryOption) *ObjectHandle

Retryer returns an object handle that is configured with custom retrybehavior as specified by the options that are passed to it. All operationson the new handle will use the customized retry configuration.These retry options will merge with the bucket's retryer (if set) for thereturned handle. Options passed into this method will take precedence overretry options on the bucket and client. Note that you must explicitly pass ineach option you want to override.

func (*ObjectHandle)SoftDeleted ¶added inv1.41.0

func (o *ObjectHandle) SoftDeleted() *ObjectHandle

SoftDeleted returns an object handle that can be used to get an object thathas been soft deleted. To get a soft deleted object, the generation must beset on the object using ObjectHandle.Generation.Note that an error will be returned if a live object is queried using this.

func (*ObjectHandle)Update ¶

func (o *ObjectHandle) Update(ctxcontext.Context, uattrsObjectAttrsToUpdate) (oa *ObjectAttrs, errerror)

Update updates an object with the provided attributes. SeeObjectAttrsToUpdate docs for details on treatment of zero values.ErrObjectNotExist will be returned if the object is not found.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/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.ObjectAttrsToUpdate{ContentType:        "text/html",ContentDisposition: "", // delete ContentDisposition})if err != nil {// TODO: handle error.}fmt.Println(objAttrs)}

typeObjectIterator ¶

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

An ObjectIterator is an iterator over ObjectAttrs.

Note: This iterator is not safe for concurrent operations without explicit synchronization.

func (*ObjectIterator)Next ¶

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

Next returns the next result. Its second return value is iterator.Done ifthere are no more results. Once Next returns iterator.Done, all subsequentcalls will return iterator.Done.

In addition, if Next returns an error other than iterator.Done, allsubsequent calls will return the same error. To continue iteration, a new`ObjectIterator` must be created. Since objects are ordered lexicographicallyby name, `Query.StartOffset` can be used to create a new iterator which willstart at the desired place. Seehttps://pkg.go.dev/cloud.google.com/go/storage?tab=doc#hdr-Listing_objects.

If Query.Delimiter is non-empty, some of the ObjectAttrs returned by Next willhave a non-empty Prefix field, and a zero value for all other fields. Theserepresent prefixes.

Note: This method is not safe for concurrent operations without explicit synchronization.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/storage""google.golang.org/api/iterator")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 == iterator.Done {break}if err != nil {// TODO: Handle error.}fmt.Println(objAttrs)}}

func (*ObjectIterator)PageInfo ¶

func (it *ObjectIterator) PageInfo() *iterator.PageInfo

PageInfo supports pagination. See the google.golang.org/api/iterator package for details.

Note: This method is not safe for concurrent operations without explicit synchronization.

typeObjectRetention ¶added inv1.36.0

type ObjectRetention struct {// Mode is the retention policy's mode on this object. Valid values are// "Locked" and "Unlocked".// Locked retention policies cannot be changed. Unlocked policies require an// override to change.Modestring// RetainUntil is the time this object will be retained until.RetainUntiltime.Time}

ObjectRetention contains the retention configuration for this object.

typePolicyV4Fields ¶added inv1.8.0

type PolicyV4Fields struct {// ACL specifies the access control permissions for the object.// Optional.ACLstring// CacheControl specifies the caching directives for the object.// Optional.CacheControlstring// ContentType specifies the media type of the object.// Optional.ContentTypestring// ContentDisposition specifies how the file will be served back to requesters.// Optional.ContentDispositionstring// ContentEncoding specifies the decompressive transcoding that the object.// This field is complementary to ContentType in that the file could be// compressed but ContentType specifies the file's original media type.// Optional.ContentEncodingstring// Metadata specifies custom metadata for the object.// If any key doesn't begin with "x-goog-meta-", an error will be returned.// Optional.Metadata map[string]string// StatusCodeOnSuccess when set, specifies the status code that Cloud Storage// will serve back on successful upload of the object.// Optional.StatusCodeOnSuccessint// RedirectToURLOnSuccess when set, specifies the URL that Cloud Storage// will serve back on successful upload of the object.// Optional.RedirectToURLOnSuccessstring}

PolicyV4Fields describes the attributes for a PostPolicyV4 request.

typePostPolicyV4 ¶added inv1.8.0

type PostPolicyV4 struct {// URL is the generated URL that the file upload will be made to.URLstring// Fields specifies the generated key-values that the file uploader// must include in their multipart upload form.Fields map[string]string}

PostPolicyV4 describes the URL and respective form fields for a generated PostPolicyV4 request.

funcGenerateSignedPostPolicyV4 ¶added inv1.8.0

func GenerateSignedPostPolicyV4(bucket, objectstring, opts *PostPolicyV4Options) (*PostPolicyV4,error)

GenerateSignedPostPolicyV4 generates a PostPolicyV4 value from bucket, object and opts.The generated URL and fields will then allow an unauthenticated client to perform multipart uploads.If initializing a Storage Client, instead use the Bucket.GenerateSignedPostPolicyV4method which uses the Client's credentials to handle authentication.

Example¶

package mainimport ("bytes""io""mime/multipart""net/http""time""cloud.google.com/go/storage")func main() {pv4, err := storage.GenerateSignedPostPolicyV4("my-bucket", "my-object.txt", &storage.PostPolicyV4Options{GoogleAccessID: "my-access-id",PrivateKey:     []byte("my-private-key"),// The upload expires in 2hours.Expires: time.Now().Add(2 * time.Hour),Fields: &storage.PolicyV4Fields{StatusCodeOnSuccess:    200,RedirectToURLOnSuccess: "https://example.org/",// It MUST only be a text file.ContentType: "text/plain",},// The conditions that the uploaded file will be expected to conform to.Conditions: []storage.PostPolicyV4Condition{// Make the file a maximum of 10mB.storage.ConditionContentLengthRange(0, 10<<20),},})if err != nil {// TODO: handle error.}// Now you can upload your file using the generated post policy// with a plain HTTP client or even the browser.formBuf := new(bytes.Buffer)mw := multipart.NewWriter(formBuf)for fieldName, value := range pv4.Fields {if err := mw.WriteField(fieldName, value); err != nil {// TODO: handle error.}}file := bytes.NewReader(bytes.Repeat([]byte("a"), 100))mf, err := mw.CreateFormFile("file", "myfile.txt")if err != nil {// TODO: handle error.}if _, err := io.Copy(mf, file); err != nil {// TODO: handle error.}if err := mw.Close(); err != nil {// TODO: handle error.}// Compose the request.req, err := http.NewRequest("POST", pv4.URL, formBuf)if err != nil {// TODO: handle error.}// Ensure the Content-Type is derived from the multipart writer.req.Header.Set("Content-Type", mw.FormDataContentType())res, err := http.DefaultClient.Do(req)if err != nil {// TODO: handle error.}_ = res}

typePostPolicyV4Condition ¶added inv1.8.0

type PostPolicyV4Condition interface {json.Marshaler// contains filtered or unexported methods}

PostPolicyV4Condition describes the constraints that the subsequentobject upload's multipart form fields will be expected to conform to.

funcConditionContentLengthRange ¶added inv1.8.0

func ConditionContentLengthRange(start, enduint64)PostPolicyV4Condition

ConditionContentLengthRange constraints the limits that themultipart upload's range header will be expected to be within.

funcConditionStartsWith ¶added inv1.8.0

func ConditionStartsWith(key, valuestring)PostPolicyV4Condition

ConditionStartsWith checks that an attributes starts with value.An empty value will cause this condition to be ignored.

typePostPolicyV4Options ¶added inv1.8.0

type PostPolicyV4Options struct {// GoogleAccessID represents the authorizer of the signed post policy 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.GoogleAccessIDstring// PrivateKey is the Google service account private key. It is obtainable// from the Google Developers Console.// Athttps://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.//// Deprecated: Use SignRawBytes. If both SignBytes and SignRawBytes are defined,// SignBytes will be ignored.// This SignBytes function expects the bytes it receives to be hashed, while// SignRawBytes accepts the raw bytes without hashing, allowing more flexibility.// Add the following to the top of your signing function to hash the bytes// to use SignRawBytes instead://shaSum := sha256.Sum256(bytes)//bytes = shaSum[:]//SignBytes func(hashBytes []byte) (signature []byte, errerror)// SignRawBytes is a function for implementing custom signing. For example, 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)//     &PostPolicyV4Options{//     GoogleAccessID: acc,//     SignRawBytes: func(b []byte) ([]byte, error) {//     _, signedBytes, err := appengine.SignBytes(ctx, b)//     return signedBytes, err//     },//     // etc.//     })//// SignRawBytes is equivalent to the SignBytes field on SignedURLOptions;// that is, you may use the same signing function for the two.//// Exactly one of PrivateKey or SignRawBytes must be non-nil.SignRawBytes func(bytes []byte) (signature []byte, errerror)// Expires is the expiration time on the signed post policy.// It must be a time in the future.// Required.Expirestime.Time// Style provides options for the type of URL to use. Options are// PathStyle (default), BucketBoundHostname, and VirtualHostedStyle. See//https://cloud.google.com/storage/docs/request-endpoints for details.// Optional.StyleURLStyle// Insecure when set indicates that the generated URL's scheme// will use "http" instead of "https" (default).// Optional.Insecurebool// Fields specifies the attributes of a PostPolicyV4 request.// When Fields is non-nil, its attributes must match those that will// passed into field Conditions.// Optional.Fields *PolicyV4Fields// The conditions that the uploaded file will be expected to conform to.// When used, the failure of an upload to satisfy a condition will result in// a 4XX status code, back with the message describing the problem.// Optional.Conditions []PostPolicyV4Condition// Hostname sets the host of the signed post policy. This field overrides// any endpoint set on a storage Client or through STORAGE_EMULATOR_HOST.// Only compatible with PathStyle URLStyle.// Optional.Hostnamestring// contains filtered or unexported fields}

PostPolicyV4Options are used to construct a signed post policy.Please seehttps://cloud.google.com/storage/docs/xml-api/post-objectfor reference about the fields.

typeProjectTeam ¶

type ProjectTeam struct {ProjectNumberstringTeamstring}

ProjectTeam is the project team associated with the entity, if any.

typeProjection ¶added inv1.13.0

type Projectionint

Projection is enumerated type for Query.Projection.

const (// ProjectionDefault returns all fields of objects.ProjectionDefaultProjection =iota// ProjectionFull returns all fields of objects.ProjectionFull// ProjectionNoACL returns all fields of objects except for Owner and ACL.ProjectionNoACL)

func (Projection)String ¶added inv1.13.0

func (pProjection) String()string

typePublicAccessPrevention ¶added inv1.16.0

type PublicAccessPreventionint

PublicAccessPrevention configures the Public Access Prevention feature, whichcan be used to disallow public access to any data in a bucket. Seehttps://cloud.google.com/storage/docs/public-access-prevention for moreinformation.

const (// PublicAccessPreventionUnknown is a zero value, used only if this field is// not set in a call to GCS.PublicAccessPreventionUnknownPublicAccessPrevention =iota// PublicAccessPreventionUnspecified corresponds to a value of "unspecified".// Deprecated: use PublicAccessPreventionInheritedPublicAccessPreventionUnspecified// PublicAccessPreventionEnforced corresponds to a value of "enforced". This// enforces Public Access Prevention on the bucket.PublicAccessPreventionEnforced// PublicAccessPreventionInherited corresponds to a value of "inherited"// and is the default for buckets.PublicAccessPreventionInherited)

func (PublicAccessPrevention)String ¶added inv1.16.0

func (pPublicAccessPrevention) String()string

typeQuery ¶

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.// Must be set to / when used with the MatchGlob parameter to filter results// in a directory-like mode.// Optional.Delimiterstring// Prefix is the prefix filter to query objects// whose names begin with this prefix.// Optional.Prefixstring// Versions indicates whether multiple versions of the same// object will be included in the results.Versionsbool// StartOffset is used to filter results to objects whose names are// lexicographically equal to or after startOffset. If endOffset is also set,// the objects listed will have names between startOffset (inclusive) and// endOffset (exclusive).StartOffsetstring// EndOffset is used to filter results to objects whose names are// lexicographically before endOffset. If startOffset is also set, the objects// listed will have names between startOffset (inclusive) and endOffset (exclusive).EndOffsetstring// Projection defines the set of properties to return. It will default to ProjectionFull,// which returns all properties. Passing ProjectionNoACL will omit Owner and ACL,// which may improve performance when listing many objects.ProjectionProjection// IncludeTrailingDelimiter controls how objects which end in a single// instance of Delimiter (for example, if Query.Delimiter = "/" and the// object name is "foo/bar/") are included in the results. By default, these// objects only show up as prefixes. If IncludeTrailingDelimiter is set to// true, they will also be included as objects and their metadata will be// populated in the returned ObjectAttrs.IncludeTrailingDelimiterbool// MatchGlob is a glob pattern used to filter results (for example, foo*bar). See//https://cloud.google.com/storage/docs/json_api/v1/objects/list#list-object-glob// for syntax details. When Delimiter is set in conjunction with MatchGlob,// it must be set to /.MatchGlobstring// IncludeFoldersAsPrefixes includes Folders and Managed Folders in the set of// prefixes returned by the query. Only applicable if Delimiter is set to /.IncludeFoldersAsPrefixesbool// SoftDeleted indicates whether to list soft-deleted objects.// If true, only objects that have been soft-deleted will be listed.// By default, soft-deleted objects are not listed.SoftDeletedbool// Filters objects based on object attributes like custom contexts.// Seehttps://docs.cloud.google.com/storage/docs/listing-objects#filter-by-object-contexts// for more details.Filterstring// contains filtered or unexported fields}

Query represents a query to filter objects from a bucket.

func (*Query)SetAttrSelection ¶added inv1.4.0

func (q *Query) SetAttrSelection(attrs []string)error

SetAttrSelection makes the query populate only specific attributes ofobjects. When iterating over objects, if you only need each object's nameand size, pass []string{"Name", "Size"} to this method. Only these fieldswill be fetched for each object across the network; the other fields ofObjectAttr will remain at their default values. This is a performanceoptimization; for more information, seehttps://cloud.google.com/storage/docs/json_api/v1/how-tos/performance

typeRPO ¶added inv1.19.0

type RPOint

RPO (Recovery Point Objective) configures the turbo replication feature. Seehttps://cloud.google.com/storage/docs/managing-turbo-replication for more information.

const (// RPOUnknown is a zero value. It may be returned from bucket.Attrs() if RPO// is not present in the bucket metadata, that is, the bucket is not dual-region.// This value is also used if the RPO field is not set in a call to GCS.RPOUnknownRPO =iota// RPODefault represents default replication. It is used to reset RPO on an// existing bucket  that has this field set to RPOAsyncTurbo. Otherwise it// is equivalent to RPOUnknown, and is always ignored. This value is valid// for dual- or multi-region buckets.RPODefault// RPOAsyncTurbo represents turbo replication and is used to enable Turbo// Replication on a bucket. This value is only valid for dual-region buckets.RPOAsyncTurbo)

func (RPO)String ¶added inv1.19.0

func (rpoRPO) String()string

typeReadHandle ¶added inv1.50.0

type ReadHandle []byte

ReadHandle associated with the object. This is periodically refreshed.

typeReader ¶

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

Reader reads a Cloud Storage object.It implements io.Reader.

Typically, a Reader computes the CRC of the downloaded content and compares it tothe stored CRC, returning an error from Read if there is a mismatch. This integrity checkis skipped if transcoding occurs. Seehttps://cloud.google.com/storage/docs/transcoding.

func (*Reader)CacheControldeprecated

func (r *Reader) CacheControl()string

CacheControl returns the cache control of the object.

Deprecated: use Reader.Attrs.CacheControl.

func (*Reader)Close ¶

func (r *Reader) Close()error

Close closes the Reader. It must be called when done reading.

func (*Reader)ContentEncodingdeprecated

func (r *Reader) ContentEncoding()string

ContentEncoding returns the content encoding of the object.

Deprecated: use Reader.Attrs.ContentEncoding.

func (*Reader)ContentTypedeprecated

func (r *Reader) ContentType()string

ContentType returns the content type of the object.

Deprecated: use Reader.Attrs.ContentType.

func (*Reader)LastModifieddeprecated

func (r *Reader) LastModified() (time.Time,error)

LastModified returns the value of the Last-Modified header.

Deprecated: use Reader.Attrs.LastModified.

func (*Reader)Metadata ¶added inv1.49.0

func (r *Reader) Metadata() map[string]string

Metadata returns user-provided metadata, in key/value pairs.

It can be nil if no metadata is present, or if the client uses the JSONAPI for downloads. Only the XML and gRPC APIs support gettingcustom metadata via the Reader; for JSON make a separate call toObjectHandle.Attrs.

func (*Reader)Read ¶

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

func (*Reader)ReadHandle ¶added inv1.50.0

func (r *Reader) ReadHandle()ReadHandle

ReadHandle returns the read handle associated with an object.ReadHandle will be periodically refreshed.

ReadHandle requires the gRPC-specific bi-directional read API, which is inprivate preview; please contact your account manager if interested.Note that this only valid for gRPC and only with zonal buckets.

func (*Reader)Remain ¶

func (r *Reader) Remain()int64

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

func (*Reader)Sizedeprecated

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 bycalls to Read or Close.Size may be out of date for a Reader to an unfinalized object.

Deprecated: use Reader.Attrs.Size.

func (*Reader)WriteTo ¶added inv1.40.0

func (r *Reader) WriteTo(wio.Writer) (int64,error)

WriteTo writes all the data from the Reader to w. Fulfills the io.WriterTo interface.This is called implicitly when calling io.Copy on a Reader.

typeReaderObjectAttrs ¶

type ReaderObjectAttrs struct {// Size is the length of the object's content.// Size may be out of date for unfinalized objects.Sizeint64// StartOffset is the byte offset within the object// from which reading begins.// This value is only non-zero for range requests.StartOffsetint64// ContentType is the MIME type of the object's content.ContentTypestring// ContentEncoding is the encoding of the object's content.ContentEncodingstring// CacheControl specifies whether and for how long browser and Internet// caches are allowed to cache your objects.CacheControlstring// LastModified is the time that the object was last modified.LastModifiedtime.Time// Generation is the generation number of the object's content.Generationint64// 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.Metagenerationint64// CRC32C is the CRC32 checksum of the entire object's content using the// Castagnoli93 polynomial, if available.CRC32Cuint32// Decompressed is true if the object is stored as a gzip file and was// decompressed when read.// Objects are automatically decompressed if the object's metadata property// "Content-Encoding" is set to "gzip" or satisfies decompressive// transcoding as perhttps://cloud.google.com/storage/docs/transcoding.//// To prevent decompression on reads, use [ObjectHandle.ReadCompressed].Decompressedbool}

ReaderObjectAttrs are attributes about the object being read. These are populatedduring the New call. This struct only holds a subset of object attributes: toget the full set of attributes, use ObjectHandle.Attrs.

Each field is read-only.

typeRestoreOptions ¶added inv1.41.0

type RestoreOptions struct {/// CopySourceACL indicates whether the restored object should copy the// access controls of the source object. Only valid for buckets with// fine-grained access. If uniform bucket-level access is enabled, setting// CopySourceACL will cause an error.CopySourceACLbool}

RestoreOptions allows you to set options when restoring an object.

typeRetentionPolicy ¶

type RetentionPolicy struct {// RetentionPeriod specifies the duration that objects need to be// retained. Retention duration must be greater than zero and less than// 100 years. Note that enforcement of retention periods less than a day// is not guaranteed. Such periods should only be used for testing// purposes.RetentionPeriodtime.Duration// EffectiveTime is the time from which the policy was enforced and// effective. This field is read-only.EffectiveTimetime.Time// IsLocked describes whether the bucket is locked. Once locked, an// object retention policy cannot be modified.// This field is read-only.IsLockedbool}

RetentionPolicy enforces a minimum retention time for all objectscontained in the bucket.

Any attempt to overwrite or delete objects younger than the retentionperiod will result in an error. An unlocked retention policy can bemodified or removed from the bucket via the Update method. Alocked retention policy cannot be removed or shortened in durationfor the lifetime of the bucket.

This feature is in private alpha release. It is not currently available tomost customers. It might be changed in backwards-incompatible ways and is notsubject to any SLA or deprecation policy.

typeRetryOption ¶added inv1.19.0

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

RetryOption allows users to configure non-default retry behavior for APIcalls made to GCS.

funcWithBackoff ¶added inv1.19.0

func WithBackoff(backoffgax.Backoff)RetryOption

WithBackoff allows configuration of the backoff timing used for retries.Available configuration options (Initial, Max and Multiplier) are describedathttps://pkg.go.dev/github.com/googleapis/gax-go/v2#Backoff. If any fieldsare not supplied by the user, gax default values will be used.

funcWithErrorFunc ¶added inv1.19.0

func WithErrorFunc(shouldRetry func(errerror)bool)RetryOption

WithErrorFunc allows users to pass a custom function to the retryer. Errorswill be retried if and only if `shouldRetry(err)` returns true.By default, the following errors are retried (see ShouldRetry for the defaultfunction):

- HTTP responses with codes 408, 429, 502, 503, and 504.

- Transient network errors such as connection reset and io.ErrUnexpectedEOF.

- Errors which are considered transient using the Temporary() interface.

- Wrapped versions of these errors.

This option can be used to retry on a different set of errors than thedefault. Users can use the default ShouldRetry function inside their customfunction if they only want to make minor modifications to default behavior.

funcWithMaxAttempts ¶added inv1.37.0

func WithMaxAttempts(maxAttemptsint)RetryOption

WithMaxAttempts configures the maximum number of times an API call can be madein the case of retryable errors.For example, if you set WithMaxAttempts(5), the operation will be attempted up to 5times total (initial call plus 4 retries).Without this setting, operations will continue retrying indefinitelyuntil either the context is canceled or a deadline is reached.

funcWithMaxRetryDuration ¶added inv1.60.0

func WithMaxRetryDuration(maxRetryDurationtime.Duration)RetryOption

WithMaxRetryDuration configures the maximum duration for which requests can be retried.Once this deadline is reached, no further retry attempts will be made, and the lasterror will be returned.For example, if you set WithMaxRetryDuration(10*time.Second), retries will stop after10 seconds even if the maximum number of attempts hasn't been reached.Without this setting, operations will continue retrying until either the maximumnumber of attempts is exhausted or the passed context is terminated by cancellationor timeout.A value of 0 allows infinite retries (subject to other constraints).

Note: This does not apply to Writer operations. For Writer operations,use Writer.ChunkRetryDeadline to control per-chunk retry timeouts, and usecontext timeout or cancellation to control the overall upload timeout.

funcWithPolicy ¶added inv1.19.0

func WithPolicy(policyRetryPolicy)RetryOption

WithPolicy allows the configuration of which operations should be performedwith retries for transient errors.

typeRetryPolicy ¶added inv1.19.0

type RetryPolicyint

RetryPolicy describes the available policies for which operations should beretried. The default is `RetryIdempotent`.

const (// RetryIdempotent causes only idempotent operations to be retried when the// service returns a transient error. Using this policy, fully idempotent// operations (such as `ObjectHandle.Attrs()`) will always be retried.// Conditionally idempotent operations (for example `ObjectHandle.Update()`)// will be retried only if the necessary conditions have been supplied (in// the case of `ObjectHandle.Update()` this would mean supplying a// `Conditions.MetagenerationMatch` condition is required).RetryIdempotentRetryPolicy =iota// RetryAlways causes all operations to be retried when the service returns a// transient error, regardless of idempotency considerations.RetryAlways// RetryNever causes the client to not perform retries on failed operations.RetryNever)

typeSignedURLOptions ¶

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.GoogleAccessIDstring// PrivateKey is the Google service account private key. It is obtainable// from the Google Developers Console.// Athttps://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. For example, 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.Methodstring// Expires is the expiration time on the signed URL. It must be// a datetime in the future. For SigningSchemeV4, the expiration may be no// more than seven days in the future.// Required.Expirestime.Time// ContentType is the content type header the client must provide// to use the generated signed URL.// Optional.ContentTypestring// Headers is a list of extension headers the client must provide// in order to use the generated signed URL. Each must be a string of the// form "key:values", with multiple values separated by a semicolon.// Optional.Headers []string// QueryParameters is a map of additional query parameters. When// SigningScheme is V4, this is used in computing the signature, and the// client must use the same query parameters when using the generated signed// URL.// Optional.QueryParametersurl.Values// 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.MD5string// Style provides options for the type of URL to use. Options are// PathStyle (default), BucketBoundHostname, and VirtualHostedStyle. See//https://cloud.google.com/storage/docs/request-endpoints for details.// Only supported for V4 signing.// Optional.StyleURLStyle// Insecure determines whether the signed URL should use HTTPS (default) or// HTTP.// Only supported for V4 signing.// Optional.Insecurebool// Scheme determines the version of URL signing to use. Default is// SigningSchemeV2.SchemeSigningScheme// Hostname sets the host of the signed URL. This field overrides any// endpoint set on a storage Client or through STORAGE_EMULATOR_HOST.// Only compatible with PathStyle and VirtualHostedStyle URLStyles.// Optional.Hostnamestring}

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

typeSigningScheme ¶

type SigningSchemeint

SigningScheme determines the API version to use when signing URLs.

const (// SigningSchemeDefault is presently V2 and will change to V4 in the future.SigningSchemeDefaultSigningScheme =iota// SigningSchemeV2 uses the V2 scheme to sign URLs.SigningSchemeV2// SigningSchemeV4 uses the V4 scheme to sign URLs.SigningSchemeV4)

typeSoftDeletePolicy ¶added inv1.41.0

type SoftDeletePolicy struct {// EffectiveTime indicates the time from which the policy, or one with a// greater retention, was effective. This field is read-only.EffectiveTimetime.Time// RetentionDuration is the amount of time that soft-deleted objects in the// bucket will be retained and cannot be permanently deleted.RetentionDurationtime.Duration}

SoftDeletePolicy contains the bucket's soft delete policy, which defines theperiod of time that soft-deleted objects will be retained, and cannot bepermanently deleted.

typeURLStyle ¶added inv1.7.0

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

URLStyle determines the style to use for the signed URL. PathStyle is thedefault. All non-default options work with V4 scheme only. Seehttps://cloud.google.com/storage/docs/request-endpoints for details.

funcBucketBoundHostname ¶added inv1.7.0

func BucketBoundHostname(hostnamestring)URLStyle

BucketBoundHostname generates a URL with a custom hostname tied to aspecific GCS bucket. The desired hostname should be passed in using thehostname argument. Generated urls will be of the form"<bucket-bound-hostname>/<object-name>". Seehttps://cloud.google.com/storage/docs/request-endpoints#cname andhttps://cloud.google.com/load-balancing/docs/https/adding-backend-buckets-to-load-balancersfor details. Note that for CNAMEs, only HTTP is supported, so Insecure mustbe set to true.

funcPathStyle ¶added inv1.7.0

func PathStyle()URLStyle

PathStyle is the default style, and will generate a URL of the form"<host-name>/<bucket-name>/<object-name>". By default, <host-name> isstorage.googleapis.com, but setting an endpoint on the storage Client orthrough STORAGE_EMULATOR_HOST overrides this. Setting Hostname onSignedURLOptions or PostPolicyV4Options overrides everything else.

funcVirtualHostedStyle ¶added inv1.7.0

func VirtualHostedStyle()URLStyle

VirtualHostedStyle generates a URL relative to the bucket's virtualhostname, e.g. "<bucket-name>.storage.googleapis.com/<object-name>".

typeUniformBucketLevelAccess ¶added inv1.2.0

type UniformBucketLevelAccess struct {// Enabled specifies whether access checks use only bucket-level IAM// policies. Enabled may be disabled until the locked time.Enabledbool// LockedTime specifies the deadline for changing Enabled from true to// false.LockedTimetime.Time}

UniformBucketLevelAccess configures access checks to use only bucket-level IAMpolicies.

typeWriter ¶

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// SendCRC32C specifies whether to transmit a CRC32C checksum. When this is// true and the Writer's CRC32C field is set, that checksum is sent to GCS.// If the data written does not match the checksum, the write is rejected.// It is necessary to set this field to true in addition to setting the// Writer's CRC32C field because zero is a valid CRC.//// By default, the client automatically calculates and sends checksums.// When using gRPC, checksums are sent for both individual chunks and the full object.// When using JSON, checksums are sent only for the full object.// However, a user-provided checksum takes precedence over the auto-calculated checksum// for the full object.//// Note: SendCRC32C must be set before the first call to Writer.Write().SendCRC32Cbool// DisableAutoChecksum disables automatic CRC32C checksum calculation and// validation in the Writer. By default, the Writer automatically performs// checksum validation. Setting this to true disables this behavior.//// Disabling automatic checksumming does not prevent a user-provided checksum// from being sent. If SendCRC32C is true and the Writer's CRC32C field is// populated, that checksum will still be sent to GCS for validation.//// For single-shot JSON uploads, a mismatch in the auto-calculated checksum returns// an error but may leave data on the server. This issue does not apply when// user-provided checksum is used. Callers relying on auto-checksum should handle the// error by removing the object or restoring a previous version.//// Automatic CRC32C checksum calculation introduces increased CPU overhead// because of checksum computation in writes. Use this field to disable// it if needed.//// Note: DisableAutoChecksum must be set before the first call to// Writer.Write(). Automatic checksumming is not enabled for full object// checksums for unfinalized writes to appendable objects in gRPC.DisableAutoChecksumbool// ChunkSize controls the maximum number of bytes of the object that the// Writer will attempt to send to the server in a single request. Objects// smaller than the size will be sent in a single request, while larger// objects will be split over multiple requests. The value will be rounded up// to the nearest multiple of 256K. The default ChunkSize is 16MiB.//// Each Writer will internally allocate a buffer of size ChunkSize. This is// used to buffer input data and allow for the input to be sent again if a// request must be retried.//// If you upload small objects (< 16MiB), you should set ChunkSize// to a value slightly larger than the objects' sizes to avoid memory bloat.// This is especially important if you are uploading many small objects// concurrently. See//https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload#size// for more information about performance trade-offs related to ChunkSize.//// If ChunkSize is set to zero, chunking will be disabled and the object will// be uploaded in a single request without the use of a buffer. This will// further reduce memory used during uploads, but will also prevent the writer// from retrying in case of a transient error from the server or resuming an// upload that fails midway through, since the buffer is required in order to// retry the failed request.//// ChunkSize must be set before the first Write call.ChunkSizeint// ChunkRetryDeadline sets a per-chunk retry deadline for multi-chunk// resumable uploads.//// For uploads of larger files, the Writer will attempt to retry if the// request to upload a particular chunk fails with a transient error.// If a single chunk has been attempting to upload for longer than this// deadline and the request fails, it will no longer be retried, and the// error will be returned to the caller. This is only applicable for files// which are large enough to require a multi-chunk resumable upload. The// default value is 32s. Users may want to pick a longer deadline if they// are using larger values for ChunkSize or if they expect to have a slow or// unreliable internet connection.//// To set a deadline on the entire upload, use context timeout or// cancellation.ChunkRetryDeadlinetime.Duration// ChunkTransferTimeout sets a per-chunk request timeout for resumable uploads.//// For resumable uploads, the Writer will terminate the request and attempt// a retry if the request to upload a particular chunk stalls for longer than// this duration. Retries may continue until the ChunkRetryDeadline is reached.//// ChunkTransferTimeout is not applicable to uploads made using a gRPC client.//// The default value is no timeout.ChunkTransferTimeouttime.Duration// ForceEmptyContentType is an optional parameter that is used to disable// auto-detection of Content-Type. By default, if a blank Content-Type// is provided, then gax.DetermineContentType is called to sniff the type.ForceEmptyContentTypebool// Append is a parameter to indicate whether the writer should use appendable// object semantics for the new object generation. Appendable objects are// visible on the first Write() call, and can be appended to until they are// finalized. If Writer.FinalizeOnClose is set to true, the object is finalized// when Writer.Close() is called; otherwise, the object is left unfinalized// and can be appended to later.//// Defaults to false unless the experiemental WithZonalBucketAPIs option was// set.//// Append is only supported for gRPC. This feature is in preview and is not// yet available for general use.Appendbool// FinalizeOnClose indicates whether the Writer should finalize an object when// closing the write stream. This only applies to Writers where Append is// true, since append semantics allow a prefix of the object to be durable and// readable. By default, objects written with Append semantics will not be// finalized, which means they can be appended to later. If Append is set// to false, this parameter will be ignored; non-appendable objects will// always be finalized when Writer.Close returns without error.//// This feature is in preview and is not yet available for general use.FinalizeOnClosebool// ProgressFunc can be used to monitor the progress of a large write// operation. If ProgressFunc is not nil and writing requires multiple// calls to the underlying service (see//https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload),// then ProgressFunc will be invoked after each call with the number of bytes of// content copied so far.//// ProgressFunc should return quickly without blocking.ProgressFunc func(int64)// contains filtered or unexported fields}

A Writer writes a Cloud Storage object.

func (*Writer)Attrs ¶

func (w *Writer) Attrs() *ObjectAttrs

Attrs 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 objectcan be retrieved by calling Attrs.

func (*Writer)CloseWithErrordeprecated

func (w *Writer) CloseWithError(errerror)error

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

Deprecated: cancel the context passed to NewWriter instead.

func (*Writer)Flush ¶added inv1.51.0

func (w *Writer) Flush() (int64,error)

Flush syncs all bytes currently in the Writer's buffer to Cloud Storage.It returns the offset of bytes that have been currently synced toCloud Storage and an error.

If Flush is never called, Writer will sync data automatically every[Writer.ChunkSize] bytes and onWriter.Close.

[Writer.ProgressFunc] will be called on Flush if present.

Do not call Flush concurrently with Write or Close. A single Writer is notsafe for unsynchronized use across threads.

Note that calling Flush very early (before 512 bytes) may interfere withautomatic content sniffing in the Writer.

Flush is supported only on gRPC clients where [Writer.Append] is setto true. This feature is in preview and is not yet available for general use.

Example¶

package mainimport ("context""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewGRPCClient(ctx)if err != nil {// TODO: handle error.}bucketName := "my-rapid-bucket"objectName := "appendable-obj"obj := client.Bucket(bucketName).Object(objectName)// Create an appendable object using NewWriter, or append to an existing// one with NewWriterFromAppendableObject.w := obj.NewWriter(ctx)w.Append = true// Calling Writer.Write, the data may still be in a local buffer in the// client.if _, err := w.Write([]byte("hello ")); err != nil {// TODO: handle error.}// Call Writer.Flush to ensure data is synced to GCS.if _, err := w.Flush(); err != nil {// TODO: Handle error.}// Write remaining data and close writer. Data is automatically synced// at ChunkSize boundaries and when Close is called.if _, err := w.Write([]byte("world!")); err != nil {// TODO: handle error.}if err := w.Close(); err != nil {// TODO: handle error.}}

func (*Writer)Write ¶

func (w *Writer) Write(p []byte) (nint, errerror)

Write appends to w. It implements the io.Writer interface.

Since writes happen asynchronously, Write may return a nilerror even though the write failed (or will fail). Alwaysuse the error returned from Writer.Close to determine ifthe upload was successful.

Writes will be retried on transient errors from the server, unlessWriter.ChunkSize has been set to zero.

Example¶

package mainimport ("context""fmt""cloud.google.com/go/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{{Entity: storage.AllUsers, Role: storage.RoleReader}}if _, err := wc.Write([]byte("hello world")); err != nil {// TODO: handle error.// Note that Write may return nil in some error situations,// so always check the error from Close.}if err := wc.Close(); err != nil {// TODO: handle error.}fmt.Println("updated object:", wc.Attrs())}

Example (Checksum)¶

To make sure the data you write is uncorrupted, use an MD5 or CRC32cchecksum. This example illustrates CRC32c.

package mainimport ("context""fmt""hash/crc32""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}data := []byte("verify me")wc := client.Bucket("bucketname").Object("filename1").NewWriter(ctx)wc.CRC32C = crc32.Checksum(data, crc32.MakeTable(crc32.Castagnoli))wc.SendCRC32C = trueif _, err := wc.Write([]byte("hello world")); err != nil {// TODO: handle error.// Note that Write may return nil in some error situations,// so always check the error from Close.}if err := wc.Close(); err != nil {// TODO: handle error.}fmt.Println("updated object:", wc.Attrs())}

Example (Timeout)¶

To limit the time to write an object (or do anything elsethat takes a context), use context.WithTimeout.

package mainimport ("context""fmt""time""cloud.google.com/go/storage")func main() {ctx := context.Background()client, err := storage.NewClient(ctx)if err != nil {// TODO: handle error.}tctx, cancel := context.WithTimeout(ctx, 30*time.Second)defer cancel() // Cancel when done, whether we time out or not.wc := client.Bucket("bucketname").Object("filename1").NewWriter(tctx)wc.ContentType = "text/plain"wc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: storage.RoleReader}}if _, err := wc.Write([]byte("hello world")); err != nil {// TODO: handle error.// Note that Write may return nil in some error situations,// so always check the error from Close.}if err := wc.Close(); err != nil {// TODO: handle error.}fmt.Println("updated object:", wc.Attrs())}

Source Files¶

View all Source files

Directories¶

Path	Synopsis
control
apiv2 Package control is an auto-generated package for the Storage Control API.	Package control is an auto-generated package for the Storage Control API.
apiv2/controlpb
dataflux Package dataflux provides an easy way to parallelize listing in Google Cloud Storage.	Package dataflux provides an easy way to parallelize listing in Google Cloud Storage.
experimental Package experimental is a collection of experimental features that might have some rough edges to them.	Package experimental is a collection of experimental features that might have some rough edges to them.
internal
apiv2 Package storage is an auto-generated package for the Cloud Storage API.	Package storage is an auto-generated package for the Cloud Storage API.
apiv2/storagepb
test/conformance
transfermanager Package transfermanager provides an easy way to parallelize downloads in Google Cloud Storage.	Package transfermanager provides an easy way to parallelize downloads in Google Cloud Storage.

?	: This menu
/	: Search site
f orF	: Jump to
y orY	: Canonical URL

Movatterモバイル変換

Details

Repository

Links

README¶

Cloud Storage

Example Usage

Documentation¶

Overview¶

Creating a Client¶

Buckets¶

Objects¶

Listing objects¶

ACLs¶

Conditions¶

Signed URLs¶

Post Policy V4 Signed Request¶

Credential requirements for signing¶

Errors¶

Retrying failed requests¶

Sending Custom Headers¶

gRPC API¶

Storage Control API¶

Index¶

Examples¶

Constants¶

Variables¶

Functions¶

funcCheckDirectConnectivitySupported¶added inv1.47.0

funcShouldRetry¶added inv1.26.0

funcSignedURL¶

funcWithDisabledClientMetrics¶added inv1.44.0

funcWithJSONReads¶added inv1.30.0

funcWithXMLReads¶added inv1.30.0

Types¶

typeACLEntity¶

typeACLHandle¶

func (*ACLHandle)Delete¶

func (*ACLHandle)List¶

func (*ACLHandle)Set¶

typeACLRole¶

typeACLRule¶

typeAppendableWriterOpts¶added inv1.52.0

typeAutoclass¶added inv1.28.0

typeBucketAttrs¶

typeBucketAttrsToUpdate¶

func (*BucketAttrsToUpdate)DeleteLabel¶

func (*BucketAttrsToUpdate)SetLabel¶

typeBucketConditions¶

typeBucketEncryption¶

typeBucketHandle¶

func (*BucketHandle)ACL¶

func (*BucketHandle)AddNotification¶

func (*BucketHandle)Attrs¶

func (*BucketHandle)BucketName¶added inv1.42.0

func (*BucketHandle)Create¶

func (*BucketHandle)DefaultObjectACL¶

func (*BucketHandle)Delete¶

func (*BucketHandle)DeleteNotification¶

func (*BucketHandle)GenerateSignedPostPolicyV4¶added inv1.19.0

func (*BucketHandle)IAM¶

func (*BucketHandle)If¶

func (*BucketHandle)LockRetentionPolicy¶

func (*BucketHandle)Notifications¶

func (*BucketHandle)Object¶

func (*BucketHandle)Objects¶

func (*BucketHandle)Retryer¶added inv1.19.0

func (*BucketHandle)SetObjectRetention¶added inv1.36.0

func (*BucketHandle)SignedURL¶added inv1.18.0

func (*BucketHandle)Update¶

func (*BucketHandle)UserProject¶

typeBucketIterator¶

func (*BucketIterator)Next¶

func (*BucketIterator)PageInfo¶

func (*BucketIterator)Unreachable¶added inv1.58.0

typeBucketLogging¶

typeBucketPolicyOnly¶

typeBucketWebsite¶

typeCORS¶

typeClient¶

README ¶

funcCheckDirectConnectivitySupported ¶added inv1.47.0

funcShouldRetry ¶added inv1.26.0

funcSignedURL ¶

funcWithDisabledClientMetrics ¶added inv1.44.0

funcWithJSONReads ¶added inv1.30.0

funcWithXMLReads ¶added inv1.30.0

typeACLEntity ¶

typeACLHandle ¶

func (*ACLHandle)Delete ¶

func (*ACLHandle)List ¶

func (*ACLHandle)Set ¶

typeACLRole ¶

typeACLRule ¶

typeAppendableWriterOpts ¶added inv1.52.0

typeAutoclass ¶added inv1.28.0

typeBucketAttrs ¶

typeBucketAttrsToUpdate ¶

func (*BucketAttrsToUpdate)DeleteLabel ¶

func (*BucketAttrsToUpdate)SetLabel ¶

typeBucketConditions ¶

typeBucketEncryption ¶

typeBucketHandle ¶

func (*BucketHandle)ACL ¶

func (*BucketHandle)AddNotification ¶

func (*BucketHandle)Attrs ¶

func (*BucketHandle)BucketName ¶added inv1.42.0

func (*BucketHandle)Create ¶

func (*BucketHandle)DefaultObjectACL ¶

func (*BucketHandle)Delete ¶

func (*BucketHandle)DeleteNotification ¶

func (*BucketHandle)GenerateSignedPostPolicyV4 ¶added inv1.19.0

func (*BucketHandle)IAM ¶

func (*BucketHandle)If ¶

func (*BucketHandle)LockRetentionPolicy ¶

func (*BucketHandle)Notifications ¶

func (*BucketHandle)Object ¶

func (*BucketHandle)Objects ¶

func (*BucketHandle)Retryer ¶added inv1.19.0

func (*BucketHandle)SetObjectRetention ¶added inv1.36.0

func (*BucketHandle)SignedURL ¶added inv1.18.0

func (*BucketHandle)Update ¶

func (*BucketHandle)UserProject ¶

typeBucketIterator ¶

func (*BucketIterator)Next ¶

func (*BucketIterator)PageInfo ¶

func (*BucketIterator)Unreachable ¶added inv1.58.0

typeBucketLogging ¶

typeBucketPolicyOnly ¶

typeBucketWebsite ¶

typeCORS ¶

typeClient ¶

funcNewClient ¶

funcNewGRPCClient ¶added inv1.33.0

func (*Client)Bucket ¶

func (*Client)Buckets ¶

func (*Client)Close ¶

func (*Client)CreateHMACKey ¶

func (*Client)HMACKeyHandle ¶

func (*Client)ListHMACKeys ¶

func (*Client)ServiceAccount ¶

func (*Client)SetRetry ¶added inv1.19.0

typeComposer ¶

func (*Composer)Run ¶

typeConditions ¶

typeCopier ¶

func (*Copier)Run ¶

typeCustomPlacementConfig ¶added inv1.24.0

typeHMACKey ¶

typeHMACKeyAttrsToUpdate ¶

typeHMACKeyHandle ¶

func (*HMACKeyHandle)Delete ¶

func (*HMACKeyHandle)Get ¶

func (*HMACKeyHandle)Update ¶

typeHMACKeyOption ¶

funcForHMACKeyServiceAccountEmail ¶

funcShowDeletedHMACKeys ¶

funcUserProjectForHMACKeys ¶added inv1.1.0

typeHMACKeysIterator ¶

func (*HMACKeysIterator)Next ¶