通过

Service Principal Entitlements - Add

服务:
Member Entitlement Management
API 版本:
7.1-preview.1

添加服务主体、分配许可证和扩展，并将其设为帐户中的项目组的成员。

注意：如果使用 AAD 应用注册，可以在企业应用程序中查找应用的服务主体，并确保在请求正文中使用服务主体的对象 ID 作为 originId 参数

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

URI 参数

名称 在 必需 类型 说明
organization
 path True

string

Azure DevOps 组织的名称。
api-version
 query True

string

要使用的 API 版本。 这应设置为“7.1-preview.1”才能使用此版本的 API。

请求正文

名称 类型 说明
accessLevel

AccessLevel

成员的访问级别由许可证表示。
dateCreated

string (date-time)

[Readonly]成员添加到集合中的日期。
groupAssignments

GroupEntitlement[]

[Readonly]此成员所属的 GroupEntitlements。
id

string (uuid)

与 GraphMember 关联的标识 ID 匹配的唯一标识符。
lastAccessedDate

string (date-time)

[Readonly]上次访问集合的成员的日期。
projectEntitlements

ProjectEntitlement[]

项目与成员在该项目中的有效权限之间的关系。
servicePrincipal

GraphServicePrincipal

ServicePrincipal 引用。

响应

名称 类型 说明
200 OK

ServicePrincipalEntitlementsPostResponse

成功作

安全性

oauth2

类型: oauth2
流向: accessCode
授权 URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
令牌 URL: 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

作用域

名称 说明
vso.memberentitlementmanagement_write 授予管理用户、其许可证以及可以访问的项目和扩展的能力

示例

示例请求

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"
  }
}

示例响应

状态代码:
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": []
  }
}

定义

名称 说明
AccessLevel

分配给用户的许可证
AccountLicenseType

帐户许可证类型（例如 Express、利益干系人等）。 若要使用 AccountLicenseType，应在请求正文中将 LicensingSource 定义为“account”。
AccountUserStatus

帐户中的用户状态
AssignmentSource

许可证的分配源（例如组、未知等）
GraphGroup

图形组实体
GraphServicePrincipal
GraphUser
Group

项目组（例如参与者、读者等）
GroupEntitlement

具有附加属性的组实体，包括其许可证、扩展和项目成员身份
GroupLicensingRuleStatus

组规则的状态。
GroupType

组类型
LicensingSource

许可源（例如帐户）MSDN 等）
MsdnLicenseType

MSDN 许可证的类型（例如 Visual Studio Professional、Visual Studio Enterprise 等）。 若要使用 MsdnLicenseType，应在请求正文中将 LicensingSource 定义为“msdn”。
ProjectEntitlement

项目与项目中用户的有效权限之间的关系。
ProjectPermissionInherited

用户是否通过 Azure DevOps 或 AAD 组成员身份继承对项目的权限。
ProjectRef

对项目的引用
ReferenceLinks

表示 REST 引用链接集合的类。
ServicePrincipalEntitlement
ServicePrincipalEntitlementOperationResult
ServicePrincipalEntitlementsPostResponse
TeamRef

对团队的引用
UserEntitlement

具有附加属性的用户实体，包括其许可证、扩展和项目成员身份

AccessLevel

Object

分配给用户的许可证

名称 类型 说明
accountLicenseType

AccountLicenseType

帐户许可证类型（例如 Express、利益干系人等）。 若要使用 AccountLicenseType，应在请求正文中将 LicensingSource 定义为“account”。
assignmentSource

AssignmentSource

许可证的分配源（例如组、未知等）
licenseDisplayName

string

许可证的显示名称
licensingSource

LicensingSource

许可源（例如帐户）MSDN 等）
msdnLicenseType

MsdnLicenseType

MSDN 许可证的类型（例如 Visual Studio Professional、Visual Studio Enterprise 等）。 若要使用 MsdnLicenseType，应在请求正文中将 LicensingSource 定义为“msdn”。
status

