Dela via


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

ContributionConstraint[]

List of shared constraints defined by this extension

contributionTypes

ContributionType[]

List of contribution types defined by this extension

contributions

Contribution[]

List of contributions made by this extension

demands

string[]

List of explicit demands required by this extension

eventCallbacks

ExtensionEventCallbackCollection

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

ExtensionFile[]

This is the set of files available from the extension.

flags

ExtensionFlags

Extension flags relevant to contribution consumers

installState

InstalledExtensionState

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

ExtensionLicensing

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

InstalledExtension

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

ContributionConstraint

Specifies a constraint that can be used to dynamically include/exclude a given contribution

ContributionLicensingBehaviorType

How the inclusion of this contribution should change based on licensing

ContributionPropertyDescription

Description about a property of a contribution type

ContributionPropertyType

The type of value used for this property

ContributionType

A contribution type, given by a json schema

ExtensionEventCallback

Base class for an event callback for an extension

ExtensionEventCallbackCollection

Collection of event callbacks - endpoints called when particular extension events occur.

ExtensionFile
ExtensionFlags

Extension flags relevant to contribution consumers

ExtensionLicensing

How an extension should handle including contributions based on licensing

ExtensionStateFlags

States of an installed extension

InstalledExtension

Represents a VSTS extension along with its installation state

InstalledExtensionState

The state of an installed extension

InstalledExtensionStateIssue

Represents an installation issue

InstalledExtensionStateIssueType

Installation issue type (Warning, Error)

JObject

Represents a JSON object.

LicensingOverride

Maps a contribution to a licensing behavior

Contribution

An individual contribution made by an extension

Name Type Description
constraints

ContributionConstraint[]

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

JObject

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

JObject

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

ContributionPropertyType

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,  ContributionPropertyDescription>

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

ExtensionEventCallback

Optional. Defines an endpoint that gets called via a POST request to notify that an extension disable has occurred.

postEnable

ExtensionEventCallback

Optional. Defines an endpoint that gets called via a POST request to notify that an extension enable has occurred.

postInstall

ExtensionEventCallback

Optional. Defines an endpoint that gets called via a POST request to notify that an extension install has completed.

postUninstall

ExtensionEventCallback

Optional. Defines an endpoint that gets called via a POST request to notify that an extension uninstall has occurred.

postUpdate

ExtensionEventCallback

Optional. Defines an endpoint that gets called via a POST request to notify that an extension update has occurred.

preInstall

ExtensionEventCallback

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

ExtensionEventCallback

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

LicensingOverride[]

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

ContributionConstraint[]

List of shared constraints defined by this extension

contributionTypes

ContributionType[]

List of contribution types defined by this extension

contributions

Contribution[]

List of contributions made by this extension

demands

string[]

List of explicit demands required by this extension

eventCallbacks

ExtensionEventCallbackCollection

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

ExtensionFile[]

This is the set of files available from the extension.

flags

ExtensionFlags

Extension flags relevant to contribution consumers

installState

InstalledExtensionState

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

ExtensionLicensing

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

ExtensionStateFlags

States of an installed extension

installationIssues

InstalledExtensionStateIssue[]

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

InstalledExtensionStateIssueType

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

ContributionLicensingBehaviorType

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