Installed Extensions - Update
Update an installed extension. Typically this API is used to enable or disable an extension.
PATCH https://extmgmt.dev.azure.com/{organization}/_apis/extensionmanagement/installedextensions?api-version=7.1-preview.1
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
organization
|
path | True |
string |
The name of the Azure DevOps organization. |
api-version
|
query | True |
string |
Version of the API to use. This should be set to '7.1-preview.1' to use this version of the api. |
Request Body
Name | Type | Description |
---|---|---|
baseUri |
string |
Uri used as base for other relative uri's defined in extension |
constraints |
List of shared constraints defined by this extension |
|
contributionTypes |
List of contribution types defined by this extension |
|
contributions |
List of contributions made by this extension |
|
demands |
string[] |
List of explicit demands required by this extension |
eventCallbacks |
Collection of endpoints that get called when particular extension events occur |
|
extensionId |
string |
The friendly extension id for this extension - unique for a given publisher. |
extensionName |
string |
The display name of the extension. |
fallbackBaseUri |
string |
Secondary location that can be used as base for other relative uri's defined in extension |
files |
This is the set of files available from the extension. |
|
flags |
Extension flags relevant to contribution consumers |
|
installState |
Information about this particular installation of the extension |
|
language |
string |
Language Culture Name set by the Gallery |
lastPublished |
string |
This represents the date/time the extensions was last updated in the gallery. This doesnt mean this version was updated the value represents changes to any and all versions of the extension. |
licensing |
How this extension behaves with respect to licensing |
|
manifestVersion |
number |
Version of the extension manifest format/content |
publisherId |
string |
Unique id of the publisher of this extension |
publisherName |
string |
The display name of the publisher |
registrationId |
string |
Unique id for this extension (the same id is used for all versions of a single extension) |
restrictedTo |
string[] |
Default user claims applied to all contributions (except the ones which have been specified restrictedTo explicitly) to control the visibility of a contribution. |
scopes |
string[] |
List of all oauth scopes required by this extension |
serviceInstanceType |
string |
The ServiceInstanceType(Guid) of the VSTS service that must be available to an account in order for the extension to be installed |
version |
string |
Version of this extension |
Responses
Name | Type | Description |
---|---|---|
200 OK |
successful operation |
Security
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
Name | Description |
---|---|
vso.extension_manage | Grants the ability to install, uninstall, and perform other administrative actions on installed extensions. |
Definitions
Name | Description |
---|---|
Contribution |
An individual contribution made by an extension |
Contribution |
Specifies a constraint that can be used to dynamically include/exclude a given contribution |
Contribution |
How the inclusion of this contribution should change based on licensing |
Contribution |
Description about a property of a contribution type |
Contribution |
The type of value used for this property |
Contribution |
A contribution type, given by a json schema |
Extension |
Base class for an event callback for an extension |
Extension |
Collection of event callbacks - endpoints called when particular extension events occur. |
Extension |
|
Extension |
Extension flags relevant to contribution consumers |
Extension |
How an extension should handle including contributions based on licensing |
Extension |
States of an installed extension |
Installed |
Represents a VSTS extension along with its installation state |
Installed |
The state of an installed extension |
Installed |
Represents an installation issue |
Installed |
Installation issue type (Warning, Error) |
JObject |
Represents a JSON object. |
Licensing |
Maps a contribution to a licensing behavior |
Contribution
An individual contribution made by an extension
Name | Type | Description |
---|---|---|
constraints |
List of constraints (filters) that should be applied to the availability of this contribution |
|
description |
string |
Description of the contribution/type |
id |
string |
Fully qualified identifier of the contribution/type |
includes |
string[] |
Includes is a set of contributions that should have this contribution included in their targets list. |
properties |
Properties/attributes of this contribution |
|
restrictedTo |
string[] |
List of demanded claims in order for the user to see this contribution (like anonymous, public, member...). |
targets |
string[] |
The ids of the contribution(s) that this contribution targets. (parent contributions) |
type |
string |
Id of the Contribution Type |
visibleTo |
string[] |
VisibleTo can be used to restrict whom can reference a given contribution/type. This value should be a list of publishers or extensions access is restricted too. Examples: "ms" - Means only the "ms" publisher can reference this. "ms.vss-web" - Means only the "vss-web" extension from the "ms" publisher can reference this. |
ContributionConstraint
Specifies a constraint that can be used to dynamically include/exclude a given contribution
Name | Type | Description |
---|---|---|
group |
integer |
An optional property that can be specified to group constraints together. All constraints within a group are AND'd together (all must be evaluate to True in order for the contribution to be included). Different groups of constraints are OR'd (only one group needs to evaluate to True for the contribution to be included). |
id |
string |
Fully qualified identifier of a shared constraint |
inverse |
boolean |
If true, negate the result of the filter (include the contribution if the applied filter returns false instead of true) |
name |
string |
Name of the IContributionFilter plugin |
properties |
Properties that are fed to the contribution filter class |
|
relationships |
string[] |
Constraints can be optionally be applied to one or more of the relationships defined in the contribution. If no relationships are defined then all relationships are associated with the constraint. This means the default behaviour will eliminate the contribution from the tree completely if the constraint is applied. |
ContributionLicensingBehaviorType
How the inclusion of this contribution should change based on licensing
Name | Type | Description |
---|---|---|
alwaysInclude |
string |
Always include the contribution regardless of whether or not the user is licensed for the extension |
onlyIfLicensed |
string |
Default value - only include the contribution if the user is licensed for the extension |
onlyIfUnlicensed |
string |
Only include the contribution if the user is NOT licensed for the extension |
ContributionPropertyDescription
Description about a property of a contribution type
Name | Type | Description |
---|---|---|
description |
string |
Description of the property |
name |
string |
Name of the property |
required |
boolean |
True if this property is required |
type |
The type of value used for this property |
ContributionPropertyType
The type of value used for this property
Name | Type | Description |
---|---|---|
array |
string |
Value is an array |
boolean |
string |
Value is True or False |
dateTime |
string |
Value is a DateTime object |
dictionary |
string |
Value is a generic Dictionary/JObject/property bag |
double |
string |
Value is a double |
guid |
string |
Value is a GUID |
integer |
string |
Value is an integer |
object |
string |
Value is an arbitrary/custom object |
string |
string |
Value is a string |
unknown |
string |
Contribution type is unknown (value may be anything) |
uri |
string |
Value is a Uri |
ContributionType
A contribution type, given by a json schema
Name | Type | Description |
---|---|---|
description |
string |
Description of the contribution/type |
id |
string |
Fully qualified identifier of the contribution/type |
indexed |
boolean |
Controls whether or not contributions of this type have the type indexed for queries. This allows clients to find all extensions that have a contribution of this type. NOTE: Only TrustedPartners are allowed to specify indexed contribution types. |
name |
string |
Friendly name of the contribution/type |
properties |
<string,
Contribution |
Describes the allowed properties for this contribution type |
visibleTo |
string[] |
VisibleTo can be used to restrict whom can reference a given contribution/type. This value should be a list of publishers or extensions access is restricted too. Examples: "ms" - Means only the "ms" publisher can reference this. "ms.vss-web" - Means only the "vss-web" extension from the "ms" publisher can reference this. |
ExtensionEventCallback
Base class for an event callback for an extension
Name | Type | Description |
---|---|---|
uri |
string |
The uri of the endpoint that is hit when an event occurs |
ExtensionEventCallbackCollection
Collection of event callbacks - endpoints called when particular extension events occur.
Name | Type | Description |
---|---|---|
postDisable |
Optional. Defines an endpoint that gets called via a POST request to notify that an extension disable has occurred. |
|
postEnable |
Optional. Defines an endpoint that gets called via a POST request to notify that an extension enable has occurred. |
|
postInstall |
Optional. Defines an endpoint that gets called via a POST request to notify that an extension install has completed. |
|
postUninstall |
Optional. Defines an endpoint that gets called via a POST request to notify that an extension uninstall has occurred. |
|
postUpdate |
Optional. Defines an endpoint that gets called via a POST request to notify that an extension update has occurred. |
|
preInstall |
Optional. Defines an endpoint that gets called via a POST request to notify that an extension install is about to occur. Response indicates whether to proceed or abort. |
|
versionCheck |
For multi-version extensions, defines an endpoint that gets called via an OPTIONS request to determine the particular version of the extension to be used |
ExtensionFile
Name | Type | Description |
---|---|---|
assetType |
string |
|
language |
string |
|
source |
string |
ExtensionFlags
Extension flags relevant to contribution consumers
Name | Type | Description |
---|---|---|
builtIn |
string |
A built-in extension is installed for all VSTS accounts by default |
trusted |
string |
The extension comes from a fully-trusted publisher |
ExtensionLicensing
How an extension should handle including contributions based on licensing
Name | Type | Description |
---|---|---|
overrides |
A list of contributions which deviate from the default licensing behavior |
ExtensionStateFlags
States of an installed extension
Name | Type | Description |
---|---|---|
autoUpgradeError |
string |
Error performing auto-upgrade. For example, if the new version has demands not supported the extension cannot be auto-upgraded. |
builtIn |
string |
Extension is a built in |
disabled |
string |
Extension is disabled |
error |
string |
Extension is currently in an error state |
multiVersion |
string |
Extension has multiple versions |
needsReauthorization |
string |
Extension scopes have changed and the extension requires re-authorization |
none |
string |
No flags set |
trusted |
string |
Trusted extensions are ones that are given special capabilities. These tend to come from Microsoft and can't be published by the general public. Note: BuiltIn extensions are always trusted. |
unInstalled |
string |
Extension is not installed. This is for builtin extensions only and can not otherwise be set. |
versionCheckError |
string |
Error performing version check |
warning |
string |
Extension is currently in a warning state, that can cause a degraded experience. The degraded experience can be caused for example by some installation issues detected such as implicit demands not supported. |
InstalledExtension
Represents a VSTS extension along with its installation state
Name | Type | Description |
---|---|---|
baseUri |
string |
Uri used as base for other relative uri's defined in extension |
constraints |
List of shared constraints defined by this extension |
|
contributionTypes |
List of contribution types defined by this extension |
|
contributions |
List of contributions made by this extension |
|
demands |
string[] |
List of explicit demands required by this extension |
eventCallbacks |
Collection of endpoints that get called when particular extension events occur |
|
extensionId |
string |
The friendly extension id for this extension - unique for a given publisher. |
extensionName |
string |
The display name of the extension. |
fallbackBaseUri |
string |
Secondary location that can be used as base for other relative uri's defined in extension |
files |
This is the set of files available from the extension. |
|
flags |
Extension flags relevant to contribution consumers |
|
installState |
Information about this particular installation of the extension |
|
language |
string |
Language Culture Name set by the Gallery |
lastPublished |
string |
This represents the date/time the extensions was last updated in the gallery. This doesnt mean this version was updated the value represents changes to any and all versions of the extension. |
licensing |
How this extension behaves with respect to licensing |
|
manifestVersion |
number |
Version of the extension manifest format/content |
publisherId |
string |
Unique id of the publisher of this extension |
publisherName |
string |
The display name of the publisher |
registrationId |
string |
Unique id for this extension (the same id is used for all versions of a single extension) |
restrictedTo |
string[] |
Default user claims applied to all contributions (except the ones which have been specified restrictedTo explicitly) to control the visibility of a contribution. |
scopes |
string[] |
List of all oauth scopes required by this extension |
serviceInstanceType |
string |
The ServiceInstanceType(Guid) of the VSTS service that must be available to an account in order for the extension to be installed |
version |
string |
Version of this extension |
InstalledExtensionState
The state of an installed extension
Name | Type | Description |
---|---|---|
flags |
States of an installed extension |
|
installationIssues |
List of installation issues |
|
lastUpdated |
string |
The time at which this installation was last updated |
InstalledExtensionStateIssue
Represents an installation issue
Name | Type | Description |
---|---|---|
message |
string |
The error message |
source |
string |
Source of the installation issue, for example "Demands" |
type |
Installation issue type (Warning, Error) |
InstalledExtensionStateIssueType
Installation issue type (Warning, Error)
Name | Type | Description |
---|---|---|
error |
string |
Represents an installation error, for example an explicit demand not supported |
warning |
string |
Represents an installation warning, for example an implicit demand not supported |
JObject
Represents a JSON object.
Name | Type | Description |
---|---|---|
item |
string |
|
type |
string |
Gets the node type for this JToken. |
LicensingOverride
Maps a contribution to a licensing behavior
Name | Type | Description |
---|---|---|
behavior |
How the inclusion of this contribution should change based on licensing |
|
id |
string |
Fully qualified contribution id which we want to define licensing behavior for |