Resource Notification Subscription APIs

Subscribe Res Notify

URLs

POST zstack/v1/zwatch/resnotify/subscriptions

Headers

Authorization: OAuth the-session-uuid

Body

{
  "params": {
    "name": "zcf-sync",
    "resourceTypes": [
      "VmInstanceVO",
      "HostVO",
      "VolumeVO"
    ],
    "eventTypes": [
      "CREATE",
      "UPDATE",
      "DELETE"
    ],
    "type": "WEBHOOK",
    "webhookUrl": "http://example.com/webhook"
  },
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields can be omitted. They are shown to indicate that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" -X POST -d '{"params":{"name":"zcf-sync","resourceTypes":["VmInstanceVO","HostVO","VolumeVO"],"eventTypes":["CREATE","UPDATE","DELETE"],"type":"WEBHOOK","webhookUrl":"http://example.com/webhook"}}' http://localhost:8080/zstack/v1/zwatch/resnotify/subscriptions

Parameter List

Name	Type	Location	Description	Allowed Values	Starting Version
name (Optional)	String	body (included in the `params` structure)	Resource change notification subscription name		5.1.0
description (Optional)	String	body (included in the `params` structure)	Detailed description of the resource change notification subscription		5.1.0
resourceTypes (Optional)	List	body (included in the `params` structure)	List of resource types to subscribe to, such as ResourceVO, HostVO, VmInstanceVO, or AuditsVO		5.1.0
eventTypes (Optional)	List	body (included in the `params` structure)	List of event types to subscribe to. Valid values are CREATE, UPDATE, and DELETE		5.1.0
type (Optional)	String	body (included in the `params` structure)	Notification subscription type. Currently, WEBHOOK is supported	WEBHOOK	5.1.0
webhookUrl	String	body (included in the `params` structure)	Webhook URL that receives resource change notifications		5.1.0
secret (Optional)	String	body (included in the `params` structure)	Secret used to generate the X-ZStack-Signature signature		5.1.0
customHeaders (Optional)	String	body (included in the `params` structure)	Custom HTTP request headers attached when delivering the webhook, in JSON string format		5.1.0
resourceUuid (Optional)	String	body (included in the `params` structure)	Resource UUID		5.1.0
tagUuids (Optional)	List	body (included in the `params` structure)	Tag UUID list		5.1.0
systemTags (Optional)	List	body	System tags		5.1.0
userTags (Optional)	List	body	User tags		5.1.0

Response Example

{
  "inventory": {}
}

Name	Type	Description	Starting Version
success	boolean	Whether the resource change notification subscription succeeded	5.1.0
inventory	ResNotifySubscriptionInventory	For details, see inventory	5.1.0
error	ErrorCode	Error code. If this field is not null, the operation failed. This field is null when the operation succeeds. For details, see error	5.1.0

#inventory

Name	Type	Description	Starting Version
uuid	String	Resource change notification subscription UUID, which uniquely identifies the subscription	5.1.0
name	String	Resource change notification subscription name	5.1.0
description	String	Detailed description of the resource change notification subscription	5.1.0
resourceTypes	String	Comma-separated list of resource types matched by the subscription	5.1.0
eventTypes	String	Comma-separated list of event types matched by the subscription	5.1.0
createDate	Timestamp	Creation time	5.1.0
lastOpDate	Timestamp	Last modification time	5.1.0
type	ResNotifyType	For details, see type	5.1.0
state	ResNotifySubscriptionState	For details, see state	5.1.0
webhookRef	ResNotifyWebhookRefInventory	For details, see webhookRef	5.1.0

#type

Name	Type	Description	Starting Version
WEBHOOK	ResNotifyType	Deliver resource change notifications through an HTTP webhook	5.1.0
WEBSOCKET	ResNotifyType	Deliver resource change notifications through WebSocket. This value is currently reserved	5.1.0

#state

Name	Type	Description	Starting Version
Enabled	ResNotifySubscriptionState	The subscription is enabled and delivers events to matching notification endpoints	5.1.0
Disabled	ResNotifySubscriptionState	The subscription is disabled and does not deliver matching events	5.1.0

#webhookRef

Name	Type	Description	Starting Version
uuid	String	UUID referenced by the webhook, identical to the resource change notification subscription UUID	5.1.0
webhookUrl	String	Webhook URL that receives resource change notifications	5.1.0
secret	String	Secret used to generate the X-ZStack-Signature signature	5.1.0
customHeaders	String	Custom HTTP request headers attached when delivering the webhook, in JSON string format	5.1.0

#error

Name	Type	Description	Starting Version
code	String	Error code, which globally and uniquely identifies the error, for example, SYS.1000 or HOST.1001	0.6
description	String	Summary description of the error	0.6
details	String	Details of the error	0.6
elaboration	String	Reserved field. The default value is null	0.6
opaque	LinkedHashMap	Reserved field. The default value is null	0.6
cause	ErrorCode	Root error that caused the current error. This field is null if there is no source error	0.6

Java SDK

SubscribeResNotifyAction action = new SubscribeResNotifyAction();
action.name = "zcf-sync";
action.resourceTypes = asList("VmInstanceVO","HostVO","VolumeVO");
action.eventTypes = asList("CREATE","UPDATE","DELETE");
action.type = "WEBHOOK";
action.webhookUrl = "http://example.com/webhook";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
SubscribeResNotifyAction.Result res = action.call();

Python SDK

action = SubscribeResNotifyAction()
action.name = "zcf-sync"
action.resourceTypes = [VmInstanceVO, HostVO, VolumeVO]
action.eventTypes = [CREATE, UPDATE, DELETE]
action.type = "WEBHOOK"
action.webhookUrl = "http://example.com/webhook"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

DeleteResNotifySubscription

Delete Res Notify Subscription

API Request

URLs

DELETE zstack/v1/zwatch/resnotify/subscriptions/{uuid}

Headers

Authorization: OAuth the-session-uuid

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" -X DELETE http://localhost:8080/zstack/v1/zwatch/resnotify/subscriptions/subscription-uuid?deleteMode=Permissive

Parameter List

Name	Type	Location	Description	Starting Version
uuid	String	url	Resource change notification subscription UUID, which uniquely identifies the subscription	5.1.0
deleteMode (Optional)	String	query	Deletion mode. Valid values are Permissive and Enforcing, and the default is Permissive	5.1.0
systemTags (Optional)	List	query	System tags	5.1.0
userTags (Optional)	List	query	User tags	5.1.0

API Response

When the API succeeds, it returns an empty JSON structure{}. If an error occurs, the returned JSON structure contains an error field, for example:

{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

SDK Examples

Java SDK

DeleteResNotifySubscriptionAction action = new DeleteResNotifySubscriptionAction();
action.uuid = "subscription-uuid";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteResNotifySubscriptionAction.Result res = action.call();

Python SDK

action = DeleteResNotifySubscriptionAction()
action.uuid = "subscription-uuid"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

QueryResNotifySubscription

Query Res Notify Subscription

API Request

URLs

GET zstack/v1/zwatch/resnotify/subscriptions
GET zstack/v1/zwatch/resnotify/subscriptions/{uuid}

Headers

Authorization: OAuth the-session-uuid

Queryable Fields

Run the CLI tool and enter QueryResNotifySubscription, and press Tab to view all queryable fields and the names of resources available for cross-table queries.

API Response

When the API succeeds, it returns an empty JSON structure{}. If an error occurs, the returned JSON structure contains an error field, for example:

{
	"error": {
		"code": "SYS.1001",
		"description": "A message or a operation timeout",
		"details": "Create VM on KVM timeout after 300s"
	}
}

UpdateResNotifySubscription

Update Res Notify Subscription

API Request

URLs

PUT zstack/v1/zwatch/resnotify/subscriptions/{uuid}/actions

Headers

Authorization: OAuth the-session-uuid

Body

{
  "updateResNotifySubscription": {
    "resourceTypes": [
      "VmInstanceVO",
      "HostVO",
      "VolumeVO",
      "ClusterVO"
    ],
    "eventTypes": [
      "CREATE",
      "UPDATE",
      "DELETE"
    ]
  },
  "systemTags": [],
  "userTags": []
}

Note: In the preceding example, the systemTags and userTags fields can be omitted. They are shown to indicate that the body can contain these two fields.

Curl Example

curl -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" -X PUT -d '{"updateResNotifySubscription":{"resourceTypes":["VmInstanceVO","HostVO","VolumeVO","ClusterVO"],"eventTypes":["CREATE","UPDATE","DELETE"]}}' http://localhost:8080/zstack/v1/zwatch/resnotify/subscriptions/subscription-uuid/actions

Parameter List

Name	Type	Location	Description	Allowed Values	Starting Version
uuid	String	url	Resource change notification subscription UUID, which uniquely identifies the subscription		5.1.0
name (Optional)	String	body (included in the `updateResNotifySubscription` structure)	Resource change notification subscription name		5.1.0
description (Optional)	String	body (included in the `updateResNotifySubscription` structure)	Detailed description of the resource change notification subscription		5.1.0
resourceTypes (Optional)	List	body (included in the `updateResNotifySubscription` structure)	List of resource types to subscribe to, such as ResourceVO, HostVO, VmInstanceVO, or AuditsVO		5.1.0
eventTypes (Optional)	List	body (included in the `updateResNotifySubscription` structure)	List of event types to subscribe to. Valid values are CREATE, UPDATE, and DELETE		5.1.0
state (Optional)	String	body (included in the `updateResNotifySubscription` structure)	Subscription state, which can be set to Enabled or Disabled	Enabled Disabled	5.1.0
webhookUrl (Optional)	String	body (included in the `updateResNotifySubscription` structure)	Webhook URL that receives resource change notifications		5.1.0
secret (Optional)	String	body (included in the `updateResNotifySubscription` structure)	Secret used to generate the X-ZStack-Signature signature		5.1.0
customHeaders (Optional)	String	body (included in the `updateResNotifySubscription` structure)	Custom HTTP request headers attached when delivering the webhook, in JSON string format		5.1.0
systemTags (Optional)	List	body	System tags		5.1.0
userTags (Optional)	List	body	User tags		5.1.0

API Response

Response Example

{
  "inventory": {}
}

Name	Type	Description	Starting Version
success	boolean	Whether the resource change notification subscription was updated successfully	5.1.0
inventory	ResNotifySubscriptionInventory	For details, see inventory	5.1.0
error	ErrorCode	Error code. If this field is not null, the operation failed. This field is null when the operation succeeds. For details, see error	5.1.0

#inventory

Name	Type	Description	Starting Version
uuid	String	Resource change notification subscription UUID, which uniquely identifies the subscription	5.1.0
name	String	Resource change notification subscription name	5.1.0
description	String	Detailed description of the resource change notification subscription	5.1.0
resourceTypes	String	Comma-separated list of resource types matched by the subscription	5.1.0
eventTypes	String	Comma-separated list of event types matched by the subscription	5.1.0
createDate	Timestamp	Creation time	5.1.0
lastOpDate	Timestamp	Last modification time	5.1.0
type	ResNotifyType	For details, see type	5.1.0
state	ResNotifySubscriptionState	For details, see state	5.1.0
webhookRef	ResNotifyWebhookRefInventory	For details, see webhookRef	5.1.0

#type

Name	Type	Description	Starting Version
WEBHOOK	ResNotifyType	Deliver resource change notifications through an HTTP webhook	5.1.0
WEBSOCKET	ResNotifyType	Deliver resource change notifications through WebSocket. This value is currently reserved	5.1.0

#state

Name	Type	Description	Starting Version
Enabled	ResNotifySubscriptionState	The subscription is enabled and delivers events to matching notification endpoints	5.1.0
Disabled	ResNotifySubscriptionState	The subscription is disabled and does not deliver matching events	5.1.0

#webhookRef

Name	Type	Description	Starting Version
uuid	String	UUID referenced by the webhook, identical to the resource change notification subscription UUID	5.1.0
webhookUrl	String	Webhook URL that receives resource change notifications	5.1.0
secret	String	Secret used to generate the X-ZStack-Signature signature	5.1.0
customHeaders	String	Custom HTTP request headers attached when delivering the webhook, in JSON string format	5.1.0

#error

Name	Type	Description	Starting Version
code	String	Error code, which globally and uniquely identifies the error, for example, SYS.1000 or HOST.1001	0.6
description	String	Summary description of the error	0.6
details	String	Details of the error	0.6
elaboration	String	Reserved field. The default value is null	0.6
opaque	LinkedHashMap	Reserved field. The default value is null	0.6
cause	ErrorCode	Root error that caused the current error. This field is null if there is no source error	0.6

SDK Examples

Java SDK

UpdateResNotifySubscriptionAction action = new UpdateResNotifySubscriptionAction();
action.uuid = "subscription-uuid";
action.resourceTypes = asList("VmInstanceVO","HostVO","VolumeVO","ClusterVO");
action.eventTypes = asList("CREATE","UPDATE","DELETE");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateResNotifySubscriptionAction.Result res = action.call();

Python SDK

action = UpdateResNotifySubscriptionAction()
action.uuid = "subscription-uuid"
action.resourceTypes = [VmInstanceVO, HostVO, VolumeVO, ClusterVO]
action.eventTypes = [CREATE, UPDATE, DELETE]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

PreviousQuerySNSTopicSubscriber NextCapacity Management APIs