1// Copyright 2023 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.talent.v4;
18
19import "google/api/annotations.proto";
20import "google/api/client.proto";
21import "google/api/field_behavior.proto";
22import "google/api/resource.proto";
23import "google/cloud/talent/v4/common.proto";
24import "google/cloud/talent/v4/company.proto";
25import "google/protobuf/empty.proto";
26import "google/protobuf/field_mask.proto";
27
28option go_package = "cloud.google.com/go/talent/apiv4/talentpb;talentpb";
29option java_multiple_files = true;
30option java_outer_classname = "CompanyServiceProto";
31option java_package = "com.google.cloud.talent.v4";
32option objc_class_prefix = "CTS";
33
34// A service that handles company management, including CRUD and enumeration.
35service CompanyService {
36  option (google.api.default_host) = "jobs.googleapis.com";
37  option (google.api.oauth_scopes) =
38      "https://www.googleapis.com/auth/cloud-platform,"
39      "https://www.googleapis.com/auth/jobs";
40
41  // Creates a new company entity.
42  rpc CreateCompany(CreateCompanyRequest) returns (Company) {
43    option (google.api.http) = {
44      post: "/v4/{parent=projects/*/tenants/*}/companies"
45      body: "company"
46    };
47    option (google.api.method_signature) = "parent,company";
48  }
49
50  // Retrieves specified company.
51  rpc GetCompany(GetCompanyRequest) returns (Company) {
52    option (google.api.http) = {
53      get: "/v4/{name=projects/*/tenants/*/companies/*}"
54    };
55    option (google.api.method_signature) = "name";
56  }
57
58  // Updates specified company.
59  rpc UpdateCompany(UpdateCompanyRequest) returns (Company) {
60    option (google.api.http) = {
61      patch: "/v4/{company.name=projects/*/tenants/*/companies/*}"
62      body: "company"
63    };
64    option (google.api.method_signature) = "company,update_mask";
65  }
66
67  // Deletes specified company.
68  // Prerequisite: The company has no jobs associated with it.
69  rpc DeleteCompany(DeleteCompanyRequest) returns (google.protobuf.Empty) {
70    option (google.api.http) = {
71      delete: "/v4/{name=projects/*/tenants/*/companies/*}"
72    };
73    option (google.api.method_signature) = "name";
74  }
75
76  // Lists all companies associated with the project.
77  rpc ListCompanies(ListCompaniesRequest) returns (ListCompaniesResponse) {
78    option (google.api.http) = {
79      get: "/v4/{parent=projects/*/tenants/*}/companies"
80    };
81    option (google.api.method_signature) = "parent";
82  }
83}
84
85// The Request of the CreateCompany method.
86message CreateCompanyRequest {
87  // Required. Resource name of the tenant under which the company is created.
88  //
89  // The format is "projects/{project_id}/tenants/{tenant_id}", for example,
90  // "projects/foo/tenants/bar".
91  string parent = 1 [
92    (google.api.field_behavior) = REQUIRED,
93    (google.api.resource_reference) = { type: "jobs.googleapis.com/Tenant" }
94  ];
95
96  // Required. The company to be created.
97  Company company = 2 [(google.api.field_behavior) = REQUIRED];
98}
99
100// Request for getting a company by name.
101message GetCompanyRequest {
102  // Required. The resource name of the company to be retrieved.
103  //
104  // The format is
105  // "projects/{project_id}/tenants/{tenant_id}/companies/{company_id}", for
106  // example, "projects/api-test-project/tenants/foo/companies/bar".
107  string name = 1 [
108    (google.api.field_behavior) = REQUIRED,
109    (google.api.resource_reference) = { type: "jobs.googleapis.com/Company" }
110  ];
111}
112
113// Request for updating a specified company.
114message UpdateCompanyRequest {
115  // Required. The company resource to replace the current resource in the
116  // system.
117  Company company = 1 [(google.api.field_behavior) = REQUIRED];
118
119  // Strongly recommended for the best service experience.
120  //
121  // If [update_mask][google.cloud.talent.v4.UpdateCompanyRequest.update_mask]
122  // is provided, only the specified fields in
123  // [company][google.cloud.talent.v4.UpdateCompanyRequest.company] are updated.
124  // Otherwise all the fields are updated.
125  //
126  // A field mask to specify the company fields to be updated. Only
127  // top level fields of [Company][google.cloud.talent.v4.Company] are
128  // supported.
129  google.protobuf.FieldMask update_mask = 2;
130}
131
132// Request to delete a company.
133message DeleteCompanyRequest {
134  // Required. The resource name of the company to be deleted.
135  //
136  // The format is
137  // "projects/{project_id}/tenants/{tenant_id}/companies/{company_id}", for
138  // example, "projects/foo/tenants/bar/companies/baz".
139  string name = 1 [
140    (google.api.field_behavior) = REQUIRED,
141    (google.api.resource_reference) = { type: "jobs.googleapis.com/Company" }
142  ];
143}
144
145// List companies for which the client has ACL visibility.
146message ListCompaniesRequest {
147  // Required. Resource name of the tenant under which the company is created.
148  //
149  // The format is "projects/{project_id}/tenants/{tenant_id}", for example,
150  // "projects/foo/tenants/bar".
151  string parent = 1 [
152    (google.api.field_behavior) = REQUIRED,
153    (google.api.resource_reference) = { type: "jobs.googleapis.com/Tenant" }
154  ];
155
156  // The starting indicator from which to return results.
157  string page_token = 2;
158
159  // The maximum number of companies to be returned, at most 100.
160  // Default is 100 if a non-positive number is provided.
161  int32 page_size = 3;
162
163  // Set to true if the companies requested must have open jobs.
164  //
165  // Defaults to false.
166  //
167  // If true, at most
168  // [page_size][google.cloud.talent.v4.ListCompaniesRequest.page_size] of
169  // companies are fetched, among which only those with open jobs are returned.
170  bool require_open_jobs = 4;
171}
172
173// The List companies response object.
174message ListCompaniesResponse {
175  // Companies for the current client.
176  repeated Company companies = 1;
177
178  // A token to retrieve the next page of results.
179  string next_page_token = 2;
180
181  // Additional information for the API invocation, such as the request
182  // tracking id.
183  ResponseMetadata metadata = 3;
184}
185