文档中心知识库API Explorer
文档中心›ZVF›ZStack ZSphere›开发手册ZVF

资源通知订阅相关接口

订阅资源变更通知(SubscribeResNotify)

创建资源变更通知订阅。订阅启用后，管理节点会在匹配的资源创建、更新或删除事件发生时向指定 webhook 地址投递通知。

API请求

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: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
name (可选) String body(包含在params结构中) 资源变更通知订阅名称 5.1.0
description (可选) String body(包含在params结构中) 资源变更通知订阅的详细描述 5.1.0
resourceTypes (可选) List body(包含在params结构中) 需要订阅的资源类型列表，例如 ResourceVO、HostVO、VmInstanceVO 或 AuditsVO 5.1.0
eventTypes (可选) List body(包含在params结构中) 需要订阅的事件类型列表，可选 CREATE、UPDATE、DELETE 5.1.0
type (可选) String body(包含在params结构中) 通知订阅类型，当前支持 WEBHOOK
  • WEBHOOK
 5.1.0
webhookUrl String body(包含在params结构中) 接收资源变更通知的 webhook URL 5.1.0
secret (可选) String body(包含在params结构中) 用于生成 X-ZStack-Signature 签名的密钥 5.1.0
customHeaders (可选) String body(包含在params结构中) 投递 webhook 时附加的自定义 HTTP 请求头，JSON 字符串格式 5.1.0
resourceUuid (可选) String body(包含在params结构中) 资源UUID 5.1.0
tagUuids (可选) List body(包含在params结构中) 标签UUID列表 5.1.0
systemTags (可选) List body 系统标签 5.1.0
userTags (可选) List body 用户标签 5.1.0

API返回

返回示例
{
  "inventory": {}
}
名字 类型 描述 起始版本
success boolean 订阅资源变更通知是否成功 5.1.0
inventory ResNotifySubscriptionInventory 详情参考inventory 5.1.0
error ErrorCode 错误码，若不为null，则表示操作失败, 操作成功时该字段为null。 详情参考error 5.1.0
#inventory
名字 类型 描述 起始版本
uuid String 资源变更通知订阅的UUID，唯一标识该订阅 5.1.0
name String 资源变更通知订阅名称 5.1.0
description String 资源变更通知订阅的详细描述 5.1.0
resourceTypes String 订阅匹配的资源类型列表，以逗号分隔 5.1.0
eventTypes String 订阅匹配的事件类型列表，以逗号分隔 5.1.0
createDate Timestamp 创建时间 5.1.0
lastOpDate Timestamp 最后一次修改时间 5.1.0
type ResNotifyType 详情参考type 5.1.0
state ResNotifySubscriptionState 详情参考state 5.1.0
webhookRef ResNotifyWebhookRefInventory 详情参考webhookRef 5.1.0
#type
名字 类型 描述 起始版本
WEBHOOK ResNotifyType 通过 HTTP webhook 投递资源变更通知 5.1.0
WEBSOCKET ResNotifyType 通过 WebSocket 投递资源变更通知，当前预留 5.1.0
#state
名字 类型 描述 起始版本
Enabled ResNotifySubscriptionState 订阅已启用，会向匹配的通知端点投递事件 5.1.0
Disabled ResNotifySubscriptionState 订阅已禁用，不会投递匹配事件 5.1.0
#webhookRef
名字 类型 描述 起始版本
uuid String webhook 引用的UUID，与资源变更通知订阅UUID一致 5.1.0
webhookUrl String 接收资源变更通知的 webhook URL 5.1.0
secret String 用于生成 X-ZStack-Signature 签名的密钥 5.1.0
customHeaders String 投递 webhook 时附加的自定义 HTTP 请求头，JSON 字符串格式 5.1.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

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)

删除指定的资源变更通知订阅，删除后该订阅不再接收资源变更事件并停止 webhook 投递。

API请求

URLs
DELETE zstack/v1/zwatch/resnotify/subscriptions/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源变更通知订阅的UUID，唯一标识该订阅 5.1.0
deleteMode (可选) String query 删除模式，可选 Permissive 或 Enforcing，默认 Permissive 5.1.0
systemTags (可选) List query 系统标签 5.1.0
userTags (可选) List query 用户标签 5.1.0

API返回

该API成功时返回一个空的JSON结构{}，出错时返回的JSON结构包含一个error字段，例如：

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

SDK示例

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)

查询资源变更通知订阅，可按 UUID 或查询条件获取订阅配置、状态以及 webhook 引用信息。

API请求

URLs
GET zstack/v1/zwatch/resnotify/subscriptions
GET zstack/v1/zwatch/resnotify/subscriptions/{uuid}
Headers
Authorization: OAuth the-session-uuid

可查询字段

