Skip to content

Commit

Permalink
feat: added RunRealtimeReport method that returns a customized report…
Browse files Browse the repository at this point in the history 
… of realtime event data for a GA4 property

docs: minor documentation updates

PiperOrigin-RevId: 340463146
  • Loading branch information
Google APIs authored and Copybara-Service committed Nov 3, 2020
1 parent c570f55 commit 705962b
Show file tree
Hide file tree
Showing 2 changed files with 160 additions and 38 deletions.
85 changes: 84 additions & 1 deletion google/analytics/data/v1alpha/analytics_data_api.proto
View file
Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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;
}
113 changes: 76 additions & 37 deletions google/analytics/data/v1alpha/data.proto
View file
Expand Up @@ -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.
Expand Down Expand Up @@ -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;
}

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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;
}

Expand Down

0 comments on commit 705962b

Please sign in to comment.