DocsKnowledge BaseAPI Explorer
Documentation›Explore more›ZStack ZSphere›API ReferenceZVF

Custom Attribute

CreateResourceAttributeKey

API Request

URLs
POST zstack/v1/resource-attributes
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "name": "Operations personnel"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, the systemTags and userTags fields can be omitted. They are listed to show that these two fields can be included in the body.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"name":"Operations personnel"}}' \
http://localhost:8080/zstack/v1/resource-attributes
Parameter List
Name Type Location Description Allowed Values Starting Version
name String body (contained in the params structure) Custom attribute key name 4.10.16
description (optional) String body (contained in the params structure) Detailed description of the resource 4.10.16
resourceTypes (optional) List body (contained in the params structure) List of resource types supported by this attribute. Defaults to all supported types 4.10.16
constraints (optional) List body (contained in the params structure) Attribute constraint list 4.10.16
resourceUuid (optional) String body (contained in the params structure) Resource UUID 4.10.16
tagUuids (optional) List body (contained in the params structure) Tag UUID list 4.10.16
systemTags (optional) List body System tags 4.10.16
userTags (optional) List body User tags 4.10.16

API Response

Response example
{
  "inventory": {
    "uuid": "ff03a2b491023030bf58b1b35ea9cd00",
    "name": "OperationsPersonnel",
    "description": "Kinny",
    "resourceTypes": [
      "VmInstanceVO"
    ],
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM",
    "constraints": [
      {
        "id": 1,
        "keyUuid": "ff03a2b491023030bf58b1b35ea9cd00",
        "type": "option",
        "parameter": "Kinny",
        "createDate": "Nov 14, 2017 2:20:57 PM",
        "lastOpDate": "Nov 14, 2017 2:20:57 PM"
      }
    ]
  }
}
Name Type Description Starting Version
success boolean Whether the creation succeeded 4.10.16
inventory ResourceAttributeKeyInventory For details, see inventory 4.10.16
error ErrorCode Error code. If not null, the operation failed. This field is null when the operation succeeds. For details, see error 0.6
#inventory
Name Type Description Starting Version
uuid String Custom attribute key UUID 4.10.16
name String Custom attribute key name 4.10.16
description String Detailed description of the resource 4.10.16
createDate Timestamp Creation time 4.10.16
lastOpDate Timestamp Last modification time 4.10.16
#error
Name Type Description Starting Version
ode String The error code number, a globally unique identifier for the error, e.g., SYS.1000, HOST.1001 0.6
description String A brief description of the error 0.6
details String The detailed error information 0.6
elaboration String Reserved field. Defaults to null 0.6
opaque LinkedHashMap Reserved field. Defaults to null 0.6
cause ErrorCode The root error, the cause of the current error. This field is null if there is no root error 0.6

SDK Examples

Java SDK
CreateResourceAttributeKeyAction action = new CreateResourceAttributeKeyAction();
action.name = "Operations personnel";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateResourceAttributeKeyAction.Result res = action.call();
Python SDK
action = CreateResourceAttributeKeyAction()
action.name = "Operations personnel"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

DeleteResourceAttributeKey

API Request

