Обновление servicePrincipal

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

Обновление свойств объекта servicePrincipal. Этот API также может обновить объект agentIdentityBlueprintPrincipal , если свойство @odata.type имеет значение #microsoft.graph.agentIdentityBlueprintPrincipal.

Важно!

• Использование метода PATCH для настройки passwordCredential не поддерживается. Используйте методы addPassword и removePassword, чтобы обновить пароль или секрет для servicePrincipal.

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

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба	Правительство США L4	Правительство США L5 (DOD)	Китай управляется 21Vianet
✅	✅	✅	✅

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения	Разрешения с наименьшими привилегиями	Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись)	Application.ReadWrite.All	AgentIdentity.EnableDisable.All, AgentIdentity.ReadWrite.All, AgentIdentityBlueprintPrincipal.EnableDisable.All, Directory.ReadWrite.All
Делегированные (личная учетная запись Майкрософт)	Не поддерживается.	Не поддерживается.
Приложение	Application.ReadWrite.OwnedBy	AgentIdentity.EnableDisable.All, AgentIdentity.ReadWrite.All, AgentIdentityBlueprintPrincipal.EnableDisable.All, Application.ReadWrite.All, Directory.ReadWrite.All

Важно!

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

• Для мультитенантных приложений:
  • Администратор приложения
  • Администратор облачного приложения
• Для приложений с одним клиентом, в которых вызывающий пользователь является неадминантным пользователем, но является владельцем резервного приложения, у пользователя должна быть роль разработчика приложений .

Разрешения для определенных сценариев

• Чтобы обновить свойство customSecurityAttributes , выполните следующие действия:
  • В делегированных сценариях администратору должна быть назначена роль администратора назначения атрибутов , а приложению — делегированное разрешение CustomSecAttributeAssignment.ReadWrite.All .
  • В сценариях только для приложений, использующих разрешения Microsoft Graph, приложению должно быть предоставлено разрешение CustomSecAttributeAssignment.ReadWrite.All .

HTTP-запрос

Вы можете обратиться к субъекту-службе, используя его идентификатор или appId. Id и appId называются идентификатором объекта и идентификатором приложения (клиента) соответственно в регистрациях приложений в Центр администрирования Microsoft Entra.

PATCH /servicePrincipals/{id}
PATCH /servicePrincipals(appId='{appId}')

Заголовки запросов

Имя	Описание
Авторизация	Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type	application/json. Обязательно.

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

В тексте запроса укажите значения для соответствующих полей, которые необходимо обновить. Существующие свойства, которые не включены в текст запроса, сохраняют свои предыдущие значения или пересчитываются на основе изменений других значений свойств. Для достижения оптимальной производительности не следует включать существующие значения, которые не изменились.

Свойство	Тип	Описание
accountEnabled	Boolean	Значение true, если учетная запись субъекта-службы включена. В противном случае используется значение false.
addIns	addIn	Определяет пользовательское поведение, которое служба может использовать для вызова приложения в определенных контекстах. Например, приложения, которые способны визуализировать файловые потоки, могут установить свойство addIns для его функции "FileHandler". Это позволяет таким службам, как Microsoft 365, вызывать приложение в контексте документа, над которым работает пользователь.
alternativeNames	Коллекция строк	Используется для получения субъектов-служб по подписке, идентификации групп ресурсов и полных идентификаторов ресурсов для управляемых удостоверений.
appRoleAssignmentRequired	Boolean	Указывает, требуется ли appRoleAssignment пользователю или группе, прежде чем Microsoft Entra ID выдаст пользователю или маркер доступа приложению. Значение null не допускается.
appRoles	Коллекция appRole	Роли приложения, предоставляемые связанным приложением. Дополнительные сведения см. в определении свойства appRoles в ресурсе приложения . Значение null не допускается.
customSecurityAttributes	customSecurityAttributeValue	Открытый сложный тип, который содержит значение настраиваемого атрибута безопасности, назначенного объекту каталога. Чтобы обновить это свойство в делегированных сценариях, вызывающему субъекту должна быть назначена роль администратора назначения атрибутов, а приложению предоставлено делегированное разрешение CustomSecAttributeAssignment.ReadWrite.All . Чтобы обновить это свойство в сценариях только для приложений с разрешениями Microsoft Graph, приложению должно быть предоставлено разрешение CustomSecAttributeAssignment.ReadWrite.All .
displayName	String	Отображаемое имя для субъекта-службы.
homepage	String	Главная или начальная страница приложения.
keyCredentials	Коллекция keyCredential	Коллекция ключевых учетных данных, связанных с субъектом-службой. Значение null не допускается.
logoutUrl	String	Указывает URL-адрес, который будет использоваться службой авторизации Майкрософт для выхода пользователя с помощью протоколов front-channel, back-channel или SAML logout.
oauth2PermissionScopes	Коллекция permissionScope	Области разрешений OAuth 2.0, предоставляемые связанным приложением. Дополнительные сведения см. в определении свойства oauth2PermissionScopes для ресурса приложения . Значение null не допускается.
preferredSingleSignOnMode	Строка	Указывает режим единого входа, настроенный для этого приложения. Microsoft Entra ID использует предпочтительный режим единого входа для запуска приложения из Microsoft 365 или портала Мои приложения. Поддерживаемые значения: password, saml, external и oidc.
replyUrls	Коллекция String	URL-адреса, которым отправляются маркеры пользователей для входа с помощью связанного приложения, или URI перенаправления, которым отправляются коды авторизации OAuth 2.0 и маркеры доступа для связанного приложения. Значение null не допускается.
ServicePrincipalNames	Коллекция объектов string	Содержит список объектов identifiersUris, скопированных из связанного объекта application. К гибридным приложениям можно добавить дополнительные значения. Эти значения можно использовать для определения разрешений, предоставляемых этим приложением в Microsoft Entra ID. Пример. Клиентские приложения, запрашивающие разрешения на доступ к этому ресурсу, могут использовать эти URI для указания необходимых разрешений в свойстве requiredResourceAccess манифеста приложения или в колонке "Разрешения API" в интерфейсе регистрации приложений. Клиентские приложения могут указать URI ресурса, основанный на значениях этого свойства для получения маркера доступа, который является URI, возвращенным в утверждении "aud". Оператор "any" требуется для выражений фильтров, применяемых к многозначным свойствам. Значение null не допускается.
tags	Коллекция String	Настраиваемые строки, которые можно использовать для классификации и определения приложения. Значение null не допускается.
tokenEncryptionKeyId	String	Задает значение открытого ключа keyId из коллекции keyCredentials. После настройки Microsoft Entra ID выдает маркеры для этого приложения, зашифрованные с помощью ключа, указанного этим свойством. Код приложения, получающий зашифрованный маркер, должен использовать соответствующий закрытый ключ для расшифровки маркера, прежде чем его можно будет применить для пользователя, выполнившего вход.

