Service Principal Entitlements - Add

參考

Service:: Member Entitlement Management

API Version:: 7.1-preview.1

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

注意：如果您使用 AAD 應用程式註冊，您可以在企業應用程式中找到應用程式的服務主體，並確定在要求本文中使用服務主體的物件識別碼作為 originId 參數

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

URI 參數

名稱	位於	必要	類型	Description
organization	path	True	string	Azure DevOps 組織的名稱。
api-version	query	True	string	要使用的 API 版本。這應該設定為 '7.1-preview.1' 以使用此版本的 API。

要求本文

名稱	類型	Description
accessLevel	AccessLevel	成員的存取層級由授權表示。
dateCreated	string	[Readonly]成員加入至集合的日期。
groupAssignments	GroupEntitlement[]	[Readonly]此成員所屬的 GroupEntitlements。
id	string	符合與 GraphMember 相關聯之身分識別識別碼的唯一識別碼。
lastAccessedDate	string	[Readonly]上次存取集合的成員日期。
projectEntitlements	ProjectEntitlement[]	專案與該專案中成員的有效許可權之間的關聯性。
servicePrincipal	GraphServicePrincipal	ServicePrincipal 參考。

回應

名稱	類型	Description
200 OK	ServicePrincipalEntitlementsPostResponse	成功作業

安全性

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token 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

Scopes

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

範例

Sample Request

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

Sample Response

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": []
  }
}

定義

