diff --git a/bigquery/go.mod b/bigquery/go.mod index c6eb9095836..309720226a6 100644 --- a/bigquery/go.mod +++ b/bigquery/go.mod @@ -6,7 +6,7 @@ require ( cloud.google.com/go v0.72.0 cloud.google.com/go/storage v1.10.0 github.com/golang/protobuf v1.4.3 - github.com/google/go-cmp v0.5.3 + github.com/google/go-cmp v0.5.4 github.com/googleapis/gax-go/v2 v2.0.5 golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c // indirect google.golang.org/api v0.35.0 diff --git a/bigquery/go.sum b/bigquery/go.sum index 94e2c34e25b..50dc0d56800 100644 --- a/bigquery/go.sum +++ b/bigquery/go.sum @@ -123,8 +123,8 @@ github.com/google/go-cmp v0.5.1 h1:JFrFEBb2xKufg6XkJsJr+WbKb4FQlURi5RUcBveYu9k= github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no= github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs= github.com/google/martian/v3 v3.0.0 h1:pMen7vLs8nvgEYhywH3KDWJIJTeEr2ULsVWHWYHQyBs= diff --git a/bigtable/go.mod b/bigtable/go.mod index 65d81f54c49..c5c0131da32 100644 --- a/bigtable/go.mod +++ b/bigtable/go.mod @@ -6,7 +6,7 @@ require ( cloud.google.com/go v0.72.0 github.com/golang/protobuf v1.4.3 github.com/google/btree v1.0.0 - github.com/google/go-cmp v0.5.3 + github.com/google/go-cmp v0.5.4 github.com/googleapis/gax-go/v2 v2.0.5 golang.org/x/oauth2 v0.0.0-20201109201403-9fd604954f58 golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c // indirect diff --git a/bigtable/go.sum b/bigtable/go.sum index 0bfb64062f2..3124ae8c642 100644 --- a/bigtable/go.sum +++ b/bigtable/go.sum @@ -129,8 +129,8 @@ github.com/google/go-cmp v0.5.1 h1:JFrFEBb2xKufg6XkJsJr+WbKb4FQlURi5RUcBveYu9k= github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no= github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs= github.com/google/martian/v3 v3.0.0/go.mod h1:y5Zk1BBys9G+gd6Jrk0W3cC1+ELVxBWuIGO+w/tUAp0= diff --git a/datastore/go.mod b/datastore/go.mod index 3437780bd82..dd66721b015 100644 --- a/datastore/go.mod +++ b/datastore/go.mod @@ -5,7 +5,7 @@ go 1.11 require ( cloud.google.com/go v0.72.0 github.com/golang/protobuf v1.4.3 - github.com/google/go-cmp v0.5.3 + github.com/google/go-cmp v0.5.4 github.com/googleapis/gax-go/v2 v2.0.5 golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c // indirect google.golang.org/api v0.35.0 diff --git a/datastore/go.sum b/datastore/go.sum index 26e20a1034c..37aedddf290 100644 --- a/datastore/go.sum +++ b/datastore/go.sum @@ -125,8 +125,8 @@ github.com/google/go-cmp v0.5.1 h1:JFrFEBb2xKufg6XkJsJr+WbKb4FQlURi5RUcBveYu9k= github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no= github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs= github.com/google/martian/v3 v3.0.0/go.mod h1:y5Zk1BBys9G+gd6Jrk0W3cC1+ELVxBWuIGO+w/tUAp0= diff --git a/datastore/load.go b/datastore/load.go index 086b6b6f31c..5b1102961b8 100644 --- a/datastore/load.go +++ b/datastore/load.go @@ -20,15 +20,19 @@ import ( "strings" "time" + "cloud.google.com/go/civil" "cloud.google.com/go/internal/fields" pb "google.golang.org/genproto/googleapis/datastore/v1" ) var ( - typeOfByteSlice = reflect.TypeOf([]byte(nil)) - typeOfTime = reflect.TypeOf(time.Time{}) - typeOfGeoPoint = reflect.TypeOf(GeoPoint{}) - typeOfKeyPtr = reflect.TypeOf(&Key{}) + typeOfByteSlice = reflect.TypeOf([]byte(nil)) + typeOfTime = reflect.TypeOf(time.Time{}) + typeOfCivilDate = reflect.TypeOf(civil.Date{}) + typeOfCivilDateTime = reflect.TypeOf(civil.DateTime{}) + typeOfCivilTime = reflect.TypeOf(civil.Time{}) + typeOfGeoPoint = reflect.TypeOf(GeoPoint{}) + typeOfKeyPtr = reflect.TypeOf(&Key{}) ) // typeMismatchReason returns a string explaining why the property p could not @@ -379,6 +383,15 @@ func setVal(v reflect.Value, p Property) (s string) { return typeMismatchReason(p, v) } v.Set(reflect.ValueOf(x)) + case typeOfCivilDate: + date := civil.DateOf(pValue.(time.Time)) + v.Set(reflect.ValueOf(date)) + case typeOfCivilDateTime: + dateTime := civil.DateTimeOf(pValue.(time.Time)) + v.Set(reflect.ValueOf(dateTime)) + case typeOfCivilTime: + timeVal := civil.TimeOf(pValue.(time.Time)) + v.Set(reflect.ValueOf(timeVal)) default: ent, ok := pValue.(*Entity) if !ok { diff --git a/datastore/load_test.go b/datastore/load_test.go index 75ccab95d62..518fa61c10b 100644 --- a/datastore/load_test.go +++ b/datastore/load_test.go @@ -20,8 +20,10 @@ import ( "testing" "time" + "cloud.google.com/go/civil" "cloud.google.com/go/internal/testutil" pb "google.golang.org/genproto/googleapis/datastore/v1" + "google.golang.org/protobuf/types/known/timestamppb" ) type Simple struct { @@ -484,6 +486,68 @@ func TestLoadToInterface(t *testing.T) { dst: &withUntypedInterface{Field: 1e9}, want: &withUntypedInterface{Field: "Newly set"}, }, + { + name: "struct with civil.Date", + src: &pb.Entity{ + Key: keyToProto(testKey0), + Properties: map[string]*pb.Value{ + "Date": {ValueType: &pb.Value_TimestampValue{TimestampValue: ×tamppb.Timestamp{Seconds: 1605474000}}}, + }, + }, + dst: &struct{ Date civil.Date }{ + Date: civil.Date{}, + }, + want: &struct{ Date civil.Date }{ + Date: civil.Date{ + Year: 2020, + Month: 11, + Day: 15, + }, + }, + }, + { + name: "struct with civil.DateTime", + src: &pb.Entity{ + Key: keyToProto(testKey0), + Properties: map[string]*pb.Value{ + "DateTime": {ValueType: &pb.Value_TimestampValue{TimestampValue: ×tamppb.Timestamp{Seconds: 1605504600}}}, + }, + }, + dst: &struct{ DateTime civil.DateTime }{ + DateTime: civil.DateTime{}, + }, + want: &struct{ DateTime civil.DateTime }{ + DateTime: civil.DateTime{ + Date: civil.Date{ + Year: 2020, + Month: 11, + Day: 16, + }, + Time: civil.Time{ + Hour: 5, + Minute: 30, + }, + }, + }, + }, + { + name: "struct with civil.Time", + src: &pb.Entity{ + Key: keyToProto(testKey0), + Properties: map[string]*pb.Value{ + "Time": {ValueType: &pb.Value_TimestampValue{TimestampValue: ×tamppb.Timestamp{Seconds: 1605504600}}}, + }, + }, + dst: &struct{ Time civil.Time }{ + Time: civil.Time{}, + }, + want: &struct{ Time civil.Time }{ + Time: civil.Time{ + Hour: 5, + Minute: 30, + }, + }, + }, } for _, tc := range testCases { diff --git a/datastore/save.go b/datastore/save.go index 08874ad7465..f6945ec6e1c 100644 --- a/datastore/save.go +++ b/datastore/save.go @@ -21,6 +21,7 @@ import ( "time" "unicode/utf8" + "cloud.google.com/go/civil" timepb "github.com/golang/protobuf/ptypes/timestamp" pb "google.golang.org/genproto/googleapis/datastore/v1" llpb "google.golang.org/genproto/googleapis/type/latlng" @@ -53,6 +54,28 @@ func reflectFieldSave(props *[]Property, p Property, name string, opts saveOpts, switch x := v.Interface().(type) { case *Key, time.Time, GeoPoint: p.Value = x + case civil.Date: + p.Value = x.In(time.UTC) + *props = append(*props, p) + return nil + case civil.Time: + var format string + if x.Nanosecond == 0 { + format = "15:04:05" + } else { + format = "15:04:05.000000000" + } + val, err := time.Parse(format, x.String()) + if err != nil { + return fmt.Errorf("datastore: error while parsing civil.Time: %v", err) + } + p.Value = val + *props = append(*props, p) + return nil + case civil.DateTime: + p.Value = x.In(time.UTC) + *props = append(*props, p) + return nil default: switch v.Kind() { case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64: diff --git a/datastore/save_test.go b/datastore/save_test.go index ac52f7c1724..5071e6054d5 100644 --- a/datastore/save_test.go +++ b/datastore/save_test.go @@ -15,9 +15,11 @@ package datastore import ( + "fmt" "testing" "time" + "cloud.google.com/go/civil" "cloud.google.com/go/internal/testutil" pb "google.golang.org/genproto/googleapis/datastore/v1" ) @@ -321,6 +323,27 @@ func TestSaveFieldsWithInterface(t *testing.T) { N2 interface{} } + civDateVal := civil.Date{ + Year: 2020, + Month: 11, + Day: 10, + } + civTimeValNano := civil.Time{ + Hour: 1, + Minute: 1, + Second: 1, + Nanosecond: 1, + } + civTimeVal := civil.Time{ + Hour: 1, + Minute: 1, + Second: 1, + } + timeValNano, _ := time.Parse("15:04:05.000000000", civTimeValNano.String()) + timeVal, _ := time.Parse("15:04:05", civTimeVal.String()) + dateTimeStr := fmt.Sprintf("%v %v", civDateVal.String(), civTimeVal.String()) + dateTimeVal, _ := time.ParseInLocation("2006-01-02 15:04:05", dateTimeStr, time.UTC) + cases := []struct { name string in interface{} @@ -371,6 +394,65 @@ func TestSaveFieldsWithInterface(t *testing.T) { {Name: "Map", Value: []Property{}}, }, }, + { + name: "civil.Date", + in: &struct { + CivDate civil.Date + }{ + CivDate: civDateVal, + }, + want: []Property{ + { + Name: "CivDate", + Value: civDateVal.In(time.UTC), + }, + }, + }, + { + name: "civil.Time-nano", + in: &struct { + CivTimeNano civil.Time + }{ + CivTimeNano: civTimeValNano, + }, + want: []Property{ + { + Name: "CivTimeNano", + Value: timeValNano, + }, + }, + }, + { + name: "civil.Time", + in: &struct { + CivTime civil.Time + }{ + CivTime: civTimeVal, + }, + want: []Property{ + { + Name: "CivTime", + Value: timeVal, + }, + }, + }, + { + name: "civil.DateTime", + in: &struct { + CivDateTime civil.DateTime + }{ + CivDateTime: civil.DateTime{ + Date: civDateVal, + Time: civTimeVal, + }, + }, + want: []Property{ + { + Name: "CivDateTime", + Value: dateTimeVal, + }, + }, + }, { name: "Nested", in: &n3{ diff --git a/firestore/go.mod b/firestore/go.mod index 3c760c4ba4b..03bcd49f5b6 100644 --- a/firestore/go.mod +++ b/firestore/go.mod @@ -5,7 +5,7 @@ go 1.11 require ( cloud.google.com/go v0.72.0 github.com/golang/protobuf v1.4.3 - github.com/google/go-cmp v0.5.3 + github.com/google/go-cmp v0.5.4 github.com/googleapis/gax-go/v2 v2.0.5 golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c // indirect google.golang.org/api v0.35.0 diff --git a/firestore/go.sum b/firestore/go.sum index 9d92b9c6a20..44ab13e6153 100644 --- a/firestore/go.sum +++ b/firestore/go.sum @@ -126,8 +126,8 @@ github.com/google/go-cmp v0.5.1 h1:JFrFEBb2xKufg6XkJsJr+WbKb4FQlURi5RUcBveYu9k= github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no= github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs= github.com/google/martian/v3 v3.0.0/go.mod h1:y5Zk1BBys9G+gd6Jrk0W3cC1+ELVxBWuIGO+w/tUAp0= diff --git a/go.mod b/go.mod index 048ab20afb6..cfce39ebd5f 100644 --- a/go.mod +++ b/go.mod @@ -6,9 +6,9 @@ require ( cloud.google.com/go/storage v1.10.0 github.com/golang/mock v1.4.4 github.com/golang/protobuf v1.4.3 - github.com/google/go-cmp v0.5.3 + github.com/google/go-cmp v0.5.4 github.com/google/martian/v3 v3.1.0 - github.com/google/pprof v0.0.0-20201116185724-cf230572f49e + github.com/google/pprof v0.0.0-20201117184057-ae444373da19 github.com/googleapis/gax-go/v2 v2.0.5 github.com/jstemmer/go-junit-report v0.9.1 go.opencensus.io v0.22.5 @@ -16,7 +16,7 @@ require ( golang.org/x/net v0.0.0-20201110031124-69a78807bb2b golang.org/x/oauth2 v0.0.0-20201109201403-9fd604954f58 golang.org/x/text v0.3.4 - golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c + golang.org/x/tools v0.0.0-20201201171514-ae829c33831c google.golang.org/api v0.35.0 google.golang.org/genproto v0.0.0-20201201144952-b05cb90ed32e google.golang.org/grpc v1.33.2 diff --git a/go.sum b/go.sum index d9dbadf180b..28183d568e9 100644 --- a/go.sum +++ b/go.sum @@ -122,8 +122,8 @@ github.com/google/go-cmp v0.5.1 h1:JFrFEBb2xKufg6XkJsJr+WbKb4FQlURi5RUcBveYu9k= github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no= github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs= github.com/google/martian/v3 v3.0.0 h1:pMen7vLs8nvgEYhywH3KDWJIJTeEr2ULsVWHWYHQyBs= @@ -140,8 +140,8 @@ github.com/google/pprof v0.0.0-20200229191704-1ebb73c60ed3/go.mod h1:ZgVRPoUq/hf github.com/google/pprof v0.0.0-20200430221834-fc25d7d30c6d/go.mod h1:ZgVRPoUq/hfqzAqh7sHMqb3I9Rq5C59dIz2SbBwJ4eM= github.com/google/pprof v0.0.0-20200708004538-1a94d8640e99 h1:Ak8CrdlwwXwAZxzS66vgPt4U8yUZX7JwLvVR58FN5jM= github.com/google/pprof v0.0.0-20200708004538-1a94d8640e99/go.mod h1:ZgVRPoUq/hfqzAqh7sHMqb3I9Rq5C59dIz2SbBwJ4eM= -github.com/google/pprof v0.0.0-20201116185724-cf230572f49e h1:x0wSM6/MWepJDtJGtAxILAbZjzcCGZx2LvuYISldxvo= -github.com/google/pprof v0.0.0-20201116185724-cf230572f49e/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE= +github.com/google/pprof v0.0.0-20201117184057-ae444373da19 h1:iFELRewmQ9CldLrqgr0E6b6ZPfZmMvLyyz6kMsR+c4w= +github.com/google/pprof v0.0.0-20201117184057-ae444373da19/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE= github.com/google/renameio v0.1.0/go.mod h1:KWCgfxg9yswjAJkECMjeO8J8rahYeXnNhOm40UhjYkI= github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/googleapis/gax-go/v2 v2.0.4 h1:hU4mGcQI4DaAYW+IbTun+2qEZVFxK0ySjQLTbS0VQKc= @@ -399,8 +399,8 @@ golang.org/x/tools v0.0.0-20200804011535-6c149bb5ef0d h1:szSOL78iTCl0LF1AMjhSWJj golang.org/x/tools v0.0.0-20200804011535-6c149bb5ef0d/go.mod h1:njjCfa9FT2d7l9Bc6FUM5FLjQPp3cFF28FI3qnDFljA= golang.org/x/tools v0.0.0-20200825202427-b303f430e36d/go.mod h1:njjCfa9FT2d7l9Bc6FUM5FLjQPp3cFF28FI3qnDFljA= golang.org/x/tools v0.0.0-20200904185747-39188db58858/go.mod h1:Cj7w3i3Rnn0Xh82ur9kSqwfTHTeVxaDqrfMjpcNT6bE= -golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c h1:D/mVYXCk6gUcyr7WuGlAk/ShHqgARUXc2VQxo27Hmws= -golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA= +golang.org/x/tools v0.0.0-20201201171514-ae829c33831c h1:QhVTFg9pX+Ew8jStOfhGgUuW2rvaGPgkTWPsHNQkk7M= +golang.org/x/tools v0.0.0-20201201171514-ae829c33831c/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4= diff --git a/internal/gapicgen/generator/config.go b/internal/gapicgen/generator/config.go index a4871621eba..1cc1dfc0913 100644 --- a/internal/gapicgen/generator/config.go +++ b/internal/gapicgen/generator/config.go @@ -694,7 +694,9 @@ var microgenGapicConfigs = []*microgenConfig{ importPath: "cloud.google.com/go/pubsublite/apiv1", gRPCServiceConfigPath: "google/cloud/pubsublite/v1/pubsublite_grpc_service_config.json", apiServiceConfigPath: "google/cloud/pubsublite/v1/gapic.yaml", - releaseLevel: "ga", + // Update to "ga" after the manual client (beta) for pubsublite is released. + // Also make sure the manual client is generated in .repo-metadata-full.json. + releaseLevel: "beta", }, { inputDirectoryPath: "google/cloud/automl/v1", diff --git a/internal/gapicgen/go.mod b/internal/gapicgen/go.mod index 7ad47723e65..8613a19214f 100644 --- a/internal/gapicgen/go.mod +++ b/internal/gapicgen/go.mod @@ -16,5 +16,5 @@ require ( golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9 gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f // indirect gopkg.in/src-d/go-git.v4 v4.13.1 - gopkg.in/yaml.v2 v2.3.0 + gopkg.in/yaml.v2 v2.4.0 ) diff --git a/internal/gapicgen/go.sum b/internal/gapicgen/go.sum index c8710c90a04..97b0542f179 100644 --- a/internal/gapicgen/go.sum +++ b/internal/gapicgen/go.sum @@ -455,8 +455,8 @@ gopkg.in/src-d/go-git.v4 v4.13.1/go.mod h1:nx5NYcxdKxq5fpltdHnPa2Exj4Sx0EclMWZQb gopkg.in/warnings.v0 v0.1.2 h1:wFXVbFY8DY5/xOe1ECiWdKCzZlxgshcYVNkBHstARME= gopkg.in/warnings.v0 v0.1.2/go.mod h1:jksf8JmL6Qr/oQM2OXTHunEvvTAsrWBLb6OOjuVWRNI= gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= -gopkg.in/yaml.v2 v2.3.0 h1:clyUAQHOM3G0M3f5vQj7LuJrETvjVot3Z5el9nffUtU= -gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= +gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= honnef.co/go/tools v0.0.0-20190106161140-3f1c8253044a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= honnef.co/go/tools v0.0.0-20190418001031-e561f6794a2a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= diff --git a/internal/godocfx/go.mod b/internal/godocfx/go.mod index 909c42d81d4..9449c2afa59 100644 --- a/internal/godocfx/go.mod +++ b/internal/godocfx/go.mod @@ -8,8 +8,8 @@ require ( cloud.google.com/go/datastore v1.1.0 cloud.google.com/go/storage v1.11.0 github.com/kr/pretty v0.2.1 // indirect - golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c - gopkg.in/yaml.v2 v2.3.0 + golang.org/x/tools v0.0.0-20201201171514-ae829c33831c + gopkg.in/yaml.v2 v2.4.0 ) replace cloud.google.com/go => ../.. diff --git a/internal/godocfx/go.sum b/internal/godocfx/go.sum index 0605ef2a7f6..d7cc971bf1c 100644 --- a/internal/godocfx/go.sum +++ b/internal/godocfx/go.sum @@ -67,11 +67,11 @@ github.com/google/go-cmp v0.5.1 h1:JFrFEBb2xKufg6XkJsJr+WbKb4FQlURi5RUcBveYu9k= github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian/v3 v3.1.0 h1:wCKgOCHuUEVfsaQLpPSJb7VdYCdTVZQAuOdYm1yc/60= github.com/google/martian/v3 v3.1.0/go.mod h1:y5Zk1BBys9G+gd6Jrk0W3cC1+ELVxBWuIGO+w/tUAp0= -github.com/google/pprof v0.0.0-20201116185724-cf230572f49e/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE= +github.com/google/pprof v0.0.0-20201117184057-ae444373da19/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE= github.com/google/renameio v0.1.0/go.mod h1:KWCgfxg9yswjAJkECMjeO8J8rahYeXnNhOm40UhjYkI= github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/googleapis/gax-go/v2 v2.0.5 h1:sjZBwGj9Jlw33ImPtvFviGYvseOtDM7hkSKB7+Tv3SM= @@ -243,8 +243,8 @@ golang.org/x/tools v0.0.0-20200618134242-20370b0cb4b2/go.mod h1:EkVYQZoAsY45+roY golang.org/x/tools v0.0.0-20200804011535-6c149bb5ef0d/go.mod h1:njjCfa9FT2d7l9Bc6FUM5FLjQPp3cFF28FI3qnDFljA= golang.org/x/tools v0.0.0-20200827163409-021d7c6f1ec3/go.mod h1:njjCfa9FT2d7l9Bc6FUM5FLjQPp3cFF28FI3qnDFljA= golang.org/x/tools v0.0.0-20200904185747-39188db58858/go.mod h1:Cj7w3i3Rnn0Xh82ur9kSqwfTHTeVxaDqrfMjpcNT6bE= -golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c h1:D/mVYXCk6gUcyr7WuGlAk/ShHqgARUXc2VQxo27Hmws= -golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA= +golang.org/x/tools v0.0.0-20201201171514-ae829c33831c h1:QhVTFg9pX+Ew8jStOfhGgUuW2rvaGPgkTWPsHNQkk7M= +golang.org/x/tools v0.0.0-20201201171514-ae829c33831c/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= @@ -331,8 +331,8 @@ gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127 h1:qIbj1fsPNlZgppZ+VLlY7N33 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI= gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= -gopkg.in/yaml.v2 v2.3.0 h1:clyUAQHOM3G0M3f5vQj7LuJrETvjVot3Z5el9nffUtU= -gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= +gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= honnef.co/go/tools v0.0.0-20190418001031-e561f6794a2a/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= diff --git a/internal/godocfx/testdata/golden/index.yml b/internal/godocfx/testdata/golden/index.yml index f1af2e1a778..416ac2ce044 100644 --- a/internal/godocfx/testdata/golden/index.yml +++ b/internal/godocfx/testdata/golden/index.yml @@ -3,7 +3,95 @@ items: - uid: cloud.google.com/go/storage name: cloud.google.com/go/storage id: storage - summary: "

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

\n

\nMore information about Google Cloud Storage is available at\nhttps://cloud.google.com/storage/docs.\n

\n

\nSee https://godoc.org/cloud.google.com/go for authentication, timeouts,\nconnection pooling and similar aspects of this package.\n

\n

\nAll of the methods of this package use exponential backoff to retry calls that fail\nwith certain errors, as described in\nhttps://cloud.google.com/storage/docs/exponential-backoff. Retrying continues\nindefinitely unless the controlling context is canceled or the client is closed. See\ncontext.WithTimeout and context.WithCancel.\n

\n

Creating a Client

\n

\nTo start working with this package, create a client:\n

\n
ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n    // TODO: Handle error.\n}\n
\n

\nThe client will use your default application credentials. Clients should be\nreused instead of created as needed. The methods of Client are safe for\nconcurrent use by multiple goroutines.\n

\n

\nIf you only wish to access public data, you can create\nan unauthenticated client with\n

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

Buckets

\n

\nA Google Cloud Storage bucket is a collection of objects. To work with a\nbucket, make a bucket handle:\n

\n
bkt := client.Bucket(bucketName)\n
\n

\nA handle is a reference to a bucket. You can have a handle even if the\nbucket doesn't exist yet. To create a bucket in Google Cloud Storage,\ncall Create on the handle:\n

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

\nNote that although buckets are associated with projects, bucket names are\nglobal across all projects.\n

\n

\nEach bucket has associated metadata, represented in this package by\nBucketAttrs. The third argument to BucketHandle.Create allows you to set\nthe initial BucketAttrs of a bucket. To retrieve a bucket's attributes, use\nAttrs:\n

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

Objects

\n

\nAn object holds arbitrary data as a sequence of bytes, like a file. You\nrefer to objects using a handle, just as with buckets, but unlike buckets\nyou don't explicitly create an object. Instead, the first time you write\nto an object it will be created. You can use the standard Go io.Reader\nand io.Writer interfaces to read and write object data:\n

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

\nObjects also have attributes, which you can fetch with Attrs:\n

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

Listing objects

\n

\nListing objects in a bucket is done with the Bucket.Objects method:\n

\n
query := &storage.Query{Prefix: ""}\n\nvar names []string\nit := bkt.Objects(ctx, query)\nfor {\n    attrs, err := it.Next()\n    if err == iterator.Done {\n        break\n    }\n    if err != nil {\n        log.Fatal(err)\n    }\n    names = append(names, attrs.Name)\n}\n
\n

\nIf only a subset of object attributes is needed when listing, specifying this\nsubset using Query.SetAttrSelection may speed up the listing process:\n

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

ACLs

\n

\nBoth objects and buckets have ACLs (Access Control Lists). An ACL is a list of\nACLRules, each of which specifies the role of a user, group or project. ACLs\nare suitable for fine-grained control, but you may prefer using IAM to control\naccess at the project level (see\nhttps://cloud.google.com/storage/docs/access-control/iam).\n

\n

\nTo list the ACLs of a bucket or object, obtain an ACLHandle and call its List method:\n

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

\nYou can also set and delete ACLs.\n

\n

Conditions

\n

\nEvery object has a generation and a metageneration. The generation changes\nwhenever the content changes, and the metageneration changes whenever the\nmetadata changes. Conditions let you check these values before an operation;\nthe operation only executes if the conditions match. You can use conditions to\nprevent race conditions in read-modify-write operations.\n

\n

\nFor example, say you've read an object's metadata into objAttrs. Now\nyou want to write to that object, but only if its contents haven't changed\nsince you read it. Here is how to express that:\n

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

Signed URLs

\n

\nYou can obtain a URL that lets anyone read or write an object for a limited time.\nYou don't need to create a client to do this. See the documentation of\nSignedURL for details.\n

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

Post Policy V4 Signed Request

\n

\nA type of signed request that allows uploads through HTML forms directly to Cloud Storage with\ntemporary permission. Conditions can be applied to restrict how the HTML form is used and exercised\nby a user.\n

\n

\nFor more information, please see https://cloud.google.com/storage/docs/xml-api/post-object as well\nas the documentation of GenerateSignedPostPolicyV4.\n

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

Errors

\n

\nErrors returned by this client are often of the type [`googleapi.Error`](https://godoc.org/google.golang.org/api/googleapi#Error).\nThese errors can be introspected for more information by type asserting to the richer `googleapi.Error` type. For example:\n

\n
if e, ok := err.(*googleapi.Error); ok {\n\t  if e.Code == 409 { ... }\n}\n
\n" + summary: "

\nPackage storage provides an easy way to work with Google Cloud Storage.\nGoogle + Cloud Storage stores data in named objects, which are grouped into buckets.\n

\n

\nMore + information about Google Cloud Storage is available at\nhttps://cloud.google.com/storage/docs.\n

\n

\nSee + https://godoc.org/cloud.google.com/go + for authentication, timeouts,\nconnection pooling and similar aspects of this + package.\n

\n

\nAll of the methods of this package use exponential backoff + to retry calls that fail\nwith certain errors, as described in\nhttps://cloud.google.com/storage/docs/exponential-backoff. + Retrying continues\nindefinitely unless the controlling context is canceled or + the client is closed. See\ncontext.WithTimeout and context.WithCancel.\n

\n

Creating a Client

\n

\nTo start working with + this package, create a client:\n

\n
ctx := context.Background()\nclient,
+    err := storage.NewClient(ctx)\nif err != nil {\n    // TODO: Handle error.\n}\n
\n

\nThe + client will use your default application credentials. Clients should be\nreused + instead of created as needed. The methods of Client are safe for\nconcurrent use + by multiple goroutines.\n

\n

\nIf you only wish to access public data, you + can create\nan unauthenticated client with\n

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

Buckets

\n

\nA + Google Cloud Storage bucket is a collection of objects. To work with a\nbucket, + make a bucket handle:\n

\n
bkt := client.Bucket(bucketName)\n
\n

\nA + handle is a reference to a bucket. You can have a handle even if the\nbucket doesn't + exist yet. To create a bucket in Google Cloud Storage,\ncall Create on the handle:\n

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

\nNote + that although buckets are associated with projects, bucket names are\nglobal across + all projects.\n

\n

\nEach bucket has associated metadata, represented in + this package by\nBucketAttrs. The third argument to BucketHandle.Create allows + you to set\nthe initial BucketAttrs of a bucket. To retrieve a bucket's attributes, + use\nAttrs:\n

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

Objects

\n

\nAn object + holds arbitrary data as a sequence of bytes, like a file. You\nrefer to objects + using a handle, just as with buckets, but unlike buckets\nyou don't explicitly + create an object. Instead, the first time you write\nto an object it will be created. + You can use the standard Go io.Reader\nand io.Writer interfaces to read and write + object data:\n

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

\nObjects + also have attributes, which you can fetch with Attrs:\n

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

Listing objects

\n

\nListing + objects in a bucket is done with the Bucket.Objects method:\n

\n
query
+    := &storage.Query{Prefix: ""}\n\nvar names []string\nit := bkt.Objects(ctx,
+    query)\nfor {\n    attrs, err := it.Next()\n    if err == iterator.Done {\n        break\n
+    \   }\n    if err != nil {\n        log.Fatal(err)\n    }\n    names = append(names,
+    attrs.Name)\n}\n
\n

\nIf only a subset of object attributes is needed when + listing, specifying this\nsubset using Query.SetAttrSelection may speed up the + listing process:\n

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

ACLs

\n

\nBoth objects and buckets + have ACLs (Access Control Lists). An ACL is a list of\nACLRules, each of which + specifies the role of a user, group or project. ACLs\nare suitable for fine-grained + control, but you may prefer using IAM to control\naccess at the project level + (see\nhttps://cloud.google.com/storage/docs/access-control/iam).\n

\n

\nTo + list the ACLs of a bucket or object, obtain an ACLHandle and call its List method:\n

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

\nYou can also set and delete ACLs.\n

\n

Conditions

\n

\nEvery + object has a generation and a metageneration. The generation changes\nwhenever + the content changes, and the metageneration changes whenever the\nmetadata changes. + Conditions let you check these values before an operation;\nthe operation only + executes if the conditions match. You can use conditions to\nprevent race conditions + in read-modify-write operations.\n

\n

\nFor example, say you've read + an object's metadata into objAttrs. Now\nyou want to write to that object, + but only if its contents haven't changed\nsince you read it. Here is how to + express that:\n

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

Signed URLs

\n

\nYou + can obtain a URL that lets anyone read or write an object for a limited time.\nYou + don't need to create a client to do this. See the documentation of\nSignedURL + for details.\n

\n
url, err := storage.SignedURL(bucketName, "shared-object",
+    opts)\nif err != nil {\n    // TODO: Handle error.\n}\nfmt.Println(url)\n
\n

Post Policy V4 Signed Request

\n

\nA + type of signed request that allows uploads through HTML forms directly to Cloud + Storage with\ntemporary permission. Conditions can be applied to restrict how + the HTML form is used and exercised\nby a user.\n

\n

\nFor more information, + please see https://cloud.google.com/storage/docs/xml-api/post-object + as well\nas the documentation of GenerateSignedPostPolicyV4.\n

\n
pv4,
+    err := storage.GenerateSignedPostPolicyV4(bucketName, objectName, opts)\nif err
+    != nil {\n    // TODO: Handle error.\n}\nfmt.Printf("URL: %s\\nFields; %v\\n",
+    pv4.URL, pv4.Fields)\n
\n

Errors

\n

\nErrors returned + by this client are often of the type [`googleapi.Error`](https://godoc.org/google.golang.org/api/googleapi#Error).\nThese + errors can be introspected for more information by type asserting to the richer + `googleapi.Error` type. For example:\n

\n
if e, ok := err.(*googleapi.Error);
+    ok {\n\t  if e.Code == 409 { ... }\n}\n
\n" type: package langs: - go @@ -151,7 +239,10 @@ items: langs: - go syntax: - content: "const (\n\n\t// DeleteAction is a lifecycle action that deletes a live and/or archived\n\t// objects. Takes precedence over SetStorageClass actions.\n\tDeleteAction = \"Delete\"\n\n\t// SetStorageClassAction changes the storage class of live and/or archived\n\t// objects.\n\tSetStorageClassAction = \"SetStorageClass\"\n)" + content: "const (\n\n\t// DeleteAction is a lifecycle action that deletes a live + and/or archived\n\t// objects. Takes precedence over SetStorageClass actions.\n\tDeleteAction + = \"Delete\"\n\n\t// SetStorageClassAction changes the storage class of live + and/or archived\n\t// objects.\n\tSetStorageClassAction = \"SetStorageClass\"\n)" - uid: cloud.google.com/go/storage.NoPayload,JSONPayload name: NoPayload, JSONPayload id: NoPayload,JSONPayload @@ -162,7 +253,9 @@ items: langs: - go syntax: - content: "const (\n\t// Send no payload with notification messages.\n\tNoPayload = \"NONE\"\n\n\t// Send object metadata as JSON with notification messages.\n\tJSONPayload = \"JSON_API_V1\"\n)" + content: "const (\n\t// Send no payload with notification messages.\n\tNoPayload + = \"NONE\"\n\n\t// Send object metadata as JSON with notification messages.\n\tJSONPayload + = \"JSON_API_V1\"\n)" - uid: cloud.google.com/go/storage.ObjectFinalizeEvent,ObjectMetadataUpdateEvent,ObjectDeleteEvent,ObjectArchiveEvent name: ObjectFinalizeEvent, ObjectMetadataUpdateEvent, ObjectDeleteEvent, ObjectArchiveEvent id: ObjectFinalizeEvent,ObjectMetadataUpdateEvent,ObjectDeleteEvent,ObjectArchiveEvent @@ -173,7 +266,12 @@ items: langs: - go syntax: - content: "const (\n\t// Event that occurs when an object is successfully created.\n\tObjectFinalizeEvent = \"OBJECT_FINALIZE\"\n\n\t// Event that occurs when the metadata of an existing object changes.\n\tObjectMetadataUpdateEvent = \"OBJECT_METADATA_UPDATE\"\n\n\t// Event that occurs when an object is permanently deleted.\n\tObjectDeleteEvent = \"OBJECT_DELETE\"\n\n\t// Event that occurs when the live version of an object becomes an\n\t// archived version.\n\tObjectArchiveEvent = \"OBJECT_ARCHIVE\"\n)" + content: "const (\n\t// Event that occurs when an object is successfully created.\n\tObjectFinalizeEvent + = \"OBJECT_FINALIZE\"\n\n\t// Event that occurs when the metadata of an existing + object changes.\n\tObjectMetadataUpdateEvent = \"OBJECT_METADATA_UPDATE\"\n\n\t// + Event that occurs when an object is permanently deleted.\n\tObjectDeleteEvent + = \"OBJECT_DELETE\"\n\n\t// Event that occurs when the live version of an object + becomes an\n\t// archived version.\n\tObjectArchiveEvent = \"OBJECT_ARCHIVE\"\n)" - uid: cloud.google.com/go/storage.ScopeFullControl,ScopeReadOnly,ScopeReadWrite name: ScopeFullControl, ScopeReadOnly, ScopeReadWrite id: ScopeFullControl,ScopeReadOnly,ScopeReadWrite @@ -182,7 +280,11 @@ items: langs: - go syntax: - content: "const (\n\t// ScopeFullControl grants permissions to manage your\n\t// data and permissions in Google Cloud Storage.\n\tScopeFullControl = raw.DevstorageFullControlScope\n\n\t// ScopeReadOnly grants permissions to\n\t// view your data in Google Cloud Storage.\n\tScopeReadOnly = raw.DevstorageReadOnlyScope\n\n\t// ScopeReadWrite grants permissions to manage your\n\t// data in Google Cloud Storage.\n\tScopeReadWrite = raw.DevstorageReadWriteScope\n)" + content: "const (\n\t// ScopeFullControl grants permissions to manage your\n\t// + data and permissions in Google Cloud Storage.\n\tScopeFullControl = raw.DevstorageFullControlScope\n\n\t// + ScopeReadOnly grants permissions to\n\t// view your data in Google Cloud Storage.\n\tScopeReadOnly + = raw.DevstorageReadOnlyScope\n\n\t// ScopeReadWrite grants permissions to manage + your\n\t// data in Google Cloud Storage.\n\tScopeReadWrite = raw.DevstorageReadWriteScope\n)" - uid: cloud.google.com/go/storage.ErrBucketNotExist,ErrObjectNotExist name: ErrBucketNotExist, ErrObjectNotExist id: ErrBucketNotExist,ErrObjectNotExist @@ -191,7 +293,10 @@ items: langs: - go syntax: - content: "var (\n\t// ErrBucketNotExist indicates that the bucket does not exist.\n\tErrBucketNotExist = errors.New(\"storage: bucket doesn't exist\")\n\t// ErrObjectNotExist indicates that the object does not exist.\n\tErrObjectNotExist = errors.New(\"storage: object doesn't exist\")\n)" + content: "var (\n\t// ErrBucketNotExist indicates that the bucket does not exist.\n\tErrBucketNotExist + = errors.New(\"storage: bucket doesn't exist\")\n\t// ErrObjectNotExist indicates + that the object does not exist.\n\tErrObjectNotExist = errors.New(\"storage: + object doesn't exist\")\n)" - uid: cloud.google.com/go/storage.ACLEntity name: ACLEntity id: ACLEntity @@ -218,7 +323,8 @@ items: langs: - go syntax: - content: "const (\n\tAllUsers ACLEntity = \"allUsers\"\n\tAllAuthenticatedUsers ACLEntity = \"allAuthenticatedUsers\"\n)" + content: "const (\n\tAllUsers ACLEntity = \"allUsers\"\n\tAllAuthenticatedUsers + ACLEntity = \"allAuthenticatedUsers\"\n)" - uid: cloud.google.com/go/storage.ACLHandle name: ACLHandle id: ACLHandle @@ -241,9 +347,14 @@ items: langs: - go syntax: - content: func (a *ACLHandle) Delete(ctx context.Context, entity ACLEntity) (err error) + content: func (a *ACLHandle) Delete(ctx context.Context, entity ACLEntity) (err + error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// No longer grant access to the bucket to everyone on the Internet.\n\tif err := client.Bucket(\"my-bucket\").ACL().Delete(ctx, storage.AllUsers); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// No longer grant access to + the bucket to everyone on the Internet.\n\tif err := client.Bucket(\"my-bucket\").ACL().Delete(ctx, + storage.AllUsers); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.ACLHandle.List name: | func (*ACLHandle) List @@ -257,7 +368,11 @@ items: syntax: content: func (a *ACLHandle) List(ctx context.Context) (rules []ACLRule, err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// List the default object ACLs for my-bucket.\n\taclRules, err := client.Bucket(\"my-bucket\").DefaultObjectACL().List(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(aclRules)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// List the default object + ACLs for my-bucket.\n\taclRules, err := client.Bucket(\"my-bucket\").DefaultObjectACL().List(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(aclRules)\n}\n" - uid: cloud.google.com/go/storage.ACLHandle.Set name: | func (*ACLHandle) Set @@ -269,9 +384,15 @@ items: langs: - go syntax: - content: func (a *ACLHandle) Set(ctx context.Context, entity ACLEntity, role ACLRole) (err error) + content: func (a *ACLHandle) Set(ctx context.Context, entity ACLEntity, role ACLRole) + (err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Let any authenticated user read my-bucket/my-object.\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\tif err := obj.ACL().Set(ctx, storage.AllAuthenticatedUsers, storage.RoleReader); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Let any authenticated user + read my-bucket/my-object.\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\tif + err := obj.ACL().Set(ctx, storage.AllAuthenticatedUsers, storage.RoleReader); + err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.ACLRole name: ACLRole id: ACLRole @@ -291,7 +412,8 @@ items: langs: - go syntax: - content: "const (\n\tRoleOwner ACLRole = \"OWNER\"\n\tRoleReader ACLRole = \"READER\"\n\tRoleWriter ACLRole = \"WRITER\"\n)" + content: "const (\n\tRoleOwner ACLRole = \"OWNER\"\n\tRoleReader ACLRole = \"READER\"\n\tRoleWriter + ACLRole = \"WRITER\"\n)" - uid: cloud.google.com/go/storage.ACLRule name: ACLRule id: ACLRule @@ -303,7 +425,8 @@ items: langs: - go syntax: - content: "type ACLRule struct {\n\tEntity ACLEntity\n\tEntityID string\n\tRole ACLRole\n\tDomain string\n\tEmail string\n\tProjectTeam *ProjectTeam\n}" + content: "type ACLRule struct {\n\tEntity ACLEntity\n\tEntityID string\n\tRole + \ ACLRole\n\tDomain string\n\tEmail string\n\tProjectTeam *ProjectTeam\n}" - uid: cloud.google.com/go/storage.BucketAttrs name: BucketAttrs id: BucketAttrs @@ -315,7 +438,55 @@ items: langs: - go syntax: - content: "type BucketAttrs struct {\n\t// Name is the name of the bucket.\n\t// This field is read-only.\n\tName string\n\n\t// ACL is the list of access control rules on the bucket.\n\tACL []ACLRule\n\n\t// BucketPolicyOnly is an alias for UniformBucketLevelAccess. Use of\n\t// UniformBucketLevelAccess is recommended above the use of this field.\n\t// Setting BucketPolicyOnly.Enabled OR UniformBucketLevelAccess.Enabled to\n\t// true, will enable UniformBucketLevelAccess.\n\tBucketPolicyOnly BucketPolicyOnly\n\n\t// UniformBucketLevelAccess configures access checks to use only bucket-level IAM\n\t// policies and ignore any ACL rules for the bucket.\n\t// See https://cloud.google.com/storage/docs/uniform-bucket-level-access\n\t// for more information.\n\tUniformBucketLevelAccess UniformBucketLevelAccess\n\n\t// DefaultObjectACL is the list of access controls to\n\t// apply to new objects when no object ACL is provided.\n\tDefaultObjectACL []ACLRule\n\n\t// DefaultEventBasedHold is the default value for event-based hold on\n\t// newly created objects in this bucket. It defaults to false.\n\tDefaultEventBasedHold bool\n\n\t// If not empty, applies a predefined set of access controls. It should be set\n\t// only when creating a bucket.\n\t// It is always empty for BucketAttrs returned from the service.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/insert\n\t// for valid values.\n\tPredefinedACL string\n\n\t// If not empty, applies a predefined set of default object access controls.\n\t// It should be set only when creating a bucket.\n\t// It is always empty for BucketAttrs returned from the service.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/insert\n\t// for valid values.\n\tPredefinedDefaultObjectACL string\n\n\t// Location is the location of the bucket. It defaults to \"US\".\n\tLocation string\n\n\t// MetaGeneration is the metadata generation of the bucket.\n\t// This field is read-only.\n\tMetaGeneration int64\n\n\t// StorageClass is the default storage class of the bucket. This defines\n\t// how objects in the bucket are stored and determines the SLA\n\t// and the cost of storage. Typical values are \"STANDARD\", \"NEARLINE\",\n\t// \"COLDLINE\" and \"ARCHIVE\". Defaults to \"STANDARD\".\n\t// See https://cloud.google.com/storage/docs/storage-classes for all\n\t// valid values.\n\tStorageClass string\n\n\t// Created is the creation time of the bucket.\n\t// This field is read-only.\n\tCreated time.Time\n\n\t// VersioningEnabled reports whether this bucket has versioning enabled.\n\tVersioningEnabled bool\n\n\t// Labels are the bucket's labels.\n\tLabels map[string]string\n\n\t// RequesterPays reports whether the bucket is a Requester Pays bucket.\n\t// Clients performing operations on Requester Pays buckets must provide\n\t// a user project (see BucketHandle.UserProject), which will be billed\n\t// for the operations.\n\tRequesterPays bool\n\n\t// Lifecycle is the lifecycle configuration for objects in the bucket.\n\tLifecycle Lifecycle\n\n\t// Retention policy enforces a minimum retention time for all objects\n\t// contained in the bucket. A RetentionPolicy of nil implies the bucket\n\t// has no minimum data retention.\n\t//\n\t// This feature is in private alpha release. It is not currently available to\n\t// most customers. It might be changed in backwards-incompatible ways and is not\n\t// subject to any SLA or deprecation policy.\n\tRetentionPolicy *RetentionPolicy\n\n\t// The bucket's Cross-Origin Resource Sharing (CORS) configuration.\n\tCORS []CORS\n\n\t// The encryption configuration used by default for newly inserted objects.\n\tEncryption *BucketEncryption\n\n\t// The logging configuration.\n\tLogging *BucketLogging\n\n\t// The website configuration.\n\tWebsite *BucketWebsite\n\n\t// Etag is the HTTP/1.1 Entity tag for the bucket.\n\t// This field is read-only.\n\tEtag string\n\n\t// LocationType describes how data is stored and replicated.\n\t// Typical values are \"multi-region\", \"region\" and \"dual-region\".\n\t// This field is read-only.\n\tLocationType string\n}" + content: "type BucketAttrs struct {\n\t// Name is the name of the bucket.\n\t// + This field is read-only.\n\tName string\n\n\t// ACL is the list of access control + rules on the bucket.\n\tACL []ACLRule\n\n\t// BucketPolicyOnly is an alias for + UniformBucketLevelAccess. Use of\n\t// UniformBucketLevelAccess is recommended + above the use of this field.\n\t// Setting BucketPolicyOnly.Enabled OR UniformBucketLevelAccess.Enabled + to\n\t// true, will enable UniformBucketLevelAccess.\n\tBucketPolicyOnly BucketPolicyOnly\n\n\t// + UniformBucketLevelAccess configures access checks to use only bucket-level IAM\n\t// + policies and ignore any ACL rules for the bucket.\n\t// See https://cloud.google.com/storage/docs/uniform-bucket-level-access\n\t// + for more information.\n\tUniformBucketLevelAccess UniformBucketLevelAccess\n\n\t// + DefaultObjectACL is the list of access controls to\n\t// apply to new objects + when no object ACL is provided.\n\tDefaultObjectACL []ACLRule\n\n\t// DefaultEventBasedHold + is the default value for event-based hold on\n\t// newly created objects in + this bucket. It defaults to false.\n\tDefaultEventBasedHold bool\n\n\t// If + not empty, applies a predefined set of access controls. It should be set\n\t// + only when creating a bucket.\n\t// It is always empty for BucketAttrs returned + from the service.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/insert\n\t// + for valid values.\n\tPredefinedACL string\n\n\t// If not empty, applies a predefined + set of default object access controls.\n\t// It should be set only when creating + a bucket.\n\t// It is always empty for BucketAttrs returned from the service.\n\t// + See https://cloud.google.com/storage/docs/json_api/v1/buckets/insert\n\t// for + valid values.\n\tPredefinedDefaultObjectACL string\n\n\t// Location is the location + of the bucket. It defaults to \"US\".\n\tLocation string\n\n\t// MetaGeneration + is the metadata generation of the bucket.\n\t// This field is read-only.\n\tMetaGeneration + int64\n\n\t// StorageClass is the default storage class of the bucket. This + defines\n\t// how objects in the bucket are stored and determines the SLA\n\t// + and the cost of storage. Typical values are \"STANDARD\", \"NEARLINE\",\n\t// + \"COLDLINE\" and \"ARCHIVE\". Defaults to \"STANDARD\".\n\t// See https://cloud.google.com/storage/docs/storage-classes + for all\n\t// valid values.\n\tStorageClass string\n\n\t// Created is the creation + time of the bucket.\n\t// This field is read-only.\n\tCreated time.Time\n\n\t// + VersioningEnabled reports whether this bucket has versioning enabled.\n\tVersioningEnabled + bool\n\n\t// Labels are the bucket's labels.\n\tLabels map[string]string\n\n\t// + RequesterPays reports whether the bucket is a Requester Pays bucket.\n\t// Clients + performing operations on Requester Pays buckets must provide\n\t// a user project + (see BucketHandle.UserProject), which will be billed\n\t// for the operations.\n\tRequesterPays + bool\n\n\t// Lifecycle is the lifecycle configuration for objects in the bucket.\n\tLifecycle + Lifecycle\n\n\t// Retention policy enforces a minimum retention time for all + objects\n\t// contained in the bucket. A RetentionPolicy of nil implies the + bucket\n\t// has no minimum data retention.\n\t//\n\t// This feature is in private + alpha release. It is not currently available to\n\t// most customers. It might + be changed in backwards-incompatible ways and is not\n\t// subject to any SLA + or deprecation policy.\n\tRetentionPolicy *RetentionPolicy\n\n\t// The bucket's + Cross-Origin Resource Sharing (CORS) configuration.\n\tCORS []CORS\n\n\t// The + encryption configuration used by default for newly inserted objects.\n\tEncryption + *BucketEncryption\n\n\t// The logging configuration.\n\tLogging *BucketLogging\n\n\t// + The website configuration.\n\tWebsite *BucketWebsite\n\n\t// Etag is the HTTP/1.1 + Entity tag for the bucket.\n\t// This field is read-only.\n\tEtag string\n\n\t// + LocationType describes how data is stored and replicated.\n\t// Typical values + are \"multi-region\", \"region\" and \"dual-region\".\n\t// This field is read-only.\n\tLocationType + string\n}" - uid: cloud.google.com/go/storage.BucketAttrsToUpdate name: BucketAttrsToUpdate id: BucketAttrsToUpdate @@ -326,7 +497,36 @@ items: langs: - go syntax: - content: "type BucketAttrsToUpdate struct {\n\t// If set, updates whether the bucket uses versioning.\n\tVersioningEnabled optional.Bool\n\n\t// If set, updates whether the bucket is a Requester Pays bucket.\n\tRequesterPays optional.Bool\n\n\t// DefaultEventBasedHold is the default value for event-based hold on\n\t// newly created objects in this bucket.\n\tDefaultEventBasedHold optional.Bool\n\n\t// BucketPolicyOnly is an alias for UniformBucketLevelAccess. Use of\n\t// UniformBucketLevelAccess is recommended above the use of this field.\n\t// Setting BucketPolicyOnly.Enabled OR UniformBucketLevelAccess.Enabled to\n\t// true, will enable UniformBucketLevelAccess. If both BucketPolicyOnly and\n\t// UniformBucketLevelAccess are set, the value of UniformBucketLevelAccess\n\t// will take precedence.\n\tBucketPolicyOnly *BucketPolicyOnly\n\n\t// UniformBucketLevelAccess configures access checks to use only bucket-level IAM\n\t// policies and ignore any ACL rules for the bucket.\n\t// See https://cloud.google.com/storage/docs/uniform-bucket-level-access\n\t// for more information.\n\tUniformBucketLevelAccess *UniformBucketLevelAccess\n\n\t// If set, updates the retention policy of the bucket. Using\n\t// RetentionPolicy.RetentionPeriod = 0 will delete the existing policy.\n\t//\n\t// This feature is in private alpha release. It is not currently available to\n\t// most customers. It might be changed in backwards-incompatible ways and is not\n\t// subject to any SLA or deprecation policy.\n\tRetentionPolicy *RetentionPolicy\n\n\t// If set, replaces the CORS configuration with a new configuration.\n\t// An empty (rather than nil) slice causes all CORS policies to be removed.\n\tCORS []CORS\n\n\t// If set, replaces the encryption configuration of the bucket. Using\n\t// BucketEncryption.DefaultKMSKeyName = \"\" will delete the existing\n\t// configuration.\n\tEncryption *BucketEncryption\n\n\t// If set, replaces the lifecycle configuration of the bucket.\n\tLifecycle *Lifecycle\n\n\t// If set, replaces the logging configuration of the bucket.\n\tLogging *BucketLogging\n\n\t// If set, replaces the website configuration of the bucket.\n\tWebsite *BucketWebsite\n\n\t// If not empty, applies a predefined set of access controls.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/patch.\n\tPredefinedACL string\n\n\t// If not empty, applies a predefined set of default object access controls.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/patch.\n\tPredefinedDefaultObjectACL string\n\t// contains filtered or unexported fields\n}" + content: "type BucketAttrsToUpdate struct {\n\t// If set, updates whether the + bucket uses versioning.\n\tVersioningEnabled optional.Bool\n\n\t// If set, updates + whether the bucket is a Requester Pays bucket.\n\tRequesterPays optional.Bool\n\n\t// + DefaultEventBasedHold is the default value for event-based hold on\n\t// newly + created objects in this bucket.\n\tDefaultEventBasedHold optional.Bool\n\n\t// + BucketPolicyOnly is an alias for UniformBucketLevelAccess. Use of\n\t// UniformBucketLevelAccess + is recommended above the use of this field.\n\t// Setting BucketPolicyOnly.Enabled + OR UniformBucketLevelAccess.Enabled to\n\t// true, will enable UniformBucketLevelAccess. + If both BucketPolicyOnly and\n\t// UniformBucketLevelAccess are set, the value + of UniformBucketLevelAccess\n\t// will take precedence.\n\tBucketPolicyOnly + *BucketPolicyOnly\n\n\t// UniformBucketLevelAccess configures access checks + to use only bucket-level IAM\n\t// policies and ignore any ACL rules for the + bucket.\n\t// See https://cloud.google.com/storage/docs/uniform-bucket-level-access\n\t// + for more information.\n\tUniformBucketLevelAccess *UniformBucketLevelAccess\n\n\t// + If set, updates the retention policy of the bucket. Using\n\t// RetentionPolicy.RetentionPeriod + = 0 will delete the existing policy.\n\t//\n\t// This feature is in private + alpha release. It is not currently available to\n\t// most customers. It might + be changed in backwards-incompatible ways and is not\n\t// subject to any SLA + or deprecation policy.\n\tRetentionPolicy *RetentionPolicy\n\n\t// If set, replaces + the CORS configuration with a new configuration.\n\t// An empty (rather than + nil) slice causes all CORS policies to be removed.\n\tCORS []CORS\n\n\t// If + set, replaces the encryption configuration of the bucket. Using\n\t// BucketEncryption.DefaultKMSKeyName + = \"\" will delete the existing\n\t// configuration.\n\tEncryption *BucketEncryption\n\n\t// + If set, replaces the lifecycle configuration of the bucket.\n\tLifecycle *Lifecycle\n\n\t// + If set, replaces the logging configuration of the bucket.\n\tLogging *BucketLogging\n\n\t// + If set, replaces the website configuration of the bucket.\n\tWebsite *BucketWebsite\n\n\t// + If not empty, applies a predefined set of access controls.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/patch.\n\tPredefinedACL + string\n\n\t// If not empty, applies a predefined set of default object access + controls.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/patch.\n\tPredefinedDefaultObjectACL + string\n\t// contains filtered or unexported fields\n}" - uid: cloud.google.com/go/storage.BucketAttrsToUpdate.DeleteLabel name: | func (*BucketAttrsToUpdate) DeleteLabel @@ -365,7 +565,12 @@ items: langs: - go syntax: - content: "type BucketConditions struct {\n\t// MetagenerationMatch specifies that the bucket must have the given\n\t// metageneration for the operation to occur.\n\t// If MetagenerationMatch is zero, it has no effect.\n\tMetagenerationMatch int64\n\n\t// MetagenerationNotMatch specifies that the bucket must not have the given\n\t// metageneration for the operation to occur.\n\t// If MetagenerationNotMatch is zero, it has no effect.\n\tMetagenerationNotMatch int64\n}" + content: "type BucketConditions struct {\n\t// MetagenerationMatch specifies that + the bucket must have the given\n\t// metageneration for the operation to occur.\n\t// + If MetagenerationMatch is zero, it has no effect.\n\tMetagenerationMatch int64\n\n\t// + MetagenerationNotMatch specifies that the bucket must not have the given\n\t// + metageneration for the operation to occur.\n\t// If MetagenerationNotMatch is + zero, it has no effect.\n\tMetagenerationNotMatch int64\n}" - uid: cloud.google.com/go/storage.BucketEncryption name: BucketEncryption id: BucketEncryption @@ -376,7 +581,10 @@ items: langs: - go syntax: - content: "type BucketEncryption struct {\n\t// A Cloud KMS key name, in the form\n\t// projects/P/locations/L/keyRings/R/cryptoKeys/K, that will be used to encrypt\n\t// objects inserted into this bucket, if no encryption method is specified.\n\t// The key's location must be the same as the bucket's.\n\tDefaultKMSKeyName string\n}" + content: "type BucketEncryption struct {\n\t// A Cloud KMS key name, in the form\n\t// + projects/P/locations/L/keyRings/R/cryptoKeys/K, that will be used to encrypt\n\t// + objects inserted into this bucket, if no encryption method is specified.\n\t// + The key's location must be the same as the bucket's.\n\tDefaultKMSKeyName string\n}" - uid: cloud.google.com/go/storage.BucketHandle name: BucketHandle id: BucketHandle @@ -390,7 +598,12 @@ items: syntax: content: "type BucketHandle struct {\n\t// contains filtered or unexported fields\n}" codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\tattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\n\tif err == storage.ErrBucketNotExist {\n\t\tfmt.Println(\"The bucket does not exist\")\n\t\treturn\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"The bucket exists and has attributes: %#v\\n\", attrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\tattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\n\tif + err == storage.ErrBucketNotExist {\n\t\tfmt.Println(\"The bucket does not exist\")\n\t\treturn\n\t}\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"The bucket exists + and has attributes: %#v\\n\", attrs)\n}\n" name: exists - uid: cloud.google.com/go/storage.BucketHandle.ACL name: | @@ -419,9 +632,15 @@ items: langs: - go syntax: - content: func (b *BucketHandle) AddNotification(ctx context.Context, n *Notification) (ret *Notification, err error) + content: func (b *BucketHandle) AddNotification(ctx context.Context, n *Notification) + (ret *Notification, err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tn, err := b.AddNotification(ctx, &storage.Notification{\n\t\tTopicProjectID: \"my-project\",\n\t\tTopicID: \"my-topic\",\n\t\tPayloadFormat: storage.JSONPayload,\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(n.ID)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tn, + err := b.AddNotification(ctx, &storage.Notification{\n\t\tTopicProjectID: \"my-project\",\n\t\tTopicID: + \ \"my-topic\",\n\t\tPayloadFormat: storage.JSONPayload,\n\t})\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(n.ID)\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Attrs name: | func (*BucketHandle) Attrs @@ -433,9 +652,13 @@ items: langs: - go syntax: - content: func (b *BucketHandle) Attrs(ctx context.Context) (attrs *BucketAttrs, err error) + content: func (b *BucketHandle) Attrs(ctx context.Context) (attrs *BucketAttrs, + err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Create name: | func (*BucketHandle) Create @@ -448,9 +671,13 @@ items: langs: - go syntax: - content: func (b *BucketHandle) Create(ctx context.Context, projectID string, attrs *BucketAttrs) (err error) + content: func (b *BucketHandle) Create(ctx context.Context, projectID string, + attrs *BucketAttrs) (err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := client.Bucket(\"my-bucket\").Create(ctx, \"my-project\", nil); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := client.Bucket(\"my-bucket\").Create(ctx, + \"my-project\", nil); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.DefaultObjectACL name: | func (*BucketHandle) DefaultObjectACL @@ -478,7 +705,10 @@ items: syntax: content: func (b *BucketHandle) Delete(ctx context.Context) (err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := client.Bucket(\"my-bucket\").Delete(ctx); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := client.Bucket(\"my-bucket\").Delete(ctx); + err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.DeleteNotification name: | func (*BucketHandle) DeleteNotification @@ -490,9 +720,15 @@ items: langs: - go syntax: - content: func (b *BucketHandle) DeleteNotification(ctx context.Context, id string) (err error) + content: func (b *BucketHandle) DeleteNotification(ctx context.Context, id string) + (err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nvar notificationID string\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\t// TODO: Obtain notificationID from BucketHandle.AddNotification\n\t// or BucketHandle.Notifications.\n\terr = b.DeleteNotification(ctx, notificationID)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nvar + notificationID string\n\nfunc main() {\n\tctx := context.Background()\n\tclient, + err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb + := client.Bucket(\"my-bucket\")\n\t// TODO: Obtain notificationID from BucketHandle.AddNotification\n\t// + or BucketHandle.Notifications.\n\terr = b.DeleteNotification(ctx, notificationID)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.IAM name: | func (*BucketHandle) IAM @@ -542,7 +778,14 @@ items: syntax: content: func (b *BucketHandle) LockRetentionPolicy(ctx context.Context) error codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tattrs, err := b.Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Note that locking the bucket without first attaching a RetentionPolicy\n\t// that's at least 1 day is a no-op\n\terr = b.If(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).LockRetentionPolicy(ctx)\n\tif err != nil {\n\t\t// TODO: handle err\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tattrs, + err := b.Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// + Note that locking the bucket without first attaching a RetentionPolicy\n\t// + that's at least 1 day is a no-op\n\terr = b.If(storage.BucketConditions{MetagenerationMatch: + attrs.MetaGeneration}).LockRetentionPolicy(ctx)\n\tif err != nil {\n\t\t// TODO: + handle err\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Notifications name: | func (*BucketHandle) Notifications @@ -555,9 +798,14 @@ items: langs: - go syntax: - content: func (b *BucketHandle) Notifications(ctx context.Context) (n map[string]*Notification, err error) + content: func (b *BucketHandle) Notifications(ctx context.Context) (n map[string]*Notification, + err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tns, err := b.Notifications(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfor id, n := range ns {\n\t\tfmt.Printf(\"%s: %+v\\n\", id, n)\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tns, + err := b.Notifications(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfor + id, n := range ns {\n\t\tfmt.Printf(\"%s: %+v\\n\", id, n)\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Object name: | func (*BucketHandle) Object @@ -591,7 +839,10 @@ items: syntax: content: func (b *BucketHandle) Objects(ctx context.Context, q *Query) *ObjectIterator codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Bucket(\"my-bucket\").Objects(ctx, nil)\n\t_ = it // TODO: iterate using Next or iterator.Pager.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Bucket(\"my-bucket\").Objects(ctx, + nil)\n\t_ = it // TODO: iterate using Next or iterator.Pager.\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Update name: | func (*BucketHandle) Update @@ -603,10 +854,22 @@ items: langs: - go syntax: - content: func (b *BucketHandle) Update(ctx context.Context, uattrs BucketAttrsToUpdate) (attrs *BucketAttrs, err error) + content: func (b *BucketHandle) Update(ctx context.Context, uattrs BucketAttrsToUpdate) + (attrs *BucketAttrs, err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Enable versioning in the bucket, regardless of its previous value.\n\tattrs, err := client.Bucket(\"my-bucket\").Update(ctx,\n\t\tstorage.BucketAttrsToUpdate{VersioningEnabled: true})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tattrs, err := b.Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tvar au storage.BucketAttrsToUpdate\n\tau.SetLabel(\"lab\", attrs.Labels[\"lab\"]+\"-more\")\n\tif attrs.Labels[\"delete-me\"] == \"yes\" {\n\t\tau.DeleteLabel(\"delete-me\")\n\t}\n\tattrs, err = b.\n\t\tIf(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).\n\t\tUpdate(ctx, au)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Enable versioning in the + bucket, regardless of its previous value.\n\tattrs, err := client.Bucket(\"my-bucket\").Update(ctx,\n\t\tstorage.BucketAttrsToUpdate{VersioningEnabled: + true})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tattrs, + err := b.Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tvar + au storage.BucketAttrsToUpdate\n\tau.SetLabel(\"lab\", attrs.Labels[\"lab\"]+\"-more\")\n\tif + attrs.Labels[\"delete-me\"] == \"yes\" {\n\t\tau.DeleteLabel(\"delete-me\")\n\t}\n\tattrs, + err = b.\n\t\tIf(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).\n\t\tUpdate(ctx, + au)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" name: readModifyWrite - uid: cloud.google.com/go/storage.BucketHandle.UserProject name: | @@ -636,7 +899,9 @@ items: langs: - go syntax: - content: "type BucketIterator struct {\n\t// Prefix restricts the iterator to buckets whose names begin with it.\n\tPrefix string\n\t// contains filtered or unexported fields\n}" + content: "type BucketIterator struct {\n\t// Prefix restricts the iterator to + buckets whose names begin with it.\n\tPrefix string\n\t// contains filtered + or unexported fields\n}" - uid: cloud.google.com/go/storage.BucketIterator.Next name: | func (*BucketIterator) Next @@ -654,7 +919,11 @@ items: syntax: content: func (it *BucketIterator) Next() (*BucketAttrs, error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Buckets(ctx, \"my-project\")\n\tfor {\n\t\tbucketAttrs, err := it.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: Handle error.\n\t\t}\n\t\tfmt.Println(bucketAttrs)\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Buckets(ctx, \"my-project\")\n\tfor + {\n\t\tbucketAttrs, err := it.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif + err != nil {\n\t\t\t// TODO: Handle error.\n\t\t}\n\t\tfmt.Println(bucketAttrs)\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketIterator.PageInfo name: | func (*BucketIterator) PageInfo @@ -681,7 +950,9 @@ items: langs: - go syntax: - content: "type BucketLogging struct {\n\t// The destination bucket where the current bucket's logs\n\t// should be placed.\n\tLogBucket string\n\n\t// A prefix for log object names.\n\tLogObjectPrefix string\n}" + content: "type BucketLogging struct {\n\t// The destination bucket where the current + bucket's logs\n\t// should be placed.\n\tLogBucket string\n\n\t// A prefix for + log object names.\n\tLogObjectPrefix string\n}" - uid: cloud.google.com/go/storage.BucketPolicyOnly name: BucketPolicyOnly id: BucketPolicyOnly @@ -693,7 +964,10 @@ items: langs: - go syntax: - content: "type BucketPolicyOnly struct {\n\t// Enabled specifies whether access checks use only bucket-level IAM\n\t// policies. Enabled may be disabled until the locked time.\n\tEnabled bool\n\t// LockedTime specifies the deadline for changing Enabled from true to\n\t// false.\n\tLockedTime time.Time\n}" + content: "type BucketPolicyOnly struct {\n\t// Enabled specifies whether access + checks use only bucket-level IAM\n\t// policies. Enabled may be disabled until + the locked time.\n\tEnabled bool\n\t// LockedTime specifies the deadline for + changing Enabled from true to\n\t// false.\n\tLockedTime time.Time\n}" - uid: cloud.google.com/go/storage.BucketWebsite name: BucketWebsite id: BucketWebsite @@ -706,7 +980,14 @@ items: langs: - go syntax: - content: "type BucketWebsite struct {\n\t// If the requested object path is missing, the service will ensure the path has\n\t// a trailing '/', append this suffix, and attempt to retrieve the resulting\n\t// object. This allows the creation of index.html objects to represent directory\n\t// pages.\n\tMainPageSuffix string\n\n\t// If the requested object path is missing, and any mainPageSuffix object is\n\t// missing, if applicable, the service will return the named object from this\n\t// bucket as the content for a 404 Not Found result.\n\tNotFoundPage string\n}" + content: "type BucketWebsite struct {\n\t// If the requested object path is missing, + the service will ensure the path has\n\t// a trailing '/', append this suffix, + and attempt to retrieve the resulting\n\t// object. This allows the creation + of index.html objects to represent directory\n\t// pages.\n\tMainPageSuffix + string\n\n\t// If the requested object path is missing, and any mainPageSuffix + object is\n\t// missing, if applicable, the service will return the named object + from this\n\t// bucket as the content for a 404 Not Found result.\n\tNotFoundPage + string\n}" - uid: cloud.google.com/go/storage.CORS name: CORS id: CORS @@ -717,7 +998,16 @@ items: langs: - go syntax: - content: "type CORS struct {\n\t// MaxAge is the value to return in the Access-Control-Max-Age\n\t// header used in preflight responses.\n\tMaxAge time.Duration\n\n\t// Methods is the list of HTTP methods on which to include CORS response\n\t// headers, (GET, OPTIONS, POST, etc) Note: \"*\" is permitted in the list\n\t// of methods, and means \"any method\".\n\tMethods []string\n\n\t// Origins is the list of Origins eligible to receive CORS response\n\t// headers. Note: \"*\" is permitted in the list of origins, and means\n\t// \"any Origin\".\n\tOrigins []string\n\n\t// ResponseHeaders is the list of HTTP headers other than the simple\n\t// response headers to give permission for the user-agent to share\n\t// across domains.\n\tResponseHeaders []string\n}" + content: "type CORS struct {\n\t// MaxAge is the value to return in the Access-Control-Max-Age\n\t// + header used in preflight responses.\n\tMaxAge time.Duration\n\n\t// Methods + is the list of HTTP methods on which to include CORS response\n\t// headers, + (GET, OPTIONS, POST, etc) Note: \"*\" is permitted in the list\n\t// of methods, + and means \"any method\".\n\tMethods []string\n\n\t// Origins is the list of + Origins eligible to receive CORS response\n\t// headers. Note: \"*\" is permitted + in the list of origins, and means\n\t// \"any Origin\".\n\tOrigins []string\n\n\t// + ResponseHeaders is the list of HTTP headers other than the simple\n\t// response + headers to give permission for the user-agent to share\n\t// across domains.\n\tResponseHeaders + []string\n}" - uid: cloud.google.com/go/storage.Client name: Client id: Client @@ -748,10 +1038,21 @@ items: langs: - go syntax: - content: func NewClient(ctx context.Context, opts ...option.ClientOption) (*Client, error) + content: func NewClient(ctx context.Context, opts ...option.ClientOption) (*Client, + error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\t// Use Google Application Default Credentials to authorize and authenticate the client.\n\t// More information about Application Default Credentials and how to enable is at\n\t// https://developers.google.com/identity/protocols/application-default-credentials.\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Use the client.\n\n\t// Close the client when finished.\n\tif err := client.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/option\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx, option.WithoutAuthentication())\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Use the client.\n\n\t// Close the client when finished.\n\tif err := client.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\t// Use Google Application Default + Credentials to authorize and authenticate the client.\n\t// More information + about Application Default Credentials and how to enable is at\n\t// https://developers.google.com/identity/protocols/application-default-credentials.\n\tclient, + err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// + Use the client.\n\n\t// Close the client when finished.\n\tif err := client.Close(); + err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/option\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx, + option.WithoutAuthentication())\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// + Use the client.\n\n\t// Close the client when finished.\n\tif err := client.Close(); + err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" name: unauthenticated - uid: cloud.google.com/go/storage.Client.Bucket name: | @@ -789,7 +1090,10 @@ items: syntax: content: func (c *Client) Buckets(ctx context.Context, projectID string) *BucketIterator codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Buckets(ctx, \"my-bucket\")\n\t_ = it // TODO: iterate using Next or iterator.Pager.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Buckets(ctx, \"my-bucket\")\n\t_ + = it // TODO: iterate using Next or iterator.Pager.\n}\n" - uid: cloud.google.com/go/storage.Client.Close name: | func (*Client) Close @@ -817,9 +1121,14 @@ items: langs: - go syntax: - content: func (c *Client) CreateHMACKey(ctx context.Context, projectID, serviceAccountEmail string, ...) (*HMACKey, error) + content: func (c *Client) CreateHMACKey(ctx context.Context, projectID, serviceAccountEmail + string, ...) (*HMACKey, error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkey, err := client.CreateHMACKey(ctx, \"project-id\", \"service-account-email\")\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = hkey // TODO: Use the HMAC Key.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkey, err := client.CreateHMACKey(ctx, + \"project-id\", \"service-account-email\")\n\tif err != nil {\n\t\t// TODO: + handle error.\n\t}\n\t_ = hkey // TODO: Use the HMAC Key.\n}\n" - uid: cloud.google.com/go/storage.Client.HMACKeyHandle name: | func (*Client) HMACKeyHandle @@ -849,12 +1158,29 @@ items: langs: - go syntax: - content: func (c *Client) ListHMACKeys(ctx context.Context, projectID string, opts ...HMACKeyOption) *HMACKeysIterator + content: func (c *Client) ListHMACKeys(ctx context.Context, projectID string, + opts ...HMACKeyOption) *HMACKeysIterator codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\titer := client.ListHMACKeys(ctx, \"project-id\")\n\tfor {\n\t\tkey, err := iter.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t\t_ = key // TODO: Use the key.\n\t}\n}\n" - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\titer := client.ListHMACKeys(ctx, \"project-id\", storage.ForHMACKeyServiceAccountEmail(\"service@account.email\"))\n\tfor {\n\t\tkey, err := iter.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t\t_ = key // TODO: Use the key.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\titer := client.ListHMACKeys(ctx, + \"project-id\")\n\tfor {\n\t\tkey, err := iter.Next()\n\t\tif err == iterator.Done + {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t\t_ + = key // TODO: Use the key.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\titer := client.ListHMACKeys(ctx, + \"project-id\", storage.ForHMACKeyServiceAccountEmail(\"service@account.email\"))\n\tfor + {\n\t\tkey, err := iter.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif + err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t\t_ = key // TODO: Use + the key.\n\t}\n}\n" name: forServiceAccountEmail - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\titer := client.ListHMACKeys(ctx, \"project-id\", storage.ShowDeletedHMACKeys())\n\tfor {\n\t\tkey, err := iter.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t\t_ = key // TODO: Use the key.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\titer := client.ListHMACKeys(ctx, + \"project-id\", storage.ShowDeletedHMACKeys())\n\tfor {\n\t\tkey, err := iter.Next()\n\t\tif + err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: + handle error.\n\t\t}\n\t\t_ = key // TODO: Use the key.\n\t}\n}\n" name: showDeletedKeys - uid: cloud.google.com/go/storage.Client.ServiceAccount name: | @@ -867,7 +1193,8 @@ items: langs: - go syntax: - content: func (c *Client) ServiceAccount(ctx context.Context, projectID string) (string, error) + content: func (c *Client) ServiceAccount(ctx context.Context, projectID string) + (string, error) - uid: cloud.google.com/go/storage.Composer name: Composer id: Composer @@ -880,7 +1207,15 @@ items: langs: - go syntax: - content: "type Composer struct {\n\t// ObjectAttrs are optional attributes to set on the destination object.\n\t// Any attributes must be initialized before any calls on the Composer. Nil\n\t// or zero-valued attributes are ignored.\n\tObjectAttrs\n\n\t// SendCRC specifies whether to transmit a CRC32C field. It should be set\n\t// to true in addition to setting the Composer's CRC32C field, because zero\n\t// is a valid CRC and normally a zero would not be transmitted.\n\t// If a CRC32C is sent, and the data in the destination object does not match\n\t// the checksum, the compose will be rejected.\n\tSendCRC32C bool\n\t// contains filtered or unexported fields\n}" + content: "type Composer struct {\n\t// ObjectAttrs are optional attributes to + set on the destination object.\n\t// Any attributes must be initialized before + any calls on the Composer. Nil\n\t// or zero-valued attributes are ignored.\n\tObjectAttrs\n\n\t// + SendCRC specifies whether to transmit a CRC32C field. It should be set\n\t// + to true in addition to setting the Composer's CRC32C field, because zero\n\t// + is a valid CRC and normally a zero would not be transmitted.\n\t// If a CRC32C + is sent, and the data in the destination object does not match\n\t// the checksum, + the compose will be rejected.\n\tSendCRC32C bool\n\t// contains filtered or + unexported fields\n}" - uid: cloud.google.com/go/storage.Composer.Run name: | func (*Composer) Run @@ -892,9 +1227,19 @@ items: langs: - go syntax: - content: func (c *Composer) Run(ctx context.Context) (attrs *ObjectAttrs, err error) + content: func (c *Composer) Run(ctx context.Context) (attrs *ObjectAttrs, err + error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tbkt := client.Bucket(\"bucketname\")\n\tsrc1 := bkt.Object(\"o1\")\n\tsrc2 := bkt.Object(\"o2\")\n\tdst := bkt.Object(\"o3\")\n\n\t// Compose and modify metadata.\n\tc := dst.ComposerFrom(src1, src2)\n\tc.ContentType = \"text/plain\"\n\n\t// Set the expected checksum for the destination object to be validated by\n\t// the backend (if desired).\n\tc.CRC32C = 42\n\tc.SendCRC32C = true\n\n\tattrs, err := c.Run(ctx)\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(attrs)\n\t// Just compose.\n\tattrs, err = dst.ComposerFrom(src1, src2).Run(ctx)\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tbkt := client.Bucket(\"bucketname\")\n\tsrc1 + := bkt.Object(\"o1\")\n\tsrc2 := bkt.Object(\"o2\")\n\tdst := bkt.Object(\"o3\")\n\n\t// + Compose and modify metadata.\n\tc := dst.ComposerFrom(src1, src2)\n\tc.ContentType + = \"text/plain\"\n\n\t// Set the expected checksum for the destination object + to be validated by\n\t// the backend (if desired).\n\tc.CRC32C = 42\n\tc.SendCRC32C + = true\n\n\tattrs, err := c.Run(ctx)\n\tif err != nil {\n\t\t// TODO: Handle + error.\n\t}\n\tfmt.Println(attrs)\n\t// Just compose.\n\tattrs, err = dst.ComposerFrom(src1, + src2).Run(ctx)\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" - uid: cloud.google.com/go/storage.Conditions name: Conditions id: Conditions @@ -911,7 +1256,20 @@ items: langs: - go syntax: - content: "type Conditions struct {\n\n\t// GenerationMatch specifies that the object must have the given generation\n\t// for the operation to occur.\n\t// If GenerationMatch is zero, it has no effect.\n\t// Use DoesNotExist to specify that the object does not exist in the bucket.\n\tGenerationMatch int64\n\n\t// GenerationNotMatch specifies that the object must not have the given\n\t// generation for the operation to occur.\n\t// If GenerationNotMatch is zero, it has no effect.\n\tGenerationNotMatch int64\n\n\t// DoesNotExist specifies that the object must not exist in the bucket for\n\t// the operation to occur.\n\t// If DoesNotExist is false, it has no effect.\n\tDoesNotExist bool\n\n\t// MetagenerationMatch specifies that the object must have the given\n\t// metageneration for the operation to occur.\n\t// If MetagenerationMatch is zero, it has no effect.\n\tMetagenerationMatch int64\n\n\t// MetagenerationNotMatch specifies that the object must not have the given\n\t// metageneration for the operation to occur.\n\t// If MetagenerationNotMatch is zero, it has no effect.\n\tMetagenerationNotMatch int64\n}" + content: "type Conditions struct {\n\n\t// GenerationMatch specifies that the + object must have the given generation\n\t// for the operation to occur.\n\t// + If GenerationMatch is zero, it has no effect.\n\t// Use DoesNotExist to specify + that the object does not exist in the bucket.\n\tGenerationMatch int64\n\n\t// + GenerationNotMatch specifies that the object must not have the given\n\t// generation + for the operation to occur.\n\t// If GenerationNotMatch is zero, it has no effect.\n\tGenerationNotMatch + int64\n\n\t// DoesNotExist specifies that the object must not exist in the bucket + for\n\t// the operation to occur.\n\t// If DoesNotExist is false, it has no + effect.\n\tDoesNotExist bool\n\n\t// MetagenerationMatch specifies that the + object must have the given\n\t// metageneration for the operation to occur.\n\t// + If MetagenerationMatch is zero, it has no effect.\n\tMetagenerationMatch int64\n\n\t// + MetagenerationNotMatch specifies that the object must not have the given\n\t// + metageneration for the operation to occur.\n\t// If MetagenerationNotMatch is + zero, it has no effect.\n\tMetagenerationNotMatch int64\n}" - uid: cloud.google.com/go/storage.Copier name: Copier id: Copier @@ -922,7 +1280,27 @@ items: langs: - go syntax: - content: "type Copier struct {\n\t// ObjectAttrs are optional attributes to set on the destination object.\n\t// Any attributes must be initialized before any calls on the Copier. Nil\n\t// or zero-valued attributes are ignored.\n\tObjectAttrs\n\n\t// RewriteToken can be set before calling Run to resume a copy\n\t// operation. After Run returns a non-nil error, RewriteToken will\n\t// have been updated to contain the value needed to resume the copy.\n\tRewriteToken string\n\n\t// ProgressFunc can be used to monitor the progress of a multi-RPC copy\n\t// operation. If ProgressFunc is not nil and copying requires multiple\n\t// calls to the underlying service (see\n\t// https://cloud.google.com/storage/docs/json_api/v1/objects/rewrite), then\n\t// ProgressFunc will be invoked after each call with the number of bytes of\n\t// content copied so far and the total size in bytes of the source object.\n\t//\n\t// ProgressFunc is intended to make upload progress available to the\n\t// application. For example, the implementation of ProgressFunc may update\n\t// a progress bar in the application's UI, or log the result of\n\t// float64(copiedBytes)/float64(totalBytes).\n\t//\n\t// ProgressFunc should return quickly without blocking.\n\tProgressFunc func(copiedBytes, totalBytes uint64)\n\n\t// The Cloud KMS key, in the form projects/P/locations/L/keyRings/R/cryptoKeys/K,\n\t// that will be used to encrypt the object. Overrides the object's KMSKeyName, if\n\t// any.\n\t//\n\t// Providing both a DestinationKMSKeyName and a customer-supplied encryption key\n\t// (via ObjectHandle.Key) on the destination object will result in an error when\n\t// Run is called.\n\tDestinationKMSKeyName string\n\t// contains filtered or unexported fields\n}" + content: "type Copier struct {\n\t// ObjectAttrs are optional attributes to set + on the destination object.\n\t// Any attributes must be initialized before any + calls on the Copier. Nil\n\t// or zero-valued attributes are ignored.\n\tObjectAttrs\n\n\t// + RewriteToken can be set before calling Run to resume a copy\n\t// operation. + After Run returns a non-nil error, RewriteToken will\n\t// have been updated + to contain the value needed to resume the copy.\n\tRewriteToken string\n\n\t// + ProgressFunc can be used to monitor the progress of a multi-RPC copy\n\t// operation. + If ProgressFunc is not nil and copying requires multiple\n\t// calls to the + underlying service (see\n\t// https://cloud.google.com/storage/docs/json_api/v1/objects/rewrite), + then\n\t// ProgressFunc will be invoked after each call with the number of bytes + of\n\t// content copied so far and the total size in bytes of the source object.\n\t//\n\t// + ProgressFunc is intended to make upload progress available to the\n\t// application. + For example, the implementation of ProgressFunc may update\n\t// a progress + bar in the application's UI, or log the result of\n\t// float64(copiedBytes)/float64(totalBytes).\n\t//\n\t// + ProgressFunc should return quickly without blocking.\n\tProgressFunc func(copiedBytes, + totalBytes uint64)\n\n\t// The Cloud KMS key, in the form projects/P/locations/L/keyRings/R/cryptoKeys/K,\n\t// + that will be used to encrypt the object. Overrides the object's KMSKeyName, + if\n\t// any.\n\t//\n\t// Providing both a DestinationKMSKeyName and a customer-supplied + encryption key\n\t// (via ObjectHandle.Key) on the destination object will result + in an error when\n\t// Run is called.\n\tDestinationKMSKeyName string\n\t// + contains filtered or unexported fields\n}" - uid: cloud.google.com/go/storage.Copier.Run name: | func (*Copier) Run @@ -936,8 +1314,22 @@ items: syntax: content: func (c *Copier) Run(ctx context.Context) (attrs *ObjectAttrs, err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tsrc := client.Bucket(\"bucketname\").Object(\"file1\")\n\tdst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\n\t// Copy content and modify metadata.\n\tcopier := dst.CopierFrom(src)\n\tcopier.ContentType = \"text/plain\"\n\tattrs, err := copier.Run(ctx)\n\tif err != nil {\n\t\t// TODO: Handle error, possibly resuming with copier.RewriteToken.\n\t}\n\tfmt.Println(attrs)\n\n\t// Just copy content.\n\tattrs, err = dst.CopierFrom(src).Run(ctx)\n\tif err != nil {\n\t\t// TODO: Handle error. No way to resume.\n\t}\n\tfmt.Println(attrs)\n}\n" - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"log\"\n)\n\nfunc main() {\n\t// Display progress across multiple rewrite RPCs.\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tsrc := client.Bucket(\"bucketname\").Object(\"file1\")\n\tdst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\n\tcopier := dst.CopierFrom(src)\n\tcopier.ProgressFunc = func(copiedBytes, totalBytes uint64) {\n\t\tlog.Printf(\"copy %.1f%% done\", float64(copiedBytes)/float64(totalBytes)*100)\n\t}\n\tif _, err := copier.Run(ctx); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tsrc := client.Bucket(\"bucketname\").Object(\"file1\")\n\tdst + := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\n\t// Copy content + and modify metadata.\n\tcopier := dst.CopierFrom(src)\n\tcopier.ContentType + = \"text/plain\"\n\tattrs, err := copier.Run(ctx)\n\tif err != nil {\n\t\t// + TODO: Handle error, possibly resuming with copier.RewriteToken.\n\t}\n\tfmt.Println(attrs)\n\n\t// + Just copy content.\n\tattrs, err = dst.CopierFrom(src).Run(ctx)\n\tif err != + nil {\n\t\t// TODO: Handle error. No way to resume.\n\t}\n\tfmt.Println(attrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"log\"\n)\n\nfunc + main() {\n\t// Display progress across multiple rewrite RPCs.\n\tctx := context.Background()\n\tclient, + err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tsrc + := client.Bucket(\"bucketname\").Object(\"file1\")\n\tdst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\n\tcopier + := dst.CopierFrom(src)\n\tcopier.ProgressFunc = func(copiedBytes, totalBytes + uint64) {\n\t\tlog.Printf(\"copy %.1f%% done\", float64(copiedBytes)/float64(totalBytes)*100)\n\t}\n\tif + _, err := copier.Run(ctx); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" name: progress - uid: cloud.google.com/go/storage.HMACKey name: HMACKey @@ -954,7 +1346,17 @@ items: langs: - go syntax: - content: "type HMACKey struct {\n\t// The HMAC's secret key.\n\tSecret string\n\n\t// AccessID is the ID of the HMAC key.\n\tAccessID string\n\n\t// Etag is the HTTP/1.1 Entity tag.\n\tEtag string\n\n\t// ID is the ID of the HMAC key, including the ProjectID and AccessID.\n\tID string\n\n\t// ProjectID is the ID of the project that owns the\n\t// service account to which the key authenticates.\n\tProjectID string\n\n\t// ServiceAccountEmail is the email address\n\t// of the key's associated service account.\n\tServiceAccountEmail string\n\n\t// CreatedTime is the creation time of the HMAC key.\n\tCreatedTime time.Time\n\n\t// UpdatedTime is the last modification time of the HMAC key metadata.\n\tUpdatedTime time.Time\n\n\t// State is the state of the HMAC key.\n\t// It can be one of StateActive, StateInactive or StateDeleted.\n\tState HMACState\n}" + content: "type HMACKey struct {\n\t// The HMAC's secret key.\n\tSecret string\n\n\t// + AccessID is the ID of the HMAC key.\n\tAccessID string\n\n\t// Etag is the HTTP/1.1 + Entity tag.\n\tEtag string\n\n\t// ID is the ID of the HMAC key, including the + ProjectID and AccessID.\n\tID string\n\n\t// ProjectID is the ID of the project + that owns the\n\t// service account to which the key authenticates.\n\tProjectID + string\n\n\t// ServiceAccountEmail is the email address\n\t// of the key's associated + service account.\n\tServiceAccountEmail string\n\n\t// CreatedTime is the creation + time of the HMAC key.\n\tCreatedTime time.Time\n\n\t// UpdatedTime is the last + modification time of the HMAC key metadata.\n\tUpdatedTime time.Time\n\n\t// + State is the state of the HMAC key.\n\t// It can be one of StateActive, StateInactive + or StateDeleted.\n\tState HMACState\n}" - uid: cloud.google.com/go/storage.HMACKeyAttrsToUpdate name: HMACKeyAttrsToUpdate id: HMACKeyAttrsToUpdate @@ -967,7 +1369,9 @@ items: langs: - go syntax: - content: "type HMACKeyAttrsToUpdate struct {\n\t// State is required and must be either StateActive or StateInactive.\n\tState HMACState\n\n\t// Etag is an optional field and it is the HTTP/1.1 Entity tag.\n\tEtag string\n}" + content: "type HMACKeyAttrsToUpdate struct {\n\t// State is required and must + be either StateActive or StateInactive.\n\tState HMACState\n\n\t// Etag is an + optional field and it is the HTTP/1.1 Entity tag.\n\tEtag string\n}" - uid: cloud.google.com/go/storage.HMACKeyHandle name: HMACKeyHandle id: HMACKeyHandle @@ -996,9 +1400,15 @@ items: langs: - go syntax: - content: func (hkh *HMACKeyHandle) Delete(ctx context.Context, opts ...HMACKeyOption) error + content: func (hkh *HMACKeyHandle) Delete(ctx context.Context, opts ...HMACKeyOption) + error codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\n\t// Make sure that the HMACKey being deleted has a status of inactive.\n\tif err := hkh.Delete(ctx); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkh := client.HMACKeyHandle(\"project-id\", + \"access-key-id\")\n\t// Make sure that the HMACKey being deleted has a status + of inactive.\n\tif err := hkh.Delete(ctx); err != nil {\n\t\t// TODO: handle + error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.HMACKeyHandle.Get name: | func (*HMACKeyHandle) Get @@ -1016,9 +1426,14 @@ items: langs: - go syntax: - content: func (hkh *HMACKeyHandle) Get(ctx context.Context, opts ...HMACKeyOption) (*HMACKey, error) + content: func (hkh *HMACKeyHandle) Get(ctx context.Context, opts ...HMACKeyOption) + (*HMACKey, error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\n\thkey, err := hkh.Get(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = hkey // TODO: Use the HMAC Key.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkh := client.HMACKeyHandle(\"project-id\", + \"access-key-id\")\n\thkey, err := hkh.Get(ctx)\n\tif err != nil {\n\t\t// TODO: + handle error.\n\t}\n\t_ = hkey // TODO: Use the HMAC Key.\n}\n" - uid: cloud.google.com/go/storage.HMACKeyHandle.Update name: | func (*HMACKeyHandle) Update @@ -1032,9 +1447,15 @@ items: langs: - go syntax: - content: func (h *HMACKeyHandle) Update(ctx context.Context, au HMACKeyAttrsToUpdate, opts ...HMACKeyOption) (*HMACKey, error) + content: func (h *HMACKeyHandle) Update(ctx context.Context, au HMACKeyAttrsToUpdate, + opts ...HMACKeyOption) (*HMACKey, error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\n\tukey, err := hkh.Update(ctx, storage.HMACKeyAttrsToUpdate{\n\t\tState: storage.Inactive,\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = ukey // TODO: Use the HMAC Key.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkh := client.HMACKeyHandle(\"project-id\", + \"access-key-id\")\n\tukey, err := hkh.Update(ctx, storage.HMACKeyAttrsToUpdate{\n\t\tState: + storage.Inactive,\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ + = ukey // TODO: Use the HMAC Key.\n}\n" - uid: cloud.google.com/go/storage.HMACKeyOption name: HMACKeyOption id: HMACKeyOption @@ -1047,7 +1468,8 @@ items: langs: - go syntax: - content: "type HMACKeyOption interface {\n\t// contains filtered or unexported methods\n}" + content: "type HMACKeyOption interface {\n\t// contains filtered or unexported + methods\n}" - uid: cloud.google.com/go/storage.HMACKeyOption.ForHMACKeyServiceAccountEmail name: | func ForHMACKeyServiceAccountEmail @@ -1111,7 +1533,8 @@ items: langs: - go syntax: - content: "type HMACKeysIterator struct {\n\t// contains filtered or unexported fields\n}" + content: "type HMACKeysIterator struct {\n\t// contains filtered or unexported + fields\n}" - uid: cloud.google.com/go/storage.HMACKeysIterator.Next name: | func (*HMACKeysIterator) Next @@ -1167,7 +1590,13 @@ items: langs: - go syntax: - content: "const (\n\t// Active is the status for an active key that can be used to sign\n\t// requests.\n\tActive HMACState = \"ACTIVE\"\n\n\t// Inactive is the status for an inactive key thus requests signed by\n\t// this key will be denied.\n\tInactive HMACState = \"INACTIVE\"\n\n\t// Deleted is the status for a key that is deleted.\n\t// Once in this state the key cannot key cannot be recovered\n\t// and does not count towards key limits. Deleted keys will be cleaned\n\t// up later.\n\tDeleted HMACState = \"DELETED\"\n)" + content: "const (\n\t// Active is the status for an active key that can be used + to sign\n\t// requests.\n\tActive HMACState = \"ACTIVE\"\n\n\t// Inactive is + the status for an inactive key thus requests signed by\n\t// this key will be + denied.\n\tInactive HMACState = \"INACTIVE\"\n\n\t// Deleted is the status for + a key that is deleted.\n\t// Once in this state the key cannot key cannot be + recovered\n\t// and does not count towards key limits. Deleted keys will be + cleaned\n\t// up later.\n\tDeleted HMACState = \"DELETED\"\n)" - uid: cloud.google.com/go/storage.Lifecycle name: Lifecycle id: Lifecycle @@ -1189,7 +1618,12 @@ items: langs: - go syntax: - content: "type LifecycleAction struct {\n\t// Type is the type of action to take on matching objects.\n\t//\n\t// Acceptable values are \"Delete\" to delete matching objects and\n\t// \"SetStorageClass\" to set the storage class defined in StorageClass on\n\t// matching objects.\n\tType string\n\n\t// StorageClass is the storage class to set on matching objects if the Action\n\t// is \"SetStorageClass\".\n\tStorageClass string\n}" + content: "type LifecycleAction struct {\n\t// Type is the type of action to take + on matching objects.\n\t//\n\t// Acceptable values are \"Delete\" to delete + matching objects and\n\t// \"SetStorageClass\" to set the storage class defined + in StorageClass on\n\t// matching objects.\n\tType string\n\n\t// StorageClass + is the storage class to set on matching objects if the Action\n\t// is \"SetStorageClass\".\n\tStorageClass + string\n}" - uid: cloud.google.com/go/storage.LifecycleCondition name: LifecycleCondition id: LifecycleCondition @@ -1203,7 +1637,30 @@ items: langs: - go syntax: - content: "type LifecycleCondition struct {\n\t// AgeInDays is the age of the object in days.\n\tAgeInDays int64\n\n\t// CreatedBefore is the time the object was created.\n\t//\n\t// This condition is satisfied when an object is created before midnight of\n\t// the specified date in UTC.\n\tCreatedBefore time.Time\n\n\t// CustomTimeBefore is the CustomTime metadata field of the object. This\n\t// condition is satisfied when an object's CustomTime timestamp is before\n\t// midnight of the specified date in UTC.\n\t//\n\t// This condition can only be satisfied if CustomTime has been set.\n\tCustomTimeBefore time.Time\n\n\t// DaysSinceCustomTime is the days elapsed since the CustomTime date of the\n\t// object. This condition can only be satisfied if CustomTime has been set.\n\tDaysSinceCustomTime int64\n\n\t// DaysSinceNoncurrentTime is the days elapsed since the noncurrent timestamp\n\t// of the object. This condition is relevant only for versioned objects.\n\tDaysSinceNoncurrentTime int64\n\n\t// Liveness specifies the object's liveness. Relevant only for versioned objects\n\tLiveness Liveness\n\n\t// MatchesStorageClasses is the condition matching the object's storage\n\t// class.\n\t//\n\t// Values include \"STANDARD\", \"NEARLINE\", \"COLDLINE\" and \"ARCHIVE\".\n\tMatchesStorageClasses []string\n\n\t// NoncurrentTimeBefore is the noncurrent timestamp of the object. This\n\t// condition is satisfied when an object's noncurrent timestamp is before\n\t// midnight of the specified date in UTC.\n\t//\n\t// This condition is relevant only for versioned objects.\n\tNoncurrentTimeBefore time.Time\n\n\t// NumNewerVersions is the condition matching objects with a number of newer versions.\n\t//\n\t// If the value is N, this condition is satisfied when there are at least N\n\t// versions (including the live version) newer than this version of the\n\t// object.\n\tNumNewerVersions int64\n}" + content: "type LifecycleCondition struct {\n\t// AgeInDays is the age of the object + in days.\n\tAgeInDays int64\n\n\t// CreatedBefore is the time the object was + created.\n\t//\n\t// This condition is satisfied when an object is created before + midnight of\n\t// the specified date in UTC.\n\tCreatedBefore time.Time\n\n\t// + CustomTimeBefore is the CustomTime metadata field of the object. This\n\t// + condition is satisfied when an object's CustomTime timestamp is before\n\t// + midnight of the specified date in UTC.\n\t//\n\t// This condition can only be + satisfied if CustomTime has been set.\n\tCustomTimeBefore time.Time\n\n\t// + DaysSinceCustomTime is the days elapsed since the CustomTime date of the\n\t// + object. This condition can only be satisfied if CustomTime has been set.\n\tDaysSinceCustomTime + int64\n\n\t// DaysSinceNoncurrentTime is the days elapsed since the noncurrent + timestamp\n\t// of the object. This condition is relevant only for versioned + objects.\n\tDaysSinceNoncurrentTime int64\n\n\t// Liveness specifies the object's + liveness. Relevant only for versioned objects\n\tLiveness Liveness\n\n\t// MatchesStorageClasses + is the condition matching the object's storage\n\t// class.\n\t//\n\t// Values + include \"STANDARD\", \"NEARLINE\", \"COLDLINE\" and \"ARCHIVE\".\n\tMatchesStorageClasses + []string\n\n\t// NoncurrentTimeBefore is the noncurrent timestamp of the object. + This\n\t// condition is satisfied when an object's noncurrent timestamp is before\n\t// + midnight of the specified date in UTC.\n\t//\n\t// This condition is relevant + only for versioned objects.\n\tNoncurrentTimeBefore time.Time\n\n\t// NumNewerVersions + is the condition matching objects with a number of newer versions.\n\t//\n\t// + If the value is N, this condition is satisfied when there are at least N\n\t// + versions (including the live version) newer than this version of the\n\t// object.\n\tNumNewerVersions + int64\n}" - uid: cloud.google.com/go/storage.LifecycleRule name: LifecycleRule id: LifecycleRule @@ -1217,7 +1674,10 @@ items: langs: - go syntax: - content: "type LifecycleRule struct {\n\t// Action is the action to take when all of the associated conditions are\n\t// met.\n\tAction LifecycleAction\n\n\t// Condition is the set of conditions that must be met for the associated\n\t// action to be taken.\n\tCondition LifecycleCondition\n}" + content: "type LifecycleRule struct {\n\t// Action is the action to take when + all of the associated conditions are\n\t// met.\n\tAction LifecycleAction\n\n\t// + Condition is the set of conditions that must be met for the associated\n\t// + action to be taken.\n\tCondition LifecycleCondition\n}" - uid: cloud.google.com/go/storage.Liveness name: Liveness id: Liveness @@ -1237,7 +1697,9 @@ items: langs: - go syntax: - content: "const (\n\t// LiveAndArchived includes both live and archived objects.\n\tLiveAndArchived Liveness = iota\n\t// Live specifies that the object is still live.\n\tLive\n\t// Archived specifies that the object is archived.\n\tArchived\n)" + content: "const (\n\t// LiveAndArchived includes both live and archived objects.\n\tLiveAndArchived + Liveness = iota\n\t// Live specifies that the object is still live.\n\tLive\n\t// + Archived specifies that the object is archived.\n\tArchived\n)" - uid: cloud.google.com/go/storage.Notification name: Notification id: Notification @@ -1249,7 +1711,17 @@ items: langs: - go syntax: - content: "type Notification struct {\n\t//The ID of the notification.\n\tID string\n\n\t// The ID of the topic to which this subscription publishes.\n\tTopicID string\n\n\t// The ID of the project to which the topic belongs.\n\tTopicProjectID string\n\n\t// Only send notifications about listed event types. If empty, send notifications\n\t// for all event types.\n\t// See https://cloud.google.com/storage/docs/pubsub-notifications#events.\n\tEventTypes []string\n\n\t// If present, only apply this notification configuration to object names that\n\t// begin with this prefix.\n\tObjectNamePrefix string\n\n\t// An optional list of additional attributes to attach to each Cloud PubSub\n\t// message published for this notification subscription.\n\tCustomAttributes map[string]string\n\n\t// The contents of the message payload.\n\t// See https://cloud.google.com/storage/docs/pubsub-notifications#payload.\n\tPayloadFormat string\n}" + content: "type Notification struct {\n\t//The ID of the notification.\n\tID string\n\n\t// + The ID of the topic to which this subscription publishes.\n\tTopicID string\n\n\t// + The ID of the project to which the topic belongs.\n\tTopicProjectID string\n\n\t// + Only send notifications about listed event types. If empty, send notifications\n\t// + for all event types.\n\t// See https://cloud.google.com/storage/docs/pubsub-notifications#events.\n\tEventTypes + []string\n\n\t// If present, only apply this notification configuration to object + names that\n\t// begin with this prefix.\n\tObjectNamePrefix string\n\n\t// + An optional list of additional attributes to attach to each Cloud PubSub\n\t// + message published for this notification subscription.\n\tCustomAttributes map[string]string\n\n\t// + The contents of the message payload.\n\t// See https://cloud.google.com/storage/docs/pubsub-notifications#payload.\n\tPayloadFormat + string\n}" - uid: cloud.google.com/go/storage.ObjectAttrs name: ObjectAttrs id: ObjectAttrs @@ -1260,7 +1732,77 @@ items: langs: - go syntax: - content: "type ObjectAttrs struct {\n\t// Bucket is the name of the bucket containing this GCS object.\n\t// This field is read-only.\n\tBucket string\n\n\t// Name is the name of the object within the bucket.\n\t// This field is read-only.\n\tName string\n\n\t// ContentType is the MIME type of the object's content.\n\tContentType string\n\n\t// ContentLanguage is the content language of the object's content.\n\tContentLanguage string\n\n\t// CacheControl is the Cache-Control header to be sent in the response\n\t// headers when serving the object data.\n\tCacheControl string\n\n\t// EventBasedHold specifies whether an object is under event-based hold. New\n\t// objects created in a bucket whose DefaultEventBasedHold is set will\n\t// default to that value.\n\tEventBasedHold bool\n\n\t// TemporaryHold specifies whether an object is under temporary hold. While\n\t// this flag is set to true, the object is protected against deletion and\n\t// overwrites.\n\tTemporaryHold bool\n\n\t// RetentionExpirationTime is a server-determined value that specifies the\n\t// earliest time that the object's retention period expires.\n\t// This is a read-only field.\n\tRetentionExpirationTime time.Time\n\n\t// ACL is the list of access control rules for the object.\n\tACL []ACLRule\n\n\t// If not empty, applies a predefined set of access controls. It should be set\n\t// only when writing, copying or composing an object. When copying or composing,\n\t// it acts as the destinationPredefinedAcl parameter.\n\t// PredefinedACL is always empty for ObjectAttrs returned from the service.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/objects/insert\n\t// for valid values.\n\tPredefinedACL string\n\n\t// Owner is the owner of the object. This field is read-only.\n\t//\n\t// If non-zero, it is in the form of \"user-\".\n\tOwner string\n\n\t// Size is the length of the object's content. This field is read-only.\n\tSize int64\n\n\t// ContentEncoding is the encoding of the object's content.\n\tContentEncoding string\n\n\t// ContentDisposition is the optional Content-Disposition header of the object\n\t// sent in the response headers.\n\tContentDisposition string\n\n\t// MD5 is the MD5 hash of the object's content. This field is read-only,\n\t// except when used from a Writer. If set on a Writer, the uploaded\n\t// data is rejected if its MD5 hash does not match this field.\n\tMD5 []byte\n\n\t// CRC32C is the CRC32 checksum of the object's content using the Castagnoli93\n\t// polynomial. This field is read-only, except when used from a Writer or\n\t// Composer. In those cases, if the SendCRC32C field in the Writer or Composer\n\t// is set to is true, the uploaded data is rejected if its CRC32C hash does\n\t// not match this field.\n\tCRC32C uint32\n\n\t// MediaLink is an URL to the object's content. This field is read-only.\n\tMediaLink string\n\n\t// Metadata represents user-provided metadata, in key/value pairs.\n\t// It can be nil if no metadata is provided.\n\tMetadata map[string]string\n\n\t// Generation is the generation number of the object's content.\n\t// This field is read-only.\n\tGeneration int64\n\n\t// Metageneration is the version of the metadata for this\n\t// object at this generation. This field is used for preconditions\n\t// and for detecting changes in metadata. A metageneration number\n\t// is only meaningful in the context of a particular generation\n\t// of a particular object. This field is read-only.\n\tMetageneration int64\n\n\t// StorageClass is the storage class of the object. This defines\n\t// how objects are stored and determines the SLA and the cost of storage.\n\t// Typical values are \"STANDARD\", \"NEARLINE\", \"COLDLINE\" and \"ARCHIVE\".\n\t// Defaults to \"STANDARD\".\n\t// See https://cloud.google.com/storage/docs/storage-classes for all\n\t// valid values.\n\tStorageClass string\n\n\t// Created is the time the object was created. This field is read-only.\n\tCreated time.Time\n\n\t// Deleted is the time the object was deleted.\n\t// If not deleted, it is the zero value. This field is read-only.\n\tDeleted time.Time\n\n\t// Updated is the creation or modification time of the object.\n\t// For buckets with versioning enabled, changing an object's\n\t// metadata does not change this property. This field is read-only.\n\tUpdated time.Time\n\n\t// CustomerKeySHA256 is the base64-encoded SHA-256 hash of the\n\t// customer-supplied encryption key for the object. It is empty if there is\n\t// no customer-supplied encryption key.\n\t// See // https://cloud.google.com/storage/docs/encryption for more about\n\t// encryption in Google Cloud Storage.\n\tCustomerKeySHA256 string\n\n\t// Cloud KMS key name, in the form\n\t// projects/P/locations/L/keyRings/R/cryptoKeys/K, used to encrypt this object,\n\t// if the object is encrypted by such a key.\n\t//\n\t// Providing both a KMSKeyName and a customer-supplied encryption key (via\n\t// ObjectHandle.Key) will result in an error when writing an object.\n\tKMSKeyName string\n\n\t// Prefix is set only for ObjectAttrs which represent synthetic \"directory\n\t// entries\" when iterating over buckets using Query.Delimiter. See\n\t// ObjectIterator.Next. When set, no other fields in ObjectAttrs will be\n\t// populated.\n\tPrefix string\n\n\t// Etag is the HTTP/1.1 Entity tag for the object.\n\t// This field is read-only.\n\tEtag string\n\n\t// A user-specified timestamp which can be applied to an object. This is\n\t// typically set in order to use the CustomTimeBefore and DaysSinceCustomTime\n\t// LifecycleConditions to manage object lifecycles.\n\t//\n\t// CustomTime cannot be removed once set on an object. It can be updated to a\n\t// later value but not to an earlier one.\n\tCustomTime time.Time\n}" + content: "type ObjectAttrs struct {\n\t// Bucket is the name of the bucket containing + this GCS object.\n\t// This field is read-only.\n\tBucket string\n\n\t// Name + is the name of the object within the bucket.\n\t// This field is read-only.\n\tName + string\n\n\t// ContentType is the MIME type of the object's content.\n\tContentType + string\n\n\t// ContentLanguage is the content language of the object's content.\n\tContentLanguage + string\n\n\t// CacheControl is the Cache-Control header to be sent in the response\n\t// + headers when serving the object data.\n\tCacheControl string\n\n\t// EventBasedHold + specifies whether an object is under event-based hold. New\n\t// objects created + in a bucket whose DefaultEventBasedHold is set will\n\t// default to that value.\n\tEventBasedHold + bool\n\n\t// TemporaryHold specifies whether an object is under temporary hold. + While\n\t// this flag is set to true, the object is protected against deletion + and\n\t// overwrites.\n\tTemporaryHold bool\n\n\t// RetentionExpirationTime + is a server-determined value that specifies the\n\t// earliest time that the + object's retention period expires.\n\t// This is a read-only field.\n\tRetentionExpirationTime + time.Time\n\n\t// ACL is the list of access control rules for the object.\n\tACL + []ACLRule\n\n\t// If not empty, applies a predefined set of access controls. + It should be set\n\t// only when writing, copying or composing an object. When + copying or composing,\n\t// it acts as the destinationPredefinedAcl parameter.\n\t// + PredefinedACL is always empty for ObjectAttrs returned from the service.\n\t// + See https://cloud.google.com/storage/docs/json_api/v1/objects/insert\n\t// for + valid values.\n\tPredefinedACL string\n\n\t// Owner is the owner of the object. + This field is read-only.\n\t//\n\t// If non-zero, it is in the form of \"user-\".\n\tOwner + string\n\n\t// Size is the length of the object's content. This field is read-only.\n\tSize + int64\n\n\t// ContentEncoding is the encoding of the object's content.\n\tContentEncoding + string\n\n\t// ContentDisposition is the optional Content-Disposition header + of the object\n\t// sent in the response headers.\n\tContentDisposition string\n\n\t// + MD5 is the MD5 hash of the object's content. This field is read-only,\n\t// + except when used from a Writer. If set on a Writer, the uploaded\n\t// data + is rejected if its MD5 hash does not match this field.\n\tMD5 []byte\n\n\t// + CRC32C is the CRC32 checksum of the object's content using the Castagnoli93\n\t// + polynomial. This field is read-only, except when used from a Writer or\n\t// + Composer. In those cases, if the SendCRC32C field in the Writer or Composer\n\t// + is set to is true, the uploaded data is rejected if its CRC32C hash does\n\t// + not match this field.\n\tCRC32C uint32\n\n\t// MediaLink is an URL to the object's + content. This field is read-only.\n\tMediaLink string\n\n\t// Metadata represents + user-provided metadata, in key/value pairs.\n\t// It can be nil if no metadata + is provided.\n\tMetadata map[string]string\n\n\t// Generation is the generation + number of the object's content.\n\t// This field is read-only.\n\tGeneration + int64\n\n\t// Metageneration is the version of the metadata for this\n\t// object + at this generation. This field is used for preconditions\n\t// and for detecting + changes in metadata. A metageneration number\n\t// is only meaningful in the + context of a particular generation\n\t// of a particular object. This field + is read-only.\n\tMetageneration int64\n\n\t// StorageClass is the storage class + of the object. This defines\n\t// how objects are stored and determines the + SLA and the cost of storage.\n\t// Typical values are \"STANDARD\", \"NEARLINE\", + \"COLDLINE\" and \"ARCHIVE\".\n\t// Defaults to \"STANDARD\".\n\t// See https://cloud.google.com/storage/docs/storage-classes + for all\n\t// valid values.\n\tStorageClass string\n\n\t// Created is the time + the object was created. This field is read-only.\n\tCreated time.Time\n\n\t// + Deleted is the time the object was deleted.\n\t// If not deleted, it is the + zero value. This field is read-only.\n\tDeleted time.Time\n\n\t// Updated is + the creation or modification time of the object.\n\t// For buckets with versioning + enabled, changing an object's\n\t// metadata does not change this property. + This field is read-only.\n\tUpdated time.Time\n\n\t// CustomerKeySHA256 is the + base64-encoded SHA-256 hash of the\n\t// customer-supplied encryption key for + the object. It is empty if there is\n\t// no customer-supplied encryption key.\n\t// + See // https://cloud.google.com/storage/docs/encryption for more about\n\t// + encryption in Google Cloud Storage.\n\tCustomerKeySHA256 string\n\n\t// Cloud + KMS key name, in the form\n\t// projects/P/locations/L/keyRings/R/cryptoKeys/K, + used to encrypt this object,\n\t// if the object is encrypted by such a key.\n\t//\n\t// + Providing both a KMSKeyName and a customer-supplied encryption key (via\n\t// + ObjectHandle.Key) will result in an error when writing an object.\n\tKMSKeyName + string\n\n\t// Prefix is set only for ObjectAttrs which represent synthetic + \"directory\n\t// entries\" when iterating over buckets using Query.Delimiter. + See\n\t// ObjectIterator.Next. When set, no other fields in ObjectAttrs will + be\n\t// populated.\n\tPrefix string\n\n\t// Etag is the HTTP/1.1 Entity tag + for the object.\n\t// This field is read-only.\n\tEtag string\n\n\t// A user-specified + timestamp which can be applied to an object. This is\n\t// typically set in + order to use the CustomTimeBefore and DaysSinceCustomTime\n\t// LifecycleConditions + to manage object lifecycles.\n\t//\n\t// CustomTime cannot be removed once set + on an object. It can be updated to a\n\t// later value but not to an earlier + one.\n\tCustomTime time.Time\n}" - uid: cloud.google.com/go/storage.ObjectAttrsToUpdate name: ObjectAttrsToUpdate id: ObjectAttrsToUpdate @@ -1281,7 +1823,14 @@ items: langs: - go syntax: - content: "type ObjectAttrsToUpdate struct {\n\tEventBasedHold optional.Bool\n\tTemporaryHold optional.Bool\n\tContentType optional.String\n\tContentLanguage optional.String\n\tContentEncoding optional.String\n\tContentDisposition optional.String\n\tCacheControl optional.String\n\tCustomTime time.Time\n\tMetadata map[string]string // set to map[string]string{} to delete\n\tACL []ACLRule\n\n\t// If not empty, applies a predefined set of access controls. ACL must be nil.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/objects/patch.\n\tPredefinedACL string\n}" + content: "type ObjectAttrsToUpdate struct {\n\tEventBasedHold optional.Bool\n\tTemporaryHold + \ optional.Bool\n\tContentType optional.String\n\tContentLanguage + \ optional.String\n\tContentEncoding optional.String\n\tContentDisposition + optional.String\n\tCacheControl optional.String\n\tCustomTime time.Time\n\tMetadata + \ map[string]string // set to map[string]string{} to delete\n\tACL + \ []ACLRule\n\n\t// If not empty, applies a predefined set of + access controls. ACL must be nil.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/objects/patch.\n\tPredefinedACL + string\n}" - uid: cloud.google.com/go/storage.ObjectHandle name: ObjectHandle id: ObjectHandle @@ -1295,7 +1844,12 @@ items: syntax: content: "type ObjectHandle struct {\n\t// contains filtered or unexported fields\n}" codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\tattrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\n\tif err == storage.ErrObjectNotExist {\n\t\tfmt.Println(\"The object does not exist\")\n\t\treturn\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"The object exists and has attributes: %#v\\n\", attrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\tattrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\n\tif + err == storage.ErrObjectNotExist {\n\t\tfmt.Println(\"The object does not exist\")\n\t\treturn\n\t}\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"The object exists + and has attributes: %#v\\n\", attrs)\n}\n" name: exists - uid: cloud.google.com/go/storage.ObjectHandle.ACL name: | @@ -1323,10 +1877,21 @@ items: langs: - go syntax: - content: func (o *ObjectHandle) Attrs(ctx context.Context) (attrs *ObjectAttrs, err error) + content: func (o *ObjectHandle) Attrs(ctx context.Context) (attrs *ObjectAttrs, + err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(objAttrs)\n}\n" - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\t// Read the object.\n\tobjAttrs1, err := obj.Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Do something else for a while.\n\ttime.Sleep(5 * time.Minute)\n\t// Now read the same contents, even if the object has been written since the last read.\n\tobjAttrs2, err := obj.Generation(objAttrs1.Generation).Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(objAttrs1, objAttrs2)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(objAttrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\t// + Read the object.\n\tobjAttrs1, err := obj.Attrs(ctx)\n\tif err != nil {\n\t\t// + TODO: handle error.\n\t}\n\t// Do something else for a while.\n\ttime.Sleep(5 + * time.Minute)\n\t// Now read the same contents, even if the object has been + written since the last read.\n\tobjAttrs2, err := obj.Generation(objAttrs1.Generation).Attrs(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(objAttrs1, objAttrs2)\n}\n" name: withConditions - uid: cloud.google.com/go/storage.ObjectHandle.BucketName name: | @@ -1376,7 +1941,13 @@ items: syntax: content: func (dst *ObjectHandle) CopierFrom(src *ObjectHandle) *Copier codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nvar key1, key2 []byte\n\nfunc main() {\n\t// To rotate the encryption key on an object, copy it onto itself.\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"bucketname\").Object(\"obj\")\n\t// Assume obj is encrypted with key1, and we want to change to key2.\n\t_, err = obj.Key(key2).CopierFrom(obj.Key(key1)).Run(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nvar + key1, key2 []byte\n\nfunc main() {\n\t// To rotate the encryption key on an + object, copy it onto itself.\n\tctx := context.Background()\n\tclient, err := + storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj + := client.Bucket(\"bucketname\").Object(\"obj\")\n\t// Assume obj is encrypted + with key1, and we want to change to key2.\n\t_, err = obj.Key(key2).CopierFrom(obj.Key(key1)).Run(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" name: rotateEncryptionKeys - uid: cloud.google.com/go/storage.ObjectHandle.Delete name: | @@ -1391,7 +1962,18 @@ items: syntax: content: func (o *ObjectHandle) Delete(ctx context.Context) error codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// To delete multiple objects in a bucket, list them with an\n\t// ObjectIterator, then Delete them.\n\n\t// If you are using this package on the App Engine Flex runtime,\n\t// you can init a bucket client with your app's default bucket name.\n\t// See http://godoc.org/google.golang.org/appengine/file#DefaultBucketName.\n\tbucket := client.Bucket(\"my-bucket\")\n\tit := bucket.Objects(ctx, nil)\n\tfor {\n\t\tobjAttrs, err := it.Next()\n\t\tif err != nil && err != iterator.Done {\n\t\t\t// TODO: Handle error.\n\t\t}\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err := bucket.Object(objAttrs.Name).Delete(ctx); err != nil {\n\t\t\t// TODO: Handle error.\n\t\t}\n\t}\n\tfmt.Println(\"deleted all object items in the bucket specified.\")\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// To delete multiple objects + in a bucket, list them with an\n\t// ObjectIterator, then Delete them.\n\n\t// + If you are using this package on the App Engine Flex runtime,\n\t// you can + init a bucket client with your app's default bucket name.\n\t// See http://godoc.org/google.golang.org/appengine/file#DefaultBucketName.\n\tbucket + := client.Bucket(\"my-bucket\")\n\tit := bucket.Objects(ctx, nil)\n\tfor {\n\t\tobjAttrs, + err := it.Next()\n\t\tif err != nil && err != iterator.Done {\n\t\t\t// TODO: + Handle error.\n\t\t}\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif + err := bucket.Object(objAttrs.Name).Delete(ctx); err != nil {\n\t\t\t// TODO: + Handle error.\n\t\t}\n\t}\n\tfmt.Println(\"deleted all object items in the bucket + specified.\")\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.Generation name: | func (*ObjectHandle) Generation @@ -1409,7 +1991,13 @@ items: syntax: content: func (o *ObjectHandle) Generation(gen int64) *ObjectHandle codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"io\"\n\t\"os\"\n)\n\nvar gen int64\n\nfunc main() {\n\t// Read an object's contents from generation gen, regardless of the\n\t// current generation of the object.\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\trc, err := obj.Generation(gen).NewReader(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\tif _, err := io.Copy(os.Stdout, rc); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"io\"\n\t\"os\"\n)\n\nvar + gen int64\n\nfunc main() {\n\t// Read an object's contents from generation gen, + regardless of the\n\t// current generation of the object.\n\tctx := context.Background()\n\tclient, + err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj + := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\trc, err := obj.Generation(gen).NewReader(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\tif _, err + := io.Copy(os.Stdout, rc); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.If name: | func (*ObjectHandle) If @@ -1427,7 +2015,17 @@ items: syntax: content: func (o *ObjectHandle) If(conds Conditions) *ObjectHandle codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/googleapi\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nvar gen int64\n\nfunc main() {\n\t// Read from an object only if the current generation is gen.\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\trc, err := obj.If(storage.Conditions{GenerationMatch: gen}).NewReader(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\tif _, err := io.Copy(os.Stdout, rc); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := rc.Close(); err != nil {\n\t\tswitch ee := err.(type) {\n\t\tcase *googleapi.Error:\n\t\t\tif ee.Code == http.StatusPreconditionFailed {\n\t\t\t\t// The condition presented in the If failed.\n\t\t\t\t// TODO: handle error.\n\t\t\t}\n\n\t\t\t// TODO: handle other status codes here.\n\n\t\tdefault:\n\t\t\t// TODO: handle error.\n\t\t}\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/googleapi\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nvar + gen int64\n\nfunc main() {\n\t// Read from an object only if the current generation + is gen.\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\trc, + err := obj.If(storage.Conditions{GenerationMatch: gen}).NewReader(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\tif _, err := io.Copy(os.Stdout, + rc); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := rc.Close(); + err != nil {\n\t\tswitch ee := err.(type) {\n\t\tcase *googleapi.Error:\n\t\t\tif + ee.Code == http.StatusPreconditionFailed {\n\t\t\t\t// The condition presented + in the If failed.\n\t\t\t\t// TODO: handle error.\n\t\t\t}\n\n\t\t\t// TODO: + handle other status codes here.\n\n\t\tdefault:\n\t\t\t// TODO: handle error.\n\t\t}\n\t}\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.Key name: | func (*ObjectHandle) Key @@ -1445,7 +2043,13 @@ items: syntax: content: func (o *ObjectHandle) Key(encryptionKey []byte) *ObjectHandle codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nvar secretKey []byte\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\t// Encrypt the object's contents.\n\tw := obj.Key(secretKey).NewWriter(ctx)\n\tif _, err := w.Write([]byte(\"top secret\")); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := w.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nvar + secretKey []byte\n\nfunc main() {\n\tctx := context.Background()\n\tclient, + err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj + := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\t// Encrypt the object's + contents.\n\tw := obj.Key(secretKey).NewWriter(ctx)\n\tif _, err := w.Write([]byte(\"top + secret\")); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := w.Close(); + err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.NewRangeReader name: | func (*ObjectHandle) NewRangeReader @@ -1466,12 +2070,31 @@ items: langs: - go syntax: - content: func (o *ObjectHandle) NewRangeReader(ctx context.Context, offset, length int64) (r *Reader, err error) + content: func (o *ObjectHandle) NewRangeReader(ctx context.Context, offset, length + int64) (r *Reader, err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Read only the first 64K.\n\trc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, 0, 64*1024)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\n\tslurp, err := ioutil.ReadAll(rc)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"first 64K of file contents:\\n%s\\n\", slurp)\n}\n" - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Read only the last 10 bytes until the end of the file.\n\trc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, -10, -1)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\n\tslurp, err := ioutil.ReadAll(rc)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"Last 10 bytes from the end of the file:\\n%s\\n\", slurp)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Read only the first 64K.\n\trc, + err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, + 0, 64*1024)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\n\tslurp, + err := ioutil.ReadAll(rc)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"first + 64K of file contents:\\n%s\\n\", slurp)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Read only the last 10 bytes + until the end of the file.\n\trc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, + -10, -1)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\n\tslurp, + err := ioutil.ReadAll(rc)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"Last + 10 bytes from the end of the file:\\n%s\\n\", slurp)\n}\n" name: lastNBytes - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Read from the 101st byte until the end of the file.\n\trc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, 100, -1)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\n\tslurp, err := ioutil.ReadAll(rc)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"From 101st byte until the end:\\n%s\\n\", slurp)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Read from the 101st byte + until the end of the file.\n\trc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, + 100, -1)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\n\tslurp, + err := ioutil.ReadAll(rc)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"From + 101st byte until the end:\\n%s\\n\", slurp)\n}\n" name: untilEnd - uid: cloud.google.com/go/storage.ObjectHandle.NewReader name: | @@ -1490,7 +2113,12 @@ items: syntax: content: func (o *ObjectHandle) NewReader(ctx context.Context) (*Reader, error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\trc, err := client.Bucket(\"my-bucket\").Object(\"my-object\").NewReader(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tslurp, err := ioutil.ReadAll(rc)\n\trc.Close()\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"file contents:\", slurp)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\trc, err := client.Bucket(\"my-bucket\").Object(\"my-object\").NewReader(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tslurp, err := ioutil.ReadAll(rc)\n\trc.Close()\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"file contents:\", + slurp)\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.NewWriter name: | func (*ObjectHandle) NewWriter @@ -1518,7 +2146,10 @@ items: syntax: content: func (o *ObjectHandle) NewWriter(ctx context.Context) *Writer codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n\t_ = wc // TODO: Use the Writer.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n\t_ + = wc // TODO: Use the Writer.\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.ObjectName name: | func (*ObjectHandle) ObjectName @@ -1556,9 +2187,16 @@ items: langs: - go syntax: - content: func (o *ObjectHandle) Update(ctx context.Context, uattrs ObjectAttrsToUpdate) (oa *ObjectAttrs, err error) + content: func (o *ObjectHandle) Update(ctx context.Context, uattrs ObjectAttrsToUpdate) + (oa *ObjectAttrs, err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Change only the content type of the object.\n\tobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Update(ctx, storage.ObjectAttrsToUpdate{\n\t\tContentType: \"text/html\",\n\t\tContentDisposition: \"\", // delete ContentDisposition\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(objAttrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Change only the content + type of the object.\n\tobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Update(ctx, + storage.ObjectAttrsToUpdate{\n\t\tContentType: \"text/html\",\n\t\tContentDisposition: + \"\", // delete ContentDisposition\n\t})\n\tif err != nil {\n\t\t// TODO: handle + error.\n\t}\n\tfmt.Println(objAttrs)\n}\n" - uid: cloud.google.com/go/storage.ObjectIterator name: ObjectIterator id: ObjectIterator @@ -1593,7 +2231,11 @@ items: syntax: content: func (it *ObjectIterator) Next() (*ObjectAttrs, error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Bucket(\"my-bucket\").Objects(ctx, nil)\n\tfor {\n\t\tobjAttrs, err := it.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: Handle error.\n\t\t}\n\t\tfmt.Println(objAttrs)\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Bucket(\"my-bucket\").Objects(ctx, + nil)\n\tfor {\n\t\tobjAttrs, err := it.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif + err != nil {\n\t\t\t// TODO: Handle error.\n\t\t}\n\t\tfmt.Println(objAttrs)\n\t}\n}\n" - uid: cloud.google.com/go/storage.ObjectIterator.PageInfo name: | func (*ObjectIterator) PageInfo @@ -1618,7 +2260,22 @@ items: langs: - go syntax: - content: "type PolicyV4Fields struct {\n\t// ACL specifies the access control permissions for the object.\n\t// Optional.\n\tACL string\n\t// CacheControl specifies the caching directives for the object.\n\t// Optional.\n\tCacheControl string\n\t// ContentType specifies the media type of the object.\n\t// Optional.\n\tContentType string\n\t// ContentDisposition specifies how the file will be served back to requesters.\n\t// Optional.\n\tContentDisposition string\n\t// ContentEncoding specifies the decompressive transcoding that the object.\n\t// This field is complementary to ContentType in that the file could be\n\t// compressed but ContentType specifies the file's original media type.\n\t// Optional.\n\tContentEncoding string\n\t// Metadata specifies custom metadata for the object.\n\t// If any key doesn't begin with \"x-goog-meta-\", an error will be returned.\n\t// Optional.\n\tMetadata map[string]string\n\t// StatusCodeOnSuccess when set, specifies the status code that Cloud Storage\n\t// will serve back on successful upload of the object.\n\t// Optional.\n\tStatusCodeOnSuccess int\n\t// RedirectToURLOnSuccess when set, specifies the URL that Cloud Storage\n\t// will serve back on successful upload of the object.\n\t// Optional.\n\tRedirectToURLOnSuccess string\n}" + content: "type PolicyV4Fields struct {\n\t// ACL specifies the access control + permissions for the object.\n\t// Optional.\n\tACL string\n\t// CacheControl + specifies the caching directives for the object.\n\t// Optional.\n\tCacheControl + string\n\t// ContentType specifies the media type of the object.\n\t// Optional.\n\tContentType + string\n\t// ContentDisposition specifies how the file will be served back to + requesters.\n\t// Optional.\n\tContentDisposition string\n\t// ContentEncoding + specifies the decompressive transcoding that the object.\n\t// This field is + complementary to ContentType in that the file could be\n\t// compressed but + ContentType specifies the file's original media type.\n\t// Optional.\n\tContentEncoding + string\n\t// Metadata specifies custom metadata for the object.\n\t// If any + key doesn't begin with \"x-goog-meta-\", an error will be returned.\n\t// Optional.\n\tMetadata + map[string]string\n\t// StatusCodeOnSuccess when set, specifies the status code + that Cloud Storage\n\t// will serve back on successful upload of the object.\n\t// + Optional.\n\tStatusCodeOnSuccess int\n\t// RedirectToURLOnSuccess when set, + specifies the URL that Cloud Storage\n\t// will serve back on successful upload + of the object.\n\t// Optional.\n\tRedirectToURLOnSuccess string\n}" - uid: cloud.google.com/go/storage.PostPolicyV4 name: PostPolicyV4 id: PostPolicyV4 @@ -1629,7 +2286,10 @@ items: langs: - go syntax: - content: "type PostPolicyV4 struct {\n\t// URL is the generated URL that the file upload will be made to.\n\tURL string\n\t// Fields specifies the generated key-values that the file uploader\n\t// must include in their multipart upload form.\n\tFields map[string]string\n}" + content: "type PostPolicyV4 struct {\n\t// URL is the generated URL that the file + upload will be made to.\n\tURL string\n\t// Fields specifies the generated key-values + that the file uploader\n\t// must include in their multipart upload form.\n\tFields + map[string]string\n}" - uid: cloud.google.com/go/storage.PostPolicyV4.GenerateSignedPostPolicyV4 name: | func GenerateSignedPostPolicyV4 @@ -1642,9 +2302,32 @@ items: langs: - go syntax: - content: func GenerateSignedPostPolicyV4(bucket, object string, opts *PostPolicyV4Options) (*PostPolicyV4, error) + content: func GenerateSignedPostPolicyV4(bucket, object string, opts *PostPolicyV4Options) + (*PostPolicyV4, error) codeexamples: - - content: "package main\n\nimport (\n\t\"bytes\"\n\t\"cloud.google.com/go/storage\"\n\t\"io\"\n\t\"mime/multipart\"\n\t\"net/http\"\n\t\"time\"\n)\n\nfunc main() {\n\tpv4, err := storage.GenerateSignedPostPolicyV4(\"my-bucket\", \"my-object.txt\", &storage.PostPolicyV4Options{\n\t\tGoogleAccessID: \"my-access-id\",\n\t\tPrivateKey: []byte(\"my-private-key\"),\n\n\t\t// The upload expires in 2hours.\n\t\tExpires: time.Now().Add(2 * time.Hour),\n\n\t\tFields: &storage.PolicyV4Fields{\n\t\t\tStatusCodeOnSuccess: 200,\n\t\t\tRedirectToURLOnSuccess: \"https://example.org/\",\n\t\t\t// It MUST only be a text file.\n\t\t\tContentType: \"text/plain\",\n\t\t},\n\n\t\t// The conditions that the uploaded file will be expected to conform to.\n\t\tConditions: []storage.PostPolicyV4Condition{\n\t\t\t// Make the file a maximum of 10mB.\n\t\t\tstorage.ConditionContentLengthRange(0, 10<<20),\n\t\t},\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\t// Now you can upload your file using the generated post policy\n\t// with a plain HTTP client or even the browser.\n\tformBuf := new(bytes.Buffer)\n\tmw := multipart.NewWriter(formBuf)\n\tfor fieldName, value := range pv4.Fields {\n\t\tif err := mw.WriteField(fieldName, value); err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t}\n\tfile := bytes.NewReader(bytes.Repeat([]byte(\"a\"), 100))\n\n\tmf, err := mw.CreateFormFile(\"file\", \"myfile.txt\")\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif _, err := io.Copy(mf, file); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := mw.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\t// Compose the request.\n\treq, err := http.NewRequest(\"POST\", pv4.URL, formBuf)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Ensure the Content-Type is derived from the multipart writer.\n\treq.Header.Set(\"Content-Type\", mw.FormDataContentType())\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = res\n}\n" + - content: "package main\n\nimport (\n\t\"bytes\"\n\t\"cloud.google.com/go/storage\"\n\t\"io\"\n\t\"mime/multipart\"\n\t\"net/http\"\n\t\"time\"\n)\n\nfunc + main() {\n\tpv4, err := storage.GenerateSignedPostPolicyV4(\"my-bucket\", \"my-object.txt\", + &storage.PostPolicyV4Options{\n\t\tGoogleAccessID: \"my-access-id\",\n\t\tPrivateKey: + \ []byte(\"my-private-key\"),\n\n\t\t// The upload expires in 2hours.\n\t\tExpires: + time.Now().Add(2 * time.Hour),\n\n\t\tFields: &storage.PolicyV4Fields{\n\t\t\tStatusCodeOnSuccess: + \ 200,\n\t\t\tRedirectToURLOnSuccess: \"https://example.org/\",\n\t\t\t// + It MUST only be a text file.\n\t\t\tContentType: \"text/plain\",\n\t\t},\n\n\t\t// + The conditions that the uploaded file will be expected to conform to.\n\t\tConditions: + []storage.PostPolicyV4Condition{\n\t\t\t// Make the file a maximum of 10mB.\n\t\t\tstorage.ConditionContentLengthRange(0, + 10<<20),\n\t\t},\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\t// + Now you can upload your file using the generated post policy\n\t// with a plain + HTTP client or even the browser.\n\tformBuf := new(bytes.Buffer)\n\tmw := multipart.NewWriter(formBuf)\n\tfor + fieldName, value := range pv4.Fields {\n\t\tif err := mw.WriteField(fieldName, + value); err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t}\n\tfile := bytes.NewReader(bytes.Repeat([]byte(\"a\"), + 100))\n\n\tmf, err := mw.CreateFormFile(\"file\", \"myfile.txt\")\n\tif err + != nil {\n\t\t// TODO: handle error.\n\t}\n\tif _, err := io.Copy(mf, file); + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := mw.Close(); err != + nil {\n\t\t// TODO: handle error.\n\t}\n\n\t// Compose the request.\n\treq, + err := http.NewRequest(\"POST\", pv4.URL, formBuf)\n\tif err != nil {\n\t\t// + TODO: handle error.\n\t}\n\t// Ensure the Content-Type is derived from the multipart + writer.\n\treq.Header.Set(\"Content-Type\", mw.FormDataContentType())\n\tres, + err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ + = res\n}\n" - uid: cloud.google.com/go/storage.PostPolicyV4Condition name: PostPolicyV4Condition id: PostPolicyV4Condition @@ -1656,7 +2339,8 @@ items: langs: - go syntax: - content: "type PostPolicyV4Condition interface {\n\tjson.Marshaler\n\t// contains filtered or unexported methods\n}" + content: "type PostPolicyV4Condition interface {\n\tjson.Marshaler\n\t// contains + filtered or unexported methods\n}" - uid: cloud.google.com/go/storage.PostPolicyV4Condition.ConditionContentLengthRange name: | func ConditionContentLengthRange @@ -1695,7 +2379,41 @@ items: langs: - go syntax: - content: "type PostPolicyV4Options struct {\n\t// GoogleAccessID represents the authorizer of the signed URL generation.\n\t// It is typically the Google service account client email address from\n\t// the Google Developers Console in the form of \"xxx@developer.gserviceaccount.com\".\n\t// Required.\n\tGoogleAccessID string\n\n\t// PrivateKey is the Google service account private key. It is obtainable\n\t// from the Google Developers Console.\n\t// At https://console.developers.google.com/project//apiui/credential,\n\t// create a service account client ID or reuse one of your existing service account\n\t// credentials. Click on the \"Generate new P12 key\" to generate and download\n\t// a new private key. Once you download the P12 file, use the following command\n\t// to convert it into a PEM file.\n\t//\n\t// $ openssl pkcs12 -in key.p12 -passin pass:notasecret -out key.pem -nodes\n\t//\n\t// Provide the contents of the PEM file as a byte slice.\n\t// Exactly one of PrivateKey or SignBytes must be non-nil.\n\tPrivateKey []byte\n\n\t// SignBytes is a function for implementing custom signing. For example, if\n\t// your application is running on Google App Engine, you can use\n\t// appengine's internal signing function:\n\t// ctx := appengine.NewContext(request)\n\t// acc, _ := appengine.ServiceAccount(ctx)\n\t// url, err := SignedURL(\"bucket\", \"object\", &SignedURLOptions{\n\t// \tGoogleAccessID: acc,\n\t// \tSignBytes: func(b []byte) ([]byte, error) {\n\t// \t\t_, signedBytes, err := appengine.SignBytes(ctx, b)\n\t// \t\treturn signedBytes, err\n\t// \t},\n\t// \t// etc.\n\t// })\n\t//\n\t// Exactly one of PrivateKey or SignBytes must be non-nil.\n\tSignBytes func(hashBytes []byte) (signature []byte, err error)\n\n\t// Expires is the expiration time on the signed URL.\n\t// It must be a time in the future.\n\t// Required.\n\tExpires time.Time\n\n\t// Style provides options for the type of URL to use. Options are\n\t// PathStyle (default), BucketBoundHostname, and VirtualHostedStyle. See\n\t// https://cloud.google.com/storage/docs/request-endpoints for details.\n\t// Optional.\n\tStyle URLStyle\n\n\t// Insecure when set indicates that the generated URL's scheme\n\t// will use \"http\" instead of \"https\" (default).\n\t// Optional.\n\tInsecure bool\n\n\t// Fields specifies the attributes of a PostPolicyV4 request.\n\t// When Fields is non-nil, its attributes must match those that will\n\t// passed into field Conditions.\n\t// Optional.\n\tFields *PolicyV4Fields\n\n\t// The conditions that the uploaded file will be expected to conform to.\n\t// When used, the failure of an upload to satisfy a condition will result in\n\t// a 4XX status code, back with the message describing the problem.\n\t// Optional.\n\tConditions []PostPolicyV4Condition\n}" + content: "type PostPolicyV4Options struct {\n\t// GoogleAccessID represents the + authorizer of the signed URL generation.\n\t// It is typically the Google service + account client email address from\n\t// the Google Developers Console in the + form of \"xxx@developer.gserviceaccount.com\".\n\t// Required.\n\tGoogleAccessID + string\n\n\t// PrivateKey is the Google service account private key. It is obtainable\n\t// + from the Google Developers Console.\n\t// At https://console.developers.google.com/project//apiui/credential,\n\t// + create a service account client ID or reuse one of your existing service account\n\t// + credentials. Click on the \"Generate new P12 key\" to generate and download\n\t// + a new private key. Once you download the P12 file, use the following command\n\t// + to convert it into a PEM file.\n\t//\n\t// $ openssl pkcs12 -in key.p12 -passin + pass:notasecret -out key.pem -nodes\n\t//\n\t// Provide the contents of the + PEM file as a byte slice.\n\t// Exactly one of PrivateKey or SignBytes must + be non-nil.\n\tPrivateKey []byte\n\n\t// SignBytes is a function for implementing + custom signing. For example, if\n\t// your application is running on Google + App Engine, you can use\n\t// appengine's internal signing function:\n\t// ctx + := appengine.NewContext(request)\n\t// acc, _ := appengine.ServiceAccount(ctx)\n\t// + \ url, err := SignedURL(\"bucket\", \"object\", &SignedURLOptions{\n\t// + \ \tGoogleAccessID: acc,\n\t// \tSignBytes: func(b []byte) ([]byte, error) + {\n\t// \t\t_, signedBytes, err := appengine.SignBytes(ctx, b)\n\t// \t\treturn + signedBytes, err\n\t// \t},\n\t// \t// etc.\n\t// })\n\t//\n\t// + Exactly one of PrivateKey or SignBytes must be non-nil.\n\tSignBytes func(hashBytes + []byte) (signature []byte, err error)\n\n\t// Expires is the expiration time + on the signed URL.\n\t// It must be a time in the future.\n\t// Required.\n\tExpires + time.Time\n\n\t// Style provides options for the type of URL to use. Options + are\n\t// PathStyle (default), BucketBoundHostname, and VirtualHostedStyle. + See\n\t// https://cloud.google.com/storage/docs/request-endpoints for details.\n\t// + Optional.\n\tStyle URLStyle\n\n\t// Insecure when set indicates that the generated + URL's scheme\n\t// will use \"http\" instead of \"https\" (default).\n\t// Optional.\n\tInsecure + bool\n\n\t// Fields specifies the attributes of a PostPolicyV4 request.\n\t// + When Fields is non-nil, its attributes must match those that will\n\t// passed + into field Conditions.\n\t// Optional.\n\tFields *PolicyV4Fields\n\n\t// The + conditions that the uploaded file will be expected to conform to.\n\t// When + used, the failure of an upload to satisfy a condition will result in\n\t// a + 4XX status code, back with the message describing the problem.\n\t// Optional.\n\tConditions + []PostPolicyV4Condition\n}" - uid: cloud.google.com/go/storage.ProjectTeam name: ProjectTeam id: ProjectTeam @@ -1717,7 +2435,22 @@ items: langs: - go syntax: - content: "type Query struct {\n\t// Delimiter returns results in a directory-like fashion.\n\t// Results will contain only objects whose names, aside from the\n\t// prefix, do not contain delimiter. Objects whose names,\n\t// aside from the prefix, contain delimiter will have their name,\n\t// truncated after the delimiter, returned in prefixes.\n\t// Duplicate prefixes are omitted.\n\t// Optional.\n\tDelimiter string\n\n\t// Prefix is the prefix filter to query objects\n\t// whose names begin with this prefix.\n\t// Optional.\n\tPrefix string\n\n\t// Versions indicates whether multiple versions of the same\n\t// object will be included in the results.\n\tVersions bool\n\n\t// StartOffset is used to filter results to objects whose names are\n\t// lexicographically equal to or after startOffset. If endOffset is also set,\n\t// the objects listed will have names between startOffset (inclusive) and\n\t// endOffset (exclusive).\n\tStartOffset string\n\n\t// EndOffset is used to filter results to objects whose names are\n\t// lexicographically before endOffset. If startOffset is also set, the objects\n\t// listed will have names between startOffset (inclusive) and endOffset (exclusive).\n\tEndOffset string\n\t// contains filtered or unexported fields\n}" + content: "type Query struct {\n\t// Delimiter returns results in a directory-like + fashion.\n\t// Results will contain only objects whose names, aside from the\n\t// + prefix, do not contain delimiter. Objects whose names,\n\t// aside from the + prefix, contain delimiter will have their name,\n\t// truncated after the delimiter, + returned in prefixes.\n\t// Duplicate prefixes are omitted.\n\t// Optional.\n\tDelimiter + string\n\n\t// Prefix is the prefix filter to query objects\n\t// whose names + begin with this prefix.\n\t// Optional.\n\tPrefix string\n\n\t// Versions indicates + whether multiple versions of the same\n\t// object will be included in the results.\n\tVersions + bool\n\n\t// StartOffset is used to filter results to objects whose names are\n\t// + lexicographically equal to or after startOffset. If endOffset is also set,\n\t// + the objects listed will have names between startOffset (inclusive) and\n\t// + endOffset (exclusive).\n\tStartOffset string\n\n\t// EndOffset is used to filter + results to objects whose names are\n\t// lexicographically before endOffset. + If startOffset is also set, the objects\n\t// listed will have names between + startOffset (inclusive) and endOffset (exclusive).\n\tEndOffset string\n\t// + contains filtered or unexported fields\n}" - uid: cloud.google.com/go/storage.Query.SetAttrSelection name: | func (*Query) SetAttrSelection @@ -1751,7 +2484,8 @@ items: langs: - go syntax: - content: "type Reader struct {\n\tAttrs ReaderObjectAttrs\n\t// contains filtered or unexported fields\n}" + content: "type Reader struct {\n\tAttrs ReaderObjectAttrs\n\t// contains filtered + or unexported fields\n}" - uid: cloud.google.com/go/storage.Reader.CacheControl name: | func (*Reader) CacheControl @@ -1872,7 +2606,19 @@ items: langs: - go syntax: - content: "type ReaderObjectAttrs struct {\n\t// Size is the length of the object's content.\n\tSize int64\n\n\t// StartOffset is the byte offset within the object\n\t// from which reading begins.\n\t// This value is only non-zero for range requests.\n\tStartOffset int64\n\n\t// ContentType is the MIME type of the object's content.\n\tContentType string\n\n\t// ContentEncoding is the encoding of the object's content.\n\tContentEncoding string\n\n\t// CacheControl specifies whether and for how long browser and Internet\n\t// caches are allowed to cache your objects.\n\tCacheControl string\n\n\t// LastModified is the time that the object was last modified.\n\tLastModified time.Time\n\n\t// Generation is the generation number of the object's content.\n\tGeneration int64\n\n\t// Metageneration is the version of the metadata for this object at\n\t// this generation. This field is used for preconditions and for\n\t// detecting changes in metadata. A metageneration number is only\n\t// meaningful in the context of a particular generation of a\n\t// particular object.\n\tMetageneration int64\n}" + content: "type ReaderObjectAttrs struct {\n\t// Size is the length of the object's + content.\n\tSize int64\n\n\t// StartOffset is the byte offset within the object\n\t// + from which reading begins.\n\t// This value is only non-zero for range requests.\n\tStartOffset + int64\n\n\t// ContentType is the MIME type of the object's content.\n\tContentType + string\n\n\t// ContentEncoding is the encoding of the object's content.\n\tContentEncoding + string\n\n\t// CacheControl specifies whether and for how long browser and Internet\n\t// + caches are allowed to cache your objects.\n\tCacheControl string\n\n\t// LastModified + is the time that the object was last modified.\n\tLastModified time.Time\n\n\t// + Generation is the generation number of the object's content.\n\tGeneration int64\n\n\t// + Metageneration is the version of the metadata for this object at\n\t// this + generation. This field is used for preconditions and for\n\t// detecting changes + in metadata. A metageneration number is only\n\t// meaningful in the context + of a particular generation of a\n\t// particular object.\n\tMetageneration int64\n}" - uid: cloud.google.com/go/storage.RetentionPolicy name: RetentionPolicy id: RetentionPolicy @@ -1894,7 +2640,15 @@ items: langs: - go syntax: - content: "type RetentionPolicy struct {\n\t// RetentionPeriod specifies the duration that objects need to be\n\t// retained. Retention duration must be greater than zero and less than\n\t// 100 years. Note that enforcement of retention periods less than a day\n\t// is not guaranteed. Such periods should only be used for testing\n\t// purposes.\n\tRetentionPeriod time.Duration\n\n\t// EffectiveTime is the time from which the policy was enforced and\n\t// effective. This field is read-only.\n\tEffectiveTime time.Time\n\n\t// IsLocked describes whether the bucket is locked. Once locked, an\n\t// object retention policy cannot be modified.\n\t// This field is read-only.\n\tIsLocked bool\n}" + content: "type RetentionPolicy struct {\n\t// RetentionPeriod specifies the duration + that objects need to be\n\t// retained. Retention duration must be greater than + zero and less than\n\t// 100 years. Note that enforcement of retention periods + less than a day\n\t// is not guaranteed. Such periods should only be used for + testing\n\t// purposes.\n\tRetentionPeriod time.Duration\n\n\t// EffectiveTime + is the time from which the policy was enforced and\n\t// effective. This field + is read-only.\n\tEffectiveTime time.Time\n\n\t// IsLocked describes whether + the bucket is locked. Once locked, an\n\t// object retention policy cannot be + modified.\n\t// This field is read-only.\n\tIsLocked bool\n}" - uid: cloud.google.com/go/storage.SignedURLOptions name: SignedURLOptions id: SignedURLOptions @@ -1905,7 +2659,50 @@ items: langs: - go syntax: - content: "type SignedURLOptions struct {\n\t// GoogleAccessID represents the authorizer of the signed URL generation.\n\t// It is typically the Google service account client email address from\n\t// the Google Developers Console in the form of \"xxx@developer.gserviceaccount.com\".\n\t// Required.\n\tGoogleAccessID string\n\n\t// PrivateKey is the Google service account private key. It is obtainable\n\t// from the Google Developers Console.\n\t// At https://console.developers.google.com/project//apiui/credential,\n\t// create a service account client ID or reuse one of your existing service account\n\t// credentials. Click on the \"Generate new P12 key\" to generate and download\n\t// a new private key. Once you download the P12 file, use the following command\n\t// to convert it into a PEM file.\n\t//\n\t// $ openssl pkcs12 -in key.p12 -passin pass:notasecret -out key.pem -nodes\n\t//\n\t// Provide the contents of the PEM file as a byte slice.\n\t// Exactly one of PrivateKey or SignBytes must be non-nil.\n\tPrivateKey []byte\n\n\t// SignBytes is a function for implementing custom signing. For example, if\n\t// your application is running on Google App Engine, you can use\n\t// appengine's internal signing function:\n\t// ctx := appengine.NewContext(request)\n\t// acc, _ := appengine.ServiceAccount(ctx)\n\t// url, err := SignedURL(\"bucket\", \"object\", &SignedURLOptions{\n\t// \tGoogleAccessID: acc,\n\t// \tSignBytes: func(b []byte) ([]byte, error) {\n\t// \t\t_, signedBytes, err := appengine.SignBytes(ctx, b)\n\t// \t\treturn signedBytes, err\n\t// \t},\n\t// \t// etc.\n\t// })\n\t//\n\t// Exactly one of PrivateKey or SignBytes must be non-nil.\n\tSignBytes func([]byte) ([]byte, error)\n\n\t// Method is the HTTP method to be used with the signed URL.\n\t// Signed URLs can be used with GET, HEAD, PUT, and DELETE requests.\n\t// Required.\n\tMethod string\n\n\t// Expires is the expiration time on the signed URL. It must be\n\t// a datetime in the future. For SigningSchemeV4, the expiration may be no\n\t// more than seven days in the future.\n\t// Required.\n\tExpires time.Time\n\n\t// ContentType is the content type header the client must provide\n\t// to use the generated signed URL.\n\t// Optional.\n\tContentType string\n\n\t// Headers is a list of extension headers the client must provide\n\t// in order to use the generated signed URL. Each must be a string of the\n\t// form \"key:values\", with multiple values separated by a semicolon.\n\t// Optional.\n\tHeaders []string\n\n\t// QueryParameters is a map of additional query parameters. When\n\t// SigningScheme is V4, this is used in computing the signature, and the\n\t// client must use the same query parameters when using the generated signed\n\t// URL.\n\t// Optional.\n\tQueryParameters url.Values\n\n\t// MD5 is the base64 encoded MD5 checksum of the file.\n\t// If provided, the client should provide the exact value on the request\n\t// header in order to use the signed URL.\n\t// Optional.\n\tMD5 string\n\n\t// Style provides options for the type of URL to use. Options are\n\t// PathStyle (default), BucketBoundHostname, and VirtualHostedStyle. See\n\t// https://cloud.google.com/storage/docs/request-endpoints for details.\n\t// Only supported for V4 signing.\n\t// Optional.\n\tStyle URLStyle\n\n\t// Insecure determines whether the signed URL should use HTTPS (default) or\n\t// HTTP.\n\t// Only supported for V4 signing.\n\t// Optional.\n\tInsecure bool\n\n\t// Scheme determines the version of URL signing to use. Default is\n\t// SigningSchemeV2.\n\tScheme SigningScheme\n}" + content: "type SignedURLOptions struct {\n\t// GoogleAccessID represents the authorizer + of the signed URL generation.\n\t// It is typically the Google service account + client email address from\n\t// the Google Developers Console in the form of + \"xxx@developer.gserviceaccount.com\".\n\t// Required.\n\tGoogleAccessID string\n\n\t// + PrivateKey is the Google service account private key. It is obtainable\n\t// + from the Google Developers Console.\n\t// At https://console.developers.google.com/project//apiui/credential,\n\t// + create a service account client ID or reuse one of your existing service account\n\t// + credentials. Click on the \"Generate new P12 key\" to generate and download\n\t// + a new private key. Once you download the P12 file, use the following command\n\t// + to convert it into a PEM file.\n\t//\n\t// $ openssl pkcs12 -in key.p12 -passin + pass:notasecret -out key.pem -nodes\n\t//\n\t// Provide the contents of the + PEM file as a byte slice.\n\t// Exactly one of PrivateKey or SignBytes must + be non-nil.\n\tPrivateKey []byte\n\n\t// SignBytes is a function for implementing + custom signing. For example, if\n\t// your application is running on Google + App Engine, you can use\n\t// appengine's internal signing function:\n\t// ctx + := appengine.NewContext(request)\n\t// acc, _ := appengine.ServiceAccount(ctx)\n\t// + \ url, err := SignedURL(\"bucket\", \"object\", &SignedURLOptions{\n\t// + \ \tGoogleAccessID: acc,\n\t// \tSignBytes: func(b []byte) ([]byte, error) + {\n\t// \t\t_, signedBytes, err := appengine.SignBytes(ctx, b)\n\t// \t\treturn + signedBytes, err\n\t// \t},\n\t// \t// etc.\n\t// })\n\t//\n\t// + Exactly one of PrivateKey or SignBytes must be non-nil.\n\tSignBytes func([]byte) + ([]byte, error)\n\n\t// Method is the HTTP method to be used with the signed + URL.\n\t// Signed URLs can be used with GET, HEAD, PUT, and DELETE requests.\n\t// + Required.\n\tMethod string\n\n\t// Expires is the expiration time on the signed + URL. It must be\n\t// a datetime in the future. For SigningSchemeV4, the expiration + may be no\n\t// more than seven days in the future.\n\t// Required.\n\tExpires + time.Time\n\n\t// ContentType is the content type header the client must provide\n\t// + to use the generated signed URL.\n\t// Optional.\n\tContentType string\n\n\t// + Headers is a list of extension headers the client must provide\n\t// in order + to use the generated signed URL. Each must be a string of the\n\t// form \"key:values\", + with multiple values separated by a semicolon.\n\t// Optional.\n\tHeaders []string\n\n\t// + QueryParameters is a map of additional query parameters. When\n\t// SigningScheme + is V4, this is used in computing the signature, and the\n\t// client must use + the same query parameters when using the generated signed\n\t// URL.\n\t// Optional.\n\tQueryParameters + url.Values\n\n\t// MD5 is the base64 encoded MD5 checksum of the file.\n\t// + If provided, the client should provide the exact value on the request\n\t// + header in order to use the signed URL.\n\t// Optional.\n\tMD5 string\n\n\t// + Style provides options for the type of URL to use. Options are\n\t// PathStyle + (default), BucketBoundHostname, and VirtualHostedStyle. See\n\t// https://cloud.google.com/storage/docs/request-endpoints + for details.\n\t// Only supported for V4 signing.\n\t// Optional.\n\tStyle URLStyle\n\n\t// + Insecure determines whether the signed URL should use HTTPS (default) or\n\t// + HTTP.\n\t// Only supported for V4 signing.\n\t// Optional.\n\tInsecure bool\n\n\t// + Scheme determines the version of URL signing to use. Default is\n\t// SigningSchemeV2.\n\tScheme + SigningScheme\n}" - uid: cloud.google.com/go/storage.SigningScheme name: SigningScheme id: SigningScheme @@ -1925,7 +2722,10 @@ items: langs: - go syntax: - content: "const (\n\t// SigningSchemeDefault is presently V2 and will change to V4 in the future.\n\tSigningSchemeDefault SigningScheme = iota\n\n\t// SigningSchemeV2 uses the V2 scheme to sign URLs.\n\tSigningSchemeV2\n\n\t// SigningSchemeV4 uses the V4 scheme to sign URLs.\n\tSigningSchemeV4\n)" + content: "const (\n\t// SigningSchemeDefault is presently V2 and will change to + V4 in the future.\n\tSigningSchemeDefault SigningScheme = iota\n\n\t// SigningSchemeV2 + uses the V2 scheme to sign URLs.\n\tSigningSchemeV2\n\n\t// SigningSchemeV4 + uses the V4 scheme to sign URLs.\n\tSigningSchemeV4\n)" - uid: cloud.google.com/go/storage.URLStyle name: URLStyle id: URLStyle @@ -1995,7 +2795,10 @@ items: langs: - go syntax: - content: "type UniformBucketLevelAccess struct {\n\t// Enabled specifies whether access checks use only bucket-level IAM\n\t// policies. Enabled may be disabled until the locked time.\n\tEnabled bool\n\t// LockedTime specifies the deadline for changing Enabled from true to\n\t// false.\n\tLockedTime time.Time\n}" + content: "type UniformBucketLevelAccess struct {\n\t// Enabled specifies whether + access checks use only bucket-level IAM\n\t// policies. Enabled may be disabled + until the locked time.\n\tEnabled bool\n\t// LockedTime specifies the deadline + for changing Enabled from true to\n\t// false.\n\tLockedTime time.Time\n}" - uid: cloud.google.com/go/storage.Writer name: Writer id: Writer @@ -2006,7 +2809,36 @@ items: langs: - go syntax: - content: "type Writer struct {\n\t// ObjectAttrs are optional attributes to set on the object. Any attributes\n\t// must be initialized before the first Write call. Nil or zero-valued\n\t// attributes are ignored.\n\tObjectAttrs\n\n\t// SendCRC specifies whether to transmit a CRC32C field. It should be set\n\t// to true in addition to setting the Writer's CRC32C field, because zero\n\t// is a valid CRC and normally a zero would not be transmitted.\n\t// If a CRC32C is sent, and the data written does not match the checksum,\n\t// the write will be rejected.\n\tSendCRC32C bool\n\n\t// ChunkSize controls the maximum number of bytes of the object that the\n\t// Writer will attempt to send to the server in a single request. Objects\n\t// smaller than the size will be sent in a single request, while larger\n\t// objects will be split over multiple requests. The size will be rounded up\n\t// to the nearest multiple of 256K.\n\t//\n\t// ChunkSize will default to a reasonable value. If you perform many\n\t// concurrent writes of small objects (under ~8MB), you may wish set ChunkSize\n\t// to a value that matches your objects' sizes to avoid consuming large\n\t// amounts of memory. See\n\t// https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload#size\n\t// for more information about performance trade-offs related to ChunkSize.\n\t//\n\t// If ChunkSize is set to zero, chunking will be disabled and the object will\n\t// be uploaded in a single request without the use of a buffer. This will\n\t// further reduce memory used during uploads, but will also prevent the writer\n\t// from retrying in case of a transient error from the server, since a buffer\n\t// is required in order to retry the failed request.\n\t//\n\t// ChunkSize must be set before the first Write call.\n\tChunkSize int\n\n\t// ProgressFunc can be used to monitor the progress of a large write.\n\t// operation. If ProgressFunc is not nil and writing requires multiple\n\t// calls to the underlying service (see\n\t// https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload),\n\t// then ProgressFunc will be invoked after each call with the number of bytes of\n\t// content copied so far.\n\t//\n\t// ProgressFunc should return quickly without blocking.\n\tProgressFunc func(int64)\n\t// contains filtered or unexported fields\n}" + content: "type Writer struct {\n\t// ObjectAttrs are optional attributes to set + on the object. Any attributes\n\t// must be initialized before the first Write + call. Nil or zero-valued\n\t// attributes are ignored.\n\tObjectAttrs\n\n\t// + SendCRC specifies whether to transmit a CRC32C field. It should be set\n\t// + to true in addition to setting the Writer's CRC32C field, because zero\n\t// + is a valid CRC and normally a zero would not be transmitted.\n\t// If a CRC32C + is sent, and the data written does not match the checksum,\n\t// the write will + be rejected.\n\tSendCRC32C bool\n\n\t// ChunkSize controls the maximum number + of bytes of the object that the\n\t// Writer will attempt to send to the server + in a single request. Objects\n\t// smaller than the size will be sent in a single + request, while larger\n\t// objects will be split over multiple requests. The + size will be rounded up\n\t// to the nearest multiple of 256K.\n\t//\n\t// ChunkSize + will default to a reasonable value. If you perform many\n\t// concurrent writes + of small objects (under ~8MB), you may wish set ChunkSize\n\t// to a value that + matches your objects' sizes to avoid consuming large\n\t// amounts of memory. + See\n\t// https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload#size\n\t// + for more information about performance trade-offs related to ChunkSize.\n\t//\n\t// + If ChunkSize is set to zero, chunking will be disabled and the object will\n\t// + be uploaded in a single request without the use of a buffer. This will\n\t// + further reduce memory used during uploads, but will also prevent the writer\n\t// + from retrying in case of a transient error from the server, since a buffer\n\t// + is required in order to retry the failed request.\n\t//\n\t// ChunkSize must + be set before the first Write call.\n\tChunkSize int\n\n\t// ProgressFunc can + be used to monitor the progress of a large write.\n\t// operation. If ProgressFunc + is not nil and writing requires multiple\n\t// calls to the underlying service + (see\n\t// https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload),\n\t// + then ProgressFunc will be invoked after each call with the number of bytes of\n\t// + content copied so far.\n\t//\n\t// ProgressFunc should return quickly without + blocking.\n\tProgressFunc func(int64)\n\t// contains filtered or unexported + fields\n}" - uid: cloud.google.com/go/storage.Writer.Attrs name: | func (*Writer) Attrs @@ -2070,10 +2902,36 @@ items: syntax: content: func (w *Writer) Write(p []byte) (n int, err error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n\twc.ContentType = \"text/plain\"\n\twc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: storage.RoleReader}}\n\tif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t\t// TODO: handle error.\n\t\t// Note that Write may return nil in some error situations,\n\t\t// so always check the error from Close.\n\t}\n\tif err := wc.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"updated object:\", wc.Attrs())\n}\n" - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"hash/crc32\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdata := []byte(\"verify me\")\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n\twc.CRC32C = crc32.Checksum(data, crc32.MakeTable(crc32.Castagnoli))\n\twc.SendCRC32C = true\n\tif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t\t// TODO: handle error.\n\t\t// Note that Write may return nil in some error situations,\n\t\t// so always check the error from Close.\n\t}\n\tif err := wc.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"updated object:\", wc.Attrs())\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n\twc.ContentType + = \"text/plain\"\n\twc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: + storage.RoleReader}}\n\tif _, err := wc.Write([]byte(\"hello world\")); err + != nil {\n\t\t// TODO: handle error.\n\t\t// Note that Write may return nil + in some error situations,\n\t\t// so always check the error from Close.\n\t}\n\tif + err := wc.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"updated + object:\", wc.Attrs())\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"hash/crc32\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdata := []byte(\"verify me\")\n\twc + := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n\twc.CRC32C + = crc32.Checksum(data, crc32.MakeTable(crc32.Castagnoli))\n\twc.SendCRC32C = + true\n\tif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t\t// + TODO: handle error.\n\t\t// Note that Write may return nil in some error situations,\n\t\t// + so always check the error from Close.\n\t}\n\tif err := wc.Close(); err != nil + {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"updated object:\", wc.Attrs())\n}\n" name: checksum - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\ttctx, cancel := context.WithTimeout(ctx, 30*time.Second)\n\tdefer cancel() // Cancel when done, whether we time out or not.\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(tctx)\n\twc.ContentType = \"text/plain\"\n\twc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: storage.RoleReader}}\n\tif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t\t// TODO: handle error.\n\t\t// Note that Write may return nil in some error situations,\n\t\t// so always check the error from Close.\n\t}\n\tif err := wc.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"updated object:\", wc.Attrs())\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc + main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif + err != nil {\n\t\t// TODO: handle error.\n\t}\n\ttctx, cancel := context.WithTimeout(ctx, + 30*time.Second)\n\tdefer cancel() // Cancel when done, whether we time out or + not.\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(tctx)\n\twc.ContentType + = \"text/plain\"\n\twc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: + storage.RoleReader}}\n\tif _, err := wc.Write([]byte(\"hello world\")); err + != nil {\n\t\t// TODO: handle error.\n\t\t// Note that Write may return nil + in some error situations,\n\t\t// so always check the error from Close.\n\t}\n\tif + err := wc.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"updated + object:\", wc.Attrs())\n}\n" name: timeout - uid: cloud.google.com/go/storage.SignedURL name: | @@ -2089,6 +2947,12 @@ items: langs: - go syntax: - content: func SignedURL(bucket, name string, opts *SignedURLOptions) (string, error) + content: func SignedURL(bucket, name string, opts *SignedURLOptions) (string, + error) codeexamples: - - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"fmt\"\n\t\"io/ioutil\"\n\t\"time\"\n)\n\nfunc main() {\n\tpkey, err := ioutil.ReadFile(\"my-private-key.pem\")\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\turl, err := storage.SignedURL(\"my-bucket\", \"my-object\", &storage.SignedURLOptions{\n\t\tGoogleAccessID: \"xxx@developer.gserviceaccount.com\",\n\t\tPrivateKey: pkey,\n\t\tMethod: \"GET\",\n\t\tExpires: time.Now().Add(48 * time.Hour),\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(url)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"fmt\"\n\t\"io/ioutil\"\n\t\"time\"\n)\n\nfunc + main() {\n\tpkey, err := ioutil.ReadFile(\"my-private-key.pem\")\n\tif err != + nil {\n\t\t// TODO: handle error.\n\t}\n\turl, err := storage.SignedURL(\"my-bucket\", + \"my-object\", &storage.SignedURLOptions{\n\t\tGoogleAccessID: \"xxx@developer.gserviceaccount.com\",\n\t\tPrivateKey: + \ pkey,\n\t\tMethod: \"GET\",\n\t\tExpires: time.Now().Add(48 + * time.Hour),\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(url)\n}\n" diff --git a/logging/go.mod b/logging/go.mod index 1a84e58f117..92852fa3350 100644 --- a/logging/go.mod +++ b/logging/go.mod @@ -6,7 +6,7 @@ require ( cloud.google.com/go v0.72.0 cloud.google.com/go/storage v1.10.0 github.com/golang/protobuf v1.4.3 - github.com/google/go-cmp v0.5.3 + github.com/google/go-cmp v0.5.4 github.com/googleapis/gax-go/v2 v2.0.5 go.opencensus.io v0.22.5 golang.org/x/oauth2 v0.0.0-20201109201403-9fd604954f58 diff --git a/logging/go.sum b/logging/go.sum index 3d5cc0fdd6a..59d29520dac 100644 --- a/logging/go.sum +++ b/logging/go.sum @@ -128,8 +128,8 @@ github.com/google/go-cmp v0.5.1 h1:JFrFEBb2xKufg6XkJsJr+WbKb4FQlURi5RUcBveYu9k= github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no= github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs= github.com/google/martian/v3 v3.0.0 h1:pMen7vLs8nvgEYhywH3KDWJIJTeEr2ULsVWHWYHQyBs= diff --git a/pubsub/go.mod b/pubsub/go.mod index b54b2377ded..b536f3bc661 100644 --- a/pubsub/go.mod +++ b/pubsub/go.mod @@ -5,7 +5,7 @@ go 1.11 require ( cloud.google.com/go v0.72.0 github.com/golang/protobuf v1.4.3 - github.com/google/go-cmp v0.5.3 + github.com/google/go-cmp v0.5.4 github.com/googleapis/gax-go/v2 v2.0.5 go.opencensus.io v0.22.5 golang.org/x/oauth2 v0.0.0-20201109201403-9fd604954f58 diff --git a/pubsub/go.sum b/pubsub/go.sum index 6e68471cd7c..40bcea4031c 100644 --- a/pubsub/go.sum +++ b/pubsub/go.sum @@ -105,8 +105,8 @@ github.com/google/go-cmp v0.5.1 h1:JFrFEBb2xKufg6XkJsJr+WbKb4FQlURi5RUcBveYu9k= github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no= github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs= github.com/google/martian/v3 v3.0.0/go.mod h1:y5Zk1BBys9G+gd6Jrk0W3cC1+ELVxBWuIGO+w/tUAp0= diff --git a/pubsublite/go.mod b/pubsublite/go.mod index 4ac615dc506..e680bb57ec2 100644 --- a/pubsublite/go.mod +++ b/pubsublite/go.mod @@ -6,7 +6,7 @@ require ( cloud.google.com/go v0.72.0 cloud.google.com/go/pubsub v1.8.3 github.com/golang/protobuf v1.4.3 - github.com/google/go-cmp v0.5.3 + github.com/google/go-cmp v0.5.4 github.com/googleapis/gax-go/v2 v2.0.5 golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c // indirect google.golang.org/api v0.35.0 diff --git a/pubsublite/go.sum b/pubsublite/go.sum index 929a5ed22cd..e79777e0b01 100644 --- a/pubsublite/go.sum +++ b/pubsublite/go.sum @@ -91,8 +91,8 @@ github.com/google/go-cmp v0.5.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/ github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs= github.com/google/martian/v3 v3.0.0/go.mod h1:y5Zk1BBys9G+gd6Jrk0W3cC1+ELVxBWuIGO+w/tUAp0= github.com/google/martian/v3 v3.1.0/go.mod h1:y5Zk1BBys9G+gd6Jrk0W3cC1+ELVxBWuIGO+w/tUAp0= diff --git a/pubsublite/internal/wire/acks.go b/pubsublite/internal/wire/acks.go index 0d17baf3953..2e55fd7a688 100644 --- a/pubsublite/internal/wire/acks.go +++ b/pubsublite/internal/wire/acks.go @@ -169,6 +169,13 @@ func (at *ackTracker) unsafeProcessAcks() { } } +// Empty returns true if there are no outstanding acks. +func (at *ackTracker) Empty() bool { + at.mu.Lock() + defer at.mu.Unlock() + return at.outstandingAcks.Front() == nil +} + // commitCursorTracker tracks pending and last successful committed offsets. // It is only accessed by the committer. type commitCursorTracker struct { diff --git a/pubsublite/internal/wire/committer.go b/pubsublite/internal/wire/committer.go index 63c7b487774..89eb2d9f997 100644 --- a/pubsublite/internal/wire/committer.go +++ b/pubsublite/internal/wire/committer.go @@ -90,8 +90,8 @@ func (c *committer) Start() { } } -// Stop initiates shutdown of the committer. The final commit offset will be -// send to the server, but acks that arrive afterward will be discarded. +// Stop initiates shutdown of the committer. It will wait for outstanding acks +// and send the final commit offset to the server. func (c *committer) Stop() { c.mu.Lock() defer c.mu.Unlock() @@ -194,23 +194,22 @@ func (c *committer) unsafeInitiateShutdown(targetStatus serviceStatus, err error return } - // Discard outstanding acks. - c.acks.Release() - // If it's a graceful shutdown, expedite sending final commits to the stream. if targetStatus == serviceTerminating { c.unsafeCommitOffsetToStream() c.unsafeCheckDone() return } - // Otherwise immediately terminate the stream. + + // Otherwise discard outstanding acks and immediately terminate the stream. + c.acks.Release() c.unsafeTerminate() } func (c *committer) unsafeCheckDone() { // The commit stream can be closed once the final commit offset has been - // confirmed. - if c.status == serviceTerminating && c.cursorTracker.UpToDate() { + // confirmed and there are no outstanding acks. + if c.status == serviceTerminating && c.cursorTracker.UpToDate() && c.acks.Empty() { c.unsafeTerminate() } } diff --git a/pubsublite/internal/wire/committer_test.go b/pubsublite/internal/wire/committer_test.go index 610a48e7827..2f0144ea0da 100644 --- a/pubsublite/internal/wire/committer_test.go +++ b/pubsublite/internal/wire/committer_test.go @@ -102,6 +102,7 @@ func TestCommitterStopFlushesCommits(t *testing.T) { stream := test.NewRPCVerifier(t) stream.Push(initCommitReq(subscription), initCommitResp(), nil) stream.Push(commitReq(34), commitResp(1), nil) + stream.Push(commitReq(56), commitResp(1), nil) verifiers.AddCommitStream(subscription.Path, subscription.Partition, stream) mockServer.OnTestStart(verifiers) @@ -114,7 +115,7 @@ func TestCommitterStopFlushesCommits(t *testing.T) { ack1.Ack() cmt.Stop() // Stop should flush the first offset - ack2.Ack() // Acks after Stop() are discarded + ack2.Ack() // Acks after Stop() are processed cmt.SendBatchCommit() // Committer terminates when all acks are processed. if gotErr := cmt.FinalError(); gotErr != nil { diff --git a/pubsublite/internal/wire/subscriber.go b/pubsublite/internal/wire/subscriber.go index deb488b4f8d..9f1d2c6a3de 100644 --- a/pubsublite/internal/wire/subscriber.go +++ b/pubsublite/internal/wire/subscriber.go @@ -17,7 +17,6 @@ import ( "context" "errors" "reflect" - "sync" "time" "google.golang.org/grpc" @@ -40,42 +39,37 @@ type ReceivedMessage struct { Ack AckConsumer } -// MessageReceiverFunc receives a batch of Pub/Sub messages from a topic -// partition. -type MessageReceiverFunc func([]*ReceivedMessage) +// MessageReceiverFunc receives a Pub/Sub message from a topic partition. +type MessageReceiverFunc func(*ReceivedMessage) -const maxMessagesBufferSize = 1000 +const maxMessageBufferSize = 10000 // messageDeliveryQueue delivers received messages to the client-provided // MessageReceiverFunc sequentially. type messageDeliveryQueue struct { receiver MessageReceiverFunc - messagesC chan []*ReceivedMessage + messagesC chan *ReceivedMessage stopC chan struct{} - - // Fields below must be guarded with mu. - mu sync.Mutex - status serviceStatus + acks *ackTracker + status serviceStatus } -func newMessageDeliveryQueue(receiver MessageReceiverFunc, bufferSize int) *messageDeliveryQueue { - // The buffer size is based on ReceiveSettings.MaxOutstandingMessages to - // handle the worst case of single messages. But ensure there's a reasonable - // limit as channel buffer capacity is allocated on creation. - if bufferSize > maxMessagesBufferSize { - bufferSize = maxMessagesBufferSize +func newMessageDeliveryQueue(acks *ackTracker, receiver MessageReceiverFunc, bufferSize int) *messageDeliveryQueue { + // The buffer size is based on ReceiveSettings.MaxOutstandingMessages. But + // ensure there's a reasonable limit as channel buffer capacity is allocated + // on creation. + if bufferSize > maxMessageBufferSize { + bufferSize = maxMessageBufferSize } return &messageDeliveryQueue{ + acks: acks, receiver: receiver, - messagesC: make(chan []*ReceivedMessage, bufferSize), + messagesC: make(chan *ReceivedMessage, bufferSize), stopC: make(chan struct{}), } } func (mq *messageDeliveryQueue) Start() { - mq.mu.Lock() - defer mq.mu.Unlock() - if mq.status == serviceUninitialized { go mq.deliverMessages() mq.status = serviceActive @@ -83,9 +77,6 @@ func (mq *messageDeliveryQueue) Start() { } func (mq *messageDeliveryQueue) Stop() { - mq.mu.Lock() - defer mq.mu.Unlock() - if mq.status < serviceTerminated { close(mq.stopC) mq.status = serviceTerminated @@ -93,11 +84,10 @@ func (mq *messageDeliveryQueue) Stop() { } func (mq *messageDeliveryQueue) Add(messages []*ReceivedMessage) { - mq.mu.Lock() - defer mq.mu.Unlock() - if mq.status == serviceActive { - mq.messagesC <- messages + for _, msg := range messages { + mq.messagesC <- msg + } } } @@ -113,8 +103,11 @@ func (mq *messageDeliveryQueue) deliverMessages() { select { case <-mq.stopC: return // Ends the goroutine. - case msgs := <-mq.messagesC: - mq.receiver(msgs) + case msg := <-mq.messagesC: + // Register outstanding acks, which are primarily handled by the + // `committer`. + mq.acks.Push(msg.Ack.(*ackConsumer)) + mq.receiver(msg) } } } @@ -138,7 +131,6 @@ type subscribeStream struct { // Fields below must be guarded with mu. stream *retryableStream - acks *ackTracker offsetTracker subscriberOffsetTracker flowControl flowControlBatcher pollFlowControl *periodicTask @@ -162,8 +154,7 @@ func newSubscribeStream(ctx context.Context, subClient *vkit.SubscriberClient, s }, }, }, - messageQueue: newMessageDeliveryQueue(receiver, settings.MaxOutstandingMessages), - acks: acks, + messageQueue: newMessageDeliveryQueue(acks, receiver, settings.MaxOutstandingMessages), } s.stream = newRetryableStream(ctx, s, settings.Timeout, reflect.TypeOf(pb.SubscribeResponse{})) @@ -290,12 +281,7 @@ func (s *subscribeStream) unsafeOnMessageResponse(response *pb.MessageResponse) var receivedMsgs []*ReceivedMessage for _, msg := range response.Messages { - // Register outstanding acks, which are primarily handled by the - // `committer`. ack := newAckConsumer(msg.GetCursor().GetOffset(), msg.GetSizeBytes(), s.onAck) - if err := s.acks.Push(ack); err != nil { - return err - } receivedMsgs = append(receivedMsgs, &ReceivedMessage{Msg: msg, Ack: ack}) } s.messageQueue.Add(receivedMsgs) diff --git a/pubsublite/internal/wire/subscriber_test.go b/pubsublite/internal/wire/subscriber_test.go index ef7dd98a3a2..9749a51e8a0 100644 --- a/pubsublite/internal/wire/subscriber_test.go +++ b/pubsublite/internal/wire/subscriber_test.go @@ -21,9 +21,9 @@ import ( "cloud.google.com/go/internal/testutil" "cloud.google.com/go/pubsublite/internal/test" - "github.com/golang/protobuf/proto" "google.golang.org/grpc/codes" "google.golang.org/grpc/status" + "google.golang.org/protobuf/proto" pb "google.golang.org/genproto/googleapis/cloud/pubsublite/v1" ) @@ -53,10 +53,8 @@ func newTestMessageReceiver(t *testing.T) *testMessageReceiver { } } -func (tr *testMessageReceiver) onMessages(msgs []*ReceivedMessage) { - for _, msg := range msgs { - tr.received <- msg - } +func (tr *testMessageReceiver) onMessage(msg *ReceivedMessage) { + tr.received <- msg } func (tr *testMessageReceiver) ValidateMsg(want *pb.SequencedMessage) AckConsumer { @@ -126,45 +124,56 @@ func newTestBlockingMessageReceiver(t *testing.T) *testBlockingMessageReceiver { } } -// onMessages is the message receiver func and blocks until there is a call to +// onMessage is the message receiver func and blocks until there is a call to // Return(). -func (tr *testBlockingMessageReceiver) onMessages(msgs []*ReceivedMessage) { - tr.testMessageReceiver.onMessages(msgs) +func (tr *testBlockingMessageReceiver) onMessage(msg *ReceivedMessage) { + tr.testMessageReceiver.onMessage(msg) <-tr.blockReceive } -// Return signals onMessages to return. +// Return signals onMessage to return. func (tr *testBlockingMessageReceiver) Return() { var void struct{} tr.blockReceive <- void } -func TestNewMessageDeliveryQueue(t *testing.T) { +func TestMessageDeliveryQueue(t *testing.T) { + acks := newAckTracker() receiver := newTestMessageReceiver(t) - messageQueue := newMessageDeliveryQueue(receiver.onMessages, 10) + messageQueue := newMessageDeliveryQueue(acks, receiver.onMessage, 10) t.Run("Add before start", func(t *testing.T) { - messageQueue.Add([]*ReceivedMessage{{Msg: seqMsgWithOffset(3)}}) + msg1 := seqMsgWithOffset(1) + ack1 := newAckConsumer(1, 0, nil) + messageQueue.Add([]*ReceivedMessage{{Msg: msg1, Ack: ack1}}) receiver.VerifyNoMsgs() }) t.Run("Add after start", func(t *testing.T) { - msg1 := seqMsgWithOffset(1) msg2 := seqMsgWithOffset(2) + ack2 := newAckConsumer(2, 0, nil) + msg3 := seqMsgWithOffset(3) + ack3 := newAckConsumer(3, 0, nil) messageQueue.Start() messageQueue.Start() // Check duplicate starts - messageQueue.Add([]*ReceivedMessage{{Msg: msg1}, {Msg: msg2}}) + messageQueue.Add([]*ReceivedMessage{ + {Msg: msg2, Ack: ack2}, + {Msg: msg3, Ack: ack3}, + }) - receiver.ValidateMsg(msg1) receiver.ValidateMsg(msg2) + receiver.ValidateMsg(msg3) }) t.Run("Add after stop", func(t *testing.T) { + msg4 := seqMsgWithOffset(4) + ack4 := newAckConsumer(4, 0, nil) + messageQueue.Stop() messageQueue.Stop() // Check duplicate stop - messageQueue.Add([]*ReceivedMessage{{Msg: seqMsgWithOffset(4)}}) + messageQueue.Add([]*ReceivedMessage{{Msg: msg4, Ack: ack4}}) receiver.VerifyNoMsgs() }) @@ -189,7 +198,7 @@ func newTestSubscribeStream(t *testing.T, subscription subscriptionPartition, se Receiver: newTestMessageReceiver(t), t: t, } - ts.sub = newSubscribeStream(ctx, subClient, settings, ts.Receiver.onMessages, subscription, acks, true) + ts.sub = newSubscribeStream(ctx, subClient, settings, ts.Receiver.onMessage, subscription, acks, true) ts.initAndStart(t, ts.sub, "Subscriber") return ts } @@ -486,7 +495,7 @@ func TestSinglePartitionSubscriberStartStop(t *testing.T) { mockServer.OnTestStart(verifiers) defer mockServer.OnTestEnd() - sub := newTestSinglePartitionSubscriber(t, receiver.onMessages, subscription) + sub := newTestSinglePartitionSubscriber(t, receiver.onMessage, subscription) if gotErr := sub.WaitStarted(); gotErr != nil { t.Errorf("Start() got err: (%v)", gotErr) } @@ -518,7 +527,7 @@ func TestSinglePartitionSubscriberSimpleMsgAck(t *testing.T) { mockServer.OnTestStart(verifiers) defer mockServer.OnTestEnd() - sub := newTestSinglePartitionSubscriber(t, receiver.onMessages, subscription) + sub := newTestSinglePartitionSubscriber(t, receiver.onMessage, subscription) if gotErr := sub.WaitStarted(); gotErr != nil { t.Errorf("Start() got err: (%v)", gotErr) } @@ -557,29 +566,32 @@ func TestSinglePartitionSubscriberMessageQueue(t *testing.T) { cmtStream := test.NewRPCVerifier(t) cmtStream.Push(initCommitReq(subscription), initCommitResp(), nil) + cmtStream.Push(commitReq(4), commitResp(1), nil) verifiers.AddCommitStream(subscription.Path, subscription.Partition, cmtStream) mockServer.OnTestStart(verifiers) defer mockServer.OnTestEnd() - sub := newTestSinglePartitionSubscriber(t, receiver.onMessages, subscription) + sub := newTestSinglePartitionSubscriber(t, receiver.onMessage, subscription) if gotErr := sub.WaitStarted(); gotErr != nil { t.Errorf("Start() got err: (%v)", gotErr) } // Verifies that messageDeliveryQueue delivers messages sequentially and waits - // for the client message receiver func to return. - receiver.ValidateMsg(msg1) - receiver.VerifyNoMsgs() - receiver.Return() - - receiver.ValidateMsg(msg2) - receiver.VerifyNoMsgs() - receiver.Return() + // for the client message receiver func to return before delivering the next + // message. + var acks []AckConsumer + for _, msg := range []*pb.SequencedMessage{msg1, msg2, msg3} { + ack := receiver.ValidateMsg(msg) + acks = append(acks, ack) + receiver.VerifyNoMsgs() + receiver.Return() + } - receiver.ValidateMsg(msg3) - receiver.VerifyNoMsgs() - receiver.Return() + // Ack all messages so that the committer terminates. + for _, ack := range acks { + ack.Ack() + } sub.Stop() if gotErr := sub.WaitStopped(); gotErr != nil { @@ -597,24 +609,23 @@ func TestSinglePartitionSubscriberStopDuringReceive(t *testing.T) { subStream := test.NewRPCVerifier(t) subStream.Push(initSubReq(subscription), initSubResp(), nil) - subStream.Push(initFlowControlReq(), msgSubResp(msg1), nil) - subStream.Push(nil, msgSubResp(msg2), nil) + subStream.Push(initFlowControlReq(), msgSubResp(msg1, msg2), nil) verifiers.AddSubscribeStream(subscription.Path, subscription.Partition, subStream) cmtStream := test.NewRPCVerifier(t) cmtStream.Push(initCommitReq(subscription), initCommitResp(), nil) + cmtStream.Push(commitReq(2), commitResp(1), nil) verifiers.AddCommitStream(subscription.Path, subscription.Partition, cmtStream) mockServer.OnTestStart(verifiers) defer mockServer.OnTestEnd() - sub := newTestSinglePartitionSubscriber(t, receiver.onMessages, subscription) + sub := newTestSinglePartitionSubscriber(t, receiver.onMessage, subscription) if gotErr := sub.WaitStarted(); gotErr != nil { t.Errorf("Start() got err: (%v)", gotErr) } - receiver.ValidateMsg(msg1) - receiver.VerifyNoMsgs() + receiver.ValidateMsg(msg1).Ack() // Stop the subscriber before returning from the message receiver func. sub.Stop() @@ -653,7 +664,7 @@ func newTestMultiPartitionSubscriber(t *testing.T, receiverFunc MessageReceiverF } func TestMultiPartitionSubscriberMultipleMessages(t *testing.T) { - subscription := "projects/123456/locations/us-central1-b/subscriptions/my-sub" + const subscription = "projects/123456/locations/us-central1-b/subscriptions/my-sub" receiver := newTestMessageReceiver(t) msg1 := seqMsgWithOffsetAndSize(22, 100) msg2 := seqMsgWithOffsetAndSize(23, 200) @@ -689,7 +700,7 @@ func TestMultiPartitionSubscriberMultipleMessages(t *testing.T) { mockServer.OnTestStart(verifiers) defer mockServer.OnTestEnd() - sub := newTestMultiPartitionSubscriber(t, receiver.onMessages, subscription, []int{1, 2}) + sub := newTestMultiPartitionSubscriber(t, receiver.onMessage, subscription, []int{1, 2}) if gotErr := sub.WaitStarted(); gotErr != nil { t.Errorf("Start() got err: (%v)", gotErr) } @@ -701,7 +712,7 @@ func TestMultiPartitionSubscriberMultipleMessages(t *testing.T) { } func TestMultiPartitionSubscriberPermanentError(t *testing.T) { - subscription := "projects/123456/locations/us-central1-b/subscriptions/my-sub" + const subscription = "projects/123456/locations/us-central1-b/subscriptions/my-sub" receiver := newTestMessageReceiver(t) msg1 := seqMsgWithOffsetAndSize(22, 100) msg2 := seqMsgWithOffsetAndSize(23, 200) @@ -737,12 +748,12 @@ func TestMultiPartitionSubscriberPermanentError(t *testing.T) { mockServer.OnTestStart(verifiers) defer mockServer.OnTestEnd() - sub := newTestMultiPartitionSubscriber(t, receiver.onMessages, subscription, []int{1, 2}) + sub := newTestMultiPartitionSubscriber(t, receiver.onMessage, subscription, []int{1, 2}) if gotErr := sub.WaitStarted(); gotErr != nil { t.Errorf("Start() got err: (%v)", gotErr) } receiver.ValidateMsgs([]*pb.SequencedMessage{msg1, msg3}) - errorBarrier.Release() // Send server error + errorBarrier.Release() // Release server error now to ensure test is deterministic if gotErr := sub.WaitStopped(); !test.ErrorEqual(gotErr, serverErr) { t.Errorf("Final error got: (%v), want: (%v)", gotErr, serverErr) } diff --git a/spanner/go.mod b/spanner/go.mod index fa7abaad14e..28f84665c58 100644 --- a/spanner/go.mod +++ b/spanner/go.mod @@ -5,7 +5,7 @@ go 1.11 require ( cloud.google.com/go v0.72.0 github.com/golang/protobuf v1.4.3 - github.com/google/go-cmp v0.5.3 + github.com/google/go-cmp v0.5.4 github.com/googleapis/gax-go/v2 v2.0.5 go.opencensus.io v0.22.5 golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c // indirect diff --git a/spanner/go.sum b/spanner/go.sum index 94988650a54..6fb1020ab26 100644 --- a/spanner/go.sum +++ b/spanner/go.sum @@ -126,8 +126,8 @@ github.com/google/go-cmp v0.5.1 h1:JFrFEBb2xKufg6XkJsJr+WbKb4FQlURi5RUcBveYu9k= github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no= github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs= github.com/google/martian/v3 v3.0.0/go.mod h1:y5Zk1BBys9G+gd6Jrk0W3cC1+ELVxBWuIGO+w/tUAp0= diff --git a/spanner/spannertest/funcs.go b/spanner/spannertest/funcs.go index cd8aafc253e..3cfa53211e4 100644 --- a/spanner/spannertest/funcs.go +++ b/spanner/spannertest/funcs.go @@ -109,6 +109,43 @@ var aggregateFuncs = map[string]aggregateFunc{ return sum, typ, nil }, }, + "AVG": { + Eval: func(values []interface{}, typ spansql.Type) (interface{}, spansql.Type, error) { + if typ.Array || !(typ.Base == spansql.Int64 || typ.Base == spansql.Float64) { + return nil, spansql.Type{}, fmt.Errorf("AVG only supports arguments of INT64 or FLOAT64 type, not %s", typ.SQL()) + } + if typ.Base == spansql.Int64 { + var sum int64 + var n float64 + for _, v := range values { + if v == nil { + continue + } + sum += v.(int64) + n++ + } + if n == 0 { + // "Returns NULL if the input contains only NULLs". + return nil, typ, nil + } + return (float64(sum) / n), float64Type, nil + } + var sum float64 + var n float64 + for _, v := range values { + if v == nil { + continue + } + sum += v.(float64) + n++ + } + if n == 0 { + // "Returns NULL if the input contains only NULLs". + return nil, typ, nil + } + return (sum / n), typ, nil + }, + }, } func evalMinMax(name string, isMin bool, values []interface{}, typ spansql.Type) (interface{}, spansql.Type, error) { diff --git a/spanner/spannertest/integration_test.go b/spanner/spannertest/integration_test.go index 365dd78d0ca..7f452464d5c 100644 --- a/spanner/spannertest/integration_test.go +++ b/spanner/spannertest/integration_test.go @@ -889,6 +889,13 @@ func TestIntegration_ReadsAndQueries(t *testing.T) { {int64(1), int64(25)}, // Jack(ID=1, Tenure=10), Sam(ID=3, Tenure=9), George(ID=5, Tenure=6) }, }, + { + `SELECT AVG(Height) FROM Staff WHERE ID <= 2`, + nil, + [][]interface{}{ + {float64(1.84)}, + }, + }, { `SELECT MAX(Name) FROM Staff WHERE Name < @lim`, map[string]interface{}{"lim": "Teal'c"}, diff --git a/spanner/spansql/keywords.go b/spanner/spansql/keywords.go index 64672d39568..7964385d2da 100644 --- a/spanner/spansql/keywords.go +++ b/spanner/spansql/keywords.go @@ -130,6 +130,7 @@ var keywords = map[string]bool{ var funcs = map[string]bool{ // Aggregate functions. "ARRAY_AGG": true, + "AVG": true, "BIT_XOR": true, "COUNT": true, "MAX": true, diff --git a/storage/go.mod b/storage/go.mod index 7154e8ce79d..6b071edfc29 100644 --- a/storage/go.mod +++ b/storage/go.mod @@ -5,7 +5,7 @@ go 1.11 require ( cloud.google.com/go v0.72.0 github.com/golang/protobuf v1.4.3 - github.com/google/go-cmp v0.5.3 + github.com/google/go-cmp v0.5.4 github.com/googleapis/gax-go/v2 v2.0.5 golang.org/x/oauth2 v0.0.0-20201109201403-9fd604954f58 golang.org/x/tools v0.0.0-20201201064407-fd09bd90d85c // indirect diff --git a/storage/go.sum b/storage/go.sum index da1bc3717cd..1ee302d19a0 100644 --- a/storage/go.sum +++ b/storage/go.sum @@ -120,8 +120,8 @@ github.com/google/go-cmp v0.5.1 h1:JFrFEBb2xKufg6XkJsJr+WbKb4FQlURi5RUcBveYu9k= github.com/google/go-cmp v0.5.1/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.5.2 h1:X2ev0eStA3AbceY54o37/0PQ/UWqKEiiO2dKL5OPaFM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= -github.com/google/go-cmp v0.5.3 h1:x95R7cp+rSeeqAMI2knLtQ0DKlaBhv2NrtrOvafPHRo= -github.com/google/go-cmp v0.5.3/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= +github.com/google/go-cmp v0.5.4 h1:L8R9j+yAqZuZjsqh/z+F1NCffTKKLShY6zXTItVIZ8M= +github.com/google/go-cmp v0.5.4/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/martian v2.1.0+incompatible h1:/CP5g8u/VJHijgedC/Legn3BAbAaWPgecwXBIDzw5no= github.com/google/martian v2.1.0+incompatible/go.mod h1:9I4somxYTbIHy5NJKHRl3wXiIaQGbYVAs8BPL6v8lEs= github.com/google/martian/v3 v3.0.0 h1:pMen7vLs8nvgEYhywH3KDWJIJTeEr2ULsVWHWYHQyBs=