api版本选择建议-九游平台

api风格说明

当前ecs服务对外开放两类风格的api：

1. ecs服务自定义规范的api（以下简称ecs api）
2. 顺从openstack社区标准原生规范的api

两种风格不同，功能相近。openstack风格api主要用于满足您在开源生态工具方面的对接需求，在某些功能上ecs api在openstack社区的api基础上，做了功能增强。为了更好的使用openstack风格api，建议您提前了解openstack相关概念与知识。

版本号介绍

弹性云服务器所提供的接口分为ecs接口与openstack原生接口。推荐您使用ecs接口。

openstack api可以使用v2和v2.1两个版本号，v2.1版本支持v2版本所有功能，且v2.1版本支持微版本。如果使用openstack api推荐用户使用v2.1接口。

若使用v2版本的openstack api接口，只需要把对应的api接口uri中的v2.1版本号改为v2版本号即可。

微版本号介绍

微版本说明：标识api中小的改动。当接口uri使用v2.1版本的时候，用户可以指定微版本号使用相应api的新功能。使用，可以查询当前支持的主版本和支持的最大与最小的微版本。

微版本的使用说明：用户想要使用微版本特性，需要在请求openstack接口时，在请求头中加入微版本头：x-openstack-nova-api-version或者openstack-api-version，例如使用微版本2.26需要在https的请求头中加入：

x-openstack-nova-api-version: 2.26或openstack-api-version: compute 2.26

当用户使用v2.1接口不传入微版本头时，默认使用的微版本openstack-api-version: compute 2.1(x-openstack-nova-api-version: 2.1)。

微版本请求样例

假设使用弹性云服务器详情信息列表api接口查询"os-ext-srv-attr:hostname"字段。

• 使用v2接口，不加微版本号
  • get: https://{endpoint}/v2/74610f3a5ad941998e91f076297ecf27/servers/detail

    其中{endpoint}为iam的终端节点，请参考获取。

  • headers:

    content-type	application/json
    x-auth-token	${token}

  • 响应消息体：

    {
      "servers": [
        {
          "tenant_id": "74610f3a5ad941998e91f076297ecf27",
          "addresses": {
            "05d4fb93-84e5-4964-853b-32992ffef627": [
              {
                "os-ext-ips-mac:mac_addr": "fa:16:3e:20:17:95",
                "os-ext-ips:type": "fixed",
                "addr": "192.168.0.228",
                "version": 4
              },
              {
                "os-ext-ips-mac:mac_addr": "fa:16:3e:20:17:95",
                "os-ext-ips:type": "floating",
                "addr": "192.168.51.61",
                "version": 4
              }
            ]
          },
          "metadata": {},
          "os-ext-sts:task_state": null,
          "os-dcf:diskconfig": "manual",
          "os-ext-az:availability_zone":"az1-dc1",
          "links": [
            {
              "rel": "self",
              "href": "https://none/v2.1/74610f3a5ad941998e91f076297ecf27/servers/89c312bb-285a-4026-a237-d441908c2f9e"
            },
            {
              "rel": "bookmark",
              "href": "https://none/74610f3a5ad941998e91f076297ecf27/servers/89c312bb-285a-4026-a237-d441908c2f9e"
            }
          ],
          "os-ext-sts:power_state": 1,
          "id": "89c312bb-285a-4026-a237-d441908c2f9e",
          "os-extended-volumes:volumes_attached": [
            {
              "id": "c70c4b8e-33bd-4d1f-ab16-14a5a38cdeaf"
            }
          ],
          "os-ext-srv-attr:host": "pod05.test.01",
          "image": {
            "links": [
              {
                "rel": "bookmark",
                "href": "https://none/74610f3a5ad941998e91f076297ecf27/images/1189efbf-d48b-46ad-a823-94b942e2a000"
              }
            ],
            "id": "1189efbf-d48b-46ad-a823-94b942e2a000"
          },
          "os-srv-usg:terminated_at": null,
          "accessipv4": "",
          "accessipv6": "",
          "created": "2018-05-11t03:21:56z",
          "hostid": "fc7a8ff86bac050f0d9454b1b078dcc97060e819acbf06f04c3e338f",
          "os-ext-srv-attr:hypervisor_hostname": "nova012@7",
          "key_name": "id_rsa",
          "flavor": {
            "links": [
              {
                "rel": "bookmark",
                "href": "https://none/74610f3a5ad941998e91f076297ecf27/flavors/s3.small.1"
              }
            ],
            "id": "s3.small.1"
          },
          "security_groups": [
            {
              "name": "default"
            }
          ],
          "config_drive": "",
          "os-ext-sts:vm_state": "active",
          "os-ext-srv-attr:instance_name": "instance-0016c624",
          "user_id": "f79791beca3c48159ac2553fff22e166",
          "name": "zt-test",
          "progress": 0,
          "os-srv-usg:launched_at": "2018-05-11t03:22:16.701600",
          "updated": "2018-05-11t03:22:51z",
          "status": "active"
        }
      ]
    }

  • 结论：响应消息体中没有"os-ext-srv-attr:hostname"字段。