名稱	Description
AccessLevel	指派給使用者的授權
AccountLicenseType	帳戶授權類型 (例如 Express、專案關係人等) 。若要使用 AccountLicenseType，LicensingSource 應該在要求本文中定義為 'account'。
AccountUserStatus	帳戶中的使用者狀態
AssignmentSource	授權指派來源 (例如群組、未知等。
GraphGroup	圖形群組實體
GraphServicePrincipal
GraphUser
Group	專案群組 (例如參與者、讀者等)
GroupEntitlement	具有其他屬性的群組實體，包括其授權、延伸模組和專案成員資格
GroupLicensingRuleStatus	群組規則的狀態。
GroupType	群組類型
LicensingSource	授權來源 (例如帳戶。MSDN etc.)
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

指派給使用者的授權

名稱	類型	Description
accountLicenseType	AccountLicenseType	帳戶授權類型 (例如 Express、專案關係人等) 。若要使用 AccountLicenseType，LicensingSource 應該在要求本文中定義為 'account'。
assignmentSource	AssignmentSource	授權指派來源 (例如群組、未知等。
licenseDisplayName	string	授權的顯示名稱
licensingSource	LicensingSource	授權來源 (例如帳戶。MSDN etc.)
msdnLicenseType	MsdnLicenseType	MSDN 授權的類型 (，例如Visual Studio Professional、Visual Studio Enterprise等。) 。若要使用 MsdnLicenseType，LicensingSource 應該在要求本文中定義為 'msdn'。
status	AccountUserStatus	帳戶中的使用者狀態
statusMessage	string	狀態訊息。

AccountLicenseType

帳戶授權類型 (例如 Express、專案關係人等) 。若要使用 AccountLicenseType，LicensingSource 應該在要求本文中定義為 'account'。

名稱	類型	Description
advanced	string
earlyAdopter	string
express	string
none	string
professional	string
stakeholder	string

AccountUserStatus

帳戶中的使用者狀態

名稱	類型	Description
active	string	使用者至少登入 VSTS 帳戶一次
deleted	string	使用者已由 VSTS 帳戶管理員從 VSTS 帳戶中移除
disabled	string	使用者無法登入;主要由系統管理員用來暫時移除使用者，因為缺少或授權重新配置
expired	string	使用者可以登入;主要用於授權處於過期狀態，並提供寬限期
none	string
pending	string	使用者被 VSTS 帳戶管理員邀請加入 VSTS 帳戶，但尚未註冊/登入
pendingDisabled	string	使用者已停用;如果重新啟用，它們仍會處於擱置狀態

AssignmentSource

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

名稱	類型	Description
groupRule	string
none	string
unknown	string

GraphGroup

圖形群組實體

名稱	類型	Description
_links	ReferenceLinks	此欄位包含圖表主旨的相關零或更多有趣連結。您可以叫用這些連結來取得其他關聯性，或取得此圖表主體的詳細資訊。
description	string	一個簡短片語，可協助人類讀者厘清類似名稱的群組
descriptor	string	描述項是在系統執行時參考圖形主旨的主要方式。此欄位可唯一識別帳戶和組織之間的相同圖表主旨。
displayName	string	這是圖形主體的非唯一顯示名稱。若要變更此欄位，您必須變更來源提供者中的值。
domain	string	這代表圖形成員的來源容器名稱。 (對於 MSA 而言，這是「Windows Live ID」，針對 AD 的名稱、針對目錄的 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 是此圖形主體來源資源的完整路由。

GraphServicePrincipal

名稱	類型	Description
_links	ReferenceLinks	此欄位包含圖表主旨的相關零或更多有趣連結。您可以叫用這些連結來取得其他關聯性，或取得此圖表主體的詳細資訊。
applicationId	string
descriptor	string	描述項是在系統執行時參考圖形主旨的主要方式。此欄位可唯一識別帳戶和組織之間的相同圖表主旨。
directoryAlias	string	簡短且通常是支援目錄中使用者的唯一名稱。對於 AAD 使用者，這會對應至郵件昵稱，這通常與使用者的郵寄地址部分類似 @sign 之前。針對 GitHub 使用者，這會對應至 GitHub 使用者控制碼。
displayName	string	這是圖形主體的非唯一顯示名稱。若要變更此欄位，您必須變更來源提供者中的值。
domain	string	這代表圖形成員的來源容器名稱。 (對於 MSA 而言，這是「Windows Live ID」，針對 AD 的名稱、針對目錄的 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 是此圖形主體來源資源的完整路由。

GraphUser

名稱	類型	Description
_links	ReferenceLinks	此欄位包含圖表主旨的相關零或更多有趣連結。您可以叫用這些連結來取得其他關聯性，或取得此圖表主體的詳細資訊。
descriptor	string	描述項是在系統執行時參考圖形主旨的主要方式。此欄位可唯一識別帳戶和組織之間的相同圖表主旨。
directoryAlias	string	簡短且通常是支援目錄中使用者的唯一名稱。對於 AAD 使用者，這會對應至郵件昵稱，這通常與使用者的郵寄地址部分類似 @sign 之前。針對 GitHub 使用者，這會對應至 GitHub 使用者控制碼。
displayName	string	這是圖形主體的非唯一顯示名稱。若要變更此欄位，您必須變更來源提供者中的值。
domain	string	這代表圖形成員的來源容器名稱。 (對於 MSA 而言，這是「Windows Live ID」，針對 AD 的名稱、針對目錄的 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

專案群組 (例如參與者、讀者等)

名稱	類型	Description
displayName	string	群組的顯示名稱
groupType	GroupType	群組類型

GroupEntitlement

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

名稱	類型	Description
group	GraphGroup	成員參考。
id	string	符合 GraphMember 識別碼的唯一識別碼。
lastExecuted	string	[Readonly]不論是否已) 進行任何變更，上次執行群組授權規則的時間都會 (。
licenseRule	AccessLevel	授權規則。
members	UserEntitlement[]	群組成員。只有在建立新群組時才會使用。
projectEntitlements	ProjectEntitlement[]	專案與該專案中成員的有效許可權之間的關聯性。
status	GroupLicensingRuleStatus	群組規則的狀態。

GroupLicensingRuleStatus

群組規則的狀態。

名稱	類型	Description
applied	string	套用規則
applyPending	string	規則已建立或更新，但套用擱置中
incompatible	string	群組規則不相容
unableToApply	string	規則無法意外套用，應該重試

GroupType

群組類型

名稱	類型	Description
custom	string
projectAdministrator	string
projectContributor	string
projectReader	string
projectStakeholder	string

LicensingSource

授權來源 (例如帳戶。MSDN etc.)

名稱	類型	Description
account	string
auto	string
msdn	string
none	string
profile	string
trial	string

MsdnLicenseType

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

名稱	類型	Description
eligible	string
enterprise	string
none	string
platforms	string
premium	string
professional	string
testProfessional	string
ultimate	string

ProjectEntitlement

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

名稱	類型	Description
assignmentSource	AssignmentSource	指派來源 (例如群組或未知) 。
group	Group	專案群組 (例如參與者、讀者等)
projectPermissionInherited	ProjectPermissionInherited	使用者是否透過 Azure DevOps 或 AAD 群組成員資格繼承專案的許可權。
projectRef	ProjectRef	Project Ref
teamRefs	TeamRef[]	Team Ref.

ProjectPermissionInherited

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

名稱	類型	Description
inherited	string
notInherited	string
notSet	string

ProjectRef

專案的參考

名稱	類型	Description
id	string	專案識別碼。
name	string	專案名稱。

ReferenceLinks

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

名稱	類型	Description
links	object	連結的唯讀檢視。因為參考連結是唯讀的，所以我們只想要將它們公開為唯讀。