Subscriptions - Query

参考

服务:: Notification

API 版本:: 7.1

查询订阅。如果订阅与一个或多个指定条件匹配，则返回订阅。

POST https://{service}dev.azure.com/{organization}/_apis/notification/subscriptionquery?api-version=7.1

URI 参数

名称	在	必需	类型	说明
organization	path		string	Azure DevOps 组织的名称。
service	path		string	此请求定向到的服务。
api-version	query	True	string	要使用的 API 版本。这应设置为“7.1”才能使用此版本的 API。

请求正文

名称	类型	说明
conditions	SubscriptionQueryCondition[]	要查询的一个或多个条件。如果指定了 2 个以上的条件，则返回每个条件的组合结果（即条件在逻辑上为 OR'ed）。
queryFlags	SubscriptionQueryFlags	标记将从查询返回的订阅类型。

响应

名称	类型	说明
200 OK	NotificationSubscription[]	成功作

安全性

oauth2

类型: oauth2
流向: 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

作用域

名称	说明
vso.notification	提供对订阅和事件元数据的读取访问权限，包括可筛选字段值。

示例

By subscriber

示例请求

HTTP

POST https://dev.azure.com/fabrikam/_apis/notification/subscriptionquery?api-version=7.1

{
  "conditions": [
    {
      "subscriber": "552e2388-e9bb-429e-ad71-c2fef2ad085f"
    }
  ]
}

示例响应

状态代码:: 200

{
  "count": 3,
  "value": [
    {
      "id": "105645",
      "url": "https://dev.azure.com/fabrikam/_apis/notification/Subscriptions/105645",
      "description": "A pull request is created or updated",
      "subscriber": {
        "id": "552e2388-e9bb-429e-ad71-c2fef2ad085f",
        "displayName": "[FabrikamCloud]\\Fab",
        "uniqueName": "vstfs:///Classification/TeamProject/3b3ae425-0079-421f-9101-bcf15d6df041\\Fab",
        "isContainer": true
      },
      "status": "enabled",
      "flags": "groupSubscription, canOptOut",
      "modifiedDate": "2017-01-10T17:53:24.337Z",
      "lastModifiedBy": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "scope": {
        "type": "none",
        "id": "00000000-0000-636f-6c6c-656374696f6e"
      },
      "filter": {
        "type": "Actor",
        "inclusions": [
          "author",
          "reviewer",
          "changedReviewers"
        ],
        "exclusions": [
          "initiator"
        ],
        "criteria": {
          "clauses": [],
          "groups": [],
          "maxGroupLevel": 0
        },
        "eventType": "ms.vss-code.git-pullrequest-event"
      },
      "channel": {
        "type": "User",
        "useCustomAddress": false
      },
      "adminSettings": {
        "blockUserOptOut": false
      },
      "subscriptionUserSettings": {
        "optedOut": false
      },
      "_links": {},
      "permissions": "view, edit, delete"
    },
    {
      "id": "105936",
      "url": "https://dev.azure.com/fabrikam/_apis/notification/Subscriptions/105936",
      "description": "A build completes",
      "subscriber": {
        "id": "552e2388-e9bb-429e-ad71-c2fef2ad085f",
        "displayName": "[FabrikamCloud]\\Fab",
        "uniqueName": "vstfs:///Classification/TeamProject/3b3ae425-0079-421f-9101-bcf15d6df041\\Fab",
        "isContainer": true
      },
      "status": "enabled",
      "flags": "groupSubscription",
      "modifiedDate": "2017-01-25T02:09:42.863Z",
      "lastModifiedBy": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "scope": {
        "type": "none",
        "id": "3b3ae425-0079-421f-9101-bcf15d6df041"
      },
      "filter": {
        "type": "Expression",
        "eventType": "ms.vss-build.build-completed-event"
      },
      "channel": {
        "type": "EmailHtml",
        "address": "tasd@boo.com",
        "useCustomAddress": true
      },
      "_links": {},
      "permissions": "view, edit, delete"
    },
    {
      "id": "114712",
      "url": "https://dev.azure.com/fabrikam/_apis/notification/Subscriptions/114712",
      "description": "A new work item enters our area path",
      "subscriber": {
        "id": "552e2388-e9bb-429e-ad71-c2fef2ad085f",
        "displayName": "[FabrikamCloud]\\Fab",
        "uniqueName": "vstfs:///Classification/TeamProject/3b3ae425-0079-421f-9101-bcf15d6df041\\Fab",
        "isContainer": true
      },
      "status": "enabled",
      "flags": "groupSubscription",
      "modifiedDate": "2017-03-13T04:46:18.027Z",
      "lastModifiedBy": {
        "id": "cd49a245-51cc-493a-ab1a-5c0feb5afaa3",
        "displayName": "Jamal Hartnett",
        "uniqueName": "fabrikamfiber16@outlook.com"
      },
      "scope": {
        "type": "none",
        "id": "00000000-0000-636f-6c6c-656374696f6e"
      },
      "filter": {
        "type": "Expression",
        "eventType": "ms.vss-work.workitem-changed-event"
      },
      "channel": {
        "type": "EmailHtml",
        "address": "myteam@fabrikam.org",
        "useCustomAddress": true
      },
      "_links": {},
      "permissions": "view, edit, delete"
    }
  ]
}