AccountUserStatus

帐户中的用户状态
statusMessage

string

状态消息。

AccountLicenseType

枚举

帐户许可证类型（例如 Express、利益干系人等）。 若要使用 AccountLicenseType，应在请求正文中将 LicensingSource 定义为“account”。

值 说明
none
earlyAdopter
express
professional
advanced
stakeholder

AccountUserStatus

枚举

帐户中的用户状态

值 说明
none
active

用户至少登录到 VSTS 帐户一次
disabled

用户无法登录;主要用于管理员因缺少或许可证重新分配而暂时删除用户
deleted

用户已由 VSTS 帐户管理员从 VSTS 帐户中删除
pending

用户被 VSTS 帐户管理员邀请加入 VSTS 帐户，但尚未注册/登录
expired

用户可以登录;主要用于许可证处于过期状态，我们给予宽限期
pendingDisabled

用户已禁用;如果重新启用，它们仍将处于挂起状态

AssignmentSource

枚举

许可证的分配源（例如组、未知等）

值 说明
none
unknown
groupRule

GraphGroup

Object

图形组实体

名称 类型 说明
_links

ReferenceLinks

此字段包含有关图形主题的零个或多个有趣的链接。 可以调用这些链接以获取有关此图形主题的其他关系或更详细的信息。
description

string

帮助人类读者消除类似名称的组的简短短语
descriptor

string

描述符是在系统运行时引用图形主题的主要方法。 此字段将唯一标识帐户和组织中的同一图形主题。
displayName

string

这是图形主题的非唯一显示名称。 若要更改此字段，必须在源提供程序中更改其值。
domain

string

这表示图形成员的源容器的名称。 （对于 MSA，这是“Windows Live ID”，对于 AD 域名、目录的租户 ID、VSTS 组 ScopeId 等）
legacyDescriptor

string

[仅限内部使用]如果需要使用标识描述符访问旧版 IMS，则此处提供了旧描述符。
mailAddress

string

给定图形成员的记录的电子邮件地址。 这可能不同于主体名称。
origin

string

源标识符的源提供程序类型（例如：AD、AAD、MSA）
originId

string

源系统的唯一标识符。 通常为 sid、对象 ID 或 Guid。 链接和取消链接作可能会导致用户更改此值，因为该用户不受其他提供程序的支持，并且新提供程序中具有不同的唯一 ID。
principalName

string

这是源提供程序中此图形成员的 PrincipalName。 源提供程序可能会随时间推移更改此字段，并且不保证 VSTS 的图形成员的生存期不可变。
subjectKind

string

此字段标识图形主题的类型（例如：组、范围、用户）。
url

string

此 URL 是指向此图形主题的源资源的完整路由。

GraphServicePrincipal

Object
名称 类型 说明
_links

ReferenceLinks

此字段包含有关图形主题的零个或多个有趣的链接。 可以调用这些链接以获取有关此图形主题的其他关系或更详细的信息。
applicationId

string

descriptor

string

描述符是在系统运行时引用图形主题的主要方法。 此字段将唯一标识帐户和组织中的同一图形主题。
directoryAlias

string

后盾目录中用户通常唯一的短名称。 对于 AAD 用户，这对应于邮件昵称，这通常但不一定类似于 @ 签名前用户电子邮件地址的一部分。 对于 GitHub 用户，这对应于 GitHub 用户句柄。
displayName

string

这是图形主题的非唯一显示名称。 若要更改此字段，必须在源提供程序中更改其值。
domain

string

这表示图形成员的源容器的名称。 （对于 MSA，这是“Windows Live ID”，对于 AD 域名、目录的租户 ID、VSTS 组 ScopeId 等）
isDeletedInOrigin

boolean

如果为 true，则已在标识提供者中删除该组
legacyDescriptor

string

[仅限内部使用]如果需要使用标识描述符访问旧版 IMS，则此处提供了旧描述符。
mailAddress

string

