Функции и действия | Справочник по API Graph

  • Статья

Область применения: API Graph | Azure Active Directory

В этом разделе обсуждаются функции и действия, предоставляемые API Graph Azure AD, и процедура вызова этих функций.

API Graph — это API REST, совместимый с OData 3.0 и предоставляющий программный доступ к объектам каталога в Azure Active Directory, таким как пользователи, группы, контакты организации и приложения.

Важно!

Доступ к функциональным возможностям API Graph Azure AD можно получить и через Microsoft Graph — универсальный API, который также включает API других служб Майкрософт, таких как Outlook, OneDrive, OneNote, Планировщик и Office Graph, и позволяет получать к ним доступ через единую конечную точку с маркером единого доступа.

Использование API Graph для вызова действий и функций

Для вызова действия или функции с помощью API Graph необходимо отправить запрос POST к соответствующей конечной точке.

В запросах API Graph используется следующий базовый URL-адрес:

https://graph.windows.net/{tenant_id}/{resource_path}?{api_version}[odata_query_parameters]

Важно!

Запросы, отправляемые в API Graph, должны иметь правильный формат, обращаться к действительной конечной точке и версии API Graph и содержать в заголовке Authorization действительный токен доступа, полученный из Azure AD. Более подробные сведения о создании запросов и получении ответов с помощью API Graph см. в статье [Operations Overview].

Функции и действия, которые вызывают для самой службы каталога, не требуют пути к ресурсу. Для функций или операций, которые вызываются для определенного ресурса, {resource_path} указывается по-разному в зависимости от того, на какой ресурс он направлен. Путь к ресурсу будет состоять из следующих частей:

  • (resource_collection} указывает коллекцию ресурсов, таких как пользователи, контакты и группы.
  • {resource_id} определяет конкретный ресурс в коллекции, к которому выполняется обращение. Обычно это идентификатор объекта (GUID), но в случае пользователя можно также применить имя субъекта-пользователя (UPN).

Для обращения к пользователю, выполнившему вход, можно также использовать псевдоним me. Псевдоним заменяет следующие сегменты в пути URL-адреса: {tenant_id}/users/{user_id}. При использовании псевдонима API Graph возвращает пользователя и клиента из токена носителя, присоединенного к запросу.

Например, следующий запрос POST можно использовать для назначения лицензии пользователю, выполнившему вход (необходимо включить соответствующий текст запроса):

POST https://graph.windows.net/me/assignLicense?api-version=1.6

Дополнительные сведения о выполнении операций с применением псевдонима me см. в статье Операции REST с пользователями, выполнившими вход.

Функции

Функции не имеют побочных эффектов в каталоге. Иными словами, вызванная функция возвращает данные, но не изменяет никакие данные в каталоге. В следующих разделах показано, как вызывать функции с помощью API Graph.

checkMemberGroups: проверка членства в списке групп

Функция checkMemberGroups позволяет проверить членство пользователя, контакта, группы или субъекта-службы в списке групп. Эта операция является транзитивной.

В одном запросе можно проверять максимум 20 групп.

{
    "api":  "Functions",
    "operation":    "checkMemberGroups" 
}

Текст запроса

Имя свойства Тип Обязательно Описание
isSyncedFromOnPremises Collection(Edm.String) Да Коллекция, содержащая идентификаторы объектов групп для проверки на членство. Можно указать до 20 групп.

Текст ответа

Имя свойства Тип Описание
value Collection(Edm.String) Коллекция, содержащая идентификаторы объектов групп, указанных в запросе, членом которых является контакт, пользователь, группа или участник-служба.

getAvailableExtensionProperties: получение свойств зарегистрированного расширения в каталоге

Функция getAvailableExtensionProperties позволяет получить все или выборочные свойства расширения, которые зарегистрированы в каталоге. Свойства расширения поддерживаются следующими сущностями: [User], [Group], [TenantDetail], [Device], [Application] и [ServicePrincipal]. Подробнее о том, как свойства расширения регистрируются в каталоге, как отменяется их регистрация и как можно изменять их значения, см. в статье [Directory Schema Extensions].

Важно. Требуется версия 1.5 или более поздняя.

{
    "api":  "Functions",
    "operation":    "getAvailableExtensionProperties" 
}

Текст запроса

Имя свойства Тип Обязательно Описание
isSyncedFromOnPremises Edm.Boolean Нет true указывает, что должны возвращаться только свойства расширения, синхронизированные с локальным каталогом; false указывает, что должны возвращаться только свойства расширения, которые не синхронизированы с локальным каталогом. Если этот параметр пропущен, возвращаются все свойства расширения (синхронизированные и несинхронизированные).

