diff --git a/google/analytics/data/v1alpha/BUILD.bazel b/google/analytics/data/v1alpha/BUILD.bazel index d835a26f..159b6571 100644 --- a/google/analytics/data/v1alpha/BUILD.bazel +++ b/google/analytics/data/v1alpha/BUILD.bazel @@ -1,4 +1,13 @@ # This file was automatically generated by BuildFileGenerator +# https://github.com/googleapis/gapic-generator/tree/master/rules_gapic/bazel + +# Most of the manual changes to this file will be overwritten. +# It's **only** allowed to change the following rule attribute values: +# - names of *_gapic_assembly_* rules +# - certain parameters of *_gapic_library rules, including but not limited to: +# * extra_protoc_parameters +# * extra_protoc_file_parameters +# The complete list of preserved parameters can be found in the source code. # This is an API workspace, having public visibility by default makes perfect sense. package(default_visibility = ["//visibility:public"]) @@ -18,6 +27,8 @@ proto_library( deps = [ "//google/api:annotations_proto", "//google/api:client_proto", + "//google/api:field_behavior_proto", + "//google/api:resource_proto", ], ) @@ -153,6 +164,8 @@ moved_proto_library( deps = [ "//google/api:annotations_proto", "//google/api:client_proto", + "//google/api:field_behavior_proto", + "//google/api:resource_proto", ], ) diff --git a/google/analytics/data/v1alpha/analytics_data_api.proto b/google/analytics/data/v1alpha/analytics_data_api.proto index b2b03120..58a80153 100644 --- a/google/analytics/data/v1alpha/analytics_data_api.proto +++ b/google/analytics/data/v1alpha/analytics_data_api.proto @@ -19,6 +19,8 @@ package google.analytics.data.v1alpha; import "google/analytics/data/v1alpha/data.proto"; import "google/api/annotations.proto"; import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; option go_package = "google.golang.org/genproto/googleapis/analytics/data/v1alpha;data"; option java_multiple_files = true; @@ -75,6 +77,37 @@ service AlphaAnalyticsData { body: "*" }; } + + // Returns metadata for dimensions and metrics available in reporting methods. + // Used to explore the dimensions and metrics. Dimensions and metrics will be + // mostly added over time, but renames and deletions may occur. + rpc GetMetadata(GetMetadataRequest) returns (Metadata) { + option (google.api.http) = { + get: "/v1alpha/{name=metadata}" + additional_bindings { + get: "/v1alpha/{name=properties/*/metadata}" + } + }; + option (google.api.method_signature) = "name"; + } +} + +// The dimensions and metrics currently accepted in reporting methods. +message Metadata { + option (google.api.resource) = { + type: "analyticsdata.googleapis.com/Metadata" + pattern: "metadata" + pattern: "properties/{property}/metadata" + }; + + // Resource name of this metadata. + string name = 3; + + // The dimensions descriptions. + repeated DimensionMetadata dimensions = 1; + + // The metric descriptions. + repeated MetricMetadata metrics = 2; } // The request to generate a report. @@ -92,25 +125,28 @@ message RunReportRequest { // 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. + // response rows for both date ranges. In a cohort request, this `dateRanges` + // must be unspecified. repeated DateRange date_ranges = 4; // The row count of the start row. The first row is counted as row 0. int64 offset = 5; - // The number of rows to return. - // If zero or unspecified, all rows are returned. + // The number of rows to return. If unspecified, 10 rows are returned. If + // -1, all rows are returned. int64 limit = 6; // Aggregation of metrics. Aggregated metric values will be shown in rows // where the dimension_values are set to "RESERVED_(MetricAggregation)". repeated MetricAggregation metric_aggregations = 7; - // The filter clause of dimensions. + // The filter clause of dimensions. Dimensions must be requested to be used in + // this filter. Metrics cannot be used in this filter. FilterExpression dimension_filter = 8; // The filter clause of metrics. Applied at post aggregation phase, similar to - // SQL having-clause. + // SQL having-clause. Metrics must be requested to be used in this filter. + // Dimensions cannot be used in this filter. FilterExpression metric_filter = 9; // Specifies how rows are ordered in the response. @@ -124,7 +160,9 @@ message RunReportRequest { // in the request the 'cohort' dimension must be present. CohortSpec cohort_spec = 12; - // If false, rows with metrics being 0 will not be returned. + // If false or unspecified, each row with all metrics equal to 0 will not be + // returned. If true, these rows will be returned if they are not separately + // removed by a filter. bool keep_empty_rows = 13; // Toggles whether to return the current state of this Analytics Property's @@ -134,7 +172,12 @@ message RunReportRequest { // The response report table corresponding to a request. message RunReportResponse { - // Describes metric columns. + // Describes dimension columns. The number of DimensionHeaders and ordering of + // DimensionHeaders matches the dimensions present in rows. + repeated DimensionHeader dimension_headers = 11; + + // Describes metric columns. The number of MetricHeaders and ordering of + // MetricHeaders matches the metrics present in rows. repeated MetricHeader metric_headers = 1; // Rows of dimension value combinations and metric values in the report. @@ -171,14 +214,13 @@ message RunPivotReportRequest { // metric_filter, order_bys. repeated Metric metrics = 3; - // The filter clause of dimensions. Requests are validated that all - // field_names in the dimension_filter are dimensions and are defined in - // Dimensions. + // The filter clause of dimensions. Dimensions must be requested to be used in + // this filter. Metrics cannot be used in this filter. FilterExpression dimension_filter = 4; // The filter clause of metrics. Applied at post aggregation phase, similar to - // SQL having-clause. Requests are validated that all field_names in the - // metric_filter are metrics and are defined in Metrics. + // SQL having-clause. Metrics must be requested to be used in this filter. + // Dimensions cannot be used in this filter. FilterExpression metric_filter = 5; // Describes the visual format of the report's dimensions in columns or rows. @@ -191,7 +233,7 @@ message RunPivotReportRequest { // ranges are specified, event data from each date range is used in the // report. A special dimension with field name "dateRange" can be included in // a Pivot's field names; if included, the report compares between date - // ranges. This dateRanges field is not used in cohorts reports. + // ranges. In a cohort request, this `dateRanges` must be unspecified. repeated DateRange date_ranges = 7; // A currency code in ISO4217 format, such as "AED", "USD", "JPY". @@ -202,7 +244,9 @@ message RunPivotReportRequest { // in the request the 'cohort' dimension must be present. CohortSpec cohort_spec = 9; - // If false, rows with metrics being 0 will not be returned. + // If false or unspecified, each row with all metrics equal to 0 will not be + // returned. If true, these rows will be returned if they are not separately + // removed by a filter. bool keep_empty_rows = 10; // Toggles whether to return the current state of this Analytics Property's @@ -250,7 +294,12 @@ message RunPivotReportResponse { // }] repeated PivotHeader pivot_headers = 1; - // Describes metric columns. + // Describes dimension columns. The number of DimensionHeaders and ordering of + // DimensionHeaders matches the dimensions present in rows. + repeated DimensionHeader dimension_headers = 7; + + // Describes metric columns. The number of MetricHeaders and ordering of + // MetricHeaders matches the metrics present in rows. repeated MetricHeader metric_headers = 2; // Rows of dimension value combinations and metric values in the report. @@ -304,3 +353,17 @@ message BatchRunPivotReportsResponse { // Individual responses. Each response has a separate pivot report request. repeated RunPivotReportResponse pivot_reports = 1; } + +// Request for dimension and metric metadata. +message GetMetadataRequest { + // Required. The name of the metadata to retrieve. Either has the form + // 'metadata' or 'properties/{property}/metadata'. This name field is + // specified in the URL path and not URL parameters. Property is a numeric + // Google Analytics App + Web Property Id. + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "analyticsdata.googleapis.com/Metadata" + } + ]; +} diff --git a/google/analytics/data/v1alpha/data.proto b/google/analytics/data/v1alpha/data.proto index 0b1dd8fd..5202800f 100644 --- a/google/analytics/data/v1alpha/data.proto +++ b/google/analytics/data/v1alpha/data.proto @@ -357,16 +357,17 @@ message Pivot { repeated string field_names = 1; // Specifies how dimensions are ordered in the pivot. In the first Pivot, the - // OrderBys determine Row and DimensionHeader ordering; in subsequent Pivots, - // the OrderBys determine only DimensionHeader ordering. Dimensions specified - // in these OrderBys must be a subset of Pivot.field_names. + // OrderBys determine Row and PivotDimensionHeader ordering; in subsequent + // Pivots, the OrderBys determine only PivotDimensionHeader ordering. + // Dimensions specified in these OrderBys must be a subset of + // Pivot.field_names. repeated OrderBy order_bys = 2; // The row count of the start row. The first row is counted as row 0. int64 offset = 3; - // The number of rows to return in this pivot. - // If zero or unspecified, all rows are returned. + // The number of rows to return in this pivot. If unspecified, 10 rows are + // returned. If -1, all rows are returned. int64 limit = 4; // Aggregate the metrics by dimensions in this pivot using the specified @@ -391,7 +392,9 @@ message CohortSpec { // belong to the same cohort. message Cohort { // Assigns a name to this cohort. The dimension `cohort` is valued to this - // name in a report response. If not set, a cohort is named the empty string. + // name in a report response. If set, cannot begin with `cohort_` or + // `RESERVED_`. If not set, cohorts are named by their zero based index + // `cohort_0`, `cohort_1`, etc. string name = 1; // The dimension used by cohort. Only supports `firstTouchDate` for retention @@ -399,12 +402,14 @@ message Cohort { string dimension = 2; // The cohort selects users whose first visit date is between start date - // and end date defined in the date_range. The date range should be aligned - // with the cohort's granularity. - // If CohortsRange uses daily granularity, the date range can be aligned to - // any day. - // If CohortsRange uses weekly granularity, the date range should be aligned - // to the week boundary, starting at Sunday and ending Saturday. If + // and end date defined in the `dateRange`. In a cohort request, this + // `dateRange` is required and the `dateRanges` in the `RunReportRequest` or + // `RunPivotReportRequest` must be unspecified. + // + // The date range should be aligned with the cohort's granularity. If + // CohortsRange uses daily granularity, the date range can be aligned to any + // day. If CohortsRange uses weekly granularity, the date range should be + // aligned to the week boundary, starting at Sunday and ending Saturday. If // CohortsRange uses monthly granularity, the date range should be aligned to // the month, starting at the first and ending on the last day of the month. DateRange date_range = 3; @@ -412,17 +417,9 @@ message Cohort { // Settings of a cohort report. message CohortReportSettings { - // If true, accumulates the result from first visit day to the end day. + // If true, accumulates the result from first visit day to the end day. Not + // supported in `RunReportRequest`. bool accumulate = 1; - - // If true, the report is for lifetime value report and should pivot on user - // event. - bool pivot_on_user_event = 2; - - // If some values are missing while computing ratios, we want to compute the - // ratios only based on non-missing values. - // This field should be set to true only for a totals request. - bool missing_value_as_zero = 4; } // Describes date range for a cohort report. @@ -462,27 +459,39 @@ message ResponseMetaData { bool data_loss_from_other_row = 3; } -// Describes the metric column in the report. +// Describes a dimension column in the report. Dimensions requested in a report +// produce column entries within rows and DimensionHeaders. However, dimensions +// used exclusively within filters or expressions do not produce columns in a +// report; correspondingly, those dimensions do not produce headers. +message DimensionHeader { + // The dimension's name. + string name = 1; +} + +// Describes a metric column in the report. Visible metrics requested in a +// report produce column entries within rows and MetricHeaders. However, +// metrics used exclusively within filters or expressions do not produce columns +// in a report; correspondingly, those metrics do not produce headers. message MetricHeader { - // Metric name. + // The metric's name. string name = 1; - // Metric data type. + // The metric's data type. MetricType type = 2; } -// Dimensions' values in a pivot. +// Dimensions' values in a single pivot. message PivotHeader { // The size is the same as the cardinality of the corresponding dimension // combinations. - repeated DimensionHeader dimension_headers = 1; + repeated PivotDimensionHeader pivot_dimension_headers = 1; // The cardinality of the pivot as if offset = 0 and limit = -1. int32 row_count = 2; } -// The header for the dimensions. -message DimensionHeader { +// Summarizes dimension values from a row for this pivot. +message PivotDimensionHeader { // Values of multiple dimensions in a pivot. repeated DimensionValue dimension_values = 1; } @@ -583,6 +592,54 @@ message QuotaStatus { int32 remaining = 2; } +// Explains a dimension. +message DimensionMetadata { + // This dimension's name. Useable in [Dimension](#Dimension)'s `name`. For + // example, `eventName`. + string api_name = 1; + + // This dimension's name within the Google Analytics user interface. For + // example, `Event name`. + string ui_name = 2; + + // Description of how this dimension is used and calculated. + string description = 3; + + // Still usable but deprecated names for this dimension. If populated, this + // dimension is available by either `apiName` or one of `deprecatedApiNames` + // for a period of time. After the deprecation period, the dimension will be + // available only by `apiName`. + repeated string deprecated_api_names = 4; +} + +// Explains a metric. +message MetricMetadata { + // A metric name. Useable in [Metric](#Metric)'s `name`. For example, + // `eventCount`. + string api_name = 1; + + // This metric's name within the Google Analytics user interface. For example, + // `Event count`. + string ui_name = 2; + + // Description of how this metric is used and calculated. + string description = 3; + + // Still usable but deprecated names for this metric. If populated, this + // metric is available by either `apiName` or one of `deprecatedApiNames` + // for a period of time. After the deprecation period, the metric will be + // available only by `apiName`. + repeated string deprecated_api_names = 4; + + // The type of this metric. + MetricType type = 5; + + // The mathematical expression for this derived metric. Can be used in + // [Metric](#Metric)'s `expression` field for equivalent reports. Most metrics + // are not expressions, and for non-expressions, this field is empty. + string expression = 6; +} + // Represents aggregation of metrics. enum MetricAggregation { // Unspecified operator. @@ -601,7 +658,7 @@ enum MetricAggregation { COUNT = 4; } -// Type of a metric value. +// A metric's value type. enum MetricType { // Unspecified type. METRIC_TYPE_UNSPECIFIED = 0; @@ -611,4 +668,10 @@ enum MetricType { // Floating point type. TYPE_FLOAT = 2; + + // A duration of seconds; a special floating point type. + TYPE_SECONDS = 4; + + // An amount of money; a special floating point type. + TYPE_CURRENCY = 9; }