Mettre à jour servicePrincipal

Article
10/18/2023

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Mettez à jour les propriétés de l’objet serviceprincipal.

Importante

L’utilisation d’un correctif pour établir passwordCredential n’est pas prise en charge. Utilisez les méthodes addPassword et removePassword pour mettre à jour le mot de passe ou le secret d’un servicePrincipal.

Cette API est disponible dans les déploiements de cloud national suivants.

Service global	Gouvernement des États-Unis L4	Us Government L5 (DOD)	Chine gérée par 21Vianet
✅	✅	✅	✅

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation	Autorisations avec privilèges minimum	Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire)	Application.ReadWrite.All	Directory.ReadWrite.All
Déléguée (compte Microsoft personnel)	Non prise en charge.	Non prise en charge.
Application	Application.ReadWrite.OwnedBy	Application.ReadWrite.OwnedBy, Application.ReadWrite.All, Directory.ReadWrite.All

Requête HTTP

Vous pouvez adresser le principal de service à l’aide de son id ou de son appId. id et appId sont respectivement appelés ID d’objet et ID d’application (client) dans les inscriptions d’applications dans le centre d'administration Microsoft Entra.

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

En-têtes de demande

Nom	Description
Autorisation	Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
Content-Type	application/json. Obligatoire.

Corps de la demande

Dans le corps de la demande, fournissez les valeurs pour les champs appropriés qui doivent être mis à jour. Les propriétés existantes qui ne sont pas incluses dans le corps de la demande conservent leurs valeurs précédentes ou sont recalculées en fonction des modifications apportées à d’autres valeurs de propriété. Pour de meilleures performances, n’incluez pas de valeurs existantes qui n’ont pas changé.

Propriété	Type	Description
accountEnabled	Booléen	Valeur true si le compte du principal de service est activé ; sinon, valeur false.
addIns	addIn	Définit un comportement personnalisé qu’un service d’utilisation peut utiliser pour appeler une application dans des contextes spécifiques. Par exemple, les applications qui peuvent afficher les flux de fichier peuvent spécifier la propriété addIns pour sa fonctionnalité « FileHandler ». Cela permet à des services tels que Microsoft 365 d’appeler l’application dans le contexte d’un document sur lequel l’utilisateur travaille.
alternativeNames	String collection	Utilisé pour récupérer les principaux de service par abonnement, identifiez les ID de groupe de ressources et de ressource complète pour les identités gérées.
appRoleAssignmentRequired	Booléen	Spécifie si un appRoleAssignment à un utilisateur ou à un groupe est requis avant que Microsoft Entra ID émette un jeton d’utilisateur ou d’accès à l’application. Ne pouvant accepter la valeur null.
appRoles	Collection de appRole	Les rôles d’application exposés par l’application associée. Pour plus d’informations, consultez la définition de la propriété appRoles sur la ressource d’application . Ne pouvant accepter la valeur null.
customSecurityAttributes	customSecurityAttributeValue	Type complexe ouvert qui contient la valeur d’un attribut de sécurité personnalisé affecté à un objet d’annuaire. Pour mettre à jour cette propriété, le principal appelant doit se voir attribuer le rôle d’Administrateur d’attribution d’attributs et doit avoir l’autorisation CustomSecAttributeAssignment.ReadWrite.All.
displayName	Chaîne	Le nom d’affichage pour le principal de service.
homepage	Chaîne	Page d’accueil ou page d’accueil de l’application.
keyCredentials	Collection keyCredential	Collection d’informations d’identification clées associées au principal de service. Ne pouvant accepter la valeur null.
loginUrl	String	Spécifie l’URL où le fournisseur de services redirige l’utilisateur vers Microsoft Entra ID pour s’authentifier. Microsoft Entra ID utilise l’URL pour lancer l’application à partir de Microsoft 365 ou du Microsoft Entra Mes applications. Lorsqu’il est vide, Microsoft Entra ID effectue l’authentification lancée par le fournisseur d’identité pour les applications configurées avec l’authentification unique SAML. L’utilisateur lance l’application à partir de Microsoft 365, du Microsoft Entra Mes applications ou de l’URL d’authentification unique Microsoft Entra.
logoutUrl	Chaîne	Spécifie l’URL qui sera utilisée par le service d’autorisation de Microsoft pour déconnecter un utilisateur à l’aide du canal frontal, du canal principal ou des protocoles de déconnexion SAML.
notificationEmailAddresses	String collection	Spécifie la liste des adresses e-mail où Microsoft Entra ID envoie une notification lorsque le certificat actif est proche de la date d’expiration. Il s’agit uniquement des certificats utilisés pour signer le jeton SAML émis pour les applications Microsoft Entra Gallery.
publishedPermissionScopes	permissionScope collection	Les permissions oAuth 2.0 exposées par l’application associée. Pour plus d’informations, consultez la définition de la propriété oauth2PermissionScopes sur la ressource d’application . Ne pouvant accepter la valeur null.
preferredSingleSignOnMode	string	Spécifie le mode d’authentification unique configuré pour cette application. Microsoft Entra ID utilise le mode d’authentification unique préféré pour lancer l’application à partir de Microsoft 365 ou du Microsoft Entra Mes applications. Les valeurs prises en charge sont mot de passe, SAML, External et OIDC.
preferredTokenSigningKeyEndDateTime	DateTimeOffset	Indique la date d’expiration de la keyCredential utilisée pour la signature de jetons, marquée par preferredTokenSigningKeyThumbprint.
preferredTokenSigningKeyThumbprint	Chaîne	Réservé à une utilisation interne. N’écrivez pas ou ne vous fiez pas à cette propriété. Risque d’être supprimé dans les versions ultérieures.
publisherName	Chaîne	Le nom d’affichage du client dans lequel l’application associée est spécifiée.
replyUrls	Collection de chaînes	Les URL auxquelles les jetons utilisateur sont envoyés pour se connecter avec l'application associée, ou les URI de redirection vers lesquelles les codes d'autorisation et les jetons d'accès OAuth 2.0 sont envoyés pour l'application associée. Ne pouvant accepter la valeur null.
samlSingleSignOnSettings	samlSingleSignOnSettings	Collection pour les paramètres liés à l’authentification unique SAML.
servicePrincipalNames	String collection	Contient la liste de identifiersUris, copiée à partir de l’application associée. D’autres valeurs peuvent être ajoutées à des applications hybrides. Ces valeurs peuvent être utilisées pour identifier les autorisations exposées par cette application dans Microsoft Entra ID. Par exemple : Les applications clientes demandant l’autorisation d’accès à cette ressource peuvent utiliser ces URIs pour spécifier les autorisations requises dans la propriété requiredResourceAccess de leur manifeste d’application, ou dans la Blade «d’autorisations API » de l’expérience d’inscriptions d’applications. Les applications clientes peuvent spécifier un URI de ressource basé sur les valeurs de cette propriété pour acquérir un jeton d’accès, qui est l’URI retourné dans la revendication « aud ». L’opérateur est requis pour les expressions de filtre sur des propriétés à valeurs multiples. Ne pouvant accepter la valeur null.
étiquettes	Collection de chaînes	Ne pouvant accepter la valeur null.
tokenEncryptionKeyId	String	Spécifie la keyId d’une clé publique de la collection keyCredentials. Une fois configuré, Microsoft Entra ID émet des jetons pour cette application chiffrés à l’aide de la clé spécifiée par cette propriété. Le code d'application qui reçoit le jeton chiffré doit utiliser la clé privée correspondante pour déchiffrer le jeton avant de pouvoir l'utiliser pour l'utilisateur connecté.

