google_cloud_orgpolicy_v2/client.rs
1// Copyright 2025 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// https://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//
15// Code generated by sidekick. DO NOT EDIT.
16#![allow(rustdoc::redundant_explicit_links)]
17#![allow(rustdoc::broken_intra_doc_links)]
18
19/// Implements a client for the Organization Policy API.
20///
21/// # Example
22/// ```
23/// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
24/// use google_cloud_gax::paginator::ItemPaginator as _;
25/// async fn sample(
26/// project_id: &str,
27/// ) -> anyhow::Result<()> {
28/// let client = OrgPolicy::builder().build().await?;
29/// let mut list = client.list_constraints()
30/// .set_parent(format!("projects/{project_id}"))
31/// .by_item();
32/// while let Some(item) = list.next().await.transpose()? {
33/// println!("{:?}", item);
34/// }
35/// Ok(())
36/// }
37/// ```
38///
39/// # Service Description
40///
41/// An interface for managing organization policies.
42///
43/// The Organization Policy Service provides a simple mechanism for
44/// organizations to restrict the allowed configurations across their entire
45/// resource hierarchy.
46///
47/// You can use a policy to configure restrictions on resources. For
48/// example, you can enforce a policy that restricts which Google
49/// Cloud APIs can be activated in a certain part of your resource
50/// hierarchy, or prevents serial port access to VM instances in a
51/// particular folder.
52///
53/// Policies are inherited down through the resource hierarchy. A policy
54/// applied to a parent resource automatically applies to all its child resources
55/// unless overridden with a policy lower in the hierarchy.
56///
57/// A constraint defines an aspect of a resource's configuration that can be
58/// controlled by an organization's policy administrator. Policies are a
59/// collection of constraints that defines their allowable configuration on a
60/// particular resource and its child resources.
61///
62/// # Configuration
63///
64/// To configure `OrgPolicy` use the `with_*` methods in the type returned
65/// by [builder()][OrgPolicy::builder]. The default configuration should
66/// work for most applications. Common configuration changes include
67///
68/// * [with_endpoint()]: by default this client uses the global default endpoint
69/// (`https://orgpolicy.googleapis.com`). Applications using regional
70/// endpoints or running in restricted networks (e.g. a network configured
71// with [Private Google Access with VPC Service Controls]) may want to
72/// override this default.
73/// * [with_credentials()]: by default this client uses
74/// [Application Default Credentials]. Applications using custom
75/// authentication may need to override this default.
76///
77/// [with_endpoint()]: super::builder::org_policy::ClientBuilder::with_endpoint
78/// [with_credentials()]: super::builder::org_policy::ClientBuilder::with_credentials
79/// [Private Google Access with VPC Service Controls]: https://cloud.google.com/vpc-service-controls/docs/private-connectivity
80/// [Application Default Credentials]: https://cloud.google.com/docs/authentication#adc
81///
82/// # Pooling and Cloning
83///
84/// `OrgPolicy` holds a connection pool internally, it is advised to
85/// create one and reuse it. You do not need to wrap `OrgPolicy` in
86/// an [Rc](std::rc::Rc) or [Arc](std::sync::Arc) to reuse it, because it
87/// already uses an `Arc` internally.
88#[derive(Clone, Debug)]
89pub struct OrgPolicy {
90 inner: std::sync::Arc<dyn super::stub::dynamic::OrgPolicy>,
91}
92
93impl OrgPolicy {
94 /// Returns a builder for [OrgPolicy].
95 ///
96 /// ```
97 /// # async fn sample() -> google_cloud_gax::client_builder::Result<()> {
98 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
99 /// let client = OrgPolicy::builder().build().await?;
100 /// # Ok(()) }
101 /// ```
102 pub fn builder() -> super::builder::org_policy::ClientBuilder {
103 crate::new_client_builder(super::builder::org_policy::client::Factory)
104 }
105
106 /// Creates a new client from the provided stub.
107 ///
108 /// The most common case for calling this function is in tests mocking the
109 /// client's behavior.
110 pub fn from_stub<T>(stub: impl Into<std::sync::Arc<T>>) -> Self
111 where
112 T: super::stub::OrgPolicy + 'static,
113 {
114 Self { inner: stub.into() }
115 }
116
117 pub(crate) async fn new(
118 config: gaxi::options::ClientConfig,
119 ) -> crate::ClientBuilderResult<Self> {
120 let inner = Self::build_inner(config).await?;
121 Ok(Self { inner })
122 }
123
124 async fn build_inner(
125 conf: gaxi::options::ClientConfig,
126 ) -> crate::ClientBuilderResult<std::sync::Arc<dyn super::stub::dynamic::OrgPolicy>> {
127 if gaxi::options::tracing_enabled(&conf) {
128 return Ok(std::sync::Arc::new(Self::build_with_tracing(conf).await?));
129 }
130 Ok(std::sync::Arc::new(Self::build_transport(conf).await?))
131 }
132
133 async fn build_transport(
134 conf: gaxi::options::ClientConfig,
135 ) -> crate::ClientBuilderResult<impl super::stub::OrgPolicy> {
136 super::transport::OrgPolicy::new(conf).await
137 }
138
139 async fn build_with_tracing(
140 conf: gaxi::options::ClientConfig,
141 ) -> crate::ClientBuilderResult<impl super::stub::OrgPolicy> {
142 Self::build_transport(conf)
143 .await
144 .map(super::tracing::OrgPolicy::new)
145 }
146
147 /// Lists constraints that could be applied on the specified resource.
148 ///
149 /// # Example
150 /// ```
151 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
152 /// use google_cloud_gax::paginator::ItemPaginator as _;
153 /// use google_cloud_orgpolicy_v2::Result;
154 /// async fn sample(
155 /// client: &OrgPolicy, project_id: &str
156 /// ) -> Result<()> {
157 /// let mut list = client.list_constraints()
158 /// .set_parent(format!("projects/{project_id}"))
159 /// .by_item();
160 /// while let Some(item) = list.next().await.transpose()? {
161 /// println!("{:?}", item);
162 /// }
163 /// Ok(())
164 /// }
165 /// ```
166 pub fn list_constraints(&self) -> super::builder::org_policy::ListConstraints {
167 super::builder::org_policy::ListConstraints::new(self.inner.clone())
168 }
169
170 /// Retrieves all of the policies that exist on a particular resource.
171 ///
172 /// # Example
173 /// ```
174 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
175 /// use google_cloud_gax::paginator::ItemPaginator as _;
176 /// use google_cloud_orgpolicy_v2::Result;
177 /// async fn sample(
178 /// client: &OrgPolicy, project_id: &str
179 /// ) -> Result<()> {
180 /// let mut list = client.list_policies()
181 /// .set_parent(format!("projects/{project_id}"))
182 /// .by_item();
183 /// while let Some(item) = list.next().await.transpose()? {
184 /// println!("{:?}", item);
185 /// }
186 /// Ok(())
187 /// }
188 /// ```
189 pub fn list_policies(&self) -> super::builder::org_policy::ListPolicies {
190 super::builder::org_policy::ListPolicies::new(self.inner.clone())
191 }
192
193 /// Gets a policy on a resource.
194 ///
195 /// If no policy is set on the resource, `NOT_FOUND` is returned. The
196 /// `etag` value can be used with `UpdatePolicy()` to update a
197 /// policy during read-modify-write.
198 ///
199 /// # Example
200 /// ```
201 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
202 /// use google_cloud_orgpolicy_v2::Result;
203 /// async fn sample(
204 /// client: &OrgPolicy, project_id: &str, policy_id: &str
205 /// ) -> Result<()> {
206 /// let response = client.get_policy()
207 /// .set_name(format!("projects/{project_id}/policies/{policy_id}"))
208 /// .send().await?;
209 /// println!("response {:?}", response);
210 /// Ok(())
211 /// }
212 /// ```
213 pub fn get_policy(&self) -> super::builder::org_policy::GetPolicy {
214 super::builder::org_policy::GetPolicy::new(self.inner.clone())
215 }
216
217 /// Gets the effective policy on a resource. This is the result of merging
218 /// policies in the resource hierarchy and evaluating conditions. The
219 /// returned policy will not have an `etag` or `condition` set because it is
220 /// an evaluated policy across multiple resources.
221 /// Subtrees of Resource Manager resource hierarchy with 'under:' prefix will
222 /// not be expanded.
223 ///
224 /// # Example
225 /// ```
226 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
227 /// use google_cloud_orgpolicy_v2::Result;
228 /// async fn sample(
229 /// client: &OrgPolicy, project_id: &str, policy_id: &str
230 /// ) -> Result<()> {
231 /// let response = client.get_effective_policy()
232 /// .set_name(format!("projects/{project_id}/policies/{policy_id}"))
233 /// .send().await?;
234 /// println!("response {:?}", response);
235 /// Ok(())
236 /// }
237 /// ```
238 pub fn get_effective_policy(&self) -> super::builder::org_policy::GetEffectivePolicy {
239 super::builder::org_policy::GetEffectivePolicy::new(self.inner.clone())
240 }
241
242 /// Creates a policy.
243 ///
244 /// Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
245 /// constraint does not exist.
246 /// Returns a `google.rpc.Status` with `google.rpc.Code.ALREADY_EXISTS` if the
247 /// policy already exists on the given Google Cloud resource.
248 ///
249 /// # Example
250 /// ```
251 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
252 /// use google_cloud_orgpolicy_v2::model::Policy;
253 /// use google_cloud_orgpolicy_v2::Result;
254 /// async fn sample(
255 /// client: &OrgPolicy, project_id: &str
256 /// ) -> Result<()> {
257 /// let response = client.create_policy()
258 /// .set_parent(format!("projects/{project_id}"))
259 /// .set_policy(
260 /// Policy::new()/* set fields */
261 /// )
262 /// .send().await?;
263 /// println!("response {:?}", response);
264 /// Ok(())
265 /// }
266 /// ```
267 pub fn create_policy(&self) -> super::builder::org_policy::CreatePolicy {
268 super::builder::org_policy::CreatePolicy::new(self.inner.clone())
269 }
270
271 /// Updates a policy.
272 ///
273 /// Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
274 /// constraint or the policy do not exist.
275 /// Returns a `google.rpc.Status` with `google.rpc.Code.ABORTED` if the etag
276 /// supplied in the request does not match the persisted etag of the policy
277 ///
278 /// Note: the supplied policy will perform a full overwrite of all
279 /// fields.
280 ///
281 /// # Example
282 /// ```
283 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
284 /// # extern crate wkt as google_cloud_wkt;
285 /// use google_cloud_wkt::FieldMask;
286 /// use google_cloud_orgpolicy_v2::model::Policy;
287 /// use google_cloud_orgpolicy_v2::Result;
288 /// async fn sample(
289 /// client: &OrgPolicy, project_id: &str, policy_id: &str
290 /// ) -> Result<()> {
291 /// let response = client.update_policy()
292 /// .set_policy(
293 /// Policy::new().set_name(format!("projects/{project_id}/policies/{policy_id}"))/* set fields */
294 /// )
295 /// .set_update_mask(FieldMask::default().set_paths(["updated.field.path1", "updated.field.path2"]))
296 /// .send().await?;
297 /// println!("response {:?}", response);
298 /// Ok(())
299 /// }
300 /// ```
301 pub fn update_policy(&self) -> super::builder::org_policy::UpdatePolicy {
302 super::builder::org_policy::UpdatePolicy::new(self.inner.clone())
303 }
304
305 /// Deletes a policy.
306 ///
307 /// Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
308 /// constraint or organization policy does not exist.
309 ///
310 /// # Example
311 /// ```
312 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
313 /// use google_cloud_orgpolicy_v2::Result;
314 /// async fn sample(
315 /// client: &OrgPolicy, project_id: &str, policy_id: &str
316 /// ) -> Result<()> {
317 /// client.delete_policy()
318 /// .set_name(format!("projects/{project_id}/policies/{policy_id}"))
319 /// .send().await?;
320 /// Ok(())
321 /// }
322 /// ```
323 pub fn delete_policy(&self) -> super::builder::org_policy::DeletePolicy {
324 super::builder::org_policy::DeletePolicy::new(self.inner.clone())
325 }
326
327 /// Creates a custom constraint.
328 ///
329 /// Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
330 /// organization does not exist.
331 /// Returns a `google.rpc.Status` with `google.rpc.Code.ALREADY_EXISTS` if the
332 /// constraint already exists on the given organization.
333 ///
334 /// # Example
335 /// ```
336 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
337 /// use google_cloud_orgpolicy_v2::model::CustomConstraint;
338 /// use google_cloud_orgpolicy_v2::Result;
339 /// async fn sample(
340 /// client: &OrgPolicy, organization_id: &str
341 /// ) -> Result<()> {
342 /// let response = client.create_custom_constraint()
343 /// .set_parent(format!("organizations/{organization_id}"))
344 /// .set_custom_constraint(
345 /// CustomConstraint::new()/* set fields */
346 /// )
347 /// .send().await?;
348 /// println!("response {:?}", response);
349 /// Ok(())
350 /// }
351 /// ```
352 pub fn create_custom_constraint(&self) -> super::builder::org_policy::CreateCustomConstraint {
353 super::builder::org_policy::CreateCustomConstraint::new(self.inner.clone())
354 }
355
356 /// Updates a custom constraint.
357 ///
358 /// Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
359 /// constraint does not exist.
360 ///
361 /// Note: the supplied policy will perform a full overwrite of all
362 /// fields.
363 ///
364 /// # Example
365 /// ```
366 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
367 /// use google_cloud_orgpolicy_v2::model::CustomConstraint;
368 /// use google_cloud_orgpolicy_v2::Result;
369 /// async fn sample(
370 /// client: &OrgPolicy, organization_id: &str, custom_constraint_id: &str
371 /// ) -> Result<()> {
372 /// let response = client.update_custom_constraint()
373 /// .set_custom_constraint(
374 /// CustomConstraint::new().set_name(format!("organizations/{organization_id}/customConstraints/{custom_constraint_id}"))/* set fields */
375 /// )
376 /// .send().await?;
377 /// println!("response {:?}", response);
378 /// Ok(())
379 /// }
380 /// ```
381 pub fn update_custom_constraint(&self) -> super::builder::org_policy::UpdateCustomConstraint {
382 super::builder::org_policy::UpdateCustomConstraint::new(self.inner.clone())
383 }
384
385 /// Gets a custom or managed constraint.
386 ///
387 /// Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
388 /// custom or managed constraint does not exist.
389 ///
390 /// # Example
391 /// ```
392 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
393 /// use google_cloud_orgpolicy_v2::Result;
394 /// async fn sample(
395 /// client: &OrgPolicy, organization_id: &str, custom_constraint_id: &str
396 /// ) -> Result<()> {
397 /// let response = client.get_custom_constraint()
398 /// .set_name(format!("organizations/{organization_id}/customConstraints/{custom_constraint_id}"))
399 /// .send().await?;
400 /// println!("response {:?}", response);
401 /// Ok(())
402 /// }
403 /// ```
404 pub fn get_custom_constraint(&self) -> super::builder::org_policy::GetCustomConstraint {
405 super::builder::org_policy::GetCustomConstraint::new(self.inner.clone())
406 }
407
408 /// Retrieves all of the custom constraints that exist on a particular
409 /// organization resource.
410 ///
411 /// # Example
412 /// ```
413 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
414 /// use google_cloud_gax::paginator::ItemPaginator as _;
415 /// use google_cloud_orgpolicy_v2::Result;
416 /// async fn sample(
417 /// client: &OrgPolicy, organization_id: &str
418 /// ) -> Result<()> {
419 /// let mut list = client.list_custom_constraints()
420 /// .set_parent(format!("organizations/{organization_id}"))
421 /// .by_item();
422 /// while let Some(item) = list.next().await.transpose()? {
423 /// println!("{:?}", item);
424 /// }
425 /// Ok(())
426 /// }
427 /// ```
428 pub fn list_custom_constraints(&self) -> super::builder::org_policy::ListCustomConstraints {
429 super::builder::org_policy::ListCustomConstraints::new(self.inner.clone())
430 }
431
432 /// Deletes a custom constraint.
433 ///
434 /// Returns a `google.rpc.Status` with `google.rpc.Code.NOT_FOUND` if the
435 /// constraint does not exist.
436 ///
437 /// # Example
438 /// ```
439 /// # use google_cloud_orgpolicy_v2::client::OrgPolicy;
440 /// use google_cloud_orgpolicy_v2::Result;
441 /// async fn sample(
442 /// client: &OrgPolicy, organization_id: &str, custom_constraint_id: &str
443 /// ) -> Result<()> {
444 /// client.delete_custom_constraint()
445 /// .set_name(format!("organizations/{organization_id}/customConstraints/{custom_constraint_id}"))
446 /// .send().await?;
447 /// Ok(())
448 /// }
449 /// ```
450 pub fn delete_custom_constraint(&self) -> super::builder::org_policy::DeleteCustomConstraint {
451 super::builder::org_policy::DeleteCustomConstraint::new(self.inner.clone())
452 }
453}