Тип ресурса servicePrincipal

Пространство имен: microsoft.graph

Представляет экземпляр приложения в каталоге. Наследуется от directoryObject.

Ресурс agentIdentityBlueprintPrincipal наследует от этого объекта.

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

Методы

Метод	Возвращаемый тип	Описание
Список	Коллекция servicePrincipal	Получение списка объектов servicePrincipal.
Создание	servicePrincipal	Создание нового объекта servicePrincipal.
Получение	servicePrincipal	Чтение свойств и связей объекта servicePrincipal.
Обновление	servicePrincipal	Обновление объекта servicePrincipal.
Upsert	servicePrincipal	Создайте новый ServicePrincipal, если его нет, или обновите свойства существующего ServicePrincipal.
Delete	Нет	Удаление объекта servicePrincipal.
Получение разницы	Коллекция servicePrincipal	Получение добавочных изменений для субъектов-служб.
Список созданных объектов	Коллекция directoryObject	Получение коллекции объектов createdObject.
Список корпоративных объектов	Коллекция directoryObject	Получение коллекции объектов ownedObject.
Удаленные элементы
List	Коллекция directoryObject	Извлечение списка недавно удаленных объектов servicePrincipal.
Получение	directoryObject	Извлечение свойств недавно удаленного объекта servicePrincipal.
Восстановление	directoryObject	Восстановление недавно удаленного объекта servicePrincipal.
Удалить без возможности восстановления	Нет	Окончательное удаление объекта servicePrincipal.
Назначение ролей приложений
Перечисление appRoleAssignments	Коллекция appRoleAssignment	Получите роли приложений, назначенные этому субъекту-службе.
Добавление объекта appRoleAssignment	appRoleAssignment	Назначение роли приложения субъекту-службе.
Удаление объекта appRoleAssignment	Нет	Удаление назначения роли приложения субъекта-службы.
List appRoleAssignedTo	Коллекция appRoleAssignment	Создание пользователей, ролей и назначенных ролей приложений для этого субъекта-службы.
Add appRoleAssignedTo	appRoleAssignment	Назначение роли для этого субъекта-службы пользователю, группе или субъекту-службе.
Remove appRoleAssignedTo	Нет	Удаление назначенной роли этого субъекта-службы у пользователя, группы или субъекта-службы.
Сертификаты и секреты
Добавление пароля	passwordCredential	Добавление стойкого пароля или секрета в servicePrincipal.
Удаление пароля	passwordCredential	Удаление пароля или секрета из servicePrincipal.
Добавление ключа	keyCredential	Добавление учетных данных ключа объекту servicePrincipal.
Удаление ключа	Нет	Удаление учетных данных ключа объекта servicePrincipal.
Добавление сертификата подписи маркера	selfSignedCertificate	Добавление самозаверяющего сертификата в субъект-службу. В основном используется для настройки приложений единого входа на основе SAML из галереи Microsoft Entra.
Классификация делегированных разрешений
List	Коллекция delegatedPermissionClassification	Получение классификаций для делегированных разрешений, предоставленных этим субъектом-службой.
Добавление	delegatedPermissionClassification	Добавление классификации для делегированных разрешений, предоставленных этим субъектом-службой.
Remove	Нет	Удаление классификации для делегированных разрешений, предоставленных этим субъектом-службой.
Делегированные разрешения (OAuth2)
List	Коллекция oAuth2PermissionGrant	Получите предоставление делегированных разрешений, предоставляющих этому объекту-службе доступ к API от имени пользователя, вошедшего в систему.
Членство.
Перечисление memberOf	Коллекция directoryObject	Получение групп, непосредственным участником которых является субъект-служба, из свойства навигации memberOf.
Укажите транзитивный член	Коллекция directoryObject	Перечисление групп, в которых участвует субъект-служба. Эта операция является транзитивной и включает группы, в которых состоит субъект-служба.
Проверка членства в группах	Коллекция String	Проверка участия в указанном списке групп.
Проверка объектов-элементов	Коллекция String	Проверка участия в указанном списке группы, роли каталога или объектах административных единиц.
Получение групп пользователя	Коллекция String	Список групп, в которых участвует субъект-служба.
Вывод объектов членства	Коллекция String	Получение списка групп, административных единиц и ролей каталога, в которых состоит субъект-служба.
Владельцы
List	Коллекция directoryObject	Получить владельцев субъекта-службы.
Добавление	directoryObject	Назначение владельца субъекту-службе. Владельцами субъекта-службы могут быть пользователи или другие субъекты службы.
Remove	Нет	Удаление владельца из субъекта-службы. Рекомендуется рекомендовать субъектам службы иметь не менее двух владельцев.

