Обновление servicePrincipal

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

Обновление свойств объекта servicePrincipal.

Важно!

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

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

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

Разрешения

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

Тип разрешения	Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись)	Application.ReadWrite.All
Делегированные (личная учетная запись Майкрософт)	Не поддерживается.
Для приложений	Application.ReadWrite.OwnedBy, Application.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.
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.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc service-principals patch --service-principal-id {servicePrincipal-id} --body '{\
  "appRoleAssignmentRequired": true\
}\
'

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

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

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

from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal

graph_client = GraphServiceClient(credentials, scopes)

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;

var requestBody = new ServicePrincipal
{
	CustomSecurityAttributes = new CustomSecurityAttributeValue
	{
		AdditionalData = new Dictionary<string, object>
		{
			{
				"Engineering" , new 
				{
					OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
					ProjectDate = "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.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc service-principals patch --service-principal-id {servicePrincipal-id} --body '{\
    "customSecurityAttributes":\
    {\
        "Engineering":\
        {\
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",\
            "ProjectDate":"2022-10-01"\
        }\
    }\
}\
'

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

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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

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

from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
from msgraph.generated.models.custom_security_attribute_value import CustomSecurityAttributeValue

graph_client = GraphServiceClient(credentials, scopes)

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