Notifications - Query
Query for notifications. A notification includes details about the event, the request to and the response from the consumer service.
POST https://{instance}/{collection}/_apis/hooks/notificationsquery?api-version=4.1
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
collection
|
path | True |
string |
The name of the Team Foundation Server collection. |
instance
|
path | True |
string |
TFS server name ({server:port}) |
api-version
|
query | True |
string |
Version of the API to use. This should be set to '4.1' to use this version of the api. |
Request Body
Name | Type | Description |
---|---|---|
associatedSubscriptions |
The subscriptions associated with the notifications returned from the query |
|
includeDetails |
boolean |
If true, we will return all notification history for the query provided; otherwise, the summary is returned. |
maxCreatedDate |
string |
Optional maximum date at which the notification was created |
maxResults |
integer |
Optional maximum number of overall results to include |
maxResultsPerSubscription |
integer |
Optional maximum number of results for each subscription. Only takes effect when a list of subscription ids is supplied in the query. |
minCreatedDate |
string |
Optional minimum date at which the notification was created |
publisherId |
string |
Optional publisher id to restrict the results to |
resultType |
Optional notification result type to filter results to |
|
results |
Results from the query |
|
status |
Optional notification status to filter results to |
|
subscriptionIds |
string[] |
Optional list of subscription ids to restrict the results to |
summary |
Summary of notifications - the count of each result type (success, fail, ..). |
Responses
Name | Type | Description |
---|---|---|
200 OK |
successful operation |
Security
accessToken
Personal access token. Use any value for the user name and the token as the password.
Type:
basic
Definitions
Name | Description |
---|---|
Event |
Encapsulates the properties of an event. |
Formatted |
Provides different formats of an event message |
Identity |
|
Notification |
Defines the data contract of the result of processing an event for a subscription. |
Notification |
Defines the data contract of notification details. |
Notification |
Result of the notification |
Notification |
Summary of a particular result and count. |
Notifications |
Defines a query for service hook notifications. |
Notification |
Status of the notification |
Notification |
Summary of the notifications for a subscription. |
Reference |
The class to represent a collection of REST reference links. |
Resource |
The base class for all resource containers, i.e. Account, Collection, Project |
Session |
Represents a session token to be attached in Events for Consumer actions that need it. |
Subscription |
Encapsulates an event subscription. |
Subscription |
Event
Encapsulates the properties of an event.
Name | Type | Description |
---|---|---|
createdDate |
string |
Gets or sets the UTC-based date and time that this event was created. |
detailedMessage |
Gets or sets the detailed message associated with this event. |
|
eventType |
string |
Gets or sets the type of this event. |
id |
string |
Gets or sets the unique identifier of this event. |
message |
Gets or sets the (brief) message associated with this event. |
|
publisherId |
string |
Gets or sets the identifier of the publisher that raised this event. |
resource |
object |
Gets or sets the data associated with this event. |
resourceContainers |
<string,
Resource |
Gets or sets the resource containers. |
resourceVersion |
string |
Gets or sets the version of the data associated with this event. |
sessionToken |
Gets or sets the Session Token that can be used in further interactions |
FormattedEventMessage
Provides different formats of an event message
Name | Type | Description |
---|---|---|
html |
string |
Gets or sets the html format of the message |
markdown |
string |
Gets or sets the markdown format of the message |
text |
string |
Gets or sets the raw text of the message |
IdentityRef
Name | Type | Description |
---|---|---|
_links |
This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject. |
|
descriptor |
string |
The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Collections. |
directoryAlias |
string |
|
displayName |
string |
This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider. |
id |
string |
|
imageUrl |
string |
|
inactive |
boolean |
|
isAadIdentity |
boolean |
|
isContainer |
boolean |
|
profileUrl |
string |
|
uniqueName |
string |
|
url |
string |
This url is the full route to the source resource of this graph subject. |
Notification
Defines the data contract of the result of processing an event for a subscription.
Name | Type | Description |
---|---|---|
createdDate |
string |
Gets or sets date and time that this result was created. |
details |
Details about this notification (if available) |
|
eventId |
string |
The event id associated with this notification |
id |
integer |
The notification id |
modifiedDate |
string |
Gets or sets date and time that this result was last modified. |
result |
Result of the notification |
|
status |
Status of the notification |
|
subscriberId |
string |
The subscriber Id associated with this notification. This is the last identity who touched in the subscription. In case of test notifications it can be the tester if the subscription is not created yet. |
subscriptionId |
string |
The subscription id associated with this notification |
NotificationDetails
Defines the data contract of notification details.
Name | Type | Description |
---|---|---|
completedDate |
string |
Gets or sets the time that this notification was completed (response received from the consumer) |
consumerActionId |
string |
Gets or sets this notification detail's consumer action identifier. |
consumerId |
string |
Gets or sets this notification detail's consumer identifier. |
consumerInputs |
object |
Gets or sets this notification detail's consumer inputs. |
dequeuedDate |
string |
Gets or sets the time that this notification was dequeued for processing |
errorDetail |
string |
Gets or sets this notification detail's error detail. |
errorMessage |
string |
Gets or sets this notification detail's error message. |
event |
Gets or sets this notification detail's event content. |
|
eventType |
string |
Gets or sets this notification detail's event type. |
processedDate |
string |
Gets or sets the time that this notification was finished processing (just before the request is sent to the consumer) |
publisherId |
string |
Gets or sets this notification detail's publisher identifier. |
publisherInputs |
object |
Gets or sets this notification detail's publisher inputs. |
queuedDate |
string |
Gets or sets the time that this notification was queued (created) |
request |
string |
Gets or sets this notification detail's request. |
requestAttempts |
integer |
Number of requests attempted to be sent to the consumer |
requestDuration |
number |
Duration of the request to the consumer in seconds |
response |
string |
Gets or sets this notification detail's reponse. |
NotificationResult
Result of the notification
Name | Type | Description |
---|---|---|
failed |
string |
The notification failed to be sent successfully to the consumer |
pending |
string |
The notification has not yet completed |
succeeded |
string |
The notification was sent successfully |
NotificationResultsSummaryDetail
Summary of a particular result and count.
Name | Type | Description |
---|---|---|
notificationCount |
integer |
Count of notification sent out with a matching result. |
result |
Result of the notification |
NotificationsQuery
Defines a query for service hook notifications.
Name | Type | Description |
---|---|---|
associatedSubscriptions |
The subscriptions associated with the notifications returned from the query |
|
includeDetails |
boolean |
If true, we will return all notification history for the query provided; otherwise, the summary is returned. |
maxCreatedDate |
string |
Optional maximum date at which the notification was created |
maxResults |
integer |
Optional maximum number of overall results to include |
maxResultsPerSubscription |
integer |
Optional maximum number of results for each subscription. Only takes effect when a list of subscription ids is supplied in the query. |
minCreatedDate |
string |
Optional minimum date at which the notification was created |
publisherId |
string |
Optional publisher id to restrict the results to |
resultType |
Optional notification result type to filter results to |
|
results |
Results from the query |
|
status |
Optional notification status to filter results to |
|
subscriptionIds |
string[] |
Optional list of subscription ids to restrict the results to |
summary |
Summary of notifications - the count of each result type (success, fail, ..). |
NotificationStatus
Status of the notification
Name | Type | Description |
---|---|---|
completed |
string |
The request completed |
processing |
string |
The notification has been dequeued and has begun processing. |
queued |
string |
The notification has been queued |
requestInProgress |
string |
The consumer action has processed the notification. The request is in progress. |
NotificationSummary
Summary of the notifications for a subscription.
Name | Type | Description |
---|---|---|
results |
The notification results for this particular subscription. |
|
subscriptionId |
string |
The subscription id associated with this notification |
ReferenceLinks
The class to represent a collection of REST reference links.
Name | Type | Description |
---|---|---|
links |
object |
The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only. |
ResourceContainer
The base class for all resource containers, i.e. Account, Collection, Project
Name | Type | Description |
---|---|---|
baseUrl |
string |
Gets or sets the container's base URL, i.e. the URL of the host (collection, application, or deploument) containing the container resource. |
id |
string |
Gets or sets the container's specific Id. |
name |
string |
Gets or sets the container's name. |
url |
string |
Gets or sets the container's REST API URL. |
SessionToken
Represents a session token to be attached in Events for Consumer actions that need it.
Name | Type | Description |
---|---|---|
error |
string |
The error message in case of error |
token |
string |
The access token |
validTo |
string |
The expiration date in UTC |
Subscription
Encapsulates an event subscription.
Name | Type | Description |
---|---|---|
_links |
Reference Links |
|
actionDescription |
string |
|
consumerActionId |
string |
|
consumerId |
string |
|
consumerInputs |
object |
Consumer input values |
createdBy | ||
createdDate |
string |
|
eventDescription |
string |
|
eventType |
string |
|
id |
string |
|
modifiedBy | ||
modifiedDate |
string |
|
probationRetries |
string |
|
publisherId |
string |
|
publisherInputs |
object |
Publisher input values |
resourceVersion |
string |
|
status | ||
subscriber | ||
url |
string |
SubscriptionStatus
Name | Type | Description |
---|---|---|
disabledBySystem |
string |
The subscription is disabled by the system. |
disabledByUser |
string |
The subscription is disabled by a user. |
enabled |
string |
The subscription is enabled. |
onProbation |
string |
The subscription is temporarily on probation by the system. |
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for