Текст ответа

Имя свойства Тип Описание
value Collection([ExtensionProperty]) Коллекция, которая содержит свойства расширения, зарегистрированные в каталоге и отфильтрованные в соответствии с запросом.

getMemberGroups: получение членств в группах (транзитивно)

Функция getMemberGroups, примененная в отношении пользователя, контакта, группы или субъекта-службы, позволяет получить список групп, членом которых является эта сущность. Эта функция является транзитивной.

Примечание. Максимальное количество возвращаемых групп — 2046. Если целевой объект имеет прямое или транзитивное членство более чем в 2046 группах, функция выдает сообщение об ошибке HTTP с кодом Directory_ResultSizeLimitExceeded.

{
    "api":  "Functions",
    "operation":    "getMemberGroups",
}

Текст запроса

Имя свойства Тип Обязательно Описание
securityEnabledOnly Edm.Boolean Да Значение true, если необходимо возвратить только группы безопасности, членом которых является сущность; значение false, если требуется возвратить все группы, членом которых является сущность. Примечание. Если этот параметр имеет значение true, то функция может вызываться только для пользователя.

Текст ответа

Имя свойства Тип Описание
value Collection(Edm.String) Коллекция, содержащая идентификаторы объектов групп, членом которых является контакт, пользователь, группа или субъект-служба.

getMemberObjects: получение всех членств в группах и ролях каталога (транзитивно)

Вызывайте функцию getMemberObjects для пользователя, контакта, группы или субъекта-службы, чтобы получить группы и роли каталога, членом которых является эта сущность. Эта функция является транзитивной.

Примечание. Максимальное количество возвращаемых групп и ролей каталога — 2046. Если целевой объект имеет прямое или транзитивное членство более чем в 2046 группах и ролях каталога, функция выдает сообщение об ошибке HTTP с кодом Directory_ResultSizeLimitExceeded.

Важно. Требуется версия 1.5 или более поздняя.

{
    "api":  "Functions",
    "operation":    "getMemberObjects" 
}

Текст запроса

Имя свойства Тип Обязательно Описание
securityEnabledOnly Edm.Boolean Да Значение true, если необходимо возвратить только группы безопасности, членом которых является сущность; значение false, если требуется получить все группы и роли каталогов, членом которых является сущность. Примечание. Если этот параметр имеет значение true, то функция может вызываться только для пользователя.

Текст ответа

Имя свойства Тип Описание
value Collection(Edm.String) Коллекция, содержащая идентификаторы объектов групп и ролей каталога, членом которых является контакт, пользователь, группа или субъект-служба.

getObjectsByObjectIds: получение объектов из списка идентификаторов объектов

Функция getObjectsByObjectIds, примененная в отношении службы каталогов, позволяет получить объекты каталога, указанные в списке идентификаторов объектов. Можно также указать, какие коллекции ресурсов (пользователей, групп и т. д.) требуется найти, задав необязательный параметр types.

Наиболее часто эта функция используется в следующих целях.

  • Разрешение идентификаторов объектов, возвращаемых функциями, которые возвращают коллекции идентификаторов объектов, такими как [getMemberObjects] или [getMemberGroups], в резервные объекты каталога.
  • Разрешение идентификаторов объектов, хранящихся во внешнем хранилище, по приложению в резервные объекты каталога.

Важно. Требуется версия 1.5 или более поздняя.

{
    "api":  "Functions",
    "operation":    "getObjectsByObjectIds" 
}

Текст запроса

Имя свойства Тип Обязательно Описание
objectIds Collection(Edm.String) Да Коллекция идентификаторов объектов, для которых возвращаются объекты. Можно указать не более 1000 идентификаторов.
типы Collection(Edm.String) Нет Коллекция типов объектов, определяющая набор коллекций ресурсов (наборов сущностей) для поиска. Если элемент не указан, используется значение по умолчанию [DirectoryObject], которое содержит все объекты в каталоге. Любой объект, который является производным от [DirectoryObject], может быть указан в коллекции. Например: [User], [Group], [ServicePrincipal] и т. д. В значениях регистр не учитывается.

Текст ответа

Имя свойства Тип Описание
value Collection([DirectoryObject]) Коллекция объектов, найденных для заданных идентификаторов объектов и коллекций ресурсов.

isMemberOf: проверка членства в определенной группе (транзитивно)

Функция IsMemberOf, примененная к службе каталогов, позволяет проверить, является ли указанный пользователь, группа, контакт или субъект-служба членом указанной группы. Эта операция является транзитивной.

{
    "api":  "Functions",
    "operation":    "isMemberOf" 
}

Текст запроса

