共用方式為

User Entitlements - Add

  • 參考
服務:
Member Entitlement Management
API 版本:
7.1

新增使用者、指派授權和延伸模組，並將其設為帳戶中專案群組的成員。

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

URI 參數

名稱 位於 必要 類型 Description
organization
 path True

string

Azure DevOps 組織的名稱。
api-version
 query True

string

要使用的 API 版本。 這應該設定為 『7.1』 以使用此版本的 API。

要求本文

名稱 類型 Description
accessLevel

AccessLevel

成員的存取層級是由授權表示。
dateCreated

string (date-time)

[Readonly]成員加入至集合的日期。
groupAssignments

GroupEntitlement[]

[Readonly]此成員所屬的 GroupEntitlements。
id

string (uuid)

符合與 GraphMember 相關聯之身分識別標識碼的唯一標識碼。
lastAccessedDate

string (date-time)

[Readonly]上次存取集合的成員日期。
projectEntitlements

ProjectEntitlement[]

專案與該專案中成員之有效許可權之間的關聯性。
user

GraphUser

用戶參考。

回應

名稱 類型 Description
200 OK

UserEntitlementsPostResponse

成功作業

安全性

oauth2

類型: oauth2
Flow: 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

範圍

名稱 Description
vso.memberentitlementmanagement_write 授與管理使用者、其授權，以及他們可存取的專案和延伸模組的能力

範例

範例要求

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

{
  "accessLevel": {
    "licensingSource": "account",
    "accountLicenseType": "express"
  },
  "extensions": [
    {
      "id": "ms.feed"
    }
  ],
  "user": {
    "principalName": "newuser@fabrikam.com",
    "subjectKind": "user"
  },
  "projectEntitlements": [
    {
      "group": {
        "groupType": "projectContributor"
      },
      "projectRef": {
        "id": "e5943a98-a842-4001-bd3b-06e756a7dfac"
      }
    }
  ]
}

範例回覆

狀態碼:
200 
{
  "operationResult": {
    "isSuccess": true,
    "errors": [],
    "userId": "08bbffa9-4944-4a98-b0c0-1fa718d5de3d",
    "result": {
      "id": "08bbffa9-4944-4a98-b0c0-1fa718d5de3d",
      "user": {
        "subjectKind": "user",
        "domain": "14c5367e-ee12-4c94-98b8-b52c1fe3cfb1",
        "principalName": "newuser@fabrikam.com",
        "mailAddress": "newuser@fabrikam.com",
        "origin": "aad",
        "originId": "00000000-0000-0000-0000-000000000000",
        "displayName": "newuser@fabrikam.com",
        "_links": {
          "self": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/bnd.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv"
          },
          "memberships": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/memberships/bnd.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv"
          },
          "membershipState": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/membershipstates/bnd.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv"
          },
          "storageKey": {
            "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/storagekeys/bnd.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv"
          }
        },
        "url": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/bnd.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv",
        "descriptor": "aad.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv"
      },
      "accessLevel": {
        "licensingSource": "account",
        "accountLicenseType": "express",
        "msdnLicenseType": "none",
        "licenseDisplayName": "Basic",
        "status": "pending",
        "statusMessage": "",
        "assignmentSource": "unknown"
      },
      "lastAccessedDate": "0001-01-01T08:00:00Z",
      "projectEntitlements": [],
      "extensions": [],
      "groupAssignments": []
    }
  },
  "isSuccess": true,
  "userEntitlement": {
    "id": "08bbffa9-4944-4a98-b0c0-1fa718d5de3d",
    "user": {
      "subjectKind": "user",
      "domain": "14c5367e-ee12-4c94-98b8-b52c1fe3cfb1",
      "principalName": "newuser@fabrikam.com",
      "mailAddress": "newuser@fabrikam.com",
      "origin": "aad",
      "originId": "00000000-0000-0000-0000-000000000000",
      "displayName": "newuser@fabrikam.com",
      "_links": {
        "self": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/bnd.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv"
        },
        "memberships": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/memberships/bnd.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv"
        },
        "membershipState": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/membershipstates/bnd.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv"
        },
        "storageKey": {
          "href": "https://vssps.dev.azure.com/fabrikam/_apis/graph/storagekeys/bnd.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv"
        }
      },
      "url": "https://vssps.dev.azure.com/fabrikam/_apis/graph/users/bnd.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv",
      "descriptor": "aad.dXBuOldpbmRvd3MgTGl2ZSBJRFxicmFuZG9uQGRldmJsYWNrb3BzLmlv"
    },
    "accessLevel": {
      "licensingSource": "account",
      "accountLicenseType": "express",
      "msdnLicenseType": "none",
      "licenseDisplayName": "Basic",
      "status": "pending",
      "statusMessage": "",
      "assignmentSource": "unknown"
    },
    "lastAccessedDate": "0001-01-01T08:00:00Z",
    "projectEntitlements": [],
    "extensions": [],
    "groupAssignments": []
  }
}