Свойства

Важно!

Определенное использование $filter и параметра запроса $search поддерживается только при применении заголовка ConsistencyLevel с присвоенным значением eventual и $count. Дополнительные сведения см. в статье Расширенные возможности запросов для объектов каталога.

Свойство	Тип	Описание
accountEnabled	Логический	Значение true, если учетная запись субъекта-службы включена. В противном случае используется значение false. Если установлено значение false, то пользователи не смогут войти в это приложение, даже если им оно назначено. Поддерживает $filter (eq, ne, not, in).
addIns	Коллекция addIn	Определяет пользовательское поведение, которое служба может использовать для вызова приложения в определенных контекстах. Например, приложения, которые способны визуализировать файловые потоки, могут установить свойство addIns для его функции "FileHandler". Это позволяет службам, таким как Microsoft 365, вызывать приложение в контексте документа, над которым работает пользователь.
alternativeNames	Коллекция строк	Используется для получения субъектов-служб по подписке, идентификации группы ресурсов и полных идентификаторов ресурсов для управляемых удостоверений. Поддерживает $filter (eq, not, ge, le, startsWith).
appDescription	Строка	Описание, предоставляемое связанным приложением.
appDisplayName	String	Отображаемое имя, предоставляемое связанным приложением. Максимальная длина: 256 символов.
appId	String	Уникальный идентификатор для связанного приложения (его свойство appId). Альтернативный ключ. Поддерживает $filter (eq, ne, not, in, startsWith).
applicationTemplateId	Строка	Уникальный идентификатор applicationTemplate. Поддерживает $filter (eq, not, ne). Только для чтения. null если субъект-служба не был создан на основе шаблона приложения.
appOwnerOrganizationId	Guid	Содержит идентификатор клиента, на котором зарегистрировано приложение. Применимо только для субъектов-служб на основе приложений. Поддерживает $filter (eq, ne, NOT, ge, le).
appRoleAssignmentRequired	Boolean	Указывает, нужно ли предоставлять назначение роли пользователям или другим субъектам-службам для этого субъекта-службы, прежде чем пользователи смогут выполнять вход, а приложения — получать маркеры. Значение по умолчанию — false. Значение NULL не допускается. Поддерживает $filter (eq, ne, NOT).
appRoles	Коллекция appRole	Роли, предоставляемые приложением, связанным с этим субъектом-службой. Дополнительные сведения см. в разделе определение свойства appRoles для сущности application . Значение null не допускается. Роли приложений и открытые области делегированных разрешений (oauth2PermissionScopes) по умолчанию используют ограничение в 700 определений разрешений для каждого субъекта-службы, включая определения, унаследованные от приложения, и определения, добавленные непосредственно в субъект-службу. Учитываются как включенные, так и отключенные определения. В этом ограничении учитываются определения, а не назначения ролей приложений. Правила подсчета, поведение существующих объектов, превышающих ограничение, и рекомендации по проектированию см. в статье Ограничения ролей приложений.
createdByAppId	String	Идентификатор AppId приложения, создавшего этот субъект-службу. Внутренняя настройка с помощью Microsoft Entra ID. Только для чтения.
customSecurityAttributes	customSecurityAttributeValue	Открытый сложный тип, который содержит значение настраиваемого атрибута безопасности, назначенного объекту каталога. Допускается значение null. Требуется $select получение. Поддерживает $filter (eq, ne, not, startsWith). Значение фильтра чувствительно к регистру. Чтобы прочитать это свойство, вызывающему приложению необходимо назначить разрешение CustomSecAttributeAssignment.Read.All . Чтобы записать это свойство, вызывающему приложению должны быть назначены разрешения CustomSecAttributeAssignment.ReadWrite.All . Чтобы прочитать или записать это свойство в делегированных сценариях, администратору должна быть назначена роль администратора назначения атрибутов .
deletedDateTime	DateTimeOffset	Дата и время удаления субъекта-службы. Только для чтения.
description	String	Поле с произвольным текстом для предоставления внутренним пользователям описания субъекта-службы. На порталах конечных пользователей, таких как MyApps , отображается описание приложения в этом поле. Максимально допустимый размер — 1024 символа. Поддерживает $filter (eq, ne, not, ge, le, startsWith) и $search.
disabledByMicrosoftStatus	Строка	Указывает, отключила ли корпорация Майкрософт зарегистрированное приложение. Возможные значения: null (значение по умолчанию), NotDisabledи DisabledDueToViolationOfServicesAgreement (причины: подозрительные, оскорбительные или злонамеренные действия либо нарушение Соглашения об использовании служб Майкрософт). Поддерживает $filter (eq, ne, not).
displayName	String	Отображаемое имя для субъекта-службы. Поддерживает $filter (eq, ne, not, ge, le, in, startsWith и eq для значений null), $search и $orderby.
homepage	String	Главная или начальная страница приложения.
id	String	Уникальный идентификатор для субъекта-службы. Наследуется от directoryObject. Ключ. Значение null не допускается. Только для чтения. Поддерживает $filter (eq, ne, not, in).
info	informationalUrl	Базовые данные профиля для полученного приложения, такие как URL-адреса маркетинга, поддержки, условий обслуживания и заявления о конфиденциальности. Условия обслуживания и заявление о конфиденциальности отображаются в окне запроса согласия пользователя. Дополнительные сведения см. в следующих разделах: Добавление условий обслуживания и заявления о конфиденциальности для зарегистрированных приложений Microsoft Entra. Поддерживает $filter (eq, ne, not, ge, le и eq для значений null).
keyCredentials	Коллекция keyCredential	Коллекция ключевых учетных данных, связанных с субъектом-службой. Значение null не допускается. Поддерживает $filter (eq, not, ge, le).
loginUrl	String	Указывает URL-адрес, по которому поставщик услуг перенаправляет пользователя в Microsoft Entra ID для проверки подлинности. Microsoft Entra ID использует URL-адрес для запуска приложения из Microsoft 365 или Microsoft Entra Мои приложения. Если этот параметр пуст, Microsoft Entra ID выполняет вход, инициированный IdP, для приложений, настроенных с использованием единого входа на основе SAML. Пользователь запускает приложение из Microsoft 365, Microsoft Entra Мои приложения или Microsoft Entra URL-адреса единого входа.
logoutUrl	String	Указывает URL-адрес, который служба авторизации Майкрософт использует для выхода пользователя с помощью протоколов выхода OpenID Connect, фронт-канала, резервного канала или SAML.
notes	String	Поле с произвольным текстом для записи сведений о субъекте-службе, обычно применяемых в рабочих целях. Максимально допустимый размер — 1024 символа.
notificationEmailAddresses	Коллекция строк	Указывает список адресов электронной почты, по которым Microsoft Entra ID отправляет уведомление, когда срок действия активного сертификата приближается к дате окончания срока действия. Это касается только сертификатов, используемых для подписи маркера SAML, выданного для приложений Microsoft Entra Gallery.
oauth2PermissionScopes	Коллекция permissionScope	Делегированные разрешения, предоставляемые приложением. Дополнительные сведения см. в свойстве oauth2PermissionScopes свойства API объекта приложения. Значение null не допускается. Для этих областей и ролей AppRoles используется ограничение по умолчанию в 700 определений разрешений на один субъект-служба. Учитываются как включенные, так и отключенные определения. Правила подсчета, поведение существующих объектов, превышающих ограничение, и рекомендации по проектированию см. в статье Ограничения ролей приложений.
passwordCredentials	Коллекция passwordCredential	Коллекция учетных данных паролей, связанных с приложением. Значение null не допускается.
preferredSingleSignOnMode	Строка	Указывает режим единого входа, настроенный для этого приложения. Microsoft Entra ID использует предпочтительный режим единого входа для запуска приложения из Microsoft 365 или портала «Мои приложения». Поддерживаемые значения: password, saml, notSupported и oidc. Примечание. Это поле может быть null для старых приложений SAML и приложений OIDC, для которых оно не настраивается автоматически.
preferredTokenSigningKeyThumbprint	String	Это свойство можно использовать в приложениях SAML (приложения, для которых параметру preferredSingleSignOnMode установлено значение saml), чтобы управлять сертификатом, используемым для подписи ответов SAML. Для приложений, не являющихся SAML, не пишите и не полагайтесь иным образом на это свойство.
replyUrls	Коллекция String	URL-адреса, которым отправляются маркеры пользователей для входа с помощью связанного приложения, или URI перенаправления, которым отправляются коды авторизации OAuth 2.0 и маркеры доступа для связанного приложения. Значение null не допускается.
resourceSpecificApplicationPermissions	Коллекция resourceSpecificPermission	Разрешения приложения для конкретных ресурсов, предоставляемых этим приложением. В настоящее время разрешения для конкретных ресурсов поддерживаются только для приложений Teams, получающих доступ к определенным чатам и командам с помощью Microsoft Graph. Только для чтения.
samlSingleSignOnSettings	samlSingleSignOnSettings	Коллекция для параметров, связанных с единым входом SAML.
ServicePrincipalNames	Коллекция объектов string	Содержит список объектов identifiersUris, скопированных из связанного объекта application. К гибридным приложениям можно добавить дополнительные значения. Эти значения можно использовать для определения разрешений, предоставляемых этим приложением в Microsoft Entra ID. Пример. Клиентские приложения могут указать URI ресурса, основанный на значениях этого свойства, чтобы получить маркер доступа, который является URI, возвращаемым в утверждении aud. Оператор "any" требуется для выражений фильтров, применяемых к многозначным свойствам. Значение null не допускается. Поддерживает $filter (eq, not, ge, le, startsWith).
servicePrincipalType	Строка	Указывает, что представляет субъект-служба: приложение, управляемое удостоверение или устаревшее приложение. Это свойство задается внутренним Microsoft Entra ID. Свойству servicePrincipalType можно присвоить три различных значения: Application - Субъект-сервис, представляющий приложение или сервис. Свойство appId определяет связанную регистрацию приложения и соответствует параметру appId объекта application, возможно, из другого клиента. Если регистрация связанного приложения отсутствует, маркеры для субъекта-службы не выдаются. ManagedIdentity – Субъект-служба, представляющий управляемое удостоверение. Субъектам-службам, представляющим управляемые удостоверения, можно предоставлять доступ и разрешения, но их нельзя обновлять или изменять напрямую. Legacy – Субъект-служба, представляющий приложение, созданное до регистрации приложения или в устаревшем интерфейсе. Устаревший субъект-служба может иметь учетные данные, имена субъектов-служб, URL-адреса ответов и другие свойства, которые могут изменяться авторизованным пользователем, но не имеет связанной регистрации приложения. Значение appId не связывает субъект-службу с регистрацией приложения. Субъект-службу можно использовать только в том клиенте, где он был создан. ServiceIdentity - Субъект-сервис, представляющий удостоверение агента. SocialIdp - Для внутреннего использования.
signInAudience	String	Указывает, учетные записи Майкрософт, которые поддерживаются для текущего приложения. Только для чтения. Поддерживаемые значения: AzureADMyOrg. Пользователи с рабочей или учебной учетной записью Майкрософт в клиенте Microsoft Entra моей организации (с одним клиентом). AzureADMultipleOrgs. Пользователи с рабочей или учебной учетной записью Майкрософт в клиенте Microsoft Entra любой организации (мультитенантный). AzureADandPersonalMicrosoftAccount. Пользователи с личной учетной записью Майкрософт, рабочей или учебной учетной записью в клиенте Microsoft Entra любой организации. PersonalMicrosoftAccount — пользователи только с личной учетной записью Майкрософт.
tags	Коллекция объектов string	Настраиваемые строки, которые можно использовать для классификации и определения субъекта-службы. Значение null не допускается. Значение представляет собой объединение строк, заданных здесь и в свойстве tags связанного объекта приложения. Поддерживает $filter (eq, not, ge, le, startsWith).
tokenEncryptionKeyId	String	Задает значение открытого ключа keyId из коллекции keyCredentials. Если конфигурация настроена, Microsoft Entra ID выдает маркеры для этого приложения, зашифрованные с использованием ключа, указанного этим свойством. Код приложения, получающий зашифрованный маркер, должен использовать соответствующий закрытый ключ для расшифровки маркера, прежде чем его можно будет применить для пользователя, выполнившего вход.
verifiedPublisher	verifiedPublisher	Указывает проверенного издателя приложения, связанного с этим субъектом-службой.