定义

名称	说明
IdentityRef
ISubscriptionChannel
ISubscriptionFilter
NotificationSubscription	订阅定义匹配事件的条件，以及如何通知订阅的订阅者有关这些事件。
ReferenceLinks	表示 REST 引用链接集合的类。
SubscriptionAdminSettings	组订阅的管理员管理设置。
SubscriptionDiagnostics	包含订阅的所有诊断设置。
SubscriptionFlags	进一步描述订阅的只读指示器。
SubscriptionPermissions	用户对此订阅拥有的权限。
SubscriptionQuery	通知订阅查询输入。
SubscriptionQueryCondition	订阅必须匹配的条件才能符合查询结果集的条件。并非所有字段都是必需的。订阅必须与指定的所有条件匹配才能符合结果集的条件。
SubscriptionQueryFlags	标记将从查询返回的订阅类型。
SubscriptionScope	资源（通常是帐户或项目），在其中发布事件。
SubscriptionStatus	订阅的状态。通常指示是否启用订阅。
SubscriptionTracing	控制订阅的单个诊断设置的数据。
SubscriptionUserSettings	组订阅的用户托管设置。

IdentityRef

Object

名称	类型	说明
_links	ReferenceLinks	此字段包含有关图形主题的零个或多个有趣的链接。可以调用这些链接以获取有关此图形主题的其他关系或更详细的信息。
descriptor	string	描述符是在系统运行时引用图形主题的主要方法。此字段将唯一标识帐户和组织中的同一图形主题。
directoryAlias	string	已弃用 - 可以通过查询 IdentityRef“_links”字典的“self”条目中引用的 Graph 用户来检索
displayName	string	这是图形主题的非唯一显示名称。若要更改此字段，必须在源提供程序中更改其值。
id	string
imageUrl	string	已弃用 - 在 IdentityRef“_links”字典的“虚拟形象”条目中可用
inactive	boolean	已弃用 - 可以通过查询 GraphUser“_links”字典的“membershipState”条目中引用的 Graph 成员身份状态来检索
isAadIdentity	boolean	已弃用 - 可以从描述符的主题类型推断（Descriptor.IsAadUserType/Descriptor.IsAadGroupType）
isContainer	boolean	已弃用 - 可以从描述符的主题类型推断（描述符.IsGroupType）
isDeletedInOrigin	boolean
profileUrl	string	已弃用 - 不在 ToIdentityRef 的大多数预先存在的实现中使用
uniqueName	string	已弃用 - 请改用 Domain+PrincipalName
url	string	此 URL 是指向此图形主题的源资源的完整路由。

