diff --git a/v2/callctx/callctx.go b/v2/callctx/callctx.go index af15fb58..9aab3d91 100644 --- a/v2/callctx/callctx.go +++ b/v2/callctx/callctx.go @@ -38,6 +38,14 @@ import ( ) const ( + // XGoogFieldMaskHeader is the canonical header key for the [System Parameter] + // that specifies the response read mask. The value(s) for this header + // must adhere to format described in [fieldmaskpb]. + // + // [System Parameter]: https://cloud.google.com/apis/docs/system-parameters + // [fieldmaskpb]: https://google.golang.org/protobuf/types/known/fieldmaskpb + XGoogFieldMaskHeader = "x-goog-fieldmask" + headerKey = contextKey("header") ) diff --git a/v2/callctx/callctx_example_test.go b/v2/callctx/callctx_example_test.go index c46c6f42..e34bc097 100644 --- a/v2/callctx/callctx_example_test.go +++ b/v2/callctx/callctx_example_test.go @@ -34,6 +34,8 @@ import ( "fmt" "github.com/googleapis/gax-go/v2/callctx" + "google.golang.org/genproto/googleapis/api/metric" + "google.golang.org/protobuf/types/known/fieldmaskpb" ) func ExampleSetHeaders() { @@ -47,3 +49,23 @@ func ExampleSetHeaders() { fmt.Println(headers["key"][0]) // Output: value } + +func ExampleXGoogFieldMaskHeader() { + ctx := context.Background() + ctx = callctx.SetHeaders(ctx, callctx.XGoogFieldMaskHeader, "field_one,field.two") + + // Send the returned context to the request you are making. +} + +func ExampleXGoogFieldMaskHeader_fieldmaskpb() { + // Build a mask using the expected response protobuf message. + mask, err := fieldmaskpb.New(&metric.MetricDescriptor{}, "display_name", "metadata.launch_stage") + if err != nil { + // handle error + } + + ctx := context.Background() + ctx = callctx.SetHeaders(ctx, callctx.XGoogFieldMaskHeader, mask.String()) + + // Send the returned context to the request you are making. +} diff --git a/v2/header.go b/v2/header.go index 453fab7e..3e53729e 100644 --- a/v2/header.go +++ b/v2/header.go @@ -103,7 +103,9 @@ func goVersion() string { return "UNKNOWN" } -// XGoogHeader is for use by the Google Cloud Libraries only. +// XGoogHeader is for use by the Google Cloud Libraries only. See package +// [github.com/googleapis/gax-go/v2/callctx] for help setting/retrieving +// request/response headers. // // XGoogHeader formats key-value pairs. // The resulting string is suitable for x-goog-api-client header. @@ -125,7 +127,8 @@ func XGoogHeader(keyval ...string) string { } // InsertMetadataIntoOutgoingContext is for use by the Google Cloud Libraries -// only. +// only. See package [github.com/googleapis/gax-go/v2/callctx] for help +// setting/retrieving request/response headers. // // InsertMetadataIntoOutgoingContext returns a new context that merges the // provided keyvals metadata pairs with any existing metadata/headers in the @@ -137,7 +140,9 @@ func InsertMetadataIntoOutgoingContext(ctx context.Context, keyvals ...string) c return metadata.NewOutgoingContext(ctx, insertMetadata(ctx, keyvals...)) } -// BuildHeaders is for use by the Google Cloud Libraries only. +// BuildHeaders is for use by the Google Cloud Libraries only. See package +// [github.com/googleapis/gax-go/v2/callctx] for help setting/retrieving +// request/response headers. // // BuildHeaders returns a new http.Header that merges the provided // keyvals header pairs with any existing metadata/headers in the provided