Export (0) Print
Expand All

DirectoryObject

Updated: April 21, 2014

  • Applies To: Azure AD Graph

This topic provides descriptions of the properties of the DirectoryObject entity type. The DirectoryObject type is the base type for all other directory entity types.

Azure AD Graph exposes metadata that describes the directory as an Entity Data Model (EDM) using Conceptual Schema Definition Language (CSDL). You can view the metadata exposed for your tenant by performing an HTTP GET from the following URL: https://graph.windows.net/yourTenantDomain/$metadata?api-version=2013-04-05. Replace yourTenantDomain with the domain of your tenant; for example, https://graph.windows.net/contoso.onmicrosoft.com/$metadata?api-version=2013-04-05. For more information about the EDM and CSDL, see Entity Data Model.

The DirectoryObject entity type is defined as follows:

Namespace: Microsoft.WindowsAzure.ActiveDirectory

Type Properties

Name Type Notes Read/Write Key Filterable Description

objectId

Edm.String

Immutable

R

Yes

A Guid that is the unique identifier for the object; for example, 12345678-9abc-def0-1234-56789abcde.

objectType

Edm.String

R

A string that identifies the object type. For example, for groups the value is always “Group”.

Navigation Properties

Name From From Multiplicity To To Multiplicity Description

manager

DirectoryObject

*

DirectoryObject

0..1

This object’s manager. Valid on users and contacts. Returns a user or a contact.

directReports

DirectoryObject

*

DirectoryObject

*

Users and contacts that report to this object. Valid on users and contacts. Returns users and contacts. Read only.

members

DirectoryObject

*

DirectoryObject

*

Objects that are members of this object. Valid on groups and roles. On groups, returns contacts, users, and groups. On roles, returns users and service principals.

memberOf

DirectoryObject

*

DirectoryObject

*

Objects that this object is a member of. Valid on contacts, groups, service principals, and users. On contacts, returns groups. On groups, returns groups. On users, returns groups and roles. On service principals, returns roles. Read only.

The property is not transitive. For example, if User A is a member of Group B and Group B is a member of Group C, the memberOf property on User A will not return Group C.

noteNote
Not all navigation properties are necessarily valid on the entity types that inherit from DirectoryObject. If a request for a property that is not valid for a specific entity is sent, a 400 Bad Request response is returned. For more information about which navigation properties are valid on specific entities, consult the documentation for that entity type.

For information about the primitive types exposed by the EDM, see Entity Data Model: Primitive Data Types.

The following list shows how to address the directory object entity set, which spans all the objects in the directory; an individual directory object; and the navigation properties of a directory object. The examples in the list use the tenant domain to address the tenant. For other ways of addressing the tenant, see Addressing Entities and Operations in the Graph API.

  • Entity Set: https://graph.windows.net/<tenantDomain>/directoryObjects?api-version=<version>. For example, https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects?api-version=2013-04-05.

  • Directory Object: https://graph.windows.net/<tenantDomain>/directoryObjects/<objectId>?api-version=<version>. For example, https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/12345678-9abc-def0-1234-56789abcde?api-version=2013-04-05.

  • Navigation Property: https://graph.windows.net/<tenantDomain>/directoryObjects/<objectId>/$links/<property name>?api-version=<version>. For example, https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/12345678-9abc-def0-1234-56789abcde/$links/members?api-version=2013-04-05.

noteNote
Remove the “$links” segment of the navigation property URI to return the objects referenced by a navigation property rather than links to them. This mode of addressing can be used for read operations only. Entities that inherit from DirectoryObject can also typically be addressed using their resource set by replacing “directoryObjects” with a string that identifies the resource set -- for example, “users” -- in the URI. Not all addressing modes are available for all entity types.

For more comprehensive information about querying directory objects, see Azure AD Graph API Common Queries and Azure AD Graph API Differential Query.

It is best to consult the documentation for the specific entity type for more detailed information about addressing for that entity.

The full set of operations that are supported on directory objects are the following (the HTTP method used for each is in parentheses): Create (POST), Read (GET), Update (PATCH), and Delete (DELETE). However, not all of these operations are supported on every entity type.

In addition, the potential set of operations supported on each of the navigation properties are:

  • manager: Read (GET), Update (PUT), and Delete (DELETE).

  • directReports: Read (GET).

  • members: Read (GET), Update (POST), and Delete (DELETE).

  • memberOf: Read (GET).

Not all navigation properties are necessarily supported on every entity type, nor are the set of potential operations for a navigation property necessarily supported on every entity type.

In general, the service principal that represents an application must be in an administrator role that has directory WRITE privileges to send PATCH, POST, PUT or DELETE requests. It must be in a role that has directory READ privileges to send GET requests. However, the permissions required for operations on a specific entity type can be different. For more information about roles in Azure AD Graph, see Azure AD Graph and Role-Based Access Control.

It is best to consult the documentation for the specific entity type for information about operations supported for and permissions required for an entity.

DirectoryObject is the base type for the following entity types: Application, Device, DirectoryLinkChange, Contact, Group, Role, ServicePrincipal, TenantDetail, and User.

See Also

Show:
© 2014 Microsoft