ISubscriptionChannel

Object

名称	类型	说明
type	string

ISubscriptionFilter

Object

名称	类型	说明
eventType	string
type	string

NotificationSubscription

Object

订阅定义匹配事件的条件，以及如何通知订阅的订阅者有关这些事件。

名称	类型	说明
_links	ReferenceLinks	指向订阅的相关资源、API 和视图的链接。
adminSettings	SubscriptionAdminSettings	订阅的管理员管理设置。仅当订阅服务器是组时适用。
channel	ISubscriptionChannel	用于传送订阅触发的通知的通道。
description	string	订阅的说明。通常描述有助于标识订阅的筛选器条件。
diagnostics	SubscriptionDiagnostics	此订阅的诊断。
extendedProperties	object	任何额外的属性，如不同上下文的详细说明、用户/组上下文
filter	ISubscriptionFilter	订阅的匹配条件。 ExpressionFilter
flags	SubscriptionFlags	进一步描述订阅的只读指示器。
id	string	订阅标识符。
lastModifiedBy	IdentityRef	上次修改订阅的用户（或已创建）。
modifiedDate	string (date-time)	上次修改订阅的日期。如果自创建订阅后尚未更新订阅，则此值将指示创建订阅的时间。
permissions	SubscriptionPermissions	用户对此订阅拥有的权限。
scope	SubscriptionScope	必须从中发布事件的容器，以便与订阅匹配。如果为空，则作用域为当前主机（通常是帐户或项目集合）。例如，限定为项目 A 的订阅不会为从项目 B 发布的事件生成通知。
status	SubscriptionStatus	订阅的状态。通常指示是否启用订阅。
statusMessage	string	提供有关订阅状态的更多详细信息的消息。
subscriber	IdentityRef	将接收与订阅筛选条件匹配的事件通知的用户或组。
url	string	订阅的 REST API URL。
userSettings	SubscriptionUserSettings	订阅的用户托管设置。仅当订阅服务器是组时适用。通常用于指示呼叫用户是选择加入还是退出组订阅。

ReferenceLinks

Object

表示 REST 引用链接集合的类。

名称	类型	说明
links	object	链接的只读视图。由于引用链接是只读的，因此我们只想将其公开为只读链接。

SubscriptionAdminSettings

Object

组订阅的管理员管理设置。

名称	类型	说明
blockUserOptOut	boolean	如果为 true，订阅关联订阅的组成员无法选择（选择不收到通知）

SubscriptionDiagnostics

Object

包含订阅的所有诊断设置。

名称	类型	说明
deliveryResults	SubscriptionTracing	用于保留传递结果的诊断设置。用于服务挂钩订阅。
deliveryTracing	SubscriptionTracing	诊断设置，用于排查通知传递问题。
evaluationTracing	SubscriptionTracing	用于排查事件匹配问题的诊断设置。

SubscriptionFlags

枚举

进一步描述订阅的只读指示器。

值	说明
canOptOut	订阅订阅组成员的用户可以选择加入/退出订阅。
contributedSubscription	订阅是参与的，不会持久保存。这意味着订阅的某些字段（如筛选器）是只读的。
groupSubscription	订阅的订阅者是组，而不是用户
none	没有
oneActorMatches	对于基于角色的订阅，预期始终至少有一个与角色匹配的参与者
teamSubscription	如果订阅者是组，则它是一个团队。

SubscriptionPermissions

枚举

用户对此订阅拥有的权限。

值	说明
delete	删除订阅
edit	更新订阅
none	没有
view	说明、筛选器等的完整视图。不受限制。

SubscriptionQuery

Object

通知订阅查询输入。

名称	类型	说明
conditions	SubscriptionQueryCondition[]	要查询的一个或多个条件。如果指定了 2 个以上的条件，则返回每个条件的组合结果（即条件在逻辑上为 OR'ed）。
queryFlags	SubscriptionQueryFlags	标记将从查询返回的订阅类型。

SubscriptionQueryCondition