给定图形成员的记录的电子邮件地址。 这可能不同于主体名称。
metaType

string

源中用户的元类型，例如“member”、“guest”等。有关可能值集，请参阅 UserMetaType。
origin

string

源标识符的源提供程序类型（例如：AD、AAD、MSA）
originId

string

源系统的唯一标识符。 通常为 sid、对象 ID 或 Guid。 链接和取消链接作可能会导致用户更改此值，因为该用户不受其他提供程序的支持，并且新提供程序中具有不同的唯一 ID。
principalName

string

这是源提供程序中此图形成员的 PrincipalName。 源提供程序可能会随时间推移更改此字段，并且不保证 VSTS 的图形成员的生存期不可变。
subjectKind

string

此字段标识图形主题的类型（例如：组、范围、用户）。
url

string

此 URL 是指向此图形主题的源资源的完整路由。

GraphUser

Object
名称 类型 说明
_links

ReferenceLinks

此字段包含有关图形主题的零个或多个有趣的链接。 可以调用这些链接以获取有关此图形主题的其他关系或更详细的信息。
descriptor

string

描述符是在系统运行时引用图形主题的主要方法。 此字段将唯一标识帐户和组织中的同一图形主题。
directoryAlias

string

后盾目录中用户通常唯一的短名称。 对于 AAD 用户，这对应于邮件昵称，这通常但不一定类似于 @ 签名前用户电子邮件地址的一部分。 对于 GitHub 用户，这对应于 GitHub 用户句柄。
displayName

string

这是图形主题的非唯一显示名称。 若要更改此字段，必须在源提供程序中更改其值。
domain

string

这表示图形成员的源容器的名称。 （对于 MSA，这是“Windows Live ID”，对于 AD 域名、目录的租户 ID、VSTS 组 ScopeId 等）
isDeletedInOrigin

boolean

如果为 true，则已在标识提供者中删除该组
legacyDescriptor

string

[仅限内部使用]如果需要使用标识描述符访问旧版 IMS，则此处提供了旧描述符。
mailAddress

string

给定图形成员的记录的电子邮件地址。 这可能不同于主体名称。
metaType

string

源中用户的元类型，例如“member”、“guest”等。有关可能值集，请参阅 UserMetaType。
origin

string

源标识符的源提供程序类型（例如：AD、AAD、MSA）
originId

string

源系统的唯一标识符。 通常为 sid、对象 ID 或 Guid。 链接和取消链接作可能会导致用户更改此值，因为该用户不受其他提供程序的支持，并且新提供程序中具有不同的唯一 ID。
principalName

string

这是源提供程序中此图形成员的 PrincipalName。 源提供程序可能会随时间推移更改此字段，并且不保证 VSTS 的图形成员的生存期不可变。
subjectKind

string

此字段标识图形主题的类型（例如：组、范围、用户）。
url

string

此 URL 是指向此图形主题的源资源的完整路由。

Group

Object

项目组（例如参与者、读者等）

名称 类型 说明
displayName

string

组的显示名称
groupType

GroupType

组类型

GroupEntitlement

Object

具有附加属性的组实体，包括其许可证、扩展和项目成员身份

名称 类型 说明
group

GraphGroup

成员引用。
id

string (uuid)

与 GraphMember ID 匹配的唯一标识符。
lastExecuted

string (date-time)

[Readonly]上次执行组许可规则时（无论是否进行了任何更改）。
licenseRule

AccessLevel

许可证规则。
members

UserEntitlement[]

组成员。 仅在创建新组时使用。
projectEntitlements

ProjectEntitlement[]

项目与成员在该项目中的有效权限之间的关系。
status

GroupLicensingRuleStatus

组规则的状态。

GroupLicensingRuleStatus

枚举

组规则的状态。

值 说明
applyPending

规则已创建或更新，但应用处于挂起状态
applied

应用规则
incompatible

组规则不兼容
unableToApply

规则无法意外应用，应重试

GroupType