Имя свойства Тип Обязательно Описание
groupId Edm.String Да Идентификатор объекта группы для проверки.
memberId Edm.String Да Идентификатор объекта контакта, группы, пользователя или субъекта-службы для проверки членства в указанной группе.

Текст ответа

Имя свойства Тип Описание
value Edm.Boolean Значение true, если указанный пользователь, группа, контакт или субъект-служба имеет прямое или транзитивное членство в указанной группе; иначе значение false.

Действия

Действия имеют побочные эффекты в каталоге. Это значит, что вызванное действие может привести к изменению данных в каталоге. Например, оно может предоставить пользователю лицензию или восстановить удаленное ранее приложение.

assignLicense: добавление или удаление лицензий у пользователя

Функция assignLicense, примененная в отношении пользователя, позволяет добавить или удалить его подписки. Можно также включать и отключать определенные планы, связанные с подпиской.

Важно. Требуется версия 2013-11-08 или более поздняя.

{
    "api":  "Functions",
    "operation":    "assignLicense" 
}

Текст запроса

Имя свойства Тип Обязательно Описание
addLicenses Collection([AssinedPlan]) Да Коллекция объектов [AssignedLicense], указывающих, какие лицензии нужно добавить. Вы можете отключить планы, связанные с лицензией, задав для свойства disabledPlans объект [AssignedLicense].
removeLicenses Collection(Edm.Guid) Да Коллекция идентификаторов GUID, определяющих удаляемые лицензии.

Примечание. Идентификаторы SKU подписки и идентификаторы планов можно считывать из объекта клиента. Например, запрос GET в отношении https://graph.windows.net/myorganization/subscribedSkus возвращает подписки, доступные для клиента пользователя, выполнившего вход. Они возвращаются как сущности [SubscribedSku], а идентификатор SKU можно прочитать в свойстве skuId. Идентификаторы планов, связанные с подпиской, можно получить из коллекции servicePlans. Доступность подписок может вычисляться из свойства consumedUnits и значений составного свойства prepaidUnits, которое содержит количество единиц в состоянии "enabled" (включено), "suspended" (приостановлено) и "warning" (предупреждение).

Дополнительные примеры

Этот запрос показывает исходное назначение лицензии SKU Enterprise Office, которая содержит планы обслуживания SharePoint Online, Lync Online и Exchange Online.

POST https://graph.windows.net/myorganization/users/alexd@a830edad9050849NDA1.onmicrosoft.com/assignLicense?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net
Content-Length: 35

{
  "addLicenses":[{"disabledPlans":[ ],"skuId":"6fd2c87f-b296-42f0-b197-1e91e994b900"}],
  "removeLicenses":[ ]
}

Этот запрос обновляет лицензию пользователя путем отключения определенных планов. В этом примере имеются два отключенных плана (SharePointOnline и LyncOnline) и остается включенным только план обслуживания Exchange.

POST https://graph.windows.net/myorganization/users/alexd@a830edad9050849NDA1.onmicrosoft.com/assignLicense?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net
Content-Length: 35

{ 
  "addLicenses":[  { "disabledPlans":  [”5dbe027f-2339-4123-9542-606e4d348a72”,
                                        “0feaeb32-d00e-4d66-bd5a-43b5b83db82c” ], 

                      "skuId":"6fd2c87f-b296-42f0-b197-1e91e994b900"
                   }  

                 ],
   "removeLicenses":[ ]

 }

Этот последний запрос показывает, как удалять лицензию у пользователя.

POST https://graph.windows.net/myorganization/users/alexd@a830edad9050849NDA1.onmicrosoft.com/assignLicense?api-version=1.5 HTTP/1.1
Authorization: Bearer eyJ0eX ... FWSXfwtQ
Content-Type: application/json
Host: graph.windows.net
Content-Length: 35

{
  "addLicenses":[ ],

  "removeLicenses":["6fd2c87f-b296-42f0-b197-1e91e994b900"]
}

changePassword: изменение пароля пользователя, выполнившего вход

Действие changePassword позволяет пользователю, выполнившему вход, изменить свой пароль.

Примечание. Это действие может вызываться только для пользователя, выполнившего вход. Для обращения к операции можно использовать не только псевдоним me, но и /users/<objectId>/changePassword и /users/userPrincipalName/changePassword, однако последние два режима доступны только в том случае, если действие направлено на пользователя, который выполнил вход.

Важно. Требуется версия 1.6 или более поздняя.

{
    "api":  "MeOps",
    "operation":    "changePassword" 
}

Текст запроса

Имя свойства Тип Обязательно Описание
currentPassword Edm.String Да Текущий пароль пользователя, выполнившего вход.
newPassword Edm.String Да Новый пароль.

