Package org.azd.graph

Class GraphApi

java.lang.Object
org.azd.utils.AzDAsyncApi<GraphApi>
org.azd.graph.GraphApi
All Implemented Interfaces:
GraphDetails
public class GraphApi extends AzDAsyncApi<GraphApi> implements GraphDetails
GraphApi class to manage graph users and groups

  • Constructor Details

    • GraphApi

      public GraphApi(Connection connection)
      Pass the connection object to work with Graph Api
      Parameters:
      connection - Connection object

  • Method Details

    • createUser

      public GraphUser createUser(String emailId, String userDescriptor) throws AzDException
      Materialize an existing AAD or MSA user into the VSTS account. NOTE: Created users are not active in an account unless they have been explicitly assigned a parent group at creation time or have signed in and been autolicensed through AAD group memberships. Adding a user to an account is required before the user can be added to VSTS groups or assigned an asset. Create a new user using the principal name as a reference to an existing user from an external AD or AAD backed provider. If the user to be added corresponds to a user that was previously deleted, then that user will be restored.
      Specified by:
      createUser in interface GraphDetails
      Parameters:
      emailId - provide the user principal name (email address) of the user to be added.
      userDescriptor - provide the user descriptor for reference
      Returns:
      GraphUser GraphUser
      Throws:
      AzDException - Default Api Exception handler.

    • addUserToGroup

      public GraphUser addUserToGroup(String emailId, String groupDescriptor) throws AzDException
      Materialize an existing AAD or MSA user into the VSTS account. Add the newly created user as a member of an existing VSTS group by providing the group descriptor.
      Specified by:
      addUserToGroup in interface GraphDetails
      Parameters:
      emailId - provide the user principal name (email address) of the user to be added.
      groupDescriptor - provide the group descriptor.
      Returns:
      GraphUser GraphUser
      Throws:
      AzDException - Default Api Exception handler.

    • deleteUser

      public Void deleteUser(String userDescriptor) throws AzDException
      Disables a user. The user will still be visible, but membership checks for the user will return false.
      Specified by:
      deleteUser in interface GraphDetails
      Parameters:
      userDescriptor - The descriptor of the user to delete.
      Throws:
      AzDException - Default Api Exception handler.

    • getUser

      public GraphUser getUser(String userDescriptor) throws AzDException
      Get a user by its descriptor.
      Specified by:
      getUser in interface GraphDetails
      Parameters:
      userDescriptor - The descriptor of the desired user.
      Returns:
      GraphUser GraphUser
      Throws:
      AzDException - Default Api Exception handler.

    • getUsers

      public GraphUsers getUsers() throws AzDException
      Get a list of all users in a given scope.
      Specified by:
      getUsers in interface GraphDetails
      Returns:
      GraphUsers GraphUsers
      Throws:
      AzDException - Default Api Exception handler.

    • getUsers

      public GraphUsers getUsers(String continuationToken, String scopeDescriptor, String subjectTypes) throws AzDException
      Get a list of all users in a given scope. Since the list of users may be large, results are returned in pages of users. If there are more results than can be returned in a single page, the result set will contain a continuation token for retrieval of the next set of results.
      Specified by:
      getUsers in interface GraphDetails
      Parameters:
      continuationToken - An opaque data blob that allows the next page of data to resume immediately after where the previous page ended. The only reliable way to know if there is more data left is the presence of a continuation token.
      scopeDescriptor - Specify a non-default scope (collection, project) to search for users.
      subjectTypes - String array of user subject subtypes to reduce the retrieved results, e.g. msa’, ‘aad’, ‘svc’ (service identity), ‘imp’ (imported identity), etc.
      Returns:
      GraphUsers GraphUsers
      Throws:
      AzDException - Default Api Exception handler.

    • getGroup

      public GraphGroup getGroup(String groupDescriptor) throws AzDException
      Get a group by its descriptor. The group will be returned even if it has been deleted from the account or has had all its memberships deleted.
      Specified by:
      getGroup in interface GraphDetails
      Parameters:
      groupDescriptor - The descriptor of the desired graph group.
      Returns:
      GraphGroup GraphGroup
      Throws:
      AzDException - Default Api Exception handler.

    • getGroups

      public GraphGroups getGroups() throws AzDException
      Gets a list of all groups in the current scope (usually organization or account).
      Specified by:
      getGroups in interface GraphDetails
      Returns:
      GraphGroups GraphGroups
      Throws:
      AzDException - Default Api Exception handler.

    • getGroupMembersOf

      public GraphMemberships getGroupMembersOf(String groupDescriptor) throws AzDException
      get subjects (users, groups) that are a member of the specified group
      Specified by:
      getGroupMembersOf in interface GraphDetails
      Parameters:
      groupDescriptor - The descriptor of the container group
      Returns:
      GraphMemberships GraphMemberships
      Throws:
      AzDException - Default Api Exception handler.

    • getMemberOfGroups

      public GraphMemberships getMemberOfGroups(String subjectDescriptor) throws AzDException
      get groups that the specified subject (user, group) belongs to
      Specified by:
      getMemberOfGroups in interface GraphDetails
      Parameters:
      subjectDescriptor - The descriptor of the subject (either user or group) that belongs to a container
      Returns:
      GraphMemberships GraphMemberships
      Throws:
      AzDException - Default Api Exception handler.

    • addMembership

      public GraphMembership addMembership(String subjectDescriptor, String groupDescriptor) throws AzDException
      add a membership relation between a subject (user or group) and a container (group)

      a more general case that allows nested groups

      Specified by:
      addMembership in interface GraphDetails
      Parameters:
      subjectDescriptor - The descriptor of the subject to add to the container
      groupDescriptor - The descriptor of the container to which to add the subject
      Returns:
      GraphMembership GraphMembership
      Throws:
      AzDException - Default Api Exception handler.

    • removeMembership

      public Void removeMembership(String subjectDescriptor, String groupDescriptor) throws AzDException
      remove a membership relation between a subject (user or group) and a container (group)
      Specified by:
      removeMembership in interface GraphDetails
      Parameters:
      subjectDescriptor - The descriptor of the subject to remove from the container
      groupDescriptor - The descriptor of the container to which to remove the subject
      Throws:
      AzDException - Default Api Exception handler.

    • createGroup

      public GraphMembership createGroup(String displayName, String description) throws AzDException
      create a local group at the collection level
      Specified by:
      createGroup in interface GraphDetails
      Parameters:
      displayName - The name of the group
      description - A generally more verbose description of the group
      Returns:
      GraphMembership GraphMembership
      Throws:
      AzDException - Default Api Exception handler.

    • createGroup

      public GraphMembership createGroup(String displayName, String description, String projectDescriptor) throws AzDException
      create a local group at the project level
      Specified by:
      createGroup in interface GraphDetails
      Parameters:
      displayName - The name of the group
      description - A generally more verbose description of the group
      Returns:
      GraphMembership GraphMembership
      Throws:
      AzDException - Default Api Exception handler.

    • deleteGroup

      public Void deleteGroup(String groupDescriptor) throws AzDException
      Removes an Azure DevOps group from all of its parent groups.

      The group will still be visible, but membership checks for the group, and all descendants which derive membership through it, will return false.

      Specified by:
      deleteGroup in interface GraphDetails
      Parameters:
      groupDescriptor - The descriptor of the target group to remove
      Throws:
      AzDException - Default Api Exception handler.

    • getDescriptor

      public GraphDescriptor getDescriptor(String storageKey) throws AzDException
      Resolve a storage key to a descriptor

      Refer to REST API documentation on descriptors

      Specified by:
      getDescriptor in interface GraphDetails
      Parameters:
      storageKey - A GUID representation of a user or group
      Returns:
      GraphDescriptor GraphDescriptor
      Throws:
      AzDException - Default Api Exception handler.

    • subjectLookup

      public SubjectLookupResponse subjectLookup(String... descriptors) throws AzDException
      resolve descriptors to subjects

      Refer to REST API documentation on storage keys

      Specified by:
      subjectLookup in interface GraphDetails
      Parameters:
      descriptors - user and group descriptor strings
      Returns:
      SubjectLookupResponse SubjectLookupResponse
      Throws:
      AzDException - Default Api Exception handler.