Installed Extensions - Get

Reference

Service:: Extension Management

API Version:: 6.0-preview.1

Get an installed extension by its publisher and extension name.

GET https://extmgmt.dev.azure.com/{organization}/_apis/extensionmanagement/installedextensionsbyname/{publisherName}/{extensionName}?api-version=6.0-preview.1

With optional parameters:

GET https://extmgmt.dev.azure.com/{organization}/_apis/extensionmanagement/installedextensionsbyname/{publisherName}/{extensionName}?assetTypes={assetTypes}&api-version=6.0-preview.1

URI Parameters

Name	In	Required	Type	Description
extensionName	path	True	string	Name of the extension. Example: "ops-tools".
organization	path	True	string	The name of the Azure DevOps organization.
publisherName	path	True	string	Name of the publisher. Example: "fabrikam".
api-version	query	True	string	Version of the API to use. This should be set to '6.0-preview.1' to use this version of the api.
assetTypes	query		string array (string)

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.

Examples

Sample request

HTTP

GET https://extmgmt.dev.azure.com/fabrikam/_apis/extensionmanagement/installedextensionsbyname/ms/samples-contributions-guide?api-version=6.0-preview.1

Sample response

Status code:: 200

{
  "extensionId": "samples-contributions-guide",
  "extensionName": "Contributions Guide",
  "publisherId": "ms-samples",
  "publisherName": "Microsoft",
  "version": "0.1.35",
  "manifestVersion": 1,
  "baseUri": "https://ms-samples.gallerycdn.vsassets.io/extensions/ms-samples/samples-contributions-guide/0.1.35/1484832479380",
  "fallbackBaseUri": "https://ms-samples.gallery.vsassets.io/_apis/public/gallery/publisher/ms-samples/extension/samples-contributions-guide/0.1.35/assetbyname",
  "scopes": [],
  "installState": {
    "flags": "none",
    "lastUpdated": "2017-11-30T21:38:02.463Z"
  },
  "contributionTypes": [],
  "lastPublished": "2017-01-19T13:28:00.85Z",
  "files": []
}

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.