@google-analytics/data 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [4.1.0](https://github.com/googleapis/google-cloud-node/compare/data-v4.0.1...data-v4.1.0) (2023-11-16)
+
+
+### Features
+
+* [analytics-data] add the `SheetExportAudienceList` method to the Data API v1 alpha ([#4804](https://github.com/googleapis/google-cloud-node/issues/4804)) ([279e77c](https://github.com/googleapis/google-cloud-node/commit/279e77c39982c98fb2f9f6b9305ee9097ae10352))
+
 ## [4.0.1](https://github.com/googleapis/google-cloud-node/compare/data-v4.0.0...data-v4.0.1) (2023-09-06)
 
 

package/README.md

@@ -114,6 +114,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/google-cloud-node/
 | Alpha_analytics_data.list_audience_lists | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-analytics-data/samples/generated/v1alpha/alpha_analytics_data.list_audience_lists.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-analytics-data/samples/generated/v1alpha/alpha_analytics_data.list_audience_lists.js,packages/google-analytics-data/samples/README.md) |
 | Alpha_analytics_data.query_audience_list | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-analytics-data/samples/generated/v1alpha/alpha_analytics_data.query_audience_list.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-analytics-data/samples/generated/v1alpha/alpha_analytics_data.query_audience_list.js,packages/google-analytics-data/samples/README.md) |
 | Alpha_analytics_data.run_funnel_report | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-analytics-data/samples/generated/v1alpha/alpha_analytics_data.run_funnel_report.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-analytics-data/samples/generated/v1alpha/alpha_analytics_data.run_funnel_report.js,packages/google-analytics-data/samples/README.md) |
+| Alpha_analytics_data.sheet_export_audience_list | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-analytics-data/samples/generated/v1alpha/alpha_analytics_data.sheet_export_audience_list.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-analytics-data/samples/generated/v1alpha/alpha_analytics_data.sheet_export_audience_list.js,packages/google-analytics-data/samples/README.md) |
 | Beta_analytics_data.batch_run_pivot_reports | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-analytics-data/samples/generated/v1beta/beta_analytics_data.batch_run_pivot_reports.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-analytics-data/samples/generated/v1beta/beta_analytics_data.batch_run_pivot_reports.js,packages/google-analytics-data/samples/README.md) |
 | Beta_analytics_data.batch_run_reports | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-analytics-data/samples/generated/v1beta/beta_analytics_data.batch_run_reports.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-analytics-data/samples/generated/v1beta/beta_analytics_data.batch_run_reports.js,packages/google-analytics-data/samples/README.md) |
 | Beta_analytics_data.check_compatibility | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-analytics-data/samples/generated/v1beta/beta_analytics_data.check_compatibility.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-analytics-data/samples/generated/v1beta/beta_analytics_data.check_compatibility.js,packages/google-analytics-data/samples/README.md) |

package/build/protos/google/analytics/data/v1alpha/analytics_data_api.proto

@@ -30,7 +30,7 @@ option java_outer_classname = "AnalyticsDataApiProto";
 option java_package = "com.google.analytics.data.v1alpha";
 option (google.api.resource_definition) = {
   type: "analyticsadmin.googleapis.com/Property"
-  pattern: "properties/{propertyId}"
+  pattern: "properties/{property}"
 };
 
 // Google Analytics reporting data service.