Réponse

En cas de réussite, cette méthode renvoie un 204 No Contentcode de réponse et l’objet servicePrincipal mis à jour dans le corps de la réponse.

Exemples

Exemple 1 : mettre à jour les propriétés du principal du service spécifié

Demande

L’exemple suivant illustre une demande.

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

{
  "appRoleAssignmentRequired": true
}


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

// Dependencies
using Microsoft.Graph.Beta.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);

Importante

Microsoft Graph SDK utilisent la version v1.0 de l’API par défaut et ne prennent pas en charge tous les types, propriétés et API disponibles dans la version bêta. Pour plus d’informations sur l’accès à l’API bêta avec le SDK, consultez Utiliser les kits de développement logiciel (SDK) Microsoft Graph avec l’API bêta.

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).



mgc-beta service-principals patch --service-principal-id {servicePrincipal-id} --body '{\
  "appRoleAssignmentRequired": true\
}\
'

Importante



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

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-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)

Importante


// 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);

Importante


const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
  appRoleAssignmentRequired: true
};

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

Importante


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


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

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

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

Importante


Import-Module Microsoft.Graph.Beta.Applications

$params = @{
	appRoleAssignmentRequired = $true
}

Update-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Importante


from msgraph_beta import GraphServiceClient
from msgraph_beta.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)

Importante

Réponse

L’exemple suivant illustre la réponse. Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 204 No Content

Exemple 2 : attribuer un attribut de sécurité personnalisé avec une valeur de chaîne à un principal du service

L’exemple suivant montre comment affecter un attribut de sécurité personnalisé avec une valeur de chaîne à un principal du service.

Jeu d’attributs : Engineering
Attribut : ProjectDate
Type de données d’attribut : chaîne
Valeur d’attribut : "2022-10-01"

Pour attribuer des attributs de sécurité personnalisés, le principal appelant doit se voir attribuer le rôle d’Administrateur d’attribution d’attributs et doit avoir l’autorisation CustomSecAttributeAssignment.ReadWrite.All.

Pour obtenir d’autres exemples similaires pour les utilisateurs, consultez Exemples : Attribuer, mettre à jour, lister ou supprimer des attributions d’attributs de sécurité personnalisées à l’aide de Microsoft API Graph.

Demande

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

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


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

// Dependencies
using Microsoft.Graph.Beta.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);

Importante



mgc-beta service-principals patch --service-principal-id {servicePrincipal-id} --body '{\
    "customSecurityAttributes":\
    {\
        "Engineering":\
        {\
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",\
            "ProjectDate":"2022-10-01"\
        }\
    }\
}\
'

Importante



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

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-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)

Importante


// 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);

Importante


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}')
	.version('beta')
	.update(servicePrincipal);

Importante


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\ServicePrincipal;
use Microsoft\Graph\Beta\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();

Importante


Import-Module Microsoft.Graph.Beta.Applications

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

Update-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Importante


from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.service_principal import ServicePrincipal
from msgraph_beta.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)

Importante

Réponse

HTTP/1.1 204 No Content

Partager via

Mettre à jour servicePrincipal

Autorisations

Requête HTTP

En-têtes de demande

Corps de la demande

Réponse

Exemples

Exemple 1 : mettre à jour les propriétés du principal du service spécifié

Demande

Réponse

Exemple 2 : attribuer un attribut de sécurité personnalisé avec une valeur de chaîne à un principal du service

Demande

Réponse

Commentaires

Commentaires

Ressources supplémentaires