From 705962b5a317e083fdbb2311d4baa72df5816686 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Tue, 3 Nov 2020 09:41:08 -0800 Subject: [PATCH] feat: added RunRealtimeReport method that returns a customized report of realtime event data for a GA4 property docs: minor documentation updates PiperOrigin-RevId: 340463146 --- .../data/v1alpha/analytics_data_api.proto | 85 ++++++++++++- google/analytics/data/v1alpha/data.proto | 113 ++++++++++++------ 2 files changed, 160 insertions(+), 38 deletions(-) diff --git a/google/analytics/data/v1alpha/analytics_data_api.proto b/google/analytics/data/v1alpha/analytics_data_api.proto index 3e8c7b6a..0aa3046b 100644 --- a/google/analytics/data/v1alpha/analytics_data_api.proto +++ b/google/analytics/data/v1alpha/analytics_data_api.proto @@ -106,6 +106,16 @@ service AlphaAnalyticsData { }; option (google.api.method_signature) = "name"; } + + // The Google Analytics Realtime API returns a customized report of realtime + // event data for your property. These reports show events and usage from the + // last 30 minutes. + rpc RunRealtimeReport(RunRealtimeReportRequest) returns (RunRealtimeReportResponse) { + option (google.api.http) = { + post: "/v1alpha/{property=properties/*}:runRealtimeReport" + body: "*" + }; + } } // The dimensions and metrics currently accepted in reporting methods. @@ -118,7 +128,7 @@ message Metadata { // Resource name of this metadata. string name = 3; - // The dimensions descriptions. + // The dimension descriptions. repeated DimensionMetadata dimensions = 1; // The metric descriptions. @@ -403,3 +413,76 @@ message GetMetadataRequest { } ]; } + +// The request to generate a realtime report. +message RunRealtimeReportRequest { + // 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/trusted-testing/analytics-data/property-id). + // + // Example: properties/1234 + string property = 1; + + // The dimensions requested and displayed. + repeated Dimension dimensions = 2; + + // The metrics requested and displayed. + repeated Metric metrics = 3; + + // The number of rows to return. If unspecified, 10 rows are returned. If + // -1, all rows are returned. + int64 limit = 4; + + // 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 = 5; + + // The filter clause of metrics. Applied at post aggregation phase, similar to + // SQL having-clause. Metrics must be requested to be used in this filter. + // Dimensions cannot be used in this filter. + FilterExpression metric_filter = 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; + + // Specifies how rows are ordered in the response. + repeated OrderBy order_bys = 8; + + // Toggles whether to return the current state of this Analytics Property's + // Realtime quota. Quota is returned in [PropertyQuota](#PropertyQuota). + bool return_property_quota = 9; +} + +// The response realtime report table corresponding to a request. +message RunRealtimeReportResponse { + // Describes dimension columns. The number of DimensionHeaders and ordering of + // DimensionHeaders matches the dimensions present in rows. + repeated DimensionHeader dimension_headers = 1; + + // 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. + repeated Row rows = 3; + + // If requested, the totaled values of metrics. + repeated Row totals = 4; + + // If requested, the maximum values of metrics. + repeated Row maximums = 5; + + // If requested, the minimum values of metrics. + repeated Row minimums = 6; + + // The total number of rows in the query result, regardless of the number of + // rows returned in the response. For example if a query returns 175 rows and + // includes limit = 50 in the API request, the response will contain row_count + // = 175 but only 50 rows. + int32 row_count = 7; + + // This Analytics Property's Realtime quota state including this request. + PropertyQuota property_quota = 8; +} diff --git a/google/analytics/data/v1alpha/data.proto b/google/analytics/data/v1alpha/data.proto index 4ca21459..8af5cc45 100644 --- a/google/analytics/data/v1alpha/data.proto +++ b/google/analytics/data/v1alpha/data.proto @@ -46,15 +46,27 @@ message DateRange { // The unique identifier of the property whose events are tracked. message Entity { - // A Google Analytics 4 (GA4) property id. + // A Google Analytics GA4 property id. To learn more, see [where to find your + // Property + // ID](https://developers.google.com/analytics/trusted-testing/analytics-data/property-id). string property_id = 1; } -// Dimensions are attributes of your data. For example, the dimension City -// indicates the city, for example, "Paris" or "New York", from which an event -// originates. Requests are allowed up to 8 dimensions. +// Dimensions are attributes of your data. For example, the dimension city +// indicates the city from which an event originates. Dimension values in report +// responses are strings; for example, city could be "Paris" or "New York". +// Requests are allowed up to 8 dimensions. message Dimension { - // The name of the dimension. + // The name of the dimension. See the [API + // Dimensions](https://developers.google.com/analytics/trusted-testing/analytics-data/api-schema#dimensions) + // for the list of dimension names. + // + // If `dimensionExpression` is specified, `name` can be any string that you + // would like. For example if a `dimensionExpression` concatenates `country` + // and `city`, you could call that dimension `countryAndCity`. + // + // Dimensions are referenced by `name` in `dimensionFilter`, `orderBys`, + // `dimensionExpression`, and `pivots`. string name = 1; // One dimension can be the result of an expression of multiple dimensions. @@ -104,19 +116,29 @@ message DimensionExpression { } } -// The quantitative measurements of a report. For example, the metric eventCount -// is the total number of events. Requests are allowed up to 10 metrics. +// The quantitative measurements of a report. For example, the metric +// `eventCount` is the total number of events. Requests are allowed up to 10 +// metrics. message Metric { - // The name of the metric. + // The name of the metric. See the [API + // Metrics](https://developers.google.com/analytics/trusted-testing/analytics-data/api-schema#metrics) + // for the list of metric names. + // + // If `expression` is specified, `name` can be any string that you would like. + // For example if `expression` is `screenPageViews/sessions`, you could call + // that metric's name = `viewsPerSession`. + // + // Metrics are referenced by `name` in `metricFilter`, `orderBys`, and metric + // `expression`. string name = 1; // A mathematical expression for derived metrics. For example, the metric - // Event count per user is eventCount/totalUsers. + // Event count per user is `eventCount/totalUsers`. string expression = 2; - // Indicates if a metric is invisible. - // If a metric is invisible, the metric is not in the response, but can be - // used in filters, order_bys or being referred to in a metric expression. + // Indicates if a metric is invisible in the report response. If a metric is + // invisible, the metric will not produce a column in the response, but can be + // used in `metricFilter`, `orderBys`, or a metric `expression`. bool invisible = 3; } @@ -241,7 +263,10 @@ message Filter { // Specify one type of filter for `Filter`. oneof one_filter { - // A filter for null values. + // A filter for null values. If True, a null dimension value is matched by + // this filter. Null filter is commonly used inside a NOT filter + // expression. For example, a NOT expression of a null filter removes rows + // when a dimension is null. bool null_filter = 2; // Strings related filter. @@ -502,28 +527,38 @@ message PivotDimensionHeader { // For example if RunReportRequest contains: // // ```none -// dimensions { -// name: "eventName" -// } -// dimensions { -// name: "countryId" -// } -// metrics { -// name: "eventCount" -// } +// "dimensions": [ +// { +// "name": "eventName" +// }, +// { +// "name": "countryId" +// } +// ], +// "metrics": [ +// { +// "name": "eventCount" +// } +// ] // ``` // -// One row with 'in_app_purchase' as the eventName, 'us' as the countryId, and +// One row with 'in_app_purchase' as the eventName, 'JP' as the countryId, and // 15 as the eventCount, would be: // // ```none -// dimension_values { -// name: 'in_app_purchase' -// name: 'us' -// } -// metric_values { -// int64_value: 15 -// } +// "dimensionValues": [ +// { +// "value": "in_app_purchase" +// }, +// { +// "value": "JP" +// } +// ], +// "metricValues": [ +// { +// "value": "15" +// } +// ] // ``` message Row { // List of requested dimension values. In a PivotReport, dimension_values @@ -568,20 +603,24 @@ message NumericValue { // property is exhausted, all requests to that property will return Resource // Exhausted errors. message PropertyQuota { - // Analytics Properties can use up to 25,000 tokens per day. Most requests + // Standard Analytics Properties can use up to 25,000 tokens per day; + // Analytics 360 Properties can use 250,000 tokens per day. Most requests // consume fewer than 10 tokens. QuotaStatus tokens_per_day = 1; - // Analytics Properties can use up to 5,000 tokens per day. An API request - // consumes a single number of tokens, and that number is deducted from both - // the hourly and daily quotas. + // Standard Analytics Properties can use up to 5,000 tokens per day; Analytics + // 360 Properties can use 50,000 tokens per day. An API request consumes a + // single number of tokens, and that number is deducted from both the hourly + // and daily quotas. QuotaStatus tokens_per_hour = 2; - // Analytics Properties can send up to 10 concurrent requests. + // Standard Analytics Properties can send up to 10 concurrent requests; + // Analytics 360 Properties can use up to 50 concurrent requests. QuotaStatus concurrent_requests = 3; - // Analytics Properties and cloud project pairs can have up to 10 - // server errors per hour. + // Standard Analytics Properties and cloud project pairs can have up to 10 + // server errors per hour; Analytics 360 Properties and cloud project pairs + // can have up to 50 server errors per hour. QuotaStatus server_errors_per_project_per_hour = 4; }