定義

名稱 Description
AccessLevel

指派給用戶的授權
AccountLicenseType

帳戶授權的類型（例如 Express、項目關係人等）。 若要使用 AccountLicenseType，LicensingSource 應該在要求本文中定義為 'account'。
AccountUserStatus

帳戶中的用戶狀態
AssignmentSource

授權的指派來源（例如群組、未知等。
GraphGroup

圖形群組實體
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 參考連結集合的類別。
TeamRef

小組的參考
UserEntitlement

具有其他屬性的用戶實體，包括其授權、延伸模組和專案成員資格
UserEntitlementOperationResult
UserEntitlementsPostResponse

AccessLevel

Object

指派給用戶的授權

名稱 類型 Description
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'。

值 Description
advanced
earlyAdopter
express
none
professional
stakeholder

AccountUserStatus

列舉型別

帳戶中的用戶狀態

值 Description
active

使用者已至少登入 VSTS 帳戶一次
deleted

VSTS 帳戶管理員會從 VSTS 帳戶中移除使用者
disabled

用戶無法登入;主要由系統管理員用來暫時移除使用者，因為缺席或授權重新配置
expired

用戶可以登入;主要用於授權處於過期狀態，並提供寬限期
none
pending

使用者被 VSTS 帳戶管理員邀請加入 VSTS 帳戶，但尚未註冊/登入
pendingDisabled

使用者已停用;如果重新啟用，它們仍會處於擱置狀態

AssignmentSource

列舉型別

授權的指派來源（例如群組、未知等。

值 Description
groupRule
none
unknown

GraphGroup

Object

圖形群組實體

名稱 類型 Description
_links

ReferenceLinks

此欄位包含圖表主旨的相關零或更多有趣連結。 您可以叫用這些連結，以取得此圖表主題的其他關聯性或更詳細的資訊。
description

string

協助人類讀者釐清具有類似名稱的群組的簡短片語
descriptor

string

描述元是在系統執行時參考圖表主旨的主要方式。 此欄位會唯一識別帳戶和組織之間的相同圖表主題。
displayName

string

這是圖形主體的非唯一顯示名稱。 若要變更此欄位，您必須在來源提供者中變更其值。
domain

string

這代表圖形成員的來源容器名稱。 （針對 MSA，這是「Windows Live ID」，針對 AD 的功能變數名稱、針對 AAD 目錄的 tenantID、VSTS 群組 ScopeId 等）
legacyDescriptor

string

[僅限內部使用]如果您需要使用身分識別描述元存取舊版 IMS，則舊版描述元在這裡。
mailAddress

string

指定圖表成員的記錄電子郵件位址。 這可能與主體名稱不同。
origin

string

來源識別碼的來源提供者類型（例如：AD、AAD、MSA）
originId

string

來源系統的唯一標識碼。 通常是 sid、物件識別碼或 Guid。 連結和取消連結作業可能會讓用戶變更此值，因為使用者不受不同的提供者支援，而且新提供者中有不同的唯一標識符。
principalName

string

這是來源提供者中這個圖表成員的 PrincipalName。 來源提供者可能會隨著時間變更此字段，而且不保證 VSTS 的圖表成員生命週期不可變。
subjectKind

string

此欄位會識別圖表主旨的類型（例如：群組、範圍、使用者）。
url

string

此 URL 是此圖表主體來源資源的完整路由。

GraphUser

Object
名稱 類型 Description
_links

ReferenceLinks

此欄位包含圖表主旨的相關零或更多有趣連結。 您可以叫用這些連結，以取得此圖表主題的其他關聯性或更詳細的資訊。
descriptor

string

描述元是在系統執行時參考圖表主旨的主要方式。 此欄位會唯一識別帳戶和組織之間的相同圖表主題。
directoryAlias

string

支援目錄中用戶的簡短一般唯一名稱。 對於 AAD 使用者，這會對應至郵件昵稱，這通常但不一定類似於 @ 符號前使用者郵件位址的一部分。 對於 GitHub 使用者，這會對應至 GitHub 使用者句柄。
displayName

string

這是圖形主體的非唯一顯示名稱。 若要變更此欄位，您必須在來源提供者中變更其值。
domain

string

這代表圖形成員的來源容器名稱。 （針對 MSA，這是「Windows Live ID」，針對 AD 的功能變數名稱、針對 AAD 目錄的 tenantID、VSTS 群組 ScopeId 等）
isDeletedInOrigin

boolean

當為 true 時，已在識別提供者中刪除群組
legacyDescriptor

string

[僅限內部使用]如果您需要使用身分識別描述元存取舊版 IMS，則舊版描述元在這裡。
mailAddress

string

指定圖表成員的記錄電子郵件位址。 這可能與主體名稱不同。
metaType

string

來源中使用者的中繼類型，例如 「member」、“guest” 等。如需一組可能的值，請參閱 UserMetaType。
origin