Связи

Важно!

Конкретное использование параметра $filter запроса поддерживается только в том случае, если используется заголовок ConsistencyLevel , заданный в eventual и $count. Дополнительные сведения см. в статье Расширенные возможности запросов для объектов каталога.

Связь	Тип	Описание
appManagementPolicies	Коллекция appManagementPolicy	Параметр appManagementPolicy, примененный к этому приложению.
appRoleAssignedTo	appRoleAssignment	Назначение ролей приложений для приложения или службы, предоставляемых пользователям, группам и другим субъектам-службам. Поддерживает $expand.
appRoleAssignments	Коллекция appRoleAssignment	Назначение роли приложения для другого приложения или службы, предоставляемых субъекту-службе. Поддерживает $expand.
claimsMappingPolicies	Коллекция claimsMappingPolicy	Типы ресурсов claimsMappingPolicy, назначенные субъекту-службе. Поддерживает $expand.
createdObjects	Коллекция directoryObject	Объекты каталога, созданные субъектом-службой. Только для чтения. Допускается значение null.
federatedIdentityCredentials	Коллекция federatedIdentityCredential	Федеративные удостоверения для управляемого субъекта-службы определенного типа. Поддерживает $expand и $filter (/$count eq 0, /$count ne 0).
homeRealmDiscoveryPolicies	Коллекция homeRealmDiscoveryPolicy	Типы ресурсов homeRealmDiscoveryPolicy, назначенные субъекту-службе. Поддерживает $expand.
memberOf	Коллекция directoryObject	Роли, в которых участвует субъект-служба. Методы HTTP: GET. Только для чтения. Допускается значение null. Поддерживает $expand.
oauth2PermissionGrants	Коллекция oAuth2PermissionGrant	Предоставленные делегированные разрешения, разрешающие этому субъекту-службе доступ к API от имени пользователя, вошедшего в систему. Только для чтения. Допускается значение null.
ownedObjects	Коллекция directoryObject	объектов каталога, принадлежащих этому субъекту-службе. Только для чтения. Допускается значение null. Поддерживает $expand, $select вложенные в $expand, и $filter (/$count eq 0, /$count ne 0, /$count eq 1, ). /$count ne 1
owners	Коллекция directoryObject	Объекты каталогов, владеющие этим объектом servicePrincipal. Владельцы — это набор пользователей без прав администратора или служебных субъектов, которым разрешено изменять этот объект. Поддерживает , (, , , ), и $select вложенные в $expand. /$count ne 1/$count eq 1/$count ne 0/$count eq 0$filter$expand
remoteDesktopSecurityConfiguration	remoteDesktopSecurityConfiguration	Объект remoteDesktopSecurityConfiguration, применяемый к этому субъекту службы. Поддерживает $filter (eq) для свойства isRemoteDesktopProtocolEnabled .
синхронизация	синхронизация	Представляет возможность синхронизации удостоверений Microsoft Entra через Microsoft API Graph.
tokenIssuancePolicies	Коллекция tokenIssuancePolicy	Политики tokenIssuancePoliciy, назначенные этому субъекту-службе.
tokenLifetimePolicies	Коллекция tokenLifetimePolicy	Типы ресурсов tokenLifetimePolicy, назначенные субъекту-службе.

