Partilhar via


Upsert servicePrincipal

Namespace: microsoft.graph

Crie um novo objeto servicePrincipal se não existir ou atualize as propriedades de um objeto servicePrincipal existente.

Importante

Não há suporte para a adição de passwordCredential durante a criação de servicePrincipals. Use o método addPassword para adicionar senhas ou segredos para um servicePrincipal.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global US Government L4 US Government L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
Delegado (conta corporativa ou de estudante) Application.ReadWrite.All Directory.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application Application.ReadWrite.OwnedBy Application.ReadWrite.All, Directory.ReadWrite.All

Para aplicações multi-inquilino, o utilizador que chama também tem de ter, pelo menos, uma das seguintes funções do Microsoft Entra:

  • Administrador de Aplicativos
  • Administrador de Aplicativos de Nuvem

Para aplicações de inquilino único em que o utilizador que chama é um utilizador não administrador, mas é o proprietário da aplicação de apoio, o utilizador tem de ter a função Programador de Aplicações .

Solicitação HTTP

PATCH /servicePrincipals(appId='appId')

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/json. Obrigatório.
Preferir create-if-missing. Necessário para o comportamento de upsert, caso contrário, o pedido é tratado como uma operação de atualização.

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON de um objeto servicePrincipal.

Resposta

Se for bem-sucedido, se não existir um servicePrincipal com appId , este método devolve um 201 Created código de resposta e um novo objeto servicePrincipal no corpo da resposta.

Se já existir um servicePrincipal com appId , este método atualiza o objeto servicePrincipal e devolve um 204 No Content código de resposta.

Exemplos

Exemplo 1: Criar um novo servicePrincipal se não existir

O exemplo seguinte cria um servicePrincipal porque não existe um servicePrincipal com o valor appId especificado.

Solicitação

O exemplo a seguir mostra uma solicitação.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals(appId='65415bb1-9267-4313-bbf5-ae259732ee12')
Content-type: application/json
Prefer: create-if-missing

{
  "displayName": "My app instance"
}

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals/$entity",
    "id": "59e617e5-e447-4adc-8b88-00af644d7c92",
    "deletedDateTime": null,
    "accountEnabled": true,
    "appDisplayName": "My App",
    "appId": "65415bb1-9267-4313-bbf5-ae259732ee12",
    "applicationTemplateId": null,
    "appOwnerOrganizationId": "1bc1c026-2f7b-48a5-98da-afa2fd8bc7bc",
    "appRoleAssignmentRequired": false,
    "displayName": "My app instance",
    "errorUrl": null,
    "homepage": null,
    "loginUrl": null,
    "logoutUrl": null,
    "notificationEmailAddresses": [],
    "preferredSingleSignOnMode": null,
    "preferredTokenSigningKeyEndDateTime": null,
    "preferredTokenSigningKeyThumbprint": null,
    "publisherName": "Contoso",
    "replyUrls": [],
    "samlMetadataUrl": null,
    "samlSingleSignOnSettings": null,
    "servicePrincipalNames": [
        "f1bd758f-4a1a-4b71-aa20-a248a22a8928"
    ],
    "signInAudience": "AzureADandPersonalMicrosoftAccount",
    "tags": [],
    "addIns": [],
    "api": {
        "resourceSpecificApplicationPermissions": []
    },
    "appRoles": [],
    "info": {
        "termsOfServiceUrl": null,
        "supportUrl": null,
        "privacyStatementUrl": null,
        "marketingUrl": null,
        "logoUrl": null
    },
    "keyCredentials": [],
    "publishedPermissionScopes": [],
    "passwordCredentials": []
}

Exemplo 2: Atualizar um servicePrincipal existente

O exemplo seguinte atualiza o servicePrincipal porque existe um servicePrincipal com o valor appId especificado.

Solicitação

O exemplo a seguir mostra uma solicitação.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals(appId='65415bb1-9267-4313-bbf5-ae259732ee12')
Content-type: application/json
Prefer: create-if-missing

{
  "displayName": "My app instance"
}

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 204 No Content