Текст ответа

Отсутствует.

restore: восстановление удаленного приложения

Функция restore вызывается в удаленном приложении для его восстановления в каталоге.

Примечание. Удаленные приложения можно найти посредством чтения коллекции ресурсов deletedApplications. Например, выполнение операции GET в следующий URL-адрес возвращает удаленные приложения, связанные с организацией https://graph.windows.net/myorganization/deletedApplications?api-version=1.5.

Важно. Требуется версия 1.5 или более поздняя.

{
    "api":  "Functions",
    "operation":    "restore" 
}

Текст запроса

Имя свойства Тип Обязательно Описание
identifierUris Collection(Edm.String) Нет Коллекция URI идентификаторов для приложения. Они будут устанавливаться в свойстве identifierUris в восстановленном приложении [Application]. Если этот параметр опущен, свойство identifierUris сохранит свое исходное значение.

Текст ответа

Тип Описание
[Приложение] Восстановленное приложение.

verify: проверка владения доменом (предварительная версия)

Действие verify применяется к домену для проверки его владельца.

Важно. Действие применяется только к непроверенному домену (свойство isVerified объекта [Domain] имеет значение false). Поддерживается только в бета-версии.

{
    "api":  "Functions",
    "operation":    "verify" 
}

Текст запроса

Отсутствует.

Текст ответа

Тип Описание
[Domain] Проверяемый домен Свойство IsVerified указывает, установлен ли владелец домена.

Дополнительные ресурсы

  • Дополнительные сведения о функциях, возможностях и предварительных версиях функций в Graph API см. в статье Основные понятия API Graph.

applications: Get application properties by object ID 

GET https://graph.windows.net/myorganization/applications/{application_oid}?api-version

Parameters

ParameterTypeValueNotes
URL
application_oidstring

00009987-f6d8-4957-a6ca-7848d986ffff

The object id of the application.
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
GET https://graph.windows.net/myorganization/applications/00009987-f6d8-4957-a6ca-7848d986ffff?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Collection(Microsoft.DirectoryServices.directoryObjects/@Element)",
  "odata.type": "Microsoft.DirectoryServices.Application",
  "objectType": "Application",
  "objectId": "35418b3b-476c-4271-81a8-6db65d397ff4",
  "deletionTimestamp": null,
  "addIns": [],
  "allowActAsForAllClients": null,
  "appBranding": null,
  "appCategory": null,
  "appData": null,
  "appId": "1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1",
  "appMetadata": {
    "version": 0,
    "data": [
      {
        "key": "ApplicationMetadata",
        "value": "eyJBcHBsaWNhd..."
      }
    ]
  },
  "appRoles": [],
  "availableToOtherTenants": true,
  "displayName": "Test App",
  "encryptedMsiApplicationSecret": null,
  "errorUrl": null,
  "groupMembershipClaims": "None",
  "homepage": null,
  "identifierUris": [],
  "keyCredentials": [
    {
      "customKeyIdentifier": "pZMUkCG+igju29A1o/BYhnWffff=",
      "endDate": "2017-10-11T07:00:00Z",
      "keyId": "dceb697c-477a-4a25-be87-38282995ffff",
      "startDate": "2012-09-11T07:00:00Z",
      "type": "AsymmetricX509Cert",
      "usage": "Verify",
      "value": null
    },
    {
      "customKeyIdentifier": "pEFcLQgJrxgCgQwBbtV/G5Cffff=",
      "endDate": "2017-06-19T07:00:00Z",
      "keyId": "fed7d654-4ae7-4a53-bd60-71dc7eb0ffff",
      "startDate": "2012-05-19T07:00:00Z",
      "type": "AsymmetricX509Cert",
      "usage": "Verify",
      "value": null
    }
  ],
  "knownClientApplications": [],
  "logoUrl": null,
  "logoutUrl": null,
  "oauth2AllowImplicitFlow": false,
  "oauth2AllowUrlPathMatching": false,
  "oauth2Permissions": [],
  "oauth2RequirePostResponse": false,
  "passwordCredentials": [],
  "publicClient": false,
  "recordConsentConditions": null,
  "replyUrls": [],
  "requiredResourceAccess": [],
  "samlMetadataUrl": null,
  "supportsConvergence": false,
  "tokenEncryptionKeyId": null
}

applicationsByAppId: Get application properties by application ID 

GET https://graph.windows.net/myorganization/applicationsByAppId/{application_id}?api-version

Parameters

ParameterTypeValueNotes
URL
application_idstring

1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1

The application ID (GUID) of the application.
Query
api-versionstring

1.6

