Upsert servicePrincipal

  • Artículo

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Cree un nuevo objeto servicePrincipal si no existe o actualice las propiedades de un objeto servicePrincipal existente.

Importante

No es compatible agregar passwordCredential cuando se crea servicePrincipals. Use el método addPassword para agregar contraseñas o secretos a un servicePrincipal.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) Application.ReadWrite.All Directory.ReadWrite.All
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación Application.ReadWrite.All Application.ReadWrite.OwnedBy, Directory.ReadWrite.All

En el caso de las aplicaciones multiinquilino, el usuario que realiza la llamada también debe estar en al menos uno de los siguientes roles de Microsoft Entra:

  • Administrador de la aplicación
  • Roles de administrador de aplicaciones en la nube

En el caso de las aplicaciones de inquilino único en las que el usuario que realiza la llamada es un usuario que no es administrador, pero es el propietario de la aplicación de respaldo, el usuario debe tener el rol Desarrollador de aplicaciones .

Solicitud HTTP

PATCH /servicePrincipals(appId='appId')

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio.
Content-Type application/json. Necesario.
Prefer create-if-missing. Necesario para el comportamiento de upsert; de lo contrario, la solicitud se trata como una operación de actualización.

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione una representación JSON de un objeto servicePrincipal.

Respuesta

Si se ejecuta correctamente, si un servicePrincipal con appId no existe, este método devuelve un 201 Created código de respuesta y un nuevo objeto servicePrincipal en el cuerpo de la respuesta.

Si ya existe un servicePrincipal con appId , este método actualiza el objeto servicePrincipal y devuelve un código de 204 No Content respuesta.

Ejemplos

Ejemplo 1: Crear un nuevo servicioPrincipal si no existe

En el ejemplo siguiente se crea un servicePrincipal porque un servicePrincipal con el valor de appId especificado no existe.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

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

{
  "displayName": "My app instance"
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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": []
}

Ejemplo 2: Actualización de un servicio existentePrincipal

En el ejemplo siguiente se actualiza servicePrincipal porque existe un servicePrincipal con el valor de appId especificado.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

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

{
  "displayName": "My app instance"
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content