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