Представление JSON

В следующем представлении JSON показан тип ресурса.

{
  "accountEnabled": true,
  "addIns": [{"@odata.type": "microsoft.graph.addIn"}],
  "alternativeNames": ["String"] ,
  "appDisplayName": "String",
  "appId": "String",
  "appOwnerOrganizationId": "Guid",
  "appRoleAssignmentRequired": true,
  "appRoles": [{"@odata.type": "microsoft.graph.appRole"}],
  "createdByAppId": "String",
  "customSecurityAttributes": {
    "@odata.type": "microsoft.graph.customSecurityAttributeValue"
  },
  "disabledByMicrosoftStatus": "String",
  "displayName": "String",
  "homepage": "String",
  "id": "String (identifier)",
  "info": {"@odata.type": "microsoft.graph.informationalUrl"},
  "keyCredentials": [{"@odata.type": "microsoft.graph.keyCredential"}],
  "logoutUrl": "String",
  "notes": "String",
  "oauth2PermissionScopes": [{"@odata.type": "microsoft.graph.permissionScope"}],
  "passwordCredentials": [{"@odata.type": "microsoft.graph.passwordCredential"}],
  "preferredTokenSigningKeyThumbprint": "String",
  "replyUrls": ["String"],
  "resourceSpecificApplicationPermissions": [{"@odata.type": "microsoft.graph.resourceSpecificPermission"}],
  "servicePrincipalNames": ["String"],
  "servicePrincipalType": "String",
  "tags": ["String"],
  "tokenEncryptionKeyId": "String",
  "verifiedPublisher": {"@odata.type": "microsoft.graph.verifiedPublisher"}
}