Skip to content

Commit 84f0429

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
docs: Bring comments and metadata up to date
feat: Deprecate the `Actor.email` field and add `username` to replace it feat: Annotate `Comment.plain_text_body` as deprecated (it was already deprecated, but now we're adding the annotation for it) PiperOrigin-RevId: 758717798
1 parent 64bf7d5 commit 84f0429

7 files changed

Lines changed: 562 additions & 114 deletions

File tree

‎google/cloud/support/v2/actor.proto‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,22 +26,31 @@ option java_package = "com.google.cloud.support.v2";
2626
option php_namespace = "Google\\Cloud\\Support\\V2";
2727
option ruby_package = "Google::Cloud::Support::V2";
2828

29-
// An object containing information about the effective user and
30-
// authenticated principal responsible for an action.
29+
// An Actor represents an entity that performed an action. For example, an actor
30+
// could be a user who posted a comment on a support case, a user who
31+
// uploaded an attachment, or a service account that created a support case.
3132
message Actor {
3233
// The name to display for the actor. If not provided, it is inferred from
3334
// credentials supplied during case creation. When an email is provided, a
3435
// display name must also be provided. This will be obfuscated if the user
3536
// is a Google Support agent.
3637
string display_name = 1;
3738

38-
// The email address of the actor. If not provided, it is inferred from
39-
// credentials supplied during case creation. If the authenticated principal
40-
// does not have an email address, one must be provided. When a name is
41-
// provided, an email must also be provided. This will be obfuscated if the
42-
// user is a Google Support agent.
43-
string email = 2;
39+
// The email address of the actor. If not provided, it is inferred from the
40+
// credentials supplied during case creation. When a name is provided, an
41+
// email must also be provided. If the user is a Google Support agent, this is
42+
// obfuscated.
43+
//
44+
// This field is deprecated. Use **username** field instead.
45+
string email = 2 [deprecated = true];
4446

4547
// Output only. Whether the actor is a Google support actor.
4648
bool google_support = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
49+
50+
// Output only. The username of the actor. It may look like an email or other
51+
// format provided by the identity provider. If not provided, it is inferred
52+
// from the credentials supplied. When a name is provided, a username must
53+
// also be provided. If the user is a Google Support agent, this will not be
54+
// set.
55+
string username = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
4756
}

‎google/cloud/support/v2/attachment.proto‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,14 @@ option java_package = "com.google.cloud.support.v2";
2929
option php_namespace = "Google\\Cloud\\Support\\V2";
3030
option ruby_package = "Google::Cloud::Support::V2";
3131

32-
// Represents a file attached to a support case.
32+
// An Attachment contains metadata about a file that was uploaded to a
33+
// case - it is NOT a file itself. That being said, the name of an Attachment
34+
// object can be used to download its accompanying file through the
35+
// `media.download` endpoint.
36+
//
37+
// While attachments can be uploaded in the console at the
38+
// same time as a comment, they're associated on a "case" level, not a
39+
// "comment" level.
3340
message Attachment {
3441
option (google.api.resource) = {
3542
type: "cloudsupport.googleapis.com/Attachment"

‎google/cloud/support/v2/attachment_service.proto‎

Lines changed: 45 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,43 @@ option java_package = "com.google.cloud.support.v2";
3030
option php_namespace = "Google\\Cloud\\Support\\V2";
3131
option ruby_package = "Google::Cloud::Support::V2";
3232

33-
// A service to manage file attachment for Google Cloud support cases.
33+
// A service to manage file attachments for Google Cloud support cases.
3434
service CaseAttachmentService {
3535
option (google.api.default_host) = "cloudsupport.googleapis.com";
3636
option (google.api.oauth_scopes) =
3737
"https://www.googleapis.com/auth/cloud-platform";
3838

39-
// Retrieve all attachments associated with a support case.
39+
// List all the attachments associated with a support case.
40+
//
41+
// EXAMPLES:
42+
//
43+
// cURL:
44+
//
45+
// ```shell
46+
// case="projects/some-project/cases/23598314"
47+
// curl \
48+
// --header "Authorization: Bearer $(gcloud auth print-access-token)" \
49+
// "https://cloudsupport.googleapis.com/v2/$case/attachments"
50+
// ```
51+
//
52+
// Python:
53+
//
54+
// ```python
55+
// import googleapiclient.discovery
56+
//
57+
// api_version = "v2"
58+
// supportApiService = googleapiclient.discovery.build(
59+
// serviceName="cloudsupport",
60+
// version=api_version,
61+
// discoveryServiceUrl=f"https://cloudsupport.googleapis.com/$discovery/rest?version={api_version}",
62+
// )
63+
// request = (
64+
// supportApiService.cases()
65+
// .attachments()
66+
// .list(parent="projects/some-project/cases/43595344")
67+
// )
68+
// print(request.execute())
69+
// ```
4070
rpc ListAttachments(ListAttachmentsRequest)
4171
returns (ListAttachmentsResponse) {
4272
option (google.api.http) = {
@@ -51,18 +81,22 @@ service CaseAttachmentService {
5181

5282
// The request message for the ListAttachments endpoint.
5383
message ListAttachmentsRequest {
54-
// Required. The resource name of Case object for which attachments should be
55-
// listed.
84+
// Required. The name of the case for which attachments should be listed.
5685
string parent = 1 [
5786
(google.api.field_behavior) = REQUIRED,
5887
(google.api.resource_reference) = {
5988
type: "cloudsupport.googleapis.com/Case"
6089
}
6190
];
6291

63-
// The maximum number of attachments fetched with each request. If not
64-
// provided, the default is 10. The maximum page size that will be returned is
65-
// 100.
92+
// The maximum number of attachments fetched with each request.
93+
//
94+
// If not provided, the default is 10. The maximum page size that will be
95+
// returned is 100.
96+
//
97+
// The size of each page can be smaller than the requested page size and can
98+
// include zero. For example, you could request 100 attachments on one page,
99+
// receive 0, and then on the next page, receive 90.
66100
int32 page_size = 2;
67101

68102
// A token identifying the page of results to return. If unspecified, the
@@ -72,11 +106,11 @@ message ListAttachmentsRequest {
72106

73107
// The response message for the ListAttachments endpoint.
74108
message ListAttachmentsResponse {
75-
// The list of attachments associated with the given case.
109+
// The list of attachments associated with a case.
76110
repeated Attachment attachments = 1;
77111

78-
// A token to retrieve the next page of results. This should be set in the
79-
// `page_token` field of subsequent `cases.attachments.list` requests. If
80-
// unspecified, there are no more results to retrieve.
112+
// A token to retrieve the next page of results. Set this in the `page_token`
113+
// field of subsequent `cases.attachments.list` requests. If unspecified,
114+
// there are no more results to retrieve.
81115
string next_page_token = 2;
82116
}

‎google/cloud/support/v2/case.proto‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,33 @@ option java_package = "com.google.cloud.support.v2";
2929
option php_namespace = "Google\\Cloud\\Support\\V2";
3030
option ruby_package = "Google::Cloud::Support::V2";
3131

32-
// A support case.
32+
// A Case is an object that contains the details of a support case. It
33+
// contains fields for the time it was created, its priority, its
34+
// classification, and more. Cases can also have comments and attachments that
35+
// get added over time.
36+
//
37+
// A case is parented by a Google Cloud organization or project.
38+
//
39+
// Organizations are identified by a number, so the name of a case parented by
40+
// an organization would look like this:
41+
//
42+
// ```
43+
// organizations/123/cases/456
44+
// ```
45+
//
46+
// Projects have two unique identifiers, an ID and a number, and they look like
47+
// this:
48+
//
49+
// ```
50+
// projects/abc/cases/456
51+
// ```
52+
//
53+
// ```
54+
// projects/123/cases/456
55+
// ```
56+
//
57+
// You can use either of them when calling the API. To learn more
58+
// about project identifiers, see [AIP-2510](https://google.aip.dev/cloud/2510).
3359
message Case {
3460
option (google.api.resource) = {
3561
type: "cloudsupport.googleapis.com/Case"
@@ -145,14 +171,27 @@ message Case {
145171
Priority priority = 32;
146172
}
147173

148-
// A classification object with a product type and value.
174+
// A Case Classification represents the topic that a case is about. It's very
175+
// important to use accurate classifications, because they're
176+
// used to route your cases to specialists who can help you.
177+
//
178+
// A classification always has an ID that is its unique identifier.
179+
// A valid ID is required when creating a case.
149180
message CaseClassification {
150181
// The unique ID for a classification. Must be specified for case creation.
151182
//
152183
// To retrieve valid classification IDs for case creation, use
153184
// `caseClassifications.search`.
185+
//
186+
// Classification IDs returned by `caseClassifications.search` are guaranteed
187+
// to be valid for at least 6 months. If a given classification is
188+
// deactiveated, it will immediately stop being returned. After 6 months,
189+
// `case.create` requests using the classification ID will fail.
154190
string id = 3;
155191

156-
// The display name of the classification.
192+
// A display name for the classification.
193+
//
194+
// The display name is not static and can change. To uniquely and consistently
195+
// identify classifications, use the `CaseClassification.id` field.
157196
string display_name = 4;
158197
}

0 commit comments

Comments
 (0)