The version of the Graph API to target. Required.
GET https://graph.windows.net/myorganization/applicationsByAppId/1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Application/@Element",
  "odata.type": "Microsoft.DirectoryServices.Application",
  "objectType": "Application",
  "objectId": "35418b3b-476c-4271-81a8-6db65d397ff4",
  "deletionTimestamp": null,
  "addIns": [],
  "allowActAsForAllClients": null,
  "appBranding": null,
  "appCategory": null,
  "appData": null,
  "appId": "1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1",
  "appMetadata": {
    "version": 0,
    "data": [
      {
        "key": "ApplicationMetadata",
        "value": "eyJBcHBsaWNhd..."
      }
    ]
  },
  "appRoles": [],
  "availableToOtherTenants": true,
  "displayName": "Test App",
  "encryptedMsiApplicationSecret": null,
  "errorUrl": null,
  "groupMembershipClaims": "None",
  "homepage": null,
  "identifierUris": [],
  "keyCredentials": [
    {
      "customKeyIdentifier": "pZMUkCG+igju29A1o/BYhnWffff=",
      "endDate": "2017-10-11T07:00:00Z",
      "keyId": "dceb697c-477a-4a25-be87-38282995ffff",
      "startDate": "2012-09-11T07:00:00Z",
      "type": "AsymmetricX509Cert",
      "usage": "Verify",
      "value": null
    },
    {
      "customKeyIdentifier": "pEFcLQgJrxgCgQwBbtV/G5Cffff=",
      "endDate": "2017-06-19T07:00:00Z",
      "keyId": "fed7d654-4ae7-4a53-bd60-71dc7eb0ffff",
      "startDate": "2012-05-19T07:00:00Z",
      "type": "AsymmetricX509Cert",
      "usage": "Verify",
      "value": null
    }
  ],
  "knownClientApplications": [],
  "logoUrl": null,
  "logoutUrl": null,
  "oauth2AllowImplicitFlow": false,
  "oauth2AllowUrlPathMatching": false,
  "oauth2Permissions": [],
  "oauth2RequirePostResponse": false,
  "passwordCredentials": [],
  "publicClient": false,
  "recordConsentConditions": null,
  "replyUrls": [],
  "requiredResourceAccess": [],
  "samlMetadataUrl": null,
  "supportsConvergence": false,
  "tokenEncryptionKeyId": null
}

Response List

Status CodeDescription
200OK. Indicates success. Returns the application object ID.

checkMemberGroups: Check for membership in a list of groups 

POST https://graph.windows.net/myorganization/{resource_collection}/{resource_id}/checkMemberGroups?api-version

Parameters

ParameterTypeValueNotes
URL
resource_collectionstring

users

Specifies the resource collection to target. Acceptable values are users, groups, contacts, and servicePrincipals.
resource_idstring

alexd@a830edad9050849NDA1.onmicrosoft.com

