Service Principal Entitlements - Add

Referencia

Servicio:: Member Entitlement Management

Versión de la API:: 7.1-preview.1

Agregue una entidad de servicio, asigne licencias y extensiones y confóquelas como miembro de un grupo de proyectos en una cuenta.

NOTA: Si está trabajando con el registro de aplicaciones de AAD, puede encontrar la entidad de servicio de la aplicación en aplicaciones empresariales y asegurarse de usar el identificador de objeto de la entidad de servicio como parámetro originId en el cuerpo de la solicitud.

POST https://vsaex.dev.azure.com/{organization}/_apis/serviceprincipalentitlements?api-version=7.1-preview.1

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
organization	path	True	string	El nombre de la organización de Azure DevOps.
api-version	query	True	string	Versión de la API que se va a usar. Debe establecerse en "7.1-preview.1" para usar esta versión de la API.

Cuerpo de la solicitud

Nombre	Tipo	Description
accessLevel	AccessLevel	Nivel de acceso del miembro indicado por una licencia.
dateCreated	string	[Readonly] Fecha en que se agregó el miembro a la colección.
groupAssignments	GroupEntitlement[]	[Readonly] GroupEntitlements a los que pertenece este miembro.
id	string	Identificador único que coincide con el identificador de la identidad asociada a GraphMember.
lastAccessedDate	string	[Readonly] Fecha en que el miembro accedió por última vez a la colección.
projectEntitlements	ProjectEntitlement[]	Relación entre un proyecto y los permisos efectivos del miembro en ese proyecto.
servicePrincipal	GraphServicePrincipal	Referencia de ServicePrincipal.

Respuestas

Nombre	Tipo	Description
200 OK	ServicePrincipalEntitlementsPostResponse	operación correcta

Seguridad

oauth2

Tipo: oauth2
Flujo: accessCode
Dirección URL de autorización: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Dirección URL del token: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Ámbitos

Nombre	Description
vso.memberentitlementmanagement_write	Concede la capacidad de administrar usuarios, sus licencias, así como proyectos y extensiones a los que pueden acceder.

Ejemplos

Solicitud de ejemplo

HTTP

POST https://vsaex.dev.azure.com/{organization}/_apis/serviceprincipalentitlements?api-version=7.1-preview.1

{
  "accessLevel": {
    "accountLicenseType": "stakeholder"
  },
  "projectEntitlements": [
    {
      "group": {
        "groupType": "projectReader"
      },
      "projectRef": {
        "id": "c944c983-e90b-4499-938a-5897ea954ace"
      }
    }
  ],
  "servicePrincipal": {
    "origin": "aad",
    "originId": "92e26ce8-8e7c-4555-bdab-813b34b8e53a",
    "subjectKind": "servicePrincipal"
  }
}

Respuesta de muestra

status code:: 200

