xref: /aosp_15_r20/external/google-cloud-java/java-resourcemanager/.readme-partials.yaml (revision 55e87721aa1bc457b326496a7ca40f3ea1a63287)
1custom_content: |
2  #### Creating an authorized service object
3  To make authenticated requests to Google Cloud Resource Manager, you must create a service object
4  with Google Cloud SDK credentials. You can then make API calls by calling methods on the Resource
5  Manager service object. The simplest way to authenticate is to use
6  [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials).
7  These credentials are automatically inferred from your environment, so you only need the following
8  code to create your service object:
9
10  ```java
11  import com.google.cloud.resourcemanager.ResourceManager;
12  import com.google.cloud.resourcemanager.ResourceManagerOptions;
13
14  ResourceManager resourceManager = ResourceManagerOptions.getDefaultInstance().getService();
15  ```
16
17  #### Getting a specific project
18  You can load a project if you know its project ID and have read permissions to the project.
19  To get a project, add the following import at the top of your file:
20
21  ```java
22  import com.google.cloud.resourcemanager.Project;
23  ```
24
25  Then use the following code to get the project:
26
27  ```java
28  String projectId = "my-globally-unique-project-id"; // Change to a unique project ID
29  Project project = resourceManager.get(projectId);
30  ```
31
32  #### Creating a project
33  All you need to create a project is a globally unique project ID. You can also optionally attach a
34  non-unique name and labels to your project. Read more about naming guidelines for project IDs,
35  names, and labels [here](https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects).
36  To create a project, add the following imports at the top of your file:
37
38  ```java
39  import com.google.cloud.resourcemanager.Project;
40  import com.google.cloud.resourcemanager.ProjectInfo;
41  ```
42
43  Then add the following code to create a project (be sure to change `projectId` to your own unique
44  project ID).
45
46  ```java
47  String projectId = "my-globally-unique-project-id"; // Change to a unique project ID
48  Project project = resourceManager.create(ProjectInfo.newBuilder(projectId).build());
49  ```
50
51  Note that the return value from `create` is a `Project` that includes additional read-only
52  information, like creation time, project number, and lifecycle state. Read more about these fields
53  on the [Projects page](https://cloud.google.com/resource-manager/reference/rest/v1beta1/projects).
54  `Project`, a subclass of `ProjectInfo`, adds a layer of service-related functionality over
55  `ProjectInfo`.
56
57  #### Editing a project
58  To edit a project, create a new `ProjectInfo` object and pass it in to the `Project.replace` method.
59  For example, to add a label to a project to denote that it's launch status is "in development", add
60  the following code:
61
62  ```java
63  Project newProject = project.toBuilder()
64      .addLabel("launch-status", "in-development")
65      .build()
66      .replace();
67  ```
68
69  Note that the values of the project you pass in to `replace` overwrite the server's values for
70  non-read-only fields, namely `projectName` and `labels`. For example, if you create a project with
71  `projectName` "some-project-name" and subsequently call replace using a `ProjectInfo` object that
72  didn't set the `projectName`, then the server will unset the project's name. The server ignores any
73  attempted changes to the read-only fields `projectNumber`, `lifecycleState`, and `createTime`.
74  The `projectId` cannot change.
75
76  #### Listing all projects
77  Suppose that we want a list of all projects for which we have read permissions. Add the following
78  import:
79
80  ```java
81  import java.util.Iterator;
82  ```
83
84  Then add the following code to print a list of projects you can view:
85
86  ```java
87  Iterator<Project> projectIterator = resourceManager.list().iterateAll().iterator();
88  System.out.println("Projects I can view:");
89  while (projectIterator.hasNext()) {
90    System.out.println(projectIterator.next().getProjectId());
91  }
92  ```
93
94  #### Managing IAM Policies
95  You can edit [Google Cloud IAM](https://cloud.google.com/iam/) (Identity and Access Management)
96  policies on the project-level using this library as well. We recommend using the read-modify-write
97  pattern to make policy changes.  This entails reading the project's current policy, updating it
98  locally, and then sending the modified policy for writing, as shown in the snippet below. First,
99  add these imports:
100
101  ```java
102  import com.google.cloud.Identity;
103  import com.google.cloud.Policy;
104  import com.google.cloud.Role;
105  ```
106
107  Assuming you have completed the steps above to create the `ResourceManager` service object and load
108  a project from the server, you just need to add the following code:
109
110  ```java
111  // Get the project's policy
112  Policy policy = project.getPolicy();
113
114  // Add a viewer
115  Policy.Builder modifiedPolicy = policy.toBuilder();
116  Identity newViewer = Identity.user("<insert user's email address here>");
117  modifiedPolicy.addIdentity(Role.viewer(), newViewer);
118
119  // Write policy
120  Policy updatedPolicy = project.replacePolicy(modifiedPolicy.build());
121  ```
122
123  Note that the policy you pass in to `replacePolicy` overwrites the original policy. For example, if
124  the original policy has two bindings and you call `replacePolicy` with a new policy containing only
125  one binding, the two original bindings are lost.
126
127  #### Complete source code
128
129  We put together all the code shown above into three programs. The programs assume that you are
130  running from your own desktop and used the Google Cloud SDK to authenticate yourself.
131
132  The first program creates a project if it does not exist. Complete source code can be found at
133  [GetOrCreateProject.java](https://github.com/googleapis/google-cloud-java/blob/master/google-cloud-examples/src/main/java/com/google/cloud/examples/resourcemanager/snippets/GetOrCreateProject.java).
134
135  The second program updates a project if it exists and lists all projects the user has permission to
136  view. Complete source code can be found at
137  [UpdateAndListProjects.java](https://github.com/googleapis/google-cloud-java/blob/master/google-cloud-examples/src/main/java/com/google/cloud/examples/resourcemanager/snippets/UpdateAndListProjects.java).
138
139  The third program modifies the IAM policy associated with a project using the read-modify-write
140  pattern.  Complete source code can be found at
141  [ModifyPolicy.java](https://github.com/googleapis/google-cloud-java/blob/master/google-cloud-examples/src/main/java/com/google/cloud/examples/resourcemanager/snippets/ModifyPolicy.java)
142