Specifies the user, contact, group, or service principal for which membership is to be checked. For contacts, groups, and service principals the entity-identifier should be an object ID (GUID); for users, it can be either the object ID or the user principal name (UPN)..
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "groupIds": [
    "8ab3f116-1afb-44cb-8e61-6b20cb1e353c",
    "be78b7e2-a94a-4ab0-9bb4-403977cc7ec6",
    "cf61b8c9-3626-4fe4-b2f7-ac31fa905605"
  ]
}
POST https://graph.windows.net/myorganization/users/alexd%40a830edad9050849NDA1.onmicrosoft.com/checkMemberGroups?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Collection(Edm.String)",
  "value": [
    "8ab3f116-1afb-44cb-8e61-6b20cb1e353c",
    "be78b7e2-a94a-4ab0-9bb4-403977cc7ec6"
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. The object IDs of the groups in the request that the target user, contact, group, or service principal has either direct or transitive membership in are returned.

getAvailableExtensionProperties: Get the registered extension properties in a directory 

POST https://graph.windows.net/myorganization/getAvailableExtensionProperties?api-version

Parameters

ParameterTypeValueNotes
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "isSyncedFromOnPremises": false
}

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects",
  "value": [
    {
      "odata.type": "Microsoft.DirectoryServices.ExtensionProperty",
      "objectType": "ExtensionProperty",
      "objectId": "d6a8bfec-893d-46e4-88fd-7db5fcc0fa62",
      "deletionTimestamp": null,
      "appDisplayName": "SampleApp",
      "name": "extension_4d405aa8baa04fb494d3e0571fd9fd71_skypeId",
      "dataType": "String",
      "isSyncedFromOnPremises": false,
      "targetObjects": [
        "User"
      ]
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. A collection that contains the extension properties is returned.

getMemberGroups: Get group memberships (transitive) 

POST https://graph.windows.net/myorganization/{resource_collection}/{resource_id}/getMemberGroups?api-version

Parameters

ParameterTypeValueNotes
URL
resource_collectionstring

users

Specifies the resource collection to target. Acceptable values are users, groups, contacts, and servicePrincipals.
resource_idstring

alexd@a830edad9050849NDA1.onmicrosoft.com

Specifies the user, contact, group, or service principal for which group memberships are to be returned. For contacts, groups, and service principals the entity-identifier should be an object ID (GUID); for users, it can be either the object ID or the user principal name (UPN)..
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "securityEnabledOnly": false
}
POST  https://graph.windows.net/myorganization/users/alexd%40a830edad9050849NDA1.onmicrosoft.com/getMemberGroups?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Collection(Edm.String)",
  "value": [
    "8ab3f116-1afb-44cb-8e61-6b20cb1e353c",
    "be78b7e2-a94a-4ab0-9bb4-403977cc7ec6",
    "5e624f44-d38d-4943-b07c-2bad078f52ff"
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. The object IDs of the groups that the target user, contact, group, or service principal has either direct or transitive membership in are returned.

getMemberObjects: Get group and directory role memberships (transitive) 

POST https://graph.windows.net/myorganization/{resource_collection}/{resource_id}/getMemberObjects?api-version

Parameters

ParameterTypeValueNotes
URL
resource_collectionstring

users

Specifies the resource collection to target. Acceptable values are users, groups, contacts, and servicePrincipals.
resource_idstring

alexd@a830edad9050849NDA1.onmicrosoft.com

Specifies the user, contact, group, or service principal for which group and directory role memberships are to be returned. For contacts, groups, and service principals the entity-identifier should be an object ID (GUID); for users, it can be either the object ID or the user principal name (UPN)..
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "securityEnabledOnly": false
}
POST https://graph.windows.net/myorganization/users/alexd%40a830edad9050849NDA1.onmicrosoft.com/getMemberObjects?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myortanization/$metadata#Collection(Edm.String)",
  "value": [
    "8ab3f116-1afb-44cb-8e61-6b20cb1e353c",
    "be78b7e2-a94a-4ab0-9bb4-403977cc7ec6",
    "5e624f44-d38d-4943-b07c-2bad078f52ff"
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. The object IDs of the groups and directory roles that the target user, contact, group, or service principal has either direct or transitive membership in are returned.

getObjectsByObjectIds: Get objects from a list of object IDs 

POST https://graph.windows.net/myorganization/getObjectsByObjectIds?api-version

Parameters

ParameterTypeValueNotes
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "objectIds": [
    "c57cdc98-0dcd-4f90-a82f-c911b288bab9",
    "cc9869f0-6ac0-4d00-bc24-621a2d949d35",
    "477c2fe9-b0e7-4661-8564-ba170666f058",
    "beb9a3bb-2fff-4d5f-99d8-0ce169e8bed7"
  ],
  "types": [
    "group"
  ]
}

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects",
  "value": [
    {
      "odata.type": "Microsoft.DirectoryServices.Group",
      "objectType": "Group",
      "objectId": "c57cdc98-0dcd-4f90-a82f-c911b288bab9",
      "deletionTimestamp": null,
      "description": "Marketing Group",
      "dirSyncEnabled": null,
      "displayName": "Marketing",
      "lastDirSyncTime": null,
      "mail": null,
      "mailNickname": "cdf76b17-0734-41bc-9c24-9a7af93f3502",
      "mailEnabled": false,
      "onPremisesSecurityIdentifier": null,
      "provisioningErrors": [],
      "proxyAddresses": [],
      "securityEnabled": true
    },
    {
      "odata.type": "Microsoft.DirectoryServices.Group",
      "objectType": "Group",
      "objectId": "cc9869f0-6ac0-4d00-bc24-621a2d949d35",
      "deletionTimestamp": null,
      "description": "Engineering Group",
      "dirSyncEnabled": null,
      "displayName": "Engineering",
      "lastDirSyncTime": null,
      "mail": null,
      "mailNickname": "ef3b8cc1-721b-4452-9e30-9867d1de80ea",
      "mailEnabled": false,
      "onPremisesSecurityIdentifier": null,
      "provisioningErrors": [],
      "proxyAddresses": [],
      "securityEnabled": true
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. A collection that contains the directory objects that match the search criterea is returned.

isMemberOf: Check membership in a specific group (transitive) 

POST https://graph.windows.net/myorganization/isMemberOf?api-version

Parameters

ParameterTypeValueNotes
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "groupId": "5e624f44-d38d-4943-b07c-2bad078f52ff",
  "memberId": "ea59e4d3-a7a1-4b5b-b65f-a25fcc0c0f99"
}

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Edm.Boolean",
  "value": true
}

Response List

Status CodeDescription
200OK. Indicates success. Returns true if the user, contact, group, or service principal is a member of the specified group; otherwsie, false.

servicePrincipalsByAppId: Get service principal object ID by application ID 

GET https://graph.windows.net/myorganization/servicePrincipalsByAppId/{application_id}/objectId?api-version

Parameters

ParameterTypeValueNotes
URL
application_idstring

1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1

The application ID (GUID) of the service principal.
Query
api-versionstring

1.6

The version of the Graph API to target. Required.
GET https://graph.windows.net/myorganization/servicePrincipalsByAppId/1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1/objectId?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Edm.String",
  "value": [
    "00b4e797-7017-4720-b187-b01981c820d6"
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. Returns the service principal object ID of the specified application ID.

verify: Verify ownership of a domain 

POST https://graph.windows.net/myorganization/domains({domain_name})/verify?api-version

Parameters

ParameterTypeValueNotes
URL
domain_namestring

contoso.com

The fully qualified domain name of the target domain. Must be enclosed in single quotes.
Query
api-versionstring

1.6

The version of the Graph API to target. Required.
POST https://graph.windows.net/myorganization/domains(contoso.com)/verify?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#domains/@Element",
  "authenticationType": "Managed",
  "availabilityStatus": "AvailableImmediately",
  "isAdminManaged": true,
  "isDefault": false,
  "isInitial": false,
  "isRoot": true,
  "isVerified": true,
  "name": "contoso.com",
  "supportedServices": []
}

Response List

Status CodeDescription
200OK. Indicates success. Returns the Domain object. The isVerified property indicates whether the ownership of the domain has been verified successfully.

addKey: Add a KeyCredential for an application 

POST https://graph.windows.net/myorganization/applications/{application_oid}/addKey?api-version

Parameters

ParameterTypeValueNotes
URL
application_oidstring

00009987-f6d8-4957-a6ca-7848d986ffff

The object id of the application.
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "keyCredential": {
    "customKeyIdentifier": "6uv7gh",
    "endDate": "endDate=2017-10-11T07:00:00Z",
    "keyId": "633b1614-b669-47c5-961e-f4a45978ffff",
    "type": "AsymmetricX509Cert",
    "usage": "Verify",
    "value": null
  },
  "passwordCredential": null,
  "proof": "Bearer eyJ0eXAiOiJKv1..."
}
POST 
https://graph.windows.net/myorganization/applications/00009987-f6d8-4957-a6ca-7848d986ffff/addKey?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Collection(Microsoft.DirectoryServices.KeyCredential)",
  "value": [
    {
      "keyCredential": {
        "customKeyIdentifier": "6uv7gh",
        "type": "AsymmetricX509Cert",
        "usage": "Verify",
        "value": "MIZB9jVCACfEw="
      },
      "passwordCredential": null,
      "proof": "eyJ0eXAiOiJKv1"
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. Returns the application's new key credential and password credential directory object.
POST https://graph.windows.net/myorganization/applicationsByAppId/{application_id}/addKey?api-version

Parameters

ParameterTypeValueNotes
URL
application_idstring

1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1

The application ID (GUID) of the application.
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "keyCredential": {
    "customKeyIdentifier": "6uv7gh",
    "type": "X509CertAndPassword",
    "usage": "Sign",
    "value": "MIIJgIBAzCCCbYGCSqGSIb3gX1MIIF..."
  },
  "passwordCredential": {
    "value": "MKTr0w1ytHhemMDY"
  },
  "proof": "Bearer eyJ0eXAiOiJKv1..."
}
POST https://graph.windows.net/myorganization/applicationsByAppId/1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1/addKey?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#Collection(Microsoft.DirectoryServices.KeyCredential)",
  "value": [
    {
      "keyCredential": {
        "customKeyIdentifier": "JXyLFwBmN=",
        "endDate": "2017-10-11T07:00:00Z",
        "keyId": "633b1614-b669-47c5-961e-f4a45978ffff",
        "startDate": "2012-09-11T07:00:00Z",
        "type": "AsymmetricX509Cert",
        "usage": "Sign",
        "value": null
      }
    },
    {
      "keyCredential": {
        "customKeyIdentifier": "JXyLFwBmN=",
        "endDate": "2017-10-11T07:00:00Z",
        "keyId": "633b1614-b669-47c5-961e-f4a45978ffff",
        "startDate": "2012-09-11T07:00:00Z",
        "type": "Password",
        "usage": "Sign",
        "value": null
      }
    }
  ]
}