@@ -38,7 +38,10 @@ service AlphaAnalyticsData {
   option (google.api.default_host) = "analyticsdata.googleapis.com";
   option (google.api.oauth_scopes) =
       "https://www.googleapis.com/auth/analytics,"
-      "https://www.googleapis.com/auth/analytics.readonly";
+      "https://www.googleapis.com/auth/analytics.readonly,"
+      "https://www.googleapis.com/auth/drive,"
+      "https://www.googleapis.com/auth/drive.file,"
+      "https://www.googleapis.com/auth/spreadsheets";
 
   // Returns a customized funnel report of your Google Analytics event data. The
   // data returned from the API is as a table with columns for the requested
@@ -70,6 +73,10 @@ service AlphaAnalyticsData {
   // first create the audience list through this method and then send the
   // audience resource name to the `QueryAudienceList` method.
   //
+  // See [Creating an Audience
+  // List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics)
+  // for an introduction to Audience Lists with examples.
+  //
   // An audience list is a snapshot of the users currently in the audience at
   // the time of audience list creation. Creating audience lists for one
   // audience on different days will return different results as users enter and
@@ -79,6 +86,12 @@ service AlphaAnalyticsData {
   // that are important to your business. To learn more, see
   // https://support.google.com/analytics/answer/9267572. Audience lists contain
   // the users in each audience.
+  //
+  // This method is introduced at alpha stability with the intention of
+  // gathering feedback on syntax and capabilities before entering beta. To give
+  // your feedback on this API, complete the
+  // [Google Analytics Audience Export API
+  // Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.
   rpc CreateAudienceList(CreateAudienceListRequest)
       returns (google.longrunning.Operation) {
     option (google.api.http) = {
@@ -95,11 +108,22 @@ service AlphaAnalyticsData {
   // Retrieves an audience list of users. After creating an audience, the users
   // are not immediately available for listing. First, a request to
   // `CreateAudienceList` is necessary to create an audience list of users, and
-  // then second, this method is used to retrieve the users in the audience.
+  // then second, this method is used to retrieve the users in the audience
+  // list.
+  //
+  // See [Creating an Audience
+  // List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics)
+  // for an introduction to Audience Lists with examples.
   //
   // Audiences in Google Analytics 4 allow you to segment your users in the ways
   // that are important to your business. To learn more, see
   // https://support.google.com/analytics/answer/9267572.
+  //
+  // This method is introduced at alpha stability with the intention of
+  // gathering feedback on syntax and capabilities before entering beta. To give
+  // your feedback on this API, complete the
+  // [Google Analytics Audience Export API
+  // Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.
   rpc QueryAudienceList(QueryAudienceListRequest)
       returns (QueryAudienceListResponse) {
     option (google.api.http) = {
@@ -109,8 +133,46 @@ service AlphaAnalyticsData {
     option (google.api.method_signature) = "name";
   }
 
+  // Exports an audience list of users to a Google Sheet. After creating an
+  // audience, the users are not immediately available for listing. First, a
+  // request to `CreateAudienceList` is necessary to create an audience list of
+  // users, and then second, this method is used to export those users in the
+  // audience list to a Google Sheet.
+  //
+  // See [Creating an Audience
+  // List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics)
+  // for an introduction to Audience Lists with examples.
+  //
+  // Audiences in Google Analytics 4 allow you to segment your users in the ways
+  // that are important to your business. To learn more, see
+  // https://support.google.com/analytics/answer/9267572.
+  //
+  // This method is introduced at alpha stability with the intention of
+  // gathering feedback on syntax and capabilities before entering beta. To give
+  // your feedback on this API, complete the
+  // [Google Analytics Audience Export API
+  // Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.
+  rpc SheetExportAudienceList(SheetExportAudienceListRequest)
+      returns (SheetExportAudienceListResponse) {
+    option (google.api.http) = {
+      post: "/v1alpha/{name=properties/*/audienceLists/*}:exportSheet"
+      body: "*"
+    };
+    option (google.api.method_signature) = "name";
+  }
+
   // Gets configuration metadata about a specific audience list. This method
   // can be used to understand an audience list after it has been created.
+  //
+  // See [Creating an Audience
+  // List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics)
+  // for an introduction to Audience Lists with examples.
+  //
+  // This method is introduced at alpha stability with the intention of
+  // gathering feedback on syntax and capabilities before entering beta. To give
+  // your feedback on this API, complete the
+  // [Google Analytics Audience Export API
+  // Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.
   rpc GetAudienceList(GetAudienceListRequest) returns (AudienceList) {
     option (google.api.http) = {
       get: "/v1alpha/{name=properties/*/audienceLists/*}"
@@ -122,6 +184,16 @@ service AlphaAnalyticsData {
   // find and reuse existing audience lists rather than creating unnecessary new
   // audience lists. The same audience can have multiple audience lists that
   // represent the list of users that were in an audience on different days.
+  //
+  // See [Creating an Audience
+  // List](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-basics)
+  // for an introduction to Audience Lists with examples.
+  //
+  // This method is introduced at alpha stability with the intention of
+  // gathering feedback on syntax and capabilities before entering beta. To give
+  // your feedback on this API, complete the
+  // [Google Analytics Audience Export API
+  // Feedback](https://forms.gle/EeA5u5LW6PEggtCEA) form.
   rpc ListAudienceLists(ListAudienceListsRequest)
       returns (ListAudienceListsResponse) {
     option (google.api.http) = {
@@ -134,7 +206,7 @@ service AlphaAnalyticsData {
 // A request to retrieve configuration metadata about a specific audience list.
 message GetAudienceListRequest {
   // Required. The audience list resource name.
-  // Format: `properties/{propertyId}/audienceLists/{audienceListId}`
+  // Format: `properties/{property}/audienceLists/{audience_list}`
   string name = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -146,7 +218,7 @@ message GetAudienceListRequest {
 // A request to list all audience lists for a property.
 message ListAudienceListsRequest {
   // Required. All audience lists for this property will be listed in the
-  // response. Format: `properties/{propertyId}`
+  // response. Format: `properties/{property}`
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -154,18 +226,18 @@ message ListAudienceListsRequest {
     }
   ];
 
-  // The maximum number of audience lists to return. The service may return
-  // fewer than this value. If unspecified, at most 200 audience lists will be
-  // returned. The maximum value is 1000 (higher values will be coerced to the
-  // maximum).
-  int32 page_size = 2;
+  // Optional. The maximum number of audience lists to return. The service may
+  // return fewer than this value. If unspecified, at most 200 audience lists
+  // will be returned. The maximum value is 1000 (higher values will be coerced
+  // to the maximum).
+  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
 
-  // A page token, received from a previous `ListAudienceLists` call. Provide
-  // this to retrieve the subsequent page.
+  // Optional. A page token, received from a previous `ListAudienceLists` call.
+  // Provide this to retrieve the subsequent page.
   //
   // When paginating, all other parameters provided to `ListAudienceLists` must
   // match the call that provided the page token.
-  string page_token = 3;
+  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // A list of all audience lists for a property.
@@ -181,7 +253,7 @@ message ListAudienceListsResponse {
 // A request to create a new audience list.
 message CreateAudienceListRequest {
   // Required. The parent resource where this audience list will be created.
-  // Format: `properties/{propertyId}`
+  // Format: `properties/{property}`
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
@@ -199,7 +271,9 @@ message CreateAudienceListRequest {
 message AudienceList {
   option (google.api.resource) = {
     type: "analyticsdata.googleapis.com/AudienceList"
-    pattern: "properties/{propertyId}/audienceLists/{audienceListId}"
+    pattern: "properties/{property}/audienceLists/{audience_list}"
+    plural: "audienceLists"
+    singular: "audienceList"
   };
 
   // The AudienceList currently exists in this state.
@@ -221,17 +295,20 @@ message AudienceList {
     FAILED = 3;
   }
 
-  // Output only. The audience list resource name assigned during creation. This
-  // resource name identifies this `AudienceList`.
+  // Output only. Identifier. The audience list resource name assigned during
+  // creation. This resource name identifies this `AudienceList`.
   //
-  // Format: `properties/{propertyId}/audienceLists/{audienceListId}`
-  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
+  // Format: `properties/{property}/audienceLists/{audience_list}`
+  string name = 1 [
+    (google.api.field_behavior) = IDENTIFIER,
+    (google.api.field_behavior) = OUTPUT_ONLY
+  ];
 
   // Required. The audience resource name. This resource name identifies the
   // audience being listed and is shared between the Analytics Data & Admin
   // APIs.
   //
-  // Format: `properties/{propertyId}/audiences/{audienceId}`
+  // Format: `properties/{property}/audiences/{audience}`
   string audience = 2 [(google.api.field_behavior) = REQUIRED];
 
   // Output only. The descriptive display name for this audience. For example,
@@ -249,6 +326,20 @@ message AudienceList {
   // AudienceList began the `CREATING` state.
   optional google.protobuf.Timestamp begin_creating_time = 6
       [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The total quota tokens charged during creation of the
+  // AudienceList. Because this token count is based on activity from the
+  // `CREATING` state, this tokens charged will be fixed once an AudienceList
+  // enters the `ACTIVE` or `FAILED` states.
+  int32 creation_quota_tokens_charged = 7
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The total number of rows in the AudienceList result.
+  optional int32 row_count = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Error message is populated when an audience list fails during
+  // creation. A common reason for such a failure is quota exhaustion.
+  optional string error_message = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // This metadata is currently blank.
@@ -256,11 +347,12 @@ message AudienceListMetadata {}
 
 // A request to list users in an audience list.
 message QueryAudienceListRequest {
-  // The name of the audience list to retrieve users from.
-  // Format: `properties/{propertyId}/audienceLists/{audienceListId}`
-  string name = 1;
+  // Required. The name of the audience list to retrieve users from.
+  // Format: `properties/{property}/audienceLists/{audience_list}`
+  string name = 1 [(google.api.field_behavior) = REQUIRED];
 
-  // The row count of the start row. The first row is counted as row 0.
+  // Optional. The row count of the start row. The first row is counted as row
+  // 0.
   //
   // When paging, the first request does not specify offset; or equivalently,
   // sets offset to 0; the first request returns the first `limit` of rows. The
@@ -269,18 +361,18 @@ message QueryAudienceListRequest {
   //
   // To learn more about this pagination parameter, see
   // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
-  int64 offset = 2;
+  int64 offset = 2 [(google.api.field_behavior) = OPTIONAL];
 
-  // The number of rows to return. If unspecified, 10,000 rows are returned. The
-  // API returns a maximum of 250,000 rows per request, no matter how many you
-  // ask for. `limit` must be positive.
+  // Optional. The number of rows to return. If unspecified, 10,000 rows are
+  // returned. The API returns a maximum of 250,000 rows per request, no matter
+  // how many you ask for. `limit` must be positive.
   //
   // The API can also return fewer rows than the requested `limit`, if there
   // aren't as many dimension values as the `limit`.
   //
   // To learn more about this pagination parameter, see
   // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
-  int64 limit = 3;
+  int64 limit = 3 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // A list of users in an audience list.
@@ -294,10 +386,10 @@ message QueryAudienceListResponse {
   // response will be less than or equal to request's page size.
   repeated AudienceRow audience_rows = 2;
 
-  // The total number of rows in the query result. `rowCount` is independent of
-  // the number of rows returned in the response, the `limit` request
-  // parameter, and the `offset` request parameter. For example if a query
-  // returns 175 rows and includes `limit` of 50 in the API request, the
+  // The total number of rows in the AudienceList result. `rowCount` is
+  // independent of the number of rows returned in the response, the `limit`
+  // request parameter, and the `offset` request parameter. For example if a
+  // query returns 175 rows and includes `limit` of 50 in the API request, the
   // response will contain `rowCount` of 175 but only 50 rows.
   //
   // To learn more about this pagination parameter, see
@@ -305,6 +397,69 @@ message QueryAudienceListResponse {
   optional int32 row_count = 3;
 }
 
+// A request to export users in an audience list to a Google Sheet.
+message SheetExportAudienceListRequest {
+  // Required. The name of the audience list to retrieve users from.
+  // Format: `properties/{property}/audienceLists/{audience_list}`
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "analyticsdata.googleapis.com/AudienceList"
+    }
+  ];
+
+  // Optional. The row count of the start row. The first row is counted as row
+  // 0.
+  //
+  // When paging, the first request does not specify offset; or equivalently,
+  // sets offset to 0; the first request returns the first `limit` of rows. The
+  // second request sets offset to the `limit` of the first request; the second
+  // request returns the second `limit` of rows.
+  //
+  // To learn more about this pagination parameter, see
+  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
+  int64 offset = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The number of rows to return. If unspecified, 10,000 rows are
+  // returned. The API returns a maximum of 250,000 rows per request, no matter
+  // how many you ask for. `limit` must be positive.
+  //
+  // The API can also return fewer rows than the requested `limit`, if there
+  // aren't as many dimension values as the `limit`.
+  //
+  // To learn more about this pagination parameter, see
+  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
+  int64 limit = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// The created Google Sheet with the list of users in an audience list.
+message SheetExportAudienceListResponse {
+  // A uri for you to visit in your browser to view the Google Sheet.
+  optional string spreadsheet_uri = 1;
+
+  // An ID that identifies the created Google Sheet resource.
+  optional string spreadsheet_id = 2;
+
+  // The total number of rows in the AudienceList result. `rowCount` is
+  // independent of the number of rows returned in the response, the `limit`
+  // request parameter, and the `offset` request parameter. For example if a
+  // query returns 175 rows and includes `limit` of 50 in the API request, the
+  // response will contain `rowCount` of 175 but only 50 rows.
+  //
+  // To learn more about this pagination parameter, see
+  // [Pagination](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination).
+  optional int32 row_count = 3;
+
+  // Configuration data about AudienceList being exported. Returned to help
+  // interpret the AudienceList in the Google Sheet of this response.
+  //
+  // For example, the AudienceList may have more rows than are present in the
+  // Google Sheet, and in that case, you may want to send an additional sheet
+  // export request with a different `offset` value to retrieve the next page of
+  // rows in an additional Google Sheet.
+  optional AudienceList audience_list = 4;
+}
+
 // Dimension value attributes for the audience user row.
 message AudienceRow {
   // Each dimension value attribute for an audience user. One dimension value
@@ -315,10 +470,10 @@ message AudienceRow {
 // An audience dimension is a user attribute. Specific user attributed are
 // requested and then later returned in the `QueryAudienceListResponse`.
 message AudienceDimension {
-  // The API name of the dimension. See the [API
+  // Optional. The API name of the dimension. See the [API
   // Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/audience-list-api-schema#dimensions)
   // for the list of dimension names.
-  string dimension_name = 1;
+  string dimension_name = 1 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The value of a dimension.
@@ -347,75 +502,79 @@ message RunFunnelReportRequest {
     TRENDED_FUNNEL = 2;
   }
 
-  // A Google Analytics GA4 property identifier whose events are tracked.
-  // Specified in the URL path and not the body. To learn more, see [where to
-  // find your Property
+  // Optional. A Google Analytics GA4 property identifier whose events are
+  // tracked. Specified in the URL path and not the body. To learn more, see
+  // [where to find your Property
   // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
   // Within a batch request, this property should either be unspecified or
   // consistent with the batch-level property.
   //
   // Example: properties/1234
-  string property = 1;
-
-  // Date ranges of data to read. If multiple date ranges are requested, each
-  // response row will contain a zero based date range index. If two date
-  // ranges overlap, the event data for the overlapping days is included in the
-  // response rows for both date ranges.
-  repeated DateRange date_ranges = 2;
-
-  // The configuration of this request's funnel. This funnel configuration is
-  // required.
-  Funnel funnel = 3;
-
-  // If specified, this breakdown adds a dimension to the funnel table sub
-  // report response. This breakdown dimension expands each funnel step to the
-  // unique values of the breakdown dimension. For example, a breakdown by the
-  // `deviceCategory` dimension will create rows for `mobile`, `tablet`,
+  string property = 1 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Date ranges of data to read. If multiple date ranges are
+  // requested, each response row will contain a zero based date range index. If
+  // two date ranges overlap, the event data for the overlapping days is
+  // included in the response rows for both date ranges.
+  repeated DateRange date_ranges = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The configuration of this request's funnel. This funnel
+  // configuration is required.
+  Funnel funnel = 3 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. If specified, this breakdown adds a dimension to the funnel table
+  // sub report response. This breakdown dimension expands each funnel step to
+  // the unique values of the breakdown dimension. For example, a breakdown by
+  // the `deviceCategory` dimension will create rows for `mobile`, `tablet`,
   // `desktop`, and the total.
-  FunnelBreakdown funnel_breakdown = 4;
+  FunnelBreakdown funnel_breakdown = 4 [(google.api.field_behavior) = OPTIONAL];
 
-  // If specified, next action adds a dimension to the funnel visualization sub
-  // report response. This next action dimension expands each funnel step to the
-  // unique values of the next action. For example a next action of the
-  // `eventName` dimension will create rows for several events (for example
-  // `session_start` & `click`) and the total.
+  // Optional. If specified, next action adds a dimension to the funnel
+  // visualization sub report response. This next action dimension expands each
+  // funnel step to the unique values of the next action. For example a next
+  // action of the `eventName` dimension will create rows for several events
+  // (for example `session_start` & `click`) and the total.
   //
   // Next action only supports `eventName` and most Page / Screen dimensions
   // like `pageTitle` and `pagePath`.
-  FunnelNextAction funnel_next_action = 5;
-
-  // The funnel visualization type controls the dimensions present in the funnel
-  // visualization sub report response. If not specified, `STANDARD_FUNNEL` is
-  // used.
-  FunnelVisualizationType funnel_visualization_type = 6;
-
-  // The configurations of segments. Segments are subsets of a property's data.
-  // In a funnel report with segments, the funnel is evaluated in each segment.
+  FunnelNextAction funnel_next_action = 5
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The funnel visualization type controls the dimensions present in
+  // the funnel visualization sub report response. If not specified,
+  // `STANDARD_FUNNEL` is used.
+  FunnelVisualizationType funnel_visualization_type = 6
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The configurations of segments. Segments are subsets of a
+  // property's data. In a funnel report with segments, the funnel is evaluated
+  // in each segment.
   //
   // Each segment specified in this request
   // produces a separate row in the response; in the response, each segment
   // identified by its name.
   //
   // The segments parameter is optional. Requests are limited to 4 segments.
-  repeated Segment segments = 7;
+  repeated Segment segments = 7 [(google.api.field_behavior) = OPTIONAL];
 
-  // The number of rows to return. If unspecified, 10,000 rows are returned. The
-  // API returns a maximum of 250,000 rows per request, no matter how many you
-  // ask for. `limit` must be positive.
+  // Optional. The number of rows to return. If unspecified, 10,000 rows are
+  // returned. The API returns a maximum of 250,000 rows per request, no matter
+  // how many you ask for. `limit` must be positive.
   //
   // The API can also return fewer rows than the requested `limit`, if there
   // aren't as many dimension values as the `limit`.
-  int64 limit = 9;
+  int64 limit = 9 [(google.api.field_behavior) = OPTIONAL];
 
-  // Dimension filters allow you to ask for only specific dimension values in
-  // the report. To learn more, see [Creating a Report: Dimension
+  // Optional. Dimension filters allow you to ask for only specific dimension
+  // values in the report. To learn more, see [Creating a Report: Dimension
   // Filters](https://developers.google.com/analytics/devguides/reporting/data/v1/basics#dimension_filters)
   // for examples. Metrics cannot be used in this filter.
-  FilterExpression dimension_filter = 10;
+  FilterExpression dimension_filter = 10
+      [(google.api.field_behavior) = OPTIONAL];
 
-  // Toggles whether to return the current state of this Analytics Property's
-  // quota. Quota is returned in [PropertyQuota](#PropertyQuota).
-  bool return_property_quota = 12;
+  // Optional. Toggles whether to return the current state of this Analytics
+  // Property's quota. Quota is returned in [PropertyQuota](#PropertyQuota).
+  bool return_property_quota = 12 [(google.api.field_behavior) = OPTIONAL];
 }
 
 // The funnel report response contains two sub reports. The two sub reports are

package/build/protos/google/analytics/data/v1alpha/data.proto

@@ -23,8 +23,8 @@ option java_multiple_files = true;
 option java_outer_classname = "ReportingApiProto";
 option java_package = "com.google.analytics.data.v1alpha";
 
-// A contiguous set of days: startDate, startDate + 1, ..., endDate. Requests
-// are allowed up to 4 date ranges.
+// A contiguous set of days: `startDate`, `startDate + 1`, ..., `endDate`.
+// Requests are allowed up to 4 date ranges.
 message DateRange {
   // The inclusive start date for the query in the format `YYYY-MM-DD`. Cannot
   // be after `end_date`. The format `NdaysAgo`, `yesterday`, or `today` is also
@@ -51,7 +51,16 @@ message DateRange {
 message Dimension {
   // The name of the dimension. See the [API
   // Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions)
-  // for the list of dimension names.
+  // for the list of dimension names supported by core reporting methods such
+  // as `runReport` and `batchRunReports`. See
+  // [Realtime
+  // Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#dimensions)
+  // for the list of dimension names supported by the `runRealtimeReport`
+  // method. See
+  // [Funnel
+  // Dimensions](https://developers.google.com/analytics/devguides/reporting/data/v1/exploration-api-schema#dimensions)
+  // for the list of dimension names supported by the `runFunnelReport`
+  // method.
   //
   // If `dimensionExpression` is specified, `name` can be any string that you
   // would like within the allowed character set. For example if a
@@ -1168,7 +1177,7 @@ message FunnelParameterFilter {
 // the funnel report.
 message FunnelResponseMetadata {
   // If funnel report results are
-  // [sampled](https://support.google.com/analytics/answer/2637192), this
+  // [sampled](https://support.google.com/analytics/answer/13331292), this
   // describes what percentage of events were used in this funnel report. One
   // `samplingMetadatas` is populated for each date range. Each
   // `samplingMetadatas` corresponds to a date range in order that date ranges
@@ -1179,7 +1188,7 @@ message FunnelResponseMetadata {
 }
 
 // If funnel report results are
-// [sampled](https://support.google.com/analytics/answer/2637192), this
+// [sampled](https://support.google.com/analytics/answer/13331292), this
 // metadata describes what percentage of events were used in this funnel
 // report for a date range. Sampling is the practice of analyzing a subset of
 // all data in order to uncover the meaningful information in the larger data