Object

订阅必须匹配的条件才能符合查询结果集的条件。并非所有字段都是必需的。订阅必须与指定的所有条件匹配才能符合结果集的条件。

名称	类型	说明
filter	ISubscriptionFilter	筛选匹配订阅必须具有的条件。通常，筛选器的类型和事件类型仅用于匹配。
flags	SubscriptionFlags	指定要查询的类型订阅的标志。
scope	string	匹配订阅必须具有的范围。
subscriberId	string (uuid)	必须订阅匹配订阅的订阅者（用户或组）的 ID。
subscriptionId	string	要查询的订阅的 ID。

SubscriptionQueryFlags

枚举

标记将从查询返回的订阅类型。

值	说明
alwaysReturnBasicInformation	对于订阅，调用方无权查看，返回基本（非机密）信息。
includeDeletedSubscriptions	包括标记为要删除的订阅。
includeFilterDetails	在每个订阅中包含完整的筛选器详细信息。
includeInvalidSubscriptions	包含具有无效订阅服务器的订阅。
includeSystemSubscriptions	包括系统订阅。
none

SubscriptionScope

Object

资源（通常是帐户或项目），在其中发布事件。

名称	类型	说明
id	string (uuid)	必需：这是类型范围的标识。
name	string	可选：作用域的显示名称
type	string	必需：范围的事件特定类型。

SubscriptionStatus

枚举

订阅的状态。通常指示是否启用订阅。

值	说明
disabled	订阅被禁用，通常由订阅的所有者禁用，并且不会生成任何通知。
disabledArgumentException	由于处理订阅时出现参数异常，订阅被禁用
disabledAsDuplicateOfDefault	订阅被禁用，因为它是默认订阅的副本。
disabledByAdmin	订阅由管理员禁用，而不是订阅的订阅者。
disabledFromProbation	由于失败，订阅已禁用服务。
disabledInactiveIdentity	订阅已禁用，因为标识不再处于活动状态
disabledInvalidPathClause	订阅已禁用，因为它具有无效的筛选器表达式。
disabledInvalidRoleExpression	订阅已禁用，因为它具有无效的角色表达式。
disabledMessageQueueNotSupported	订阅被禁用，因为不支持消息队列。
disabledMissingIdentity	订阅被禁用，因为它的订阅者未知。
disabledMissingPermissions	订阅被禁用，因为标识没有适当的权限
disabledProjectInvalid	由于项目无效，订阅被禁用
enabled	订阅处于活动状态。
enabledOnProbation	订阅处于活动状态，但由于交付失败或其他订阅问题，订阅处于缓期状态。
jailedByNotificationsVolume	订阅已禁用，因为它生成了大量通知。
pendingDeletion	订阅已禁用，将被删除。

SubscriptionTracing

Object

控制订阅的单个诊断设置的数据。

名称	类型	说明
enabled	boolean	指示是否启用诊断跟踪。
endDate	string (date-time)	跟踪到指定的结束日期。
maxTracedEntries	integer (int32)	要跟踪的结果详细信息的最大数目。
startDate	string (date-time)	日期和时间跟踪已启动。
tracedEntries	integer (int32)	跟踪直到剩余计数达到 0。

SubscriptionUserSettings

Object

组订阅的用户托管设置。

名称	类型	说明
optedOut	boolean	指示用户是否将收到关联组订阅的通知。

通过

Subscriptions - Query

URI 参数

请求正文

响应

安全性

oauth2

作用域

示例

By subscriber

示例请求

示例响应

定义

IdentityRef

ISubscriptionChannel

ISubscriptionFilter

NotificationSubscription

ReferenceLinks

SubscriptionAdminSettings

SubscriptionDiagnostics

SubscriptionFlags

SubscriptionPermissions

SubscriptionQuery

SubscriptionQueryCondition

SubscriptionQueryFlags

SubscriptionScope

SubscriptionStatus

SubscriptionTracing

SubscriptionUserSettings

其他资源