URLs
DELETE zstack/v1/resource-attributes/{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/resource-attributes/ff03a2b491023030bf58b1b35ea9cd00?deleteMode=Permissive
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Custom attribute key UUID 4.10.16
deleteMode (optional) String query Deletion mode (Permissive or Enforcing, defaults to Permissive) 4.10.16
systemTags (optional) List query System tags 4.10.16
userTags (optional) List query User tags 4.10.16

API Response

On success, this API returns an empty JSON structure {}. On error, 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
DeleteResourceAttributeKeyAction action = new DeleteResourceAttributeKeyAction();
action.uuid = "ff03a2b491023030bf58b1b35ea9cd00";
action.deleteMode = "Permissive";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteResourceAttributeKeyAction.Result res = action.call();
Python SDK
action = DeleteResourceAttributeKeyAction()
action.uuid = "ff03a2b491023030bf58b1b35ea9cd00"
action.deleteMode = "Permissive"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

UpdateResourceAttributeKey

API Request

URLs
PUT zstack/v1/resource-attributes/{uuid}/actions
Headers
Authorization: OAuth the-session-uuid
Body
{
  "updateResourceAttributeKey": {
    "description": "test"
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, the systemTags and userTags fields can be omitted. They are listed to show that these two fields can be included in the body.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X PUT -d '{"updateResourceAttributeKey":{"description":"test"}}' \
http://localhost:8080/zstack/v1/resource-attributes/ff03a2b491023030bf58b1b35ea9cd00/actions
Parameter List
Name Type Location Description Allowed Values Starting Version
uuid String url Custom attribute key UUID 4.10.16
name (optional) String body (contained in the updateResourceAttributeKey structure) Key name 4.10.16
description (optional) String body (contained in the updateResourceAttributeKey structure) Detailed description of the resource 4.10.16
resourceTypes (optional) List body (contained in the updateResourceAttributeKey structure) List of resource types supported by this attribute 4.10.16
createConstraints (optional) List body (contained in the updateResourceAttributeKey structure) Newly created constraints 4.10.16
updateConstraints (optional) List body (contained in the updateResourceAttributeKey structure) Updated constraints 4.10.16
deleteConstraintIds (optional) List body (contained in the updateResourceAttributeKey structure) List of constraint IDs to delete 4.10.16
systemTags (optional) List body System tags 4.10.16
userTags (optional) List body User tags 4.10.16

API Response

Response example
{
  "inventory": {
    "uuid": "ff03a2b491023030bf58b1b35ea9cd00",
    "name": "OperationsPersonnel",
    "description": "Kinny",
    "resourceTypes": [
      "VmInstanceVO"
    ],
    "createDate": "Nov 14, 2017 2:20:57 PM",
    "lastOpDate": "Nov 14, 2017 2:20:57 PM",
    "constraints": [
      {
        "id": 1,
        "keyUuid": "ff03a2b491023030bf58b1b35ea9cd00",
        "type": "option",
        "parameter": "Kinny",
        "createDate": "Nov 14, 2017 2:20:57 PM",
        "lastOpDate": "Nov 14, 2017 2:20:57 PM"
      }
    ]
  }
}
Name Type Description Starting Version
success boolean Whether the update succeeded 4.10.16
inventory ResourceAttributeKeyInventory For details, see inventory 4.10.16
error ErrorCode For details, see error 4.10.16
#inventory
Name Type Description Starting Version
uuid String Custom attribute key UUID 4.10.16
name String Custom attribute key name 4.10.16
description String Detailed description of the resource 4.10.16
createDate Timestamp Creation time 4.10.16
lastOpDate Timestamp Last modification time 4.10.16
#error
Name Type Description Starting Version
ode String The error code number, a globally unique identifier for the error, e.g., SYS.1000, HOST.1001 0.6
description String A brief description of the error 0.6
details String The detailed error information 0.6
elaboration String Reserved field. Defaults to null 0.6
opaque LinkedHashMap Reserved field. Defaults to null 0.6
cause ErrorCode The root error, the cause of the current error. This field is null if there is no root error 0.6

SDK Examples

Java SDK
UpdateResourceAttributeKeyAction action = new UpdateResourceAttributeKeyAction();
action.uuid = "ff03a2b491023030bf58b1b35ea9cd00";
action.description = "test";
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
UpdateResourceAttributeKeyAction.Result res = action.call();
Python SDK
action = UpdateResourceAttributeKeyAction()
action.uuid = "ff03a2b491023030bf58b1b35ea9cd00"
action.description = "test"
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

QueryResourceAttributeKey

API Request

URLs
GET zstack/v1/resource-attributes/keys
GET zstack/v1/resource-attributes/keys/{uuid}
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/resource-attributes/keys?q=name=OperationsPersonnel
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/resource-attributes/keys/dbd98db0aeb939c38a6574e64b822b7d

Queryable Fields

Run the CLI tool, enter QueryResourceAttributeKey and press the Tab key to view all queryable fields and cross-table queryable resource names.

API Response

Response example
{
  "inventories": [
    {
      "uuid": "ff03a2b491023030bf58b1b35ea9cd00",
      "name": "OperationsPersonnel",
      "description": "Kinny",
      "resourceTypes": [
        "VmInstanceVO"
      ],
      "createDate": "Nov 14, 2017 2:20:57 PM",
      "lastOpDate": "Nov 14, 2017 2:20:57 PM",
      "constraints": [
        {
          "id": 1,
          "keyUuid": "ff03a2b491023030bf58b1b35ea9cd00",
          "type": "option",
          "parameter": "Kinny",
          "createDate": "Nov 14, 2017 2:20:57 PM",
          "lastOpDate": "Nov 14, 2017 2:20:57 PM"
        }
      ]
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the query succeeded 4.10.16
inventories List For details, see inventories 4.10.16
error ErrorCode For details, see error 4.10.16
#inventories
Name Type Description Starting Version
uuid String Custom attribute key UUID 4.10.16
name String Custom attribute key name 4.10.16
description String Detailed description of the resource 4.10.16
createDate Timestamp Creation time 4.10.16
lastOpDate Timestamp Last modification time 4.10.16
#error
Name Type Description Starting Version
ode String The error code number, a globally unique identifier for the error, e.g., SYS.1000, HOST.1001 0.6
description String A brief description of the error 0.6
details String The detailed error information 0.6
elaboration String Reserved field. Defaults to null 0.6
opaque LinkedHashMap Reserved field. Defaults to null 0.6
cause ErrorCode The root error, the cause of the current error. This field is null if there is no root error 0.6

SDK Examples

Java SDK
QueryResourceAttributeKeyAction action = new QueryResourceAttributeKeyAction();
action.conditions = asList("name=OperationsPersonnel");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryResourceAttributeKeyAction.Result res = action.call();
Python SDK
action = QueryResourceAttributeKeyAction()
action.conditions = ["name=OperationsPersonnel"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

CreateResourceAttributeValue

API Request

URLs
POST zstack/v1/resource-attributes/{keyUuid}/resources
Headers
Authorization: OAuth the-session-uuid
Body
{
  "params": {
    "value": "Kinny",
    "resourceUuids": [
      "ff01ec80fd11327cba7519b66119d900"
    ]
  },
  "systemTags": [],
  "userTags": []
}
Note: In the above example, the systemTags and userTags fields can be omitted. They are listed to show that these two fields can be included in the body.
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X POST -d '{"params":{"value":"Kinny","resourceUuids":["ff01ec80fd11327cba7519b66119d900"]}}' \
http://localhost:8080/zstack/v1/resource-attributes/ff03a2b491023030bf58b1b35ea9cd00/resources
Parameter List
Name Type Location Description Allowed Values Starting Version
keyUuid String url Custom attribute key UUID 4.10.16
value String body (contained in the params structure) Value 4.10.16
resourceUuids List body (contained in the params structure) Resource UUID 4.10.16
systemTags (optional) List body System tags 4.10.16
userTags (optional) List body User tags 4.10.16

API Response

Response example
{
  "inventories": [
    {
      "inventory": {
        "keyUuid": "ff03a2b491023030bf58b1b35ea9cd00",
        "key": {
          "uuid": "ff03a2b491023030bf58b1b35ea9cd00",
          "name": "OperationsPersonnel",
          "description": "Kinny",
          "resourceTypes": [
            "VmInstanceVO"
          ],
          "createDate": "Nov 14, 2017 2:20:57 PM",
          "lastOpDate": "Nov 14, 2017 2:20:57 PM",
          "constraints": [
            {
              "id": 1,
              "keyUuid": "ff03a2b491023030bf58b1b35ea9cd00",
              "type": "option",
              "parameter": "Kinny",
              "createDate": "Nov 14, 2017 2:20:57 PM",
              "lastOpDate": "Nov 14, 2017 2:20:57 PM"
            }
          ]
        },
        "value": "Kinny",
        "resourceUuid": "ff01ec80fd11327cba7519b66119d900",
        "resourceType": "VmInstanceVO",
        "createDate": "Nov 14, 2017 2:20:57 PM"
      },
      "success": true
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the creation succeeded 4.10.16
inventories List For details, see inventories 4.10.16
error ErrorCode For details, see error 4.10.16
#inventories
Name Type Description Starting Version
success boolean Whether the creation succeeded 4.10.16
error ErrorCode For details, see error 4.10.16
inventory ResourceAttributeValueInventory For details, see inventory 4.10.16
#error
Name Type Description Starting Version
ode String The error code number, a globally unique identifier for the error, e.g., SYS.1000, HOST.1001 0.6
description String A brief description of the error 0.6
details String The detailed error information 0.6
elaboration String Reserved field. Defaults to null 0.6
opaque LinkedHashMap Reserved field. Defaults to null 0.6
cause ErrorCode The root error, the cause of the current error. This field is null if there is no root error 0.6
#inventory
Name Type Description Starting Version
keyUuid String Custom attribute key UUID 4.10.16
value String Value 4.10.16
resourceUuid String Resource UUID 4.10.16
resourceType String Resource type 4.10.16
createDate Timestamp Creation time 4.10.16
key ResourceAttributeKeyInventory For details, see key 4.10.16
#key
Name Type Description Starting Version
uuid String Custom attribute key UUID 4.10.16
name String Custom attribute key name 4.10.16
description String Detailed description of the resource 4.10.16
createDate Timestamp Creation time 4.10.16
lastOpDate Timestamp Last modification time 4.10.16
#error
Name Type Description Starting Version
ode String The error code number, a globally unique identifier for the error, e.g., SYS.1000, HOST.1001 0.6
description String A brief description of the error 0.6
details String The detailed error information 0.6
elaboration String Reserved field. Defaults to null 0.6
opaque LinkedHashMap Reserved field. Defaults to null 0.6
cause ErrorCode The root error, the cause of the current error. This field is null if there is no root error 0.6

SDK Examples

Java SDK
CreateResourceAttributeValueAction action = new CreateResourceAttributeValueAction();
action.keyUuid = "ff03a2b491023030bf58b1b35ea9cd00";
action.value = "Kinny";
action.resourceUuids = asList("ff01ec80fd11327cba7519b66119d900");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
CreateResourceAttributeValueAction.Result res = action.call();
Python SDK
action = CreateResourceAttributeValueAction()
action.keyUuid = "ff03a2b491023030bf58b1b35ea9cd00"
action.value = "Kinny"
action.resourceUuids = [ff01ec80fd11327cba7519b66119d900]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

DeleteResourceAttributeValue

API Request

URLs
DELETE zstack/v1/resource-attributes/{keyUuid}/resources
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/resource-attributes/ff03a2b491023030bf58b1b35ea9cd00/resources?resourceUuids=ff01ec80fd11327cba7519b66119d900
Parameter List
Name Type Location Description Allowed Values Starting Version
keyUuid String url Custom attribute key UUID 4.10.16
resourceUuids List query Resource UUID 4.10.16
systemTags (optional) List query System tags 4.10.16
userTags (optional) List query User tags 4.10.16

API Response

On success, this API returns an empty JSON structure {}. On error, 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
DeleteResourceAttributeValueAction action = new DeleteResourceAttributeValueAction();
action.keyUuid = "ff03a2b491023030bf58b1b35ea9cd00";
action.resourceUuids = asList("ff01ec80fd11327cba7519b66119d900");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
DeleteResourceAttributeValueAction.Result res = action.call();
Python SDK
action = DeleteResourceAttributeValueAction()
action.keyUuid = "ff03a2b491023030bf58b1b35ea9cd00"
action.resourceUuids = [ff01ec80fd11327cba7519b66119d900]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()

QueryResourceAttributeValue

API Request

URLs
GET zstack/v1/resource-attributes
Headers
Authorization: OAuth the-session-uuid
Curl Example
curl -H "Content-Type: application/json;charset=UTF-8" \
-H "Authorization: OAuth b86c9016b4f24953a9edefb53ca0678c" \
-X GET http://localhost:8080/zstack/v1/resource-attributes?q=keyUuid=ff03a2b491023030bf58b1b35ea9cd00

Queryable Fields

Run the CLI tool, enter QueryResourceAttributeValue and press the Tab key to view all queryable fields and cross-table queryable resource names.

API Response

Response example
{
  "inventories": [
    {
      "keyUuid": "ff03a2b491023030bf58b1b35ea9cd00",
      "key": {
        "uuid": "ff03a2b491023030bf58b1b35ea9cd00",
        "name": "OperationsPersonnel",
        "description": "Kinny",
        "resourceTypes": [
          "VmInstanceVO"
        ],
        "createDate": "Nov 14, 2017 2:20:57 PM",
        "lastOpDate": "Nov 14, 2017 2:20:57 PM",
        "constraints": [
          {
            "id": 1,
            "keyUuid": "ff03a2b491023030bf58b1b35ea9cd00",
            "type": "option",
            "parameter": "Kinny",
            "createDate": "Nov 14, 2017 2:20:57 PM",
            "lastOpDate": "Nov 14, 2017 2:20:57 PM"
          }
        ]
      },
      "value": "Kinny",
      "resourceUuid": "ff01ec80fd11327cba7519b66119d900",
      "resourceType": "VmInstanceVO",
      "createDate": "Nov 14, 2017 2:20:57 PM"
    }
  ]
}
Name Type Description Starting Version
success boolean Whether the query succeeded 4.10.16
inventories List For details, see inventories 4.10.16
error ErrorCode For details, see error 4.10.16
#inventories
Name Type Description Starting Version
keyUuid String Custom attribute key UUID 4.10.16
value String Value 4.10.16
resourceUuid String Resource UUID 4.10.16
resourceType String Resource type 4.10.16
createDate Timestamp Creation time 4.10.16
key ResourceAttributeKeyInventory For details, see key 4.10.16
#key
Name Type Description Starting Version
uuid String Custom attribute key UUID 4.10.16
name String Custom attribute key name 4.10.16
description String Detailed description of the resource 4.10.16
createDate Timestamp Creation time 4.10.16
lastOpDate Timestamp Last modification time 4.10.16
#error
Name Type Description Starting Version
ode String The error code number, a globally unique identifier for the error, e.g., SYS.1000, HOST.1001 0.6
description String A brief description of the error 0.6
details String The detailed error information 0.6
elaboration String Reserved field. Defaults to null 0.6
opaque LinkedHashMap Reserved field. Defaults to null 0.6
cause ErrorCode The root error, the cause of the current error. This field is null if there is no root error 0.6

SDK Examples

Java SDK
QueryResourceAttributeValueAction action = new QueryResourceAttributeValueAction();
action.conditions = asList("keyUuid=ff03a2b491023030bf58b1b35ea9cd00");
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c";
QueryResourceAttributeValueAction.Result res = action.call();
Python SDK
action = QueryResourceAttributeValueAction()
action.conditions = ["keyUuid=ff03a2b491023030bf58b1b35ea9cd00"]
action.sessionId = "b86c9016b4f24953a9edefb53ca0678c"
res = action.call()
PreviousTag Management APIsNextMigration Service APIs
API Reference | ZStack ZSphere · ZVF | ZStack Resource Center