• 使用v2.1接口，加微版本号
  • get: https://{endpoint}/v2.1/74610f3a5ad941998e91f076297ecf27/servers/detail

    其中{endpoint}为iam的终端节点，请参考获取。

  • headers:

    content-type	application/json
    x-auth-token	${token}
    x-openstack-nova-api-version	2.26

  • 响应消息体：

    {
      "servers": [
        {
          "tenant_id": "74610f3a5ad941998e91f076297ecf27",
          "addresses": {
            "05d4fb93-84e5-4964-853b-32992ffef627": [
              {
                "os-ext-ips-mac:mac_addr": "fa:16:3e:20:17:95",
                "os-ext-ips:type": "fixed",
                "addr": "192.168.0.228",
                "version": 4
              },
              {
                "os-ext-ips-mac:mac_addr": "fa:16:3e:20:17:95",
                "os-ext-ips:type": "floating",
                "addr": "192.168.51.61",
                "version": 4
              }
            ]
          },
          "metadata": {},
          "os-ext-sts:task_state": null,
          "description": "zt-test",
          "os-ext-srv-attr:hostname": "zt-test",
          "os-dcf:diskconfig": "manual",
          "os-ext-az:availability_zone":"az-test-01",
          "links": [
            {
              "rel": "self",
              "href": "https://none/v2.1/74610f3a5ad941998e91f076297ecf27/servers/89c312bb-285a-4026-a237-d441908c2f9e"
            },
            {
              "rel": "bookmark",
              "href": "https://none/74610f3a5ad941998e91f076297ecf27/servers/89c312bb-285a-4026-a237-d441908c2f9e"
            }
          ],
          "os-ext-sts:power_state": 1,
          "id": "89c312bb-285a-4026-a237-d441908c2f9e",
          "os-extended-volumes:volumes_attached": [
            {
              "delete_on_termination": true,
              "id": "c70c4b8e-33bd-4d1f-ab16-14a5a38cdeaf"
            }
          ],
          "locked": false,
          "os-ext-srv-attr:kernel_id": "",
          "os-ext-srv-attr:host":"pod05.test.01" ,
          "os-ext-srv-attr:ramdisk_id": "",
          "image": {
            "links": [
              {
                "rel": "bookmark",
                "href": "https://none/74610f3a5ad941998e91f076297ecf27/images/1189efbf-d48b-46ad-a823-94b942e2a000"
              }
            ],
            "id": "1189efbf-d48b-46ad-a823-94b942e2a000"
          },
          "accessipv4": "",
          "os-srv-usg:terminated_at": null,
          "accessipv6": "",
          "os-ext-srv-attr:launch_index": 0,
          "created": "2018-05-11t03:21:56z",
          "os-ext-srv-attr:user_data": null,
          "hostid": "fc7a8ff86bac050f0d9454b1b078dcc97060e819acbf06f04c3e338f",
          "os-ext-srv-attr:reservation_id": "r-pbqmaxer",
          "os-ext-srv-attr:root_device_name": "/dev/vda",
          "host_status": "up",
          "os-ext-srv-attr:hypervisor_hostname": "nova012@7",
          "tags": [],
          "key_name": "id_rsa",
          "flavor": {
            "links": [
              {
                "rel": "bookmark",
                "href": "https://none/74610f3a5ad941998e91f076297ecf27/flavors/s3.small.1"
              }
            ],
            "id": "s3.small.1"
          },
          "security_groups": [
            {
              "name": "default"
            }
          ],
          "config_drive": "",
          "os-ext-sts:vm_state": "active",
          "os-ext-srv-attr:instance_name": "instance-0016c624",
          "user_id": "f79791beca3c48159ac2553fff22e166",
          "name": "zt-test",
          "progress": 0,
          "os-srv-usg:launched_at": "2018-05-11t03:22:16.701600",
          "updated": "2018-05-11t03:22:51z",
          "status": "active"
        }
      ]
    }

  • 结论：响应消息体中有"os-ext-srv-attr:hostname"字段。

微版本响应样例

如果“version”和“min_version”这两个值为空字符串，说明此endpoint不支持微版本。其中：

• version： 最大微版本号。
• min_version：最小微版本号。

客户端应该指定最大和最小微版本范围内的微版本号去访问endpoint。客户端通过以下http header指定微版本号：

x-openstack-nova-api-version: 2.4

从微版本2.27开始，也可以用以下header指定微版本：

openstack-api-version: compute 2.27

如下响应样例中支持的最大微版本为“2.14”，最小微版本为“2.1”：

{
  "versions": [
      {
          "id": "v2.0",
          "links": [
              {
                  "href": "http://openstack.example.com/v2/",
                  "rel": "self"
              }
          ],
          "status": "supported",
          "version": "",
          "min_version": "",
          "updated": "2011-01-21t11:33:21z"
      },
      {
          "id": "v2.1",
          "links": [
              {
                  "href": "http://openstack.example.com/v2.1/",
                  "rel": "self"
              }
          ],
          "status": "current",
          "version": "2.14",
          "min_version": "2.1",
          "updated": "2013-07-23t11:33:21z"
      }
  ]
}