string

來源識別碼的來源提供者類型（例如：AD、AAD、MSA）
originId

string

來源系統的唯一標識碼。 通常是 sid、物件識別碼或 Guid。 連結和取消連結作業可能會讓用戶變更此值，因為使用者不受不同的提供者支援，而且新提供者中有不同的唯一標識符。
principalName

string

這是來源提供者中這個圖表成員的 PrincipalName。 來源提供者可能會隨著時間變更此字段，而且不保證 VSTS 的圖表成員生命週期不可變。
subjectKind

string

此欄位會識別圖表主旨的類型（例如：群組、範圍、使用者）。
url

string

此 URL 是此圖表主體來源資源的完整路由。

Group

Object

專案群組（例如參與者、讀者等）

名稱 類型 Description
displayName

string

群組的顯示名稱
groupType

GroupType

群組類型

GroupEntitlement

Object

具有其他屬性的群組實體，包括其授權、延伸模組和專案成員資格

名稱 類型 Description
group

GraphGroup

成員參考。
id

string (uuid)

符合 GraphMember 識別碼的唯一標識碼。
lastExecuted

string (date-time)

[Readonly]上次執行群組授權規則的時間（不論是否進行任何變更）。
licenseRule

AccessLevel

授權規則。
members

UserEntitlement[]

群組成員。 只有在建立新群組時才會使用。
projectEntitlements

ProjectEntitlement[]

專案與該專案中成員之有效許可權之間的關聯性。
status

GroupLicensingRuleStatus

群組規則的狀態。

GroupLicensingRuleStatus

列舉型別

群組規則的狀態。

值 Description
applied

套用規則
applyPending

規則已建立或更新，但套用擱置中
incompatible

群組規則不相容
unableToApply

規則無法意外套用，應重試

GroupType

列舉型別

群組類型

值 Description
custom
projectAdministrator
projectContributor
projectReader
projectStakeholder

LicensingSource

列舉型別

授權來源（例如帳戶。MSDN 等）

值 Description
account
auto
msdn
none
profile
trial

MsdnLicenseType

列舉型別

MSDN 授權的類型（例如 Visual Studio Professional、Visual Studio Enterprise 等）。 若要使用 MsdnLicenseType，LicensingSource 應該在要求本文中定義為 'msdn'。

值 Description
eligible
enterprise
none
platforms
premium
professional
testProfessional
ultimate

ProjectEntitlement

Object

專案與該專案中使用者有效許可權之間的關聯性。

名稱 類型 Description
assignmentSource

AssignmentSource

指派來源（例如群組或未知）。
group

Group

專案群組（例如參與者、讀者等）
projectPermissionInherited

ProjectPermissionInherited

使用者是否透過 Azure DevOps 或 AAD 群組成員資格繼承項目的許可權。
projectRef

ProjectRef

項目參考
teamRefs

TeamRef[]

團隊參考。

ProjectPermissionInherited

列舉型別

使用者是否透過 Azure DevOps 或 AAD 群組成員資格繼承項目的許可權。

值 Description
inherited
notInherited
notSet

ProjectRef

Object

項目的參考

名稱 類型 Description
id

string (uuid)

項目標識碼。
name

string

專案名稱。
Object

表示 REST 參考連結集合的類別。

名稱 類型 Description
links

object

連結的只讀檢視。 因為參考連結是只讀的，所以我們只想要將其公開為只讀。

TeamRef

Object

小組的參考

名稱 類型 Description
id

string (uuid)

小組標識碼
name

string

小組名稱

UserEntitlement

Object

具有其他屬性的用戶實體，包括其授權、延伸模組和專案成員資格

名稱 類型 Description
accessLevel

AccessLevel

成員的存取層級是由授權表示。
dateCreated

string (date-time)

[Readonly]成員加入至集合的日期。
groupAssignments

GroupEntitlement[]

[Readonly]此成員所屬的 GroupEntitlements。
id

string (uuid)

符合與 GraphMember 相關聯之身分識別標識碼的唯一標識碼。
lastAccessedDate

string (date-time)

[Readonly]上次存取集合的成員日期。
projectEntitlements

ProjectEntitlement[]

專案與該專案中成員之有效許可權之間的關聯性。
user

GraphUser

用戶參考。

UserEntitlementOperationResult

Object
名稱 類型 Description
errors

object[]

與對應的錯誤訊息配對的錯誤碼清單。
isSuccess

boolean

作業的成功狀態。
result

string (T)

產生的權利屬性。 如需特定實作，請參閱：
userId

string (uuid)

正在處理之成員的標識碼。

UserEntitlementsPostResponse

Object
名稱 類型 Description
isSuccess

boolean

如果所有作業都成功，則為 True。
operationResult

UserEntitlementOperationResult

作業結果。
userEntitlement

UserEntitlement

套用作業之後的用戶權利結果。