Response List

Status CodeDescription
200OK. Indicates success. Returns the application's new key credential and password credential directory object.

assignLicense: Add or remove licenses from a user 

POST https://graph.windows.net/myorganization/users/{user_id}/assignLicense?api-version

Parameters

ParameterTypeValueNotes
URL
user_idstring

alexd@a830edad9050849NDA1.onmicrosoft.com

The user ID. Can be the object ID (GUID) or the user principal name (someuser@a830edad9050849NDA1.onmicrosoft.com) of the target user.
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "addLicenses": [
    {
      "disabledPlans": [],
      "skuId": "6fd2c87f-b296-42f0-b197-1e91e994b900"
    }
  ],
  "removeLicenses": []
}
POST https://graph.windows.net/myorganization/users/alexd%40a830edad9050849NDA1.onmicrosoft.com/assignLicense?api-version=1.6

Response

Status Code:200

Content-Type: application/json

none

Response List

Status CodeDescription
200OK. Indicates success. No response body is returned.

changePassword: Change password of the signed-in user 

POST https://graph.windows.net/me/changePassword?api-version

Parameters

ParameterTypeValueNotes
Query
api-versionstring

1.6

Specifies the version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "currentPassword": "Test1234!",
  "newPassword": "Test5678!"
}

Response

Status Code:204