{
  "operationResult": {
    "servicePrincipalId": "b34cdbfd-1f2d-60c6-b04a-8a99d301a6cd",
    "isSuccess": true,
    "errors": [],
    "result": {
      "servicePrincipal": {
        "subjectKind": "servicePrincipal",
        "applicationId": "a9a6a563-c4c6-42cd-8bd6-90259e8f99f4",
        "metaType": "application",
        "directoryAlias": "92e26ce8-8e7c-4555-bdab-813b34b8e53a",
        "domain": "5e46c442-89f0-4452-b132-3336eaeec3fc",
        "principalName": "a9a6a563-c4c6-42cd-8bd6-90259e8f99f4",
        "mailAddress": null,
        "origin": "aad",
        "originId": "92e26ce8-8e7c-4555-bdab-813b34b8e53a",
        "displayName": "Service principal",
        "_links": {
          "self": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/ServicePrincipals/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
          },
          "memberships": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/Memberships/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
          },
          "membershipState": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/MembershipStates/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
          },
          "storageKey": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/StorageKeys/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
          },
          "avatar": {
            "href": "https://dev.azure.com/fabrikam/_apis/GraphProfile/MemberAvatars/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
          }
        },
        "url": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/ServicePrincipals/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk",
        "descriptor": "aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
      },
      "id": "b34cdbfd-1f2d-60c6-b04a-8a99d301a6cd",
      "accessLevel": {
        "licensingSource": "account",
        "accountLicenseType": "earlyAdopter",
        "msdnLicenseType": "none",
        "licenseDisplayName": "Early Adopter",
        "status": "pending",
        "statusMessage": "",
        "assignmentSource": "unknown"
      },
      "lastAccessedDate": "0001-01-01T00:00:00Z",
      "dateCreated": "2023-03-27T11:32:45.7401972Z",
      "projectEntitlements": [],
      "groupAssignments": []
    }
  },
  "isSuccess": true,
  "servicePrincipalEntitlement": {
    "servicePrincipal": {
      "subjectKind": "servicePrincipal",
      "applicationId": "a9a6a563-c4c6-42cd-8bd6-90259e8f99f4",
      "metaType": "application",
      "directoryAlias": "92e26ce8-8e7c-4555-bdab-813b34b8e53a",
      "domain": "5e46c442-89f0-4452-b132-3336eaeec3fc",
      "principalName": "a9a6a563-c4c6-42cd-8bd6-90259e8f99f4",
      "mailAddress": null,
      "origin": "aad",
      "originId": "92e26ce8-8e7c-4555-bdab-813b34b8e53a",
      "displayName": "Service principal",
      "_links": {
        "self": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/ServicePrincipals/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
        },
        "memberships": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/Memberships/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
        },
        "membershipState": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/MembershipStates/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
        },
        "storageKey": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/StorageKeys/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
        },
        "avatar": {
          "href": "https://dev.azure.com/fabrikam/_apis/GraphProfile/MemberAvatars/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
        }
      },
      "url": "https://vssps.dev.azure.com/fabrikam/_apis/Graph/ServicePrincipals/aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk",
      "descriptor": "aadsp.YjM0Y2RiZmQtMWYyZC03MGM2LWIwNGEtOGE5OWQzMDFhNmNk"
    },
    "id": "b34cdbfd-1f2d-60c6-b04a-8a99d301a6cd",
    "accessLevel": {
      "licensingSource": "account",
      "accountLicenseType": "earlyAdopter",
      "msdnLicenseType": "none",
      "licenseDisplayName": "Early Adopter",
      "status": "pending",
      "statusMessage": "",
      "assignmentSource": "unknown"
    },
    "lastAccessedDate": "0001-01-01T00:00:00Z",
    "dateCreated": "2023-03-27T11:32:45.7401972Z",
    "projectEntitlements": [],
    "groupAssignments": []
  }
}

Definiciones

