用户标签（User Tags）

1. 用户可以在所拥有的资源上创建用户标签，这对于管理相似资源的聚集特别有用。
   例如，用户可以为作为网页服务器的云主机设置一个标签web：

   1. CreateUserTag resourceType=VmInstanceVO \
      resourceUuid=613af3fe005914c1643a15c36fd578c6 tag=web

      CreateUserTag resourceType=VmInstanceVO \
      resourceUuid=5eb55c39db015c1782c7d814900a9609 tag=web

      CreateUserTag resourceType=VmInstanceVO \
      resourceUuid=0cd1ef8c9b9e0ba82e0cc9cc17226a26 tag=web

   2. 之后，可以通过Query API with tags <query with tags>来获取这些云主机：

      QueryVmInstance __userTag__=web

   用户也可以在创建云主机的时候设置多个标签，标签之间用","分隔，这样可以实现多个usertags

   1. CreateVmInstance instanceOfferingUuid=1cf417bfd0e94175aea92131f1000011  \
      imageUuid=ee14c7c8cc46309d821c51bbae3adb70 l3NetworkUuids=ac5c7e736f1b499bbd0c12763b30051d  \
      name=tesd2 userTags=capability::liveSnapshot,os::centos::7.4

   2. 用户可以标识：容量40G，OS Centos7.4，密码是123456，用于Apache 场景。这些跟 :: 没有特别的关系

      CreateVmInstance instanceOfferingUuid=1cf417bfd0e94175aea92131f1000011  \
      imageUuid=ee14c7c8cc46309d821c51bbae3adb70 l3NetworkUuids=ac5c7e736f1b499bbd0c12763b30051d name=tesd2   \
      userTags=capability:40G,OS:CentOS7.4,password:123456,usage:Apache

2. 用户也可以通过用户标签和系统标签（system tags）合作来改变业务逻辑。

   例如，用户想在所有作为网页服务器的云主机上，在一个特定的通过SSD提高IO性能的主存储上，创建他们的根云盘。

   要达到这一目的，用户可以这样做：

   1. 在主存储上创建一个用户标签forWebTierVM：

      CreateUserTag tag=forWebTierVM resourceType=PrimaryStorageVO \
      resourceUuid=6572ce44c3f6422d8063b0fb262cbc62

   2. 然后，在计算规格上创建一个系统标签：

      CreateSystemTag tag=primaryStorage::allocator::userTag::forWebTierVM \
      resourceType=InstanceOfferingVO resourceUuid=8f69ef6c2c444cdf8c019fa0969d56a5

   3. 这样，当用户通过计算规格（UUID：8f69ef6c2c444cdf8c019fa0969d56a5）创建云主机时，ZStack Cloud会保证云主机的根云盘都会被创建在拥有用户标签forWebTierVM的主存储（UUID：6572ce44c3f6422d8063b0fb262cbc62）上。

系统标签（System Tags）

系统标签相比用户标签有更广泛的用途。就像上节中的例子一样，用户可以灵活使用它们来指挥ZStack Cloud执行特殊的业务逻辑。

1. 内部系统标签

   扩展ZStack Cloud功能的插件，可以通过使用系统标签来引入额外的资源属性，或记录和资源紧密相关的元数据。

   例如，用户想在KVM云主机上实施在线迁移或者在线快照。

   ZStack Cloud需要知道KVM云主机的libvirt版本和QEMU版本，这些信息都是元数据，ZStack Cloud将它们作为云主机的系统标签存储起来。

   1. 管理员可以通过以下命令查看一个KVM云主机的系统标签：

      QuerySystemTag fields=tag resourceUuid=d07066c4de02404a948772e131139eb4

   2. d07066c4de02404a948772e131139eb4是该KVM云主机的UUID，查询结果为：

      {
        "inventories": [
            {
                "tag": "capability:liveSnapshot"
            },
            {
                "tag": "qemu-img::version::2.0.0"
            },
            {
                "tag": "os::version::14.04"
            },
            {
                "tag": "libvirt::version::1.2.2"
            },
            {
                "tag": "os::release::trusty"
            },
            {
                "tag": "os::distribution::Ubuntu"
            }
        ],
        "success": true
      }

   这类系统标签，被称为内部系统标签。内部系统标签只能被ZStack Cloud的服务或插件创建，并且不能被DeleteTag API删除。

2. 非内部系统标签

   为了增加新的功能，插件通常需要为一个资源添加新的属性。虽然插件不能通过改变一个资源的数据库模式来增加一个新的列，但它可以为一个资源创建作为系统标签的新属性。

   例如，当创建一个云主机时，用户可以为云主机某L3网络上的网卡绑定一个可以通过网络访问的主机名：

   1. CreateVmInstance name=testTag systemTags=hostname::web-server-1 \
      l3NetworkUuids=6572ce44c3f6422d8063b0fb262cbc62 \
      instanceOfferingUuid=04b5419ca3134885be90a48e372d3895 \
      imageUuid=f1205825ec405cd3f2d259730d47d1d8

   2. 这个主机名被实现为一个系统标签；
   3. 如果查看VM inventory in chapter ‘Virtual Machine’, 那里没有叫做hostname的属性；
   4. 然而，可以在云主机的系统标签中发现它：

      QuerySystemTag fields=tag uuid resourceUuid=76e119bf9e16461aaf3d1b47c645c7b7

      {
        "inventories": [
            {
                "tag": "hostname::web-server-1",
                "uuid": "596070a6276746edbf0f54ef721f654e"
            }
        ],
        "success": true
      }

   这类系统标签就是非内部的，用户可以通过DeleteTag API删除它。

   例如，用户想把一个之前的云主机的主机名更改为web-server-nginx，可以这样做：

   1. DeleteTag uuid=596070a6276746edbf0f54ef721f654e

   2. CreateSystemTag resourceType=VmInstanceVO tag=hostname::web-server-nginx \
      resourceUuid=76e119bf9e16461aaf3d1b47c645c7b7

   3. 停止和启动云主机之后，云主机中的系统会接受到web-server-nginx作为新的主机名。

命名约定（Name Convention）

资源类型（Resource Type）

创建一个标签时, 用户必须指定标签所关联的资源类型。

在每个资源的对应Tags章节中, 我们有解释需用什么资源类型来创建对应的标签。

系统标签清单(SystemTag inventory)

资源标签清单(Tag inventory)

{
  "inventories": [
    {
      "uuid": "f7ac675964d0386b89d8df713f68aee0",
      "name": "SSD",
      "value": "SSD",
      "description": "SSD volume",
      "color": "#FFFFFF",
      "type": "simple",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}

用户标签清单(UserTag inventory)

{
  "inventories": [
    {
      "uuid": "ae4f2dd05a513e1e8d350d448c2071a9",
      "resourceType": "DiskOfferingVO",
      "tag": "for-large-DB",
      "type": "User",
      "createDate": "Nov 14, 2017 10:20:57 PM",
      "lastOpDate": "Nov 14, 2017 10:20:57 PM"
    }
  ]
}

参数（Parameters）

原生域查询（Primitive Fields of Query）

请参见系统标签清单(SystemTag inventory)。

参数（Parameters）

参数（Parameters）

原生域查询（Primitive Fields of Query）

请参见用户标签清单(UserTag inventory)。

参数（Parameters）

参数（Parameters）

原生域查询（Primitive Fields of Query）

请参见资源标签清单(Tag inventory)。

嵌套和扩展域查询（Nested And Expanded Fields of Query）

参数（Parameters）

参数（Parameters）

参数（Parameters）