Content-Type: application/json

none

Response List

Status CodeDescription
204No Content. Indicates success. No response body is returned.

removeKey: Remove a KeyCredential for an application 

POST https://graph.windows.net/myorganization/applications/{application_oid}/removeKey?api-version

POST https://graph.windows.net/myorganization/applications/{application_oid}/removeKey?api-version=1.6

Response

Status Code:204

Content-Type: none

none

Response List

Status CodeDescription
204No Content. Indicates success. No response body is returned.
POST https://graph.windows.net/myorganization/applicationsByAppId/{application_id}/removeKey?api-version

POST https://graph.windows.net/myorganization/applicationsByAppId/1062a13d-f7e5-4ea7-8d24-427f6ff1e5e1/removeKey?api-version=1.6

Response

Status Code:204

Content-Type: none

none

Response List

Status CodeDescription
204No Content. Indicates success. No response body is returned.

restore: Restore a deleted application 

POST https://graph.windows.net/myorganization/deletedApplications/{application_id}/restore?api-version

Parameters

ParameterTypeValueNotes
URL
application_idstring

1e22de0f-0ed1-4c01-b725-a822632467e3

The object ID (GUID) of the application to restore.
Query
api-versionstring

1.6

The version of the Graph API to target. Beginning with version 1.5, the api-version string is represented in major.minor format. Prior releases were represented as date strings: '2013-11-08' and '2013-04-05'. Required.
Body

Content-Type: application/json

{
  "identifierUris": [
    "https://restoredApp/"
  ]
}
POST https://graph.windows.net/myorganization/deletedApplications/1e22de0f-0ed1-4c01-b725-a822632467e3/restore?api-version=1.6

Response

Status Code:200

Content-Type: application/json

{
  "odata.metadata": "https://graph.windows.net/myorganization/$metadata#directoryObjects/Microsoft.DirectoryServices.Application/@Element",
  "odata.type": "Microsoft.DirectoryServices.Application",
  "objectType": "Application",
  "objectId": "1e22de0f-0ed1-4c01-b725-a822632467e3",
  "deletionTimestamp": null,
  "appId": "f4ecf40c-e94f-4d79-af83-f920f81bcb66",
  "appRoles": [],
  "availableToOtherTenants": false,
  "displayName": "Sample App 1",
  "errorUrl": null,
  "groupMembershipClaims": null,
  "homepage": "https://localhost",
  "identifierUris": [
    "https://restoredApp/"
  ],
  "keyCredentials": [],
  "knownClientApplications": [],
  "logoutUrl": null,
  "oauth2AllowImplicitFlow": false,
  "oauth2AllowUrlPathMatching": false,
  "oauth2Permissions": [],
  "oauth2RequirePostResponse": false,
  "passwordCredentials": [],
  "publicClient": null,
  "replyUrls": [
    "https://localhost"
  ],
  "requiredResourceAccess": [
    {
      "resourceAppId": "00000002-0000-0000-c000-000000000000",
      "resourceAccess": [
        {
          "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
          "type": "Scope"
        }
      ]
    }
  ],
  "samlMetadataUrl": null
}

Response List

Status CodeDescription
200OK. Indicates success. Returns the restored Application object. The identifierUris property in the restored application is set or restored according to the identifierUris collection specified in the request.