docs(iam): Update comments and terminology in IAM samples (#9887)

* Update Quickstart.java comments

Includes changing "member" to "principal" and linking to principal identifiers page instead of specifying recommended format.

* Update AddMember.java comments (#9886)

Includes changing "member" to "principal" and linking to principal identifiers page instead of specifying recommended format.

* Update AddBinding.java

Includes changing "member" to "principal" and linking to principal identifiers page instead of specifying recommended format.
 melaniedejong-patch-1 (#4895)

* Update RemoveMember.java comments

Includes changing "member" to "principal" and linking to principal identifiers page instead of specifying recommended format.

* Update Quickstart.java

* Update AddMember.java

Author: melaniedejong

iam/snippets/src/main/java/AddBinding.java

@@ -27,13 +27,14 @@ public static void main(String[] args) {
     Policy policy = Policy.newBuilder().build();
     // TODO: Replace with your role.
     String role = "roles/role-to-add";
-    // TODO: Replace with your members.
-    List<String> members = Collections.singletonList("user:member-to-add@example.com");
+    // TODO: Replace with your principals.
+    // For examples, see https://cloud.google.com/iam/docs/principal-identifiers
+    List<String> members = Collections.singletonList("principal-id");
 
     addBinding(policy, role, members);
   }
 
-  // Adds a member to a role.
+  // Adds a principals to a role.
   public static Policy addBinding(Policy policy, String role, List<String> members) {
     Binding binding = Binding.newBuilder()
             .setRole(role)

iam/snippets/src/main/java/AddMember.java

@@ -26,13 +26,14 @@ public static void main(String[] args) {
     Policy policy = Policy.newBuilder().build();
     // TODO: Replace with your role.
     String role = "roles/existing-role";
-    // TODO: Replace with your member.
-    String member = "user:member-to-add@example.com";
+    // TODO: Replace with your principal.
+    // For examples, see https://cloud.google.com/iam/docs/principal-identifiers
+    String member = "principal-id";
 
     addMember(policy, role, member);
   }
 
-  // Adds a member to a pre-existing role.
+  // Adds a principal to a pre-existing role.
   public static Policy addMember(Policy policy, String role, String member) {
     List<Binding> newBindingsList = new ArrayList<>();
 
@@ -44,13 +45,13 @@ public static Policy addMember(Policy policy, String role, String member) {
       }
     }
 
-    // Update the policy to add the member.
+    // Update the policy to add the principal.
     Policy updatedPolicy = policy.toBuilder()
             .clearBindings()
             .addAllBindings(newBindingsList)
             .build();
 
-    System.out.println("Added member: " + updatedPolicy.getBindingsList());
+    System.out.println("Added principal: " + updatedPolicy.getBindingsList());
 
     return updatedPolicy;
   }

iam/snippets/src/main/java/Quickstart.java

@@ -34,8 +34,9 @@ public static void main(String[] args) throws IOException {
     String projectId = "your-project";
     // TODO: Replace with your service account name.
     String serviceAccount = "your-service-account";
-    // TODO: Replace with the ID of your member in the form "user:member@example.com"
-    String member = "your-member";
+    // TODO: Replace with the ID of your principal.
+    // For examples, see https://cloud.google.com/iam/docs/principal-identifiers
+    String member = "your-principal";
     // The role to be granted.
     String role = "roles/logging.logWriter";
 
@@ -56,10 +57,10 @@ public static void quickstart(String projectId, String serviceAccount,
     // This client only needs to be created once, and can be reused for multiple requests.
     try (IAMClient iamClient = IAMClient.create()) {
 
-      // Grants your member the "Log writer" role for your project.
+      // Grants your principal the "Log writer" role for your project.
       addBinding(iamClient, projectId, serviceAccount, member, role);
 
-      // Get the project's policy and print all members with the "Log Writer" role
+      // Get the project's policy and print all principals with the "Log Writer" role
       Policy policy = getPolicy(iamClient, projectId, serviceAccount);
 
       Binding binding = null;
@@ -73,14 +74,14 @@ public static void quickstart(String projectId, String serviceAccount,
       }
 
       System.out.println("Role: " + binding.getRole());
-      System.out.print("Members: ");
+      System.out.print("Principals: ");
 
       for (String m : binding.getMembersList()) {
         System.out.print("[" + m + "] ");
       }
       System.out.println();
 
-      // Removes member from the "Log writer" role.
+      // Removes principal from the "Log writer" role.
       removeMember(iamClient, projectId, serviceAccount, member, role);
     }
   }
@@ -107,7 +108,7 @@ public static void addBinding(IAMClient iamClient, String projectId, String serv
     }
 
     if (binding != null) {
-      // If binding already exists, adds member to binding.
+      // If binding already exists, adds principal to binding.
       binding.getMembersList().add(member);
     } else {
       // If binding does not exist, adds binding to policy.
@@ -127,7 +128,7 @@ public static void removeMember(IAMClient iamClient, String projectId, String se
     // Gets the project's policy.
     Policy.Builder policy = getPolicy(iamClient, projectId, serviceAccount).toBuilder();
 
-    // Removes the member from the role.
+    // Removes the principal from the role.
     Binding binding = null;
     for (Binding b : policy.getBindingsList()) {
       if (b.getRole().equals(role)) {

iam/snippets/src/main/java/RemoveMember.java

@@ -27,13 +27,14 @@ public static void main(String[] args) throws IOException {
     Policy policy = Policy.newBuilder().build();
     // TODO: Replace with your role.
     String role = "roles/existing-role";
-    // TODO: Replace with your member.
-    String member = "user:member-to-add@example.com";
+    // TODO: Replace with your principal.
+    // For examples, see https://cloud.google.com/iam/docs/principal-identifiers
+    String member = "principal-id";
 
     removeMember(policy, role, member);
   }
 
-  // Removes member from a role; removes binding if binding contains no members.
+  // Removes principal from a role; removes binding if binding contains no members.
   public static Policy removeMember(Policy policy, String role, String member) {
     // Creating new builder with all values copied from origin policy
     Policy.Builder policyBuilder = policy.toBuilder();
@@ -49,12 +50,12 @@ public static Policy removeMember(Policy policy, String role, String member) {
 
     if (binding != null && binding.getMembersList().contains(member)) {
       List<String> newMemberList = new ArrayList<>(binding.getMembersList());
-      // Removing member from a role
+      // Removing principal from the role
       newMemberList.remove(member);
 
       System.out.println("Member " + member + " removed from " + role);
 
-      // Adding all remaining members to create new binding
+      // Adding all remaining principals to create new binding
       Binding newBinding = binding.toBuilder()
               .clearMembers()
               .addAllMembers(newMemberList)
@@ -70,14 +71,14 @@ public static Policy removeMember(Policy policy, String role, String member) {
         newBindingList.add(newBinding);
       }
 
-      // Update the policy to remove the member.
+      // Update the policy to remove the principal.
       policyBuilder.clearBindings()
               .addAllBindings(newBindingList);
     }
 
     Policy updatedPolicy = policyBuilder.build();
 
-    System.out.println("Exising members: " + updatedPolicy.getBindingsList());
+    System.out.println("Exising principals: " + updatedPolicy.getBindingsList());
 
     return updatedPolicy;
   }