枚举

组类型

值 说明
projectStakeholder
projectReader
projectContributor
projectAdministrator
custom

LicensingSource

枚举

许可源（例如帐户）MSDN 等）

值 说明
none
account
msdn
profile
auto
trial

MsdnLicenseType

枚举

MSDN 许可证的类型（例如 Visual Studio Professional、Visual Studio Enterprise 等）。 若要使用 MsdnLicenseType，应在请求正文中将 LicensingSource 定义为“msdn”。

值 说明
none
eligible
professional
platforms
testProfessional
premium
ultimate
enterprise

ProjectEntitlement

Object

项目与项目中用户的有效权限之间的关系。

名称 类型 说明
assignmentSource

AssignmentSource

分配源（例如组或未知）。
group

Group

项目组（例如参与者、读者等）
projectPermissionInherited

ProjectPermissionInherited

用户是否通过 Azure DevOps 或 AAD 组成员身份继承对项目的权限。
projectRef

ProjectRef

Project Ref
teamRefs

TeamRef[]

团队参考

ProjectPermissionInherited

枚举

用户是否通过 Azure DevOps 或 AAD 组成员身份继承对项目的权限。

值 说明
notSet
notInherited
inherited

ProjectRef

Object

对项目的引用

名称 类型 说明
id

string (uuid)

项目 ID。
name

string

项目名称。
Object

表示 REST 引用链接集合的类。

名称 类型 说明
links

object

链接的只读视图。 由于引用链接是只读的，因此我们只想将其公开为只读链接。

ServicePrincipalEntitlement

Object
名称 类型 说明
accessLevel

AccessLevel

成员的访问级别由许可证表示。
dateCreated

string (date-time)

[Readonly]成员添加到集合中的日期。
groupAssignments

GroupEntitlement[]

[Readonly]此成员所属的 GroupEntitlements。
id

string (uuid)

与 GraphMember 关联的标识 ID 匹配的唯一标识符。
lastAccessedDate

string (date-time)

[Readonly]上次访问集合的成员的日期。
projectEntitlements

ProjectEntitlement[]

项目与成员在该项目中的有效权限之间的关系。
servicePrincipal

GraphServicePrincipal

ServicePrincipal 引用。

ServicePrincipalEntitlementOperationResult

Object
名称 类型 说明
errors

object[]

与相应的错误消息配对的错误代码列表。
isSuccess

boolean

作的成功状态。
result

string (T)

生成的权利属性。 有关特定实现，另请参阅： <seealso cref=“T：Microsoft.VisualStudio.Services.MemberEntitlementManagement.WebApi.ServicePrincipalEntitlementOperationResult” /><seealso cref=“T：Microsoft.VisualStudio.Services.MemberEntitlementManagement.WebApi.UserEntitlementOperationResult” />
servicePrincipalId

string (uuid)

要对其执行 ServicePrincipal 的标识符。

ServicePrincipalEntitlementsPostResponse

Object
名称 类型 说明
isSuccess

boolean

operationResult

ServicePrincipalEntitlementOperationResult

servicePrincipalEntitlement

ServicePrincipalEntitlement

TeamRef

Object

对团队的引用

名称 类型 说明
id

string (uuid)

团队 ID
name

string

团队名称

UserEntitlement

Object

具有附加属性的用户实体，包括其许可证、扩展和项目成员身份

名称 类型 说明
accessLevel

AccessLevel

成员的访问级别由许可证表示。
dateCreated

string (date-time)

[Readonly]成员添加到集合中的日期。
groupAssignments

GroupEntitlement[]

[Readonly]此成员所属的 GroupEntitlements。
id

string (uuid)

与 GraphMember 关联的标识 ID 匹配的唯一标识符。
lastAccessedDate

string (date-time)

[Readonly]上次访问集合的成员的日期。
projectEntitlements

ProjectEntitlement[]

项目与成员在该项目中的有效权限之间的关系。
user

GraphUser

用户参考。