feat: add CreateRecurringAudienceList, GetRecurringAudienceList, ListRecurringAudienceLists methods to the Data API v1 alpha

Google APIs · copybara-github · commit 9ca4a254e367 · 2023-11-29T13:08:23.000-08:00
feat: add the `RecurringAudienceList` type
feat: add `percentage_completed`, `recurring_audience_list` fields to the `AudienceList` resource

PiperOrigin-RevId: 586431787
diff --git a/google/analytics/data/v1alpha/BUILD.bazel b/google/analytics/data/v1alpha/BUILD.bazel
@@ -322,6 +322,7 @@ load(
 
 csharp_proto_library(
     name = "data_csharp_proto",
+    extra_opts = [],
     deps = [":data_proto"],
 )
 
diff --git a/google/analytics/data/v1alpha/analytics_data_api.proto b/google/analytics/data/v1alpha/analytics_data_api.proto
@@ -201,6 +201,200 @@ service AlphaAnalyticsData {
     };
     option (google.api.method_signature) = "parent";
   }
+
+  // Creates a recurring audience list. Recurring audience lists produces new
+  // audience lists each day. Audience lists are users in an audience at the
+  // time of the list's creation.
+  //
+  // A recurring audience list ensures that you have audience list based on the
+  // most recent data available for use each day. If you manually create
+  // audience list, you don't know when an audience list based on an additional
+  // day's data is available. This recurring audience list automates the
+  // creation of an audience list when an additional day's data is available.
+  // You will consume fewer quota tokens by using recurring audience list versus
+  // manually creating audience list at various times of day trying to guess
+  // when an additional day's data is ready.
+  //
+  // 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 CreateRecurringAudienceList(CreateRecurringAudienceListRequest)
+      returns (RecurringAudienceList) {
+    option (google.api.http) = {
+      post: "/v1alpha/{parent=properties/*}/recurringAudienceLists"
+      body: "recurring_audience_list"
+    };
+    option (google.api.method_signature) = "parent,recurring_audience_list";
+  }
+
+  // Gets configuration metadata about a specific recurring audience list. This
+  // method can be used to understand a recurring audience list's state after it
+  // has been created. For example, a recurring audience list resource will
+  // generate audience list instances for each day, and this method can be used
+  // to get the resource name of the most recent audience list instance.
+  //
+  // 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 GetRecurringAudienceList(GetRecurringAudienceListRequest)
+      returns (RecurringAudienceList) {
+    option (google.api.http) = {
+      get: "/v1alpha/{name=properties/*/recurringAudienceLists/*}"
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Lists all recurring audience lists for a property. This method can be used
+  // for you to find and reuse existing recurring audience lists rather than
+  // creating unnecessary new recurring audience lists. The same audience can
+  // have multiple recurring audience lists that represent different dimension
+  // combinations; for example, just the dimension `deviceId` or both the
+  // dimensions `deviceId` and `userId`.
+  //
+  // 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 ListRecurringAudienceLists(ListRecurringAudienceListsRequest)
+      returns (ListRecurringAudienceListsResponse) {
+    option (google.api.http) = {
+      get: "/v1alpha/{parent=properties/*}/recurringAudienceLists"
+    };
+    option (google.api.method_signature) = "parent";
+  }
+}
+
+// A request to create a new recurring audience list.
+message CreateRecurringAudienceListRequest {
+  // Required. The parent resource where this recurring audience list will be
+  // created. Format: `properties/{property}`
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "analyticsdata.googleapis.com/RecurringAudienceList"
+    }
+  ];
+
+  // Required. The recurring audience list to create.
+  RecurringAudienceList recurring_audience_list = 2
+      [(google.api.field_behavior) = REQUIRED];
+}
+
+// A recurring audience list produces new audience lists each day. Audience
+// lists are users in an audience at the time of the list's creation. A
+// recurring audience list ensures that you have audience list based on the most
+// recent data available for use each day.
+message RecurringAudienceList {
+  option (google.api.resource) = {
+    type: "analyticsdata.googleapis.com/RecurringAudienceList"
+    pattern: "properties/{property}/recurringAudienceLists/{recurring_audience_list}"
+    plural: "recurringAudienceLists"
+    singular: "recurringAudienceList"
+  };
+
+  // Output only. Identifier. The recurring audience list resource name assigned
+  // during creation. This resource name identifies this
+  // `RecurringAudienceList`.
+  //
+  // Format:
+  // `properties/{property}/recurringAudienceLists/{recurring_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/{property}/audiences/{audience}`
+  string audience = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Output only. The descriptive display name for this audience. For example,
+  // "Purchasers".
+  string audience_display_name = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Required. The dimensions requested and displayed in the audience list
+  // response.
+  repeated AudienceDimension dimensions = 4
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. The number of remaining days that a recurring audience export
+  // will produce an audience list instance. This counter decreases by one each
+  // day, and when it reaches zero, no new audience lists will be created.
+  //
+  // Recurring audience list request for Analytics 360 properties default to 180
+  // days and have a maximum of 365 days. Requests for standard Analytics
+  // properties default to 14 days and have a maximum of 30 days.
+  //
+  // The minimum value allowed during creation is 1. Requests above their
+  // respective maximum will be coerced to their maximum.
+  optional int32 active_days_remaining = 5
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. Audience list resource names for audience list instances
+  // created for this recurring audience list. One audience list is created for
+  // each day, and the audience list will be listed here.
+  //
+  // This list is ordered with the most recently created audience list first.
+  repeated string audience_lists = 6
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+}
+
+// A request to retrieve configuration metadata about a specific recurring
+// audience list.
+message GetRecurringAudienceListRequest {
+  // Required. The recurring audience list resource name.
+  // Format:
+  // `properties/{property}/recurringAudienceLists/{recurring_audience_list}`
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "analyticsdata.googleapis.com/RecurringAudienceList"
+    }
+  ];
+}
+
+// A request to list all recurring audience lists for a property.
+message ListRecurringAudienceListsRequest {
+  // Required. All recurring audience lists for this property will be listed in
+  // the response. Format: `properties/{property}`
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      child_type: "analyticsdata.googleapis.com/RecurringAudienceList"
+    }
+  ];
+
+  // Optional. The maximum number of recurring audience lists to return. The
+  // service may return fewer than this value. If unspecified, at most 200
+  // recurring 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];
+
+  // Optional. A page token, received from a previous
+  // `ListRecurringAudienceLists` call. Provide this to retrieve the subsequent
+  // page.
+  //
+  // When paginating, all other parameters provided to
+  // `ListRecurringAudienceLists` must match the call that provided the page
+  // token.
+  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// A list of all recurring audience lists for a property.
+message ListRecurringAudienceListsResponse {
+  // Each recurring audience list for a property.
+  repeated RecurringAudienceList recurring_audience_lists = 1;
+
+  // A token, which can be sent as `page_token` to retrieve the next page.
+  // If this field is omitted, there are no subsequent pages.
+  optional string next_page_token = 2;
 }
 
 // A request to retrieve configuration metadata about a specific audience list.
@@ -315,7 +509,7 @@ message AudienceList {
   // "Purchasers".
   string audience_display_name = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Required. The dimensions requested and displayed in the report response.
+  // Required. The dimensions requested and displayed in the query response.
   repeated AudienceDimension dimensions = 4
       [(google.api.field_behavior) = REQUIRED];
 
@@ -340,6 +534,19 @@ message AudienceList {
   // 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];
+
+  // Output only. The percentage completed for this audience export ranging
+  // between 0 to 100.
+  optional double percentage_completed = 11
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The recurring audience list that created this audience list.
+  // Recurring audience lists create audience lists daily.
+  //
+  // If audience lists are created directly, they will have no associated
+  // recurring audience list, and this field will be blank.
+  optional string recurring_audience_list = 12
+      [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // This metadata is currently blank.

Original file line number	Diff line number	Diff line change
`@@ -322,6 +322,7 @@ load(`
`322`	`322`
`323`	`323`	`csharp_proto_library(`
`324`	`324`	`name = "data_csharp_proto",`
	`325`	`+ extra_opts = [],`
`325`	`326`	`deps = [":data_proto"],`
`326`	`327`	`)`
`327`	`328`