运行CLI命令行工具，输入QueryResNotifySubscription并按Tab键查看所有可查询字段以及可跨表查询的资源名。

API返回

该API成功时返回一个空的JSON结构{}，出错时返回的JSON结构包含一个error字段，例如：

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

更新资源变更通知订阅(UpdateResNotifySubscription)

更新资源变更通知订阅配置，包括订阅名称、资源类型、事件类型、状态、webhook 地址、签名密钥以及自定义请求头。

API请求

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: 上述示例中systemTags、userTags字段可以省略。列出是为了表示body中可以包含这两个字段。
Curl示例
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
参数列表
名字 类型 位置 描述 可选值 起始版本
uuid String url 资源变更通知订阅的UUID，唯一标识该订阅 5.1.0
name (可选) String body(包含在updateResNotifySubscription结构中) 资源变更通知订阅名称 5.1.0
description (可选) String body(包含在updateResNotifySubscription结构中) 资源变更通知订阅的详细描述 5.1.0
resourceTypes (可选) List body(包含在updateResNotifySubscription结构中) 需要订阅的资源类型列表，例如 ResourceVO、HostVO、VmInstanceVO 或 AuditsVO 5.1.0
eventTypes (可选) List body(包含在updateResNotifySubscription结构中) 需要订阅的事件类型列表，可选 CREATE、UPDATE、DELETE 5.1.0
state (可选) String body(包含在updateResNotifySubscription结构中) 订阅状态，可设置为 Enabled 或 Disabled
  • Enabled
  • Disabled
 5.1.0
webhookUrl (可选) String body(包含在updateResNotifySubscription结构中) 接收资源变更通知的 webhook URL 5.1.0
secret (可选) String body(包含在updateResNotifySubscription结构中) 用于生成 X-ZStack-Signature 签名的密钥 5.1.0
customHeaders (可选) String body(包含在updateResNotifySubscription结构中) 投递 webhook 时附加的自定义 HTTP 请求头，JSON 字符串格式 5.1.0
systemTags (可选) List body 系统标签 5.1.0
userTags (可选) List body 用户标签 5.1.0

API返回

返回示例
{
  "inventory": {}
}
名字 类型 描述 起始版本
success boolean 更新资源变更通知订阅是否成功 5.1.0
inventory ResNotifySubscriptionInventory 详情参考inventory 5.1.0
error ErrorCode 错误码，若不为null，则表示操作失败, 操作成功时该字段为null。 详情参考error 5.1.0
#inventory
名字 类型 描述 起始版本
uuid String 资源变更通知订阅的UUID，唯一标识该订阅 5.1.0
name String 资源变更通知订阅名称 5.1.0
description String 资源变更通知订阅的详细描述 5.1.0
resourceTypes String 订阅匹配的资源类型列表，以逗号分隔 5.1.0
eventTypes String 订阅匹配的事件类型列表，以逗号分隔 5.1.0
createDate Timestamp 创建时间 5.1.0
lastOpDate Timestamp 最后一次修改时间 5.1.0
type ResNotifyType 详情参考type 5.1.0
state ResNotifySubscriptionState 详情参考state 5.1.0
webhookRef ResNotifyWebhookRefInventory 详情参考webhookRef 5.1.0
#type
名字 类型 描述 起始版本
WEBHOOK ResNotifyType 通过 HTTP webhook 投递资源变更通知 5.1.0
WEBSOCKET ResNotifyType 通过 WebSocket 投递资源变更通知，当前预留 5.1.0
#state
名字 类型 描述 起始版本
Enabled ResNotifySubscriptionState 订阅已启用，会向匹配的通知端点投递事件 5.1.0
Disabled ResNotifySubscriptionState 订阅已禁用，不会投递匹配事件 5.1.0
#webhookRef
名字 类型 描述 起始版本
uuid String webhook 引用的UUID，与资源变更通知订阅UUID一致 5.1.0
webhookUrl String 接收资源变更通知的 webhook URL 5.1.0
secret String 用于生成 X-ZStack-Signature 签名的密钥 5.1.0
customHeaders String 投递 webhook 时附加的自定义 HTTP 请求头，JSON 字符串格式 5.1.0
#error
名字 类型 描述 起始版本
code String 错误码号，错误的全局唯一标识，例如SYS.1000, HOST.1001 0.6
description String 错误的概要描述 0.6
details String 错误的详细信息 0.6
elaboration String 保留字段，默认为null 0.6
opaque LinkedHashMap 保留字段，默认为null 0.6
cause ErrorCode 根错误，引发当前错误的源错误，若无原错误，该字段为null 0.6

SDK示例

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()
上一篇查询SNS主题订阅(QuerySNSTopicSubscriber)下一篇容量管理相关接口
开发手册 | ZStack ZSphere · ZVF | ZStack 资源中心