Nombre	Description
AccessLevel	Licencia asignada a un usuario
AccountLicenseType	Tipo de licencia de cuenta (por ejemplo, Express, Parte interesada, etc.). Para usar AccountLicenseType, LicensingSource debe definirse como "account" en el cuerpo de la solicitud.
AccountUserStatus	Estado del usuario en la cuenta
AssignmentSource	Origen de asignación de la licencia (por ejemplo, Grupo, Desconocido, etc.
GraphGroup	Entidad de grupo de grafos
GraphServicePrincipal
GraphUser
Group	Grupo de proyectos (por ejemplo, Colaborador, Lector, etc.)
GroupEntitlement	Una entidad de grupo con propiedades adicionales, incluidas su licencia, extensiones y pertenencia a proyectos
GroupLicensingRuleStatus	Estado de la regla de grupo.
GroupType	Tipo de grupo
LicensingSource	Origen de licencias (por ejemplo, Cuenta. MSDN, etc.)
MsdnLicenseType	Tipo de licencia de MSDN (por ejemplo, Visual Studio Professional, Visual Studio Enterprise etc.). Para usar MsdnLicenseType, LicensingSource debe definirse como "msdn" en el cuerpo de la solicitud.
ProjectEntitlement	Relación entre un proyecto y los permisos efectivos del usuario en ese proyecto.
ProjectPermissionInherited	Si el usuario hereda los permisos de un proyecto a través de una pertenencia a grupos de Azure DevOps o AAD.
ProjectRef	Referencia a un proyecto
ReferenceLinks	Clase que se va a representar una colección de vínculos de referencia de REST.
ServicePrincipalEntitlement
ServicePrincipalEntitlementOperationResult
ServicePrincipalEntitlementsPostResponse
TeamRef	Referencia a un equipo
UserEntitlement	Una entidad de usuario con propiedades adicionales, incluidas sus licencias, extensiones y pertenencia a proyectos

AccessLevel

Object

Licencia asignada a un usuario

Nombre	Tipo	Description
accountLicenseType	AccountLicenseType	Tipo de licencia de cuenta (por ejemplo, Express, Parte interesada, etc.). Para usar AccountLicenseType, LicensingSource debe definirse como "account" en el cuerpo de la solicitud.
assignmentSource	AssignmentSource	Origen de asignación de la licencia (por ejemplo, Grupo, Desconocido, etc.
licenseDisplayName	string	Nombre para mostrar de la licencia
licensingSource	LicensingSource	Origen de licencias (por ejemplo, Cuenta. MSDN, etc.)
msdnLicenseType	MsdnLicenseType	Tipo de licencia de MSDN (por ejemplo, Visual Studio Professional, Visual Studio Enterprise etc.). Para usar MsdnLicenseType, LicensingSource debe definirse como "msdn" en el cuerpo de la solicitud.
status	AccountUserStatus	Estado del usuario en la cuenta
statusMessage	string	Mensaje de estado.

AccountLicenseType

Enumeration

Tipo de licencia de cuenta (por ejemplo, Express, Parte interesada, etc.). Para usar AccountLicenseType, LicensingSource debe definirse como "account" en el cuerpo de la solicitud.

Valor	Description
advanced
earlyAdopter
express
none
professional
stakeholder

AccountUserStatus

Enumeration

Estado del usuario en la cuenta

Valor	Description
active	El usuario ha iniciado sesión al menos una vez en la cuenta de VSTS
deleted	El administrador de la cuenta de VSTS quita el usuario de la cuenta de VSTS.
disabled	El usuario no puede iniciar sesión; usado principalmente por el administrador para quitar temporalmente un usuario debido a la ausencia o a la reasignación de licencias
expired	El usuario puede iniciar sesión; se usa principalmente cuando la licencia está en estado expirado y se proporciona un período de gracia
none
pending	El usuario está invitado a unirse a la cuenta de VSTS por el administrador de la cuenta de VSTS, pero aún no se ha registrado o iniciado sesión.
pendingDisabled	El usuario está deshabilitado; si se vuelve a habilitar, seguirán estando en estado Pendiente.

AssignmentSource

Enumeration

Origen de asignación de la licencia (por ejemplo, Grupo, Desconocido, etc.

Valor	Description
groupRule
none
unknown

GraphGroup

Object

Entidad de grupo de grafos

Nombre	Tipo	Description
_links	ReferenceLinks	Este campo contiene cero o más vínculos interesantes sobre el tema del grafo. Estos vínculos se pueden invocar para obtener relaciones adicionales o información más detallada sobre este tema del grafo.
description	string	Una frase corta para ayudar a los lectores humanos a desambiguar grupos con nombres similares
descriptor	string	El descriptor es la forma principal de hacer referencia al asunto del grafo mientras se ejecuta el sistema. Este campo identificará de forma única el mismo asunto del grafo en cuentas y organizaciones.
displayName	string	Este es el nombre para mostrar no único del asunto del grafo. Para cambiar este campo, debe modificar su valor en el proveedor de origen.
domain	string	Representa el nombre del contenedor de origen para un miembro de grafo. (Para MSA, este es "Windows Live ID", para AD el nombre del dominio, para AAD el tenantID del directorio, para los grupos de VSTS ScopeId, etc.)
legacyDescriptor	string	[Solo uso interno] El descriptor heredado está aquí en caso de que tenga que acceder a la versión anterior de IMS mediante el descriptor de identidad.
mailAddress	string	Dirección de correo electrónico del registro de un miembro de grafo determinado. Puede ser diferente del nombre principal.
origin	string	Tipo de proveedor de origen para el identificador de origen (por ejemplo: AD, AAD, MSA)
originId	string	Identificador único del sistema de origen. Normalmente, un sid, un identificador de objeto o un GUID. Las operaciones de vinculación y desvinculación pueden hacer que este valor cambie para un usuario porque el usuario no está respaldado por un proveedor diferente y tiene un identificador único diferente en el nuevo proveedor.
principalName	string	Este es el nombre principal de este miembro del grafo del proveedor de origen. El proveedor de origen puede cambiar este campo a lo largo del tiempo y no se garantiza que sea inmutable durante la vida del miembro del grafo por VSTS.
subjectKind	string	Este campo identifica el tipo del asunto del grafo (por ejemplo, Grupo, Ámbito, Usuario).
url	string	Esta dirección URL es la ruta completa al recurso de origen de este tema del grafo.

GraphServicePrincipal

Object

Nombre	Tipo	Description
_links	ReferenceLinks	Este campo contiene cero o más vínculos interesantes sobre el tema del grafo. Estos vínculos se pueden invocar para obtener relaciones adicionales o información más detallada sobre este tema del grafo.
applicationId	string
descriptor	string	El descriptor es la forma principal de hacer referencia al asunto del grafo mientras se ejecuta el sistema. Este campo identificará de forma única el mismo asunto del grafo en cuentas y organizaciones.
directoryAlias	string	Nombre corto, generalmente único para el usuario en el directorio de respaldo. Para los usuarios de AAD, esto corresponde al alias de correo, que suele ser similar a la parte de la dirección de correo del usuario antes del signo @ . Para los usuarios de GitHub, esto corresponde al identificador de usuario de GitHub.
displayName	string	Este es el nombre para mostrar no único del asunto del grafo. Para cambiar este campo, debe modificar su valor en el proveedor de origen.
domain	string	Representa el nombre del contenedor de origen para un miembro de grafo. (Para MSA, este es "Windows Live ID", para AD el nombre del dominio, para AAD el tenantID del directorio, para los grupos de VSTS ScopeId, etc.)
isDeletedInOrigin	boolean	Cuando es true, el grupo se ha eliminado en el proveedor de identidades.
legacyDescriptor	string	[Solo uso interno] El descriptor heredado está aquí en caso de que tenga que acceder a la versión anterior de IMS mediante el descriptor de identidad.
mailAddress	string	Dirección de correo electrónico del registro de un miembro de grafo determinado. Puede ser diferente del nombre principal.
metaType	string	Meta type del usuario en el origen, como "member", "guest", etc. Consulte UserMetaType para obtener el conjunto de valores posibles.
origin	string	Tipo de proveedor de origen para el identificador de origen (por ejemplo: AD, AAD, MSA)
originId	string	Identificador único del sistema de origen. Normalmente, un sid, un identificador de objeto o un GUID. Las operaciones de vinculación y desvinculación pueden hacer que este valor cambie para un usuario porque el usuario no está respaldado por un proveedor diferente y tiene un identificador único diferente en el nuevo proveedor.
principalName	string	Este es el nombre principal de este miembro del grafo del proveedor de origen. El proveedor de origen puede cambiar este campo a lo largo del tiempo y no se garantiza que sea inmutable durante la vida del miembro del grafo por VSTS.
subjectKind	string	Este campo identifica el tipo del asunto del grafo (por ejemplo, Grupo, Ámbito, Usuario).
url	string	Esta dirección URL es la ruta completa al recurso de origen de este tema del grafo.

GraphUser

Object

Nombre	Tipo	Description
_links	ReferenceLinks	Este campo contiene cero o más vínculos interesantes sobre el tema del grafo. Estos vínculos se pueden invocar para obtener relaciones adicionales o información más detallada sobre este tema del grafo.
descriptor	string	El descriptor es la forma principal de hacer referencia al asunto del grafo mientras se ejecuta el sistema. Este campo identificará de forma única el mismo asunto del grafo en cuentas y organizaciones.
directoryAlias	string	Nombre corto, generalmente único para el usuario en el directorio de respaldo. Para los usuarios de AAD, esto corresponde al alias de correo, que suele ser similar a la parte de la dirección de correo del usuario antes del signo @ . Para los usuarios de GitHub, esto corresponde al identificador de usuario de GitHub.
displayName	string	Este es el nombre para mostrar no único del asunto del grafo. Para cambiar este campo, debe modificar su valor en el proveedor de origen.
domain	string	Representa el nombre del contenedor de origen de un miembro de grafo. (Para MSA, es "Windows Live ID", para AD el nombre del dominio, para AAD el tenantID del directorio, para los grupos de VSTS scopeId, etc.)
isDeletedInOrigin	boolean	Cuando es true, el grupo se ha eliminado en el proveedor de identidades.
legacyDescriptor	string	[Solo uso interno] El descriptor heredado está aquí en caso de que necesite acceder a IMS de la versión anterior mediante el descriptor de identidad.
mailAddress	string	Dirección de correo electrónico del registro de un miembro de grafo determinado. Puede ser diferente del nombre principal.
metaType	string	El metatipo del usuario en el origen, como "miembro", "invitado", etc. Consulte UserMetaType para conocer el conjunto de valores posibles.
origin	string	Tipo de proveedor de origen para el identificador de origen (por ejemplo: AD, AAD, MSA)
originId	string	Identificador único del sistema de origen. Normalmente, un sid, un identificador de objeto o un GUID. Las operaciones de vinculación y desvinculación pueden hacer que este valor cambie para un usuario porque el usuario no está respaldado por otro proveedor y tiene un identificador único diferente en el nuevo proveedor.
principalName	string	Este es el nombre principal de este miembro del grafo del proveedor de origen. El proveedor de origen puede cambiar este campo a lo largo del tiempo y no se garantiza que sea inmutable durante la vida del miembro del grafo mediante VSTS.
subjectKind	string	Este campo identifica el tipo del asunto del grafo (por ejemplo: Grupo, Ámbito, Usuario).
url	string	Esta dirección URL es la ruta completa al recurso de origen de este tema del grafo.

Group

Object

Grupo de proyectos (por ejemplo, Colaborador, Lector, etc.)

Nombre	Tipo	Description
displayName	string	Nombre para mostrar del grupo
groupType	GroupType	Tipo de grupo

GroupEntitlement

Object

Una entidad de grupo con propiedades adicionales, incluidas su licencia, extensiones y pertenencia a proyectos

Nombre	Tipo	Description
group	GraphGroup	Referencia de miembro.
id	string	Identificador único que coincide con el identificador de GraphMember.
lastExecuted	string	[Readonly] La última vez que se ejecutó la regla de licencias de grupo (independientemente de si se realizaron cambios).
licenseRule	AccessLevel	Regla de licencia.
members	UserEntitlement[]	Miembros del grupo. Solo se usa al crear un nuevo grupo.
projectEntitlements	ProjectEntitlement[]	Relación entre un proyecto y los permisos efectivos del miembro en ese proyecto.
status	GroupLicensingRuleStatus	Estado de la regla de grupo.

GroupLicensingRuleStatus

Enumeration

Estado de la regla de grupo.

Valor	Description
applied	Se aplica la regla
applyPending	La regla se crea o actualiza, pero la aplicación está pendiente
incompatible	La regla de grupo no era compatible
unableToApply	La regla no se pudo aplicar inesperadamente y se debe reintentar

GroupType

Enumeration

Tipo de grupo

Valor	Description
custom
projectAdministrator
projectContributor
projectReader
projectStakeholder

LicensingSource

Enumeration

Origen de licencias (por ejemplo, Cuenta. MSDN, etc.)

Valor	Description
account
auto
msdn
none
profile
trial

MsdnLicenseType

Enumeration

Tipo de licencia de MSDN (por ejemplo, Visual Studio Professional, Visual Studio Enterprise etc.). Para usar MsdnLicenseType, LicensingSource debe definirse como "msdn" en el cuerpo de la solicitud.

Valor	Description
eligible
enterprise
none
platforms
premium
professional
testProfessional
ultimate

ProjectEntitlement

Object

Relación entre un proyecto y los permisos efectivos del usuario en ese proyecto.

Nombre	Tipo	Description
assignmentSource	AssignmentSource	Origen de asignación (por ejemplo, Grupo o Desconocido).
group	Group	Grupo de proyectos (por ejemplo, Colaborador, Lector, etc.)
projectPermissionInherited	ProjectPermissionInherited	Si el usuario hereda permisos para un proyecto a través de una pertenencia a grupos de Azure DevOps o AAD.
projectRef	ProjectRef	Referencia del proyecto
teamRefs	TeamRef[]	Referencia del equipo.

ProjectPermissionInherited

Enumeration

Si el usuario hereda los permisos de un proyecto a través de una pertenencia a grupos de Azure DevOps o AAD.

Valor	Description
inherited
notInherited
notSet

ProjectRef

Object

Referencia a un proyecto

Nombre	Tipo	Description
id	string	Identificador de proyecto.
name	string	Nombre del proyecto.

ReferenceLinks

Object

Clase que se va a representar una colección de vínculos de referencia de REST.

Nombre	Tipo	Description
links	object	Vista de lectura de los vínculos. Dado que los vínculos de referencia son de solo lectura, solo queremos exponerlos como de solo lectura.