Upsert 应用程序

2025-07-05

命名空间：microsoft.graph

创建新的应用程序对象（如果不存在），或更新现有应用程序对象的属性。

重要

不支持使用 PATCH 设置 passwordCredential。使用 addPassword 和 removePassword 方法更新应用程序的密码或机密。

全局服务	美国政府 L4	美国政府 L5 (DOD)	由世纪互联运营的中国
✅	✅	✅	✅

权限

为此 API 选择标记为最低特权的权限。只有在应用需要它时，才使用更高的特权权限。有关委派权限和应用程序权限的详细信息，请参阅权限类型。要了解有关这些权限的详细信息，请参阅权限参考。

权限类型	最低特权权限	更高特权权限
委派（工作或学校帐户）	Application.ReadWrite.All	不可用。
委派（个人 Microsoft 帐户）	Application.ReadWrite.All	不可用。
应用程序	Application.ReadWrite.OwnedBy	Application.ReadWrite.All

在具有工作或学校帐户的委派方案中，必须为管理员分配受支持的Microsoft Entra角色或具有受支持角色权限的自定义角色。此作支持以下最低特权角色。

非管理员成员或具有默认用户权限的来宾，除非租户管理员具有受限访问权限
应用程序开发人员 - 即使管理员限制对成员和来宾的访问权限，也可以创建应用;向具有此角色的主体分配了他们创建的应用的所有权
目录编写器 - 更新扩展属性
混合标识管理员 - 仅更新基本属性
安全管理员
云应用程序管理员
应用程序管理员

HTTP 请求

若要创建或更新应用程序，请指定 uniqueName 客户端提供的备用键。

PATCH /applications(uniqueName='{uniqueName}')

请求标头

名称	说明
Authorization	持有者 {token}。必填。详细了解身份验证和授权。
Content-Type	application/json. 必需。
Prefer	`create-if-missing`. 对于 upsert 行为是必需的，否则请求被视为更新作。

请求正文

在请求正文中，提供应用程序对象的 JSON 表示形式。请求正文必须包含 displayName，这是必需属性。指定应用程序所需的其他可写属性，以便创建或更新。

响应

如果不存在具有 uniqueName 的应用程序对象，此方法在响应正文中返回响应 201 Created 代码和新的应用程序对象。为应用程序分配了 uniqueName 值。

如果不存在具有 uniqueName 的应用程序对象， Prefer: create-if-missing 并且未指定标头，则此方法将 404 Not Found 返回错误代码。

如果已存在具有 uniqueName 的应用程序对象，此方法将更新应用程序对象并返回 204 No Content 响应代码。

示例

示例 1：创建新的应用程序（如果不存在）

以下示例创建应用程序，因为不存在具有指定 uniqueName 值的应用程序。

请求

以下示例显示了一个请求。

PATCH https://graph.microsoft.com/v1.0/applications(uniqueName='app-65278')
Content-Type: application/json
Prefer: create-if-missing

{
  "displayName": "Display name"
}


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

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Application
{
	DisplayName = "Display name",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ApplicationsWithUniqueName("{uniqueName}").PatchAsync(requestBody, (requestConfiguration) =>
{
	requestConfiguration.Headers.Add("Prefer", "create-if-missing");
});



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

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

headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "create-if-missing")

configuration := &graphapplicationswithuniquename.ApplicationsWithUniqueNameRequestBuilderPatchRequestConfiguration{
	Headers: headers,
}
requestBody := graphmodels.NewApplication()
displayName := "Display name"
requestBody.SetDisplayName(&displayName) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
uniqueName := "{uniqueName}"
applications, err := graphClient.ApplicationsWithUniqueName(&uniqueName).Patch(context.Background(), requestBody, configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Application application = new Application();
application.setDisplayName("Display name");
Application result = graphClient.applicationsWithUniqueName("{uniqueName}").patch(application, requestConfiguration -> {
	requestConfiguration.headers.add("Prefer", "create-if-missing");
});


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Applications(uniqueName='{uniqueName}')\ApplicationsWithUniqueNameRequestBuilderPatchRequestConfiguration;
use Microsoft\Graph\Generated\Models\Application;


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

$requestBody = new Application();
$requestBody->setDisplayName('Display name');
$requestConfiguration = new ApplicationsWithUniqueNameRequestBuilderPatchRequestConfiguration();
$headers = [
		'Prefer' => 'create-if-missing',
	];
$requestConfiguration->headers = $headers;


$result = $graphServiceClient->applicationsWithUniqueName('{uniqueName}', )->patch($requestBody, $requestConfiguration)->wait();


Import-Module Microsoft.Graph.Applications

$params = @{
	displayName = "Display name"
}

Update-MgApplicationByUniqueName -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.applications(unique_name='{unique_name}').applications_with_unique_name_request_builder import ApplicationsWithUniqueNameRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
from msgraph.generated.models.application import Application
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Application(
	display_name = "Display name",
)

request_configuration = RequestConfiguration()
request_configuration.headers.add("Prefer", "create-if-missing")


result = await graph_client.applications_with_unique_name("{uniqueName}").patch(request_body, request_configuration = request_configuration)

响应

以下示例显示了相应的响应。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
    "id": "03ef14b0-ca33-4840-8f4f-d6e91916010e",
    "deletedDateTime": null,
    "isFallbackPublicClient": null,
    "appId": "631a96bc-a705-4eda-9f99-fdaf9f54f6a2",
    "applicationTemplateId": null,
    "identifierUris": [],
    "createdDateTime": "2019-09-17T19:10:35.2742618Z",
    "displayName": "Display name",
    "isDeviceOnlyAuthSupported": null,
    "groupMembershipClaims": null,
    "optionalClaims": null,
    "addIns": [],
    "publisherDomain": "contoso.onmicrosoft.com",
    "samlMetadataUrl": "https://graph.microsoft.com/2h5hjaj542de/app",
    "signInAudience": "AzureADandPersonalMicrosoftAccount",
    "tags": [],
    "tokenEncryptionKeyId": null,
    "api": {
        "requestedAccessTokenVersion": 2,
        "acceptMappedClaims": null,
        "knownClientApplications": [],
        "oauth2PermissionScopes": [],
        "preAuthorizedApplications": []
    },
    "appRoles": [],
    "publicClient": {
        "redirectUris": []
    },
    "info": {
        "termsOfServiceUrl": null,
        "supportUrl": null,
        "privacyStatementUrl": null,
        "marketingUrl": null,
        "logoUrl": null
    },
    "keyCredentials": [],
    "parentalControlSettings": {
        "countriesBlockedForMinors": [],
        "legalAgeGroupRule": "Allow"
    },
    "passwordCredentials": [],
    "requiredResourceAccess": [],
    "uniqueName": "app-65278",
    "web": {
        "redirectUris": [],
        "homePageUrl": null,
        "logoutUrl": null,
        "implicitGrantSettings": {
            "enableIdTokenIssuance": false,
            "enableAccessTokenIssuance": false
        }
    }, 
    "windows" : null
}

示例 2：更新现有应用程序

以下示例更新应用程序，因为存在具有指定 uniqueName 值的应用程序。

请求