Отклик

В случае успеха этот метод возвращает код отклика 204 No Content и обновленный объект servicePrincipal в тексте отклика.

Пример

Пример 1. Обновление свойств указанного субъекта-службы

Запрос

Ниже показан пример запроса.

HTTP

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
  "appRoleAssignmentRequired": true
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new ServicePrincipal
{
	AppRoleAssignmentRequired = true,
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewServicePrincipal()
appRoleAssignmentRequired := true
requestBody.SetAppRoleAssignmentRequired(&appRoleAssignmentRequired) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setAppRoleAssignmentRequired(true);
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").patch(servicePrincipal);

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
  appRoleAssignmentRequired: true
};

await client.api('/servicePrincipals/{id}')
	.update(servicePrincipal);

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new ServicePrincipal();
$requestBody->setAppRoleAssignmentRequired(true);

$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->patch($requestBody)->wait();

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PowerShell

Import-Module Microsoft.Graph.Applications

$params = @{
	appRoleAssignmentRequired = $true
}

Update-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ServicePrincipal(
	app_role_assignment_required = True,
)

result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').patch(request_body)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

Ниже показан пример отклика. Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.

HTTP/1.1 204 No Content

Пример 2. Назначение настраиваемого атрибута безопасности со строковым значением субъекту-службе

В следующем примере показано, как назначить субъекту-службе настраиваемый атрибут безопасности со строковым значением.

• Набор атрибутов: Engineering
• Атрибут: ProjectDate
• Тип данных атрибута: строка
• Значение атрибута: "2022-10-01"

Чтобы назначить настраиваемые атрибуты безопасности, вызывающему субъекту должна быть присвоена роль администратора назначения атрибутов и должно быть предоставлено разрешение CustomSecAttributeAssignment.ReadWrite.All.

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

Запрос

Ниже показан пример запроса.

HTTP

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":"2022-10-01"
        }
    }
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;
using Microsoft.Kiota.Abstractions.Serialization;

var requestBody = new ServicePrincipal
{
	CustomSecurityAttributes = new CustomSecurityAttributeValue
	{
		AdditionalData = new Dictionary<string, object>
		{
			{
				"Engineering" , new UntypedObject(new Dictionary<string, UntypedNode>
				{
					{
						"@odata.type", new UntypedString("#Microsoft.DirectoryServices.CustomSecurityAttributeValue")
					},
					{
						"projectDate", new UntypedString("2022-10-01")
					},
				})
			},
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Go

// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewServicePrincipal()
customSecurityAttributes := graphmodels.NewCustomSecurityAttributeValue()
additionalData := map[string]interface{}{
engineering := graph.New()
projectDate := "2022-10-01"
engineering.SetProjectDate(&projectDate) 
	customSecurityAttributes.SetEngineering(engineering)
}
customSecurityAttributes.SetAdditionalData(additionalData)
requestBody.SetCustomSecurityAttributes(customSecurityAttributes)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ServicePrincipal servicePrincipal = new ServicePrincipal();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
 engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setProjectDate("2022-10-01");
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
servicePrincipal.setCustomSecurityAttributes(customSecurityAttributes);
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").patch(servicePrincipal);

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
    customSecurityAttributes: 
    {
        Engineering: 
        {
            '@odata.type':'#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
            ProjectDate: '2022-10-01'
        }
    }
};

await client.api('/servicePrincipals/{id}')
	.update(servicePrincipal);

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;
use Microsoft\Graph\Generated\Models\CustomSecurityAttributeValue;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new ServicePrincipal();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
	'Engineering' => [
		'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
		'projectDate' => '2022-10-01',
	],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);

$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->patch($requestBody)->wait();

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

PowerShell

Import-Module Microsoft.Graph.Applications

$params = @{
	customSecurityAttributes = @{
		Engineering = @{
			"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
			ProjectDate = "2022-10-01"
		}
	}
}

Update-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
from msgraph.generated.models.custom_security_attribute_value import CustomSecurityAttributeValue
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ServicePrincipal(
	custom_security_attributes = CustomSecurityAttributeValue(
		additional_data = {
				"engineering" : {
						"@odata_type" : "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
						"project_date" : "2022-10-01",
				},
		}
	),
)

result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').patch(request_body)

Подробнее о том, как добавить SDK в свой проект и создать экземпляр authProvider, см. в документации по SDK.

Отклик

Ниже приводится пример отклика.

HTTP/1.1 204 No Content