@google-analytics/data 2.6.0 → 3.0.0

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

@@ -104,6 +104,71 @@ service BetaAnalyticsData {
       body: "*"
     };
   }
+
+  // This compatibility method lists dimensions and metrics that can be added to
+  // a report request and maintain compatibility. This method fails if the
+  // request's dimensions and metrics are incompatible.
+  //
+  // In Google Analytics, reports fail if they request incompatible dimensions
+  // and/or metrics; in that case, you will need to remove dimensions and/or
+  // metrics from the incompatible report until the report is compatible.
+  //
+  // The Realtime and Core reports have different compatibility rules. This
+  // method checks compatibility for Core reports.
+  rpc CheckCompatibility(CheckCompatibilityRequest) returns (CheckCompatibilityResponse) {
+    option (google.api.http) = {
+      post: "/v1beta/{property=properties/*}:checkCompatibility"
+      body: "*"
+    };
+  }
+}
+
+// The request for compatibility information for a report's dimensions and
+// metrics. Check compatibility provides a preview of the compatibility of a
+// report; fields shared with the `runReport` request should be the same values
+// as in your `runReport` request.
+message CheckCompatibilityRequest {
+  // A Google Analytics GA4 property identifier whose events are tracked. To
+  // learn more, see [where to find your Property
+  // ID](https://developers.google.com/analytics/devguides/reporting/data/v1/property-id).
+  // `property` should be the same value as in your `runReport` request.
+  //
+  // Example: properties/1234
+  //
+  // Set the Property ID to 0 for compatibility checking on dimensions and
+  // metrics common to all properties. In this special mode, this method will
+  // not return custom dimensions and metrics.
+  string property = 1;
+
+  // The dimensions in this report. `dimensions` should be the same value as in
+  // your `runReport` request.
+  repeated Dimension dimensions = 2;
+
+  // The metrics in this report. `metrics` should be the same value as in your
+  // `runReport` request.
+  repeated Metric metrics = 3;
+
+  // The filter clause of dimensions. `dimensionFilter` should be the same value
+  // as in your `runReport` request.
+  FilterExpression dimension_filter = 4;
+
+  // The filter clause of metrics. `metricFilter` should be the same value as in
+  // your `runReport` request
+  FilterExpression metric_filter = 5;
+
+  // Filters the dimensions and metrics in the response to just this
+  // compatibility. Commonly used as `”compatibilityFilter”: “COMPATIBLE”`
+  // to only return compatible dimensions & metrics.
+  Compatibility compatibility_filter = 6;
+}
+
+// The compatibility response with the compatibility of each dimension & metric.
+message CheckCompatibilityResponse {
+  // The compatibility of each dimension.
+  repeated DimensionCompatibility dimension_compatibilities = 1;
+
+  // The compatibility of each metric.
+  repeated MetricCompatibility metric_compatibilities = 2;
 }
 
 // The dimensions and metrics currently accepted in reporting methods.
@@ -148,13 +213,14 @@ message RunReportRequest {
   // must be unspecified.
   repeated DateRange date_ranges = 4;
 
-  // The filter clause of dimensions. Dimensions must be requested to be used in
-  // this filter. Metrics cannot be used in this filter.
+  // Dimension filters allow you to ask for only specific dimension values in
+  // the report. To learn more, see [Fundamentals of 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 = 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.
+  // SQL having-clause. Dimensions cannot be used in this filter.
   FilterExpression metric_filter = 6;
 
   // The row count of the start row. The first row is counted as row 0.

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

@@ -52,8 +52,8 @@ message MinuteRange {
   //
   // If unspecified, `startMinutesAgo` is defaulted to 29. Standard Analytics
   // properties can request up to the last 30 minutes of event data
-  // (`startMinutesAgo <= 29`), and 360 Analytics properties can request up to
-  // the last 60 minutes of event data (`startMinutesAgo <= 59`).
+  // (`startMinutesAgo <= 29`), and Google Analytics 360 properties can request
+  // up to the last 60 minutes of event data (`startMinutesAgo <= 59`).
   optional int32 start_minutes_ago = 1;
 
   // The inclusive end minute for the query as a number of minutes before now.
@@ -63,8 +63,8 @@ message MinuteRange {
   //
   // If unspecified, `endMinutesAgo` is defaulted to 0. Standard Analytics
   // properties can request any minute in the last 30 minutes of event data
-  // (`endMinutesAgo <= 29`), and 360 Analytics properties can request any
-  // minute in the last 60 minutes of event data (`endMinutesAgo <= 59`).
+  // (`endMinutesAgo <= 29`), and Google Analytics 360 properties can request
+  // any minute in the last 60 minutes of event data (`endMinutesAgo <= 59`).
   optional int32 end_minutes_ago = 2;
 
   // Assigns a name to this minute range. The dimension `dateRange` is valued to
@@ -87,7 +87,7 @@ message Dimension {
   // would like within the allowed character set. For example if a
   // `dimensionExpression` concatenates `country` and `city`, you could call
   // that dimension `countryAndCity`. Dimension names that you choose must match
-  // the regular expression "^[a-zA-Z0-9_]$".
+  // the regular expression `^[a-zA-Z0-9_]$`.
   //
   // Dimensions are referenced by `name` in `dimensionFilter`, `orderBys`,
   // `dimensionExpression`, and `pivots`.
@@ -152,7 +152,7 @@ message Metric {
   // within the allowed character set. For example if `expression` is
   // `screenPageViews/sessions`, you could call that metric's name =
   // `viewsPerSession`. Metric names that you choose must match the regular
-  // expression "^[a-zA-Z0-9_]$".
+  // expression `^[a-zA-Z0-9_]$`.
   //
   // Metrics are referenced by `name` in `metricFilter`, `orderBys`, and metric
   // `expression`.
@@ -555,9 +555,55 @@ message CohortReportSettings {
 
 // Response's metadata carrying additional information about the report content.
 message ResponseMetaData {
+  // The schema restrictions actively enforced in creating this report. To learn
+  // more, see [Access and data-restriction
+  // management](https://support.google.com/analytics/answer/10851388).
+  message SchemaRestrictionResponse {
+    // A metric actively restricted in creating the report.
+    message ActiveMetricRestriction {
+      // The name of the restricted metric.
+      optional string metric_name = 1;
+
+      // The reason for this metric's restriction.
+      repeated RestrictedMetricType restricted_metric_types = 2;
+    }
+
+    // All restrictions actively enforced in creating the report. For example,
+    // `purchaseRevenue` always has the restriction type `REVENUE_DATA`.
+    // However, this active response restriction is only populated if the user's
+    // custom role disallows access to `REVENUE_DATA`.
+    repeated ActiveMetricRestriction active_metric_restrictions = 1;
+  }
+
   // If true, indicates some buckets of dimension combinations are rolled into
   // "(other)" row. This can happen for high cardinality reports.
   bool data_loss_from_other_row = 3;
+
+  // Describes the schema restrictions actively enforced in creating this
+  // report. To learn more, see [Access and data-restriction
+  // management](https://support.google.com/analytics/answer/10851388).
+  optional SchemaRestrictionResponse schema_restriction_response = 4;
+
+  // The currency code used in this report. Intended to be used in formatting
+  // currency metrics like `purchaseRevenue` for visualization. If currency_code
+  // was specified in the request, this response parameter will echo the request
+  // parameter; otherwise, this response parameter is the property's current
+  // currency_code.
+  //
+  // Currency codes are string encodings of currency types from the ISO 4217
+  // standard (https://en.wikipedia.org/wiki/ISO_4217); for example "USD",
+  // "EUR", "JPY". To learn more, see
+  // https://support.google.com/analytics/answer/9796179.
+  optional string currency_code = 5;
+
+  // The property's current timezone. Intended to be used to interpret
+  // time-based dimensions like `hour` and `minute`. Formatted as strings from
+  // the IANA Time Zone database (https://www.iana.org/time-zones); for example
+  // "America/New_York" or "Asia/Tokyo".
+  optional string time_zone = 6;
+
+  // If empty reason is specified, the report is empty for this reason.
+  optional string empty_reason = 7;
 }
 
 // Describes a dimension column in the report. Dimensions requested in a report
@@ -736,10 +782,28 @@ message DimensionMetadata {
 
   // True if the dimension is a custom dimension for this property.
   bool custom_definition = 5;
+
+  // The display name of the category that this dimension belongs to. Similar
+  // dimensions and metrics are categorized together.
+  string category = 7;
 }
 
 // Explains a metric.
 message MetricMetadata {
+  // Justifications for why this metric is blocked.
+  enum BlockedReason {
+    // Will never be specified in API response.
+    BLOCKED_REASON_UNSPECIFIED = 0;
+
+    // If present, your access is blocked to revenue related metrics for this
+    // property, and this metric is revenue related.
+    NO_REVENUE_METRICS = 1;
+
+    // If present, your access is blocked to cost related metrics for this
+    // property, and this metric is cost related.
+    NO_COST_METRICS = 2;
+  }
+
   // A metric name. Useable in [Metric](#Metric)'s `name`. For example,
   // `eventCount`.
   string api_name = 1;
@@ -767,6 +831,44 @@ message MetricMetadata {
 
   // True if the metric is a custom metric for this property.
   bool custom_definition = 7;
+
+  // If reasons are specified, your access is blocked to this metric for this
+  // property. API requests from you to this property for this metric will
+  // succeed; however, the report will contain only zeros for this metric. API
+  // requests with metric filters on blocked metrics will fail. If reasons are
+  // empty, you have access to this metric.
+  //
+  // To learn more, see [Access and data-restriction
+  // management](https://support.google.com/analytics/answer/10851388).
+  repeated BlockedReason blocked_reasons = 8;
+
+  // The display name of the category that this metrics belongs to. Similar
+  // dimensions and metrics are categorized together.
+  string category = 10;
+}
+
+// The compatibility for a single dimension.
+message DimensionCompatibility {
+  // The dimension metadata contains the API name for this compatibility
+  // information. The dimension metadata also contains other helpful information
+  // like the UI name and description.
+  optional DimensionMetadata dimension_metadata = 1;
+
+  // The compatibility of this dimension. If the compatibility is COMPATIBLE,
+  // this dimension can be successfully added to the report.
+  optional Compatibility compatibility = 2;
+}
+
+// The compatibility for a single metric.
+message MetricCompatibility {
+  // The metric metadata contains the API name for this compatibility
+  // information. The metric metadata also contains other helpful information
+  // like the UI name and description.
+  optional MetricMetadata metric_metadata = 1;
+
+  // The compatibility of this metric. If the compatibility is COMPATIBLE,
+  // this metric can be successfully added to the report.
+  optional Compatibility compatibility = 2;
 }
 
 // Represents aggregation of metrics.
@@ -828,3 +930,30 @@ enum MetricType {
   // A length in kilometers; a special floating point type.
   TYPE_KILOMETERS = 13;
 }
+
+// Categories of data that you may be restricted from viewing on certain GA4
+// properties.
+enum RestrictedMetricType {
+  // Unspecified type.
+  RESTRICTED_METRIC_TYPE_UNSPECIFIED = 0;
+
+  // Cost metrics such as `adCost`.
+  COST_DATA = 1;
+
+  // Revenue metrics such as `purchaseRevenue`.
+  REVENUE_DATA = 2;
+}
+
+// The compatibility types for a single dimension or metric.
+enum Compatibility {
+  // Unspecified compatibility.
+  COMPATIBILITY_UNSPECIFIED = 0;
+
+  // The dimension or metric is compatible. This dimension or metric can be
+  // successfully added to a report.
+  COMPATIBLE = 1;
+
+  // The dimension or metric is incompatible. This dimension or metric cannot be
+  // successfully added to a report.
+  INCOMPATIBLE = 2;
+}