Neutron/APIv2-specification
Neutron v2 API
此页面是一个草案规范，可能不反映实际实现。
请参考 https://developer.openstack.org/api-ref-networking-v2.html 获取最新信息。
概述
Neutron 是一个项目，旨在为 OpenStack 计算服务管理的设备提供虚拟网络服务。本文档介绍了 Neutron API 的 2.0 版本。有关 Neutron 项目的更多信息和附加文档，请访问 https://wiki.openstack.org/Neutron 和 docs.openstack.org。我们欢迎反馈、评论和错误报告，请发送至 https://bugs.launchpad.net/neutron。
v2.0 API 代表了 Quantum v1.1 API 与来自 Melange API 的一些最重要的 IPAM 功能的组合。这些 IPAM 功能侧重于能够将地址块和其他网络配置（例如默认网关、dns 服务器）与 Neutron 网络关联，然后能够从该块中分配 IP 地址并将其与通过 Neutron 端口连接到网络的设备关联。
v2.0 API 通过引入一个新的实体，称为子网来实现这一点。子网可以表示绑定到先前创建的 Quantum 网络的 IPv4 或 IPv6 地址块，并且每个 Neutron 网络通常有一个或多个子网。当在网络上创建端口时，默认情况下，将从每个 IP 版本的指定子网中分配一个可用的固定 IP 地址。当端口被销毁时，分配的地址返回到子网上的可用 IP 池。Neutron API 的用户可以选择从块中选择特定的 IP 地址，或者让 Neutron 选择第一个可用的 IP 地址。
请注意，Neutron API 的 1.x 版本已从源代码树中删除。为了使用 v1.x API，应安装 Neutron 的早期版本。
高级流程
- 租户创建一个网络（例如，“net1”）
- 租户创建一个子网（例如，“10.0.0.0/24”），这隐式地将地址空间与该网络关联。这种关联创建了地址空间到先前创建的网络之间的绑定。虽然通常说子网由 IPv4 或 IPv6 地址范围表示，但仅地址范围本身不是子网。相反，是将地址空间绑定到网络，从而创建了子网。
- 租户启动一个 VM，指定一个连接到“net1”的单个 NIC（例如：nova boot --image <image_name> --nic net-id=<id_of_net1> <server_name>）
- Nova 联系 Neutron 并创建 net1 上的 port1。
- Neutron 为 port1 分配 IP。 (IP 由 Neutron 选择)
- 租户销毁 VM。
- Nova 联系 Neutron 并销毁 port1。分配的 IP 返回到可用 IP 池。
插件
Neutron API 代表了虚拟网络服务与用户和其他服务的接口。这些网络服务由一个称为“插件”的组件实现。插件可以采用不同的技术和技术来为租户提供隔离的虚拟网络，以及提供其他服务，例如 IP 地址管理。用户不应关心所使用的特定插件，只要与本文档中讨论的 API 保持一致，因为每个插件都将实现 Neutron v2 API 中包含的所有操作。
但是，某些插件可能会通过 API 扩展公开其他功能，稍后在本文档中讨论。有关特定插件公开的扩展的更多信息，请参阅插件文档。
概念
Neutron v2 API 管理三种类型的实体
- 网络，代表隔离的虚拟 Layer-2 域；网络也可以被视为虚拟（或逻辑）交换机；
- 子网，代表 IPv4 或 IPv6 地址块，可用于为连接到给定网络的虚拟机分配 IP 地址。
- 端口，代表给定网络上的虚拟（或逻辑）交换机端口。
所有实体，在本章的其余部分中详细讨论，都支持使用 POST/GET/PUT/DELETE 动词的基本 CRUD 操作，并具有自动生成唯一的标识符。
网络
网络是一个虚拟隔离的 Layer-2 广播域，通常保留给创建它的租户，除非网络已明确配置为共享。租户可以创建多个网络，直到达到由基于租户的配额指定的阈值（有关更多详细信息，请参阅下一章）。网络是 Neutron API 的主要实体。端口和子网必须始终与网络关联。下表描述了网络对象的属性。对于每个属性，CRUD 列应按如下方式读取
- C - 该属性可用于创建操作；
- R - 该属性在显示或列出操作的响应中返回；
- U - 可以更新属性的值；
- D - 可以删除属性的值；
| 属性 | 类型 | 必需 | CRUD | 默认值 | 验证约束 |
| id | uuid-str | 不适用 | CR | 生成 | UUID_PATTERN |
| name | 字符串 | 否 | CRU | 无 | 不适用 |
| admin_state_up | 布尔值 | 否 | CRU | 真 | { 真 | 假 } |
| status | 字符串 | 不适用 | R | 不适用 | 不适用 |
| 子网 | list(uuid-str) | 否 | R | 空列表 | 不适用 |
| shared | 布尔值 | 否 | CRU | 假 | { 真 | 假 } |
| tenant_id | uuid-str | 否* | CR | 不适用 | 不适用 |
子网
子网代表一个 IP 地址块，可用于为虚拟机分配 IP 地址。每个子网必须具有 CIDR 并且必须与网络关联。IP 可以从整个子网 CIDR 中选择，也可以从用户可以指定的“分配池”中选择。
子网还可以选择性地具有网关、DNS 名称服务器列表和主机路由。所有这些信息都将推送到与子网关联的接口的实例。
| 属性 | 类型 | 必需 | CRUD | 默认 | 验证约束 |
| id | uuid-str | 不适用 | CR | 生成 | UUID_PATTERN |
| name | 字符串 | 否 | CRU | 无 | 不适用 |
| network_id | uuid-str | Yes | CR | 生成 | 现有的网络标识符。 |
| ip_version | 整数 | Yes | CR | 4 | { 4 | 6 } |
| cidr | 字符串 | Yes | CR | 不适用 | 形式为 <network_address>/<prefix> 的有效 CIDR |
| gateway_ip | 字符串或 null | 否 | CRUD | CIDR 中的第一个地址 | 有效的 IP 地址或 null |
| dns_nameservers | list(str) | 否 | CRU | 无 | 每个子网可配置的最大名称服务器数量。默认值为 5。 |
| allocation_pools | list(dict) | 否 | CR | CIDR 中所有地址，不包括配置的gateway IP（如果已配置） | 范围的开始/结束必须是有效的 IP |
| host_routes | list(dict) | 否 | CRU | 默认路由到 gateway_ip | {'destination': <CIDR>, "nexthop": <有效的 IP 地址>}. 每个子网可配置的最大路由数量。默认值为 20。 |
| enable_dhcp | 布尔值 | 否 | CRU | 真 | { 真 | 假 } |
| tenant_id | uuid-str | 否* | CR | 不适用 | 不适用 |
端口
端口代表给定逻辑网络交换机上的虚拟交换机端口。虚拟机将其接口连接到端口。逻辑端口还定义了连接到端口的接口的 MAC 地址和 IP 地址（地址）。当将 IP 地址与端口关联时，这也意味着该端口与子网关联，因为 IP 地址是从特定子网的分配池中获取的。
| 属性 | 类型 | 必需 | CRUD | 默认 | 验证约束 |
| id | uuid-str | 不适用 | CR | 生成 | UUID_PATTERN |
| name | 字符串 | 否 | CRU | 无 | 不适用 |
| network_id | uuid-str | Yes | CR | 不适用 | 现有的网络标识符。 |
| admin_state_up | 布尔值 | 否 | CRU | 真 | { 真 | 假 } |
| status | 字符串 | 不适用 | R | 不适用 | 不适用 |
| mac_address | 字符串 | 否 | CR | 生成 | 6 字节形式的有效 MAC 地址，用冒号分隔。 |
| fixed_ips | list(dict) | 否 | CRU | 自动从池中分配。 | 有效的 IP 地址和现有的子网标识符。 |
| device_id | str | 否 | CRUD | 无 | 无约束 |
| device_owner | str | 否 | CRUD | 无 | 无约束 |
| tenant_id | uuid-str | 否* | CR | 不适用 | 不适用 |
* 如果 Neutron 未与 Keystone Identity 服务一起运行，则 tenant_id 属性是必需的
通用 API 信息
身份验证和授权
Neutron 使用 Keystone 身份服务 (http://keystone.openstack.org) 作为默认身份验证服务。当启用 keystone 时，提交请求到 Neutron 服务的用户必须在 X-Auth-Token 请求标头中提供身份验证令牌。上述令牌应通过使用 Keystone 端点进行身份验证来获取。有关使用 Keystone 进行身份验证的更多信息，请参阅 Keystone 文档。当启用 keystone 时，在创建请求中指定 tenant_id 不是必需的，因为租户标识符将从身份验证令牌派生。请注意，默认授权设置仅允许管理用户代表其他租户创建资源。
Neutron 使用从 Keystone 接收到的信息来授权用户请求。Neutron 处理两种类型的授权策略
- 基于操作：指定特定操作的访问标准的策略，可以对特定属性进行细粒度控制
- 基于资源：是否根据为资源配置的权限授予对特定资源的访问权限（当前仅适用于网络资源）
Neutron 中实施的实际授权策略可能因部署而异。
请求和响应类型
OpenStack Neutron API 支持 JSON 数据格式。请求和响应的格式可以通过使用 Accept 标头或在请求 URI 中添加 .json 扩展名来指定。
示例：带有标头的请求/响应：JSON
请求
POST /v1.0/tenants/tenantX/networks HTTP/1.1
Host 127.0.0.1:9696
Content-Type application/json
Accept application/json
Content-Length 57
{
"network":
{
"name": "net-name",
"admin_state_up": true
}
}
响应
HTTP/1.1 200 Accepted
Content-Type application/json
Content-Length 204
{
"network":
{
"status": "ACTIVE",
"subnets": [],
"name": "net-name",
"admin_state_up": true,
"tenant_id": "388a70781bae4ca895f17b7f6293eb70",
"shared": false, "id": "2a4017ef-31ff-496a-9294-e96ecc3bc9c9"
}
}
注意：我们仍需最终确定有关 XML 支持的决定。 Quantum v2 API XML 蓝图
过滤和列选择
Neutron API 支持基于资源所有顶级属性进行过滤。过滤器适用于所有列出请求。例如
GET /v2.0/networks?name=foobar
将返回所有名称为 foobar 的网络。当指定多个过滤器时，Neutron API 将仅返回满足所有过滤器的对象，从而在过滤器之间应用 AND 条件。Neutron 不提供 OR 过滤器的机制。为此，用户可以为每个过滤器提交不同的请求，然后从接收到的响应中在客户端构建集合。
默认情况下，Neutron 在任何 Show 或 List 调用中返回所有属性。Neutron API 具有一种机制来限制返回的属性集（例如，仅返回“id”）。Neutron API 返回的属性可以使用 fields 查询参数控制。例如，以下请求
GET /v2.0/networks.json?fields=id&fields=name
将仅返回每个网络的id 和 name。
同步与异步插件行为
Neutron API 呈现虚拟网络连接性的逻辑模型，包括网络、端口和子网。由 Neutron 插件负责与底层基础设施通信，以确保数据包转发与逻辑模型一致。插件可以异步执行这些操作。这意味着当 API 客户端使用 HTTP POST、PUT 或 DELETE 修改逻辑模型时，API 调用可能在插件对底层虚拟和/或物理交换设备进行任何修改之前返回。API 客户端的唯一保证是，所有后续 API 调用都将正确反映更改后的逻辑模型。例如，考虑客户端使用 HTTP PUT 设置端口的附件的情况。一旦 HTTP 调用返回，发送到接口中命名的附件中的数据包不一定会立即转发。但是，保证后续 HTTP GET 以查看该端口上的附件将返回新的附件值。“status”属性，适用于网络和端口资源，可用于了解 Neutron 插件是否已成功完成感兴趣资源的配置。
批量创建操作
Neutron API 允许在同一个 API 请求中创建相同类型的多个对象。批量创建操作使用与单个创建操作完全相同的 API，唯一的区别在于请求主体中指定的是对象列表，而不是单个对象。
批量操作始终以原子方式执行，这意味着请求主体中的所有对象都将创建，或者不创建任何对象。如果特定的插件不支持原子操作，Neutron API 将模拟原子行为，从而确保用户可以期望相同的行为，而与后端运行的特定插件无关。
Neutron 可能被部署而不支持批量操作。在这种情况下，当客户端尝试批量创建操作时，将返回400 Bad Request错误。
有关如何将批量请求提交到 Neutron API 的更多详细信息，请参阅下一章中讨论的创建操作。
配额
[待定] Yong 将贡献
通知
[待定] Yong 将贡献
扩展
Neutron API 是可扩展的。扩展服务于多种目的
- 它们允许在不更改 API 版本的情况下引入新功能；
- 它们允许引入供应商特定的利基功能
- 它们充当未来 API 版本中可能包含的实验功能的试验场。
应用程序可以通过对 v2.0/extensions URI 执行 GET 来以编程方式确定可用的扩展。扩展也可以通过其唯一的别名通过执行 GET 到 /v2.0/extensions/alias_name 进行查询。这是检查扩展是否可用最简单的方法，因为不可用的扩展将发出 itemNotFound (404) 响应。现有的核心 API 资源可以通过新的操作或额外的属性进行扩展。此外，还可以将新资源作为扩展添加。扩展通常具有标签，以防止与其他定义具有相同名称的属性和/或资源的扩展发生冲突，以及与核心资源和属性发生冲突。由于扩展可能不受所有插件支持，因此扩展的可用性会因部署和使用的特定插件而异。
错误
如果处理请求时发生故障，Neutron API 将返回错误响应。Neutron 仅使用标准的 HTTP 错误代码。4xx 错误表示客户端发送的特定请求中存在问题。
| 错误 |
| 4>|400 Bad Request |
| 2>|404 Not Found |
| 3>|409 Conflict |
| 2>|400 Bad Request |
| 500 服务器内部错误 |
| 503 ServiceUnavailable |
向 Neutron API 发送请求的用户也可能收到以下错误
- 401 未授权 - 如果提供的凭据无效
- 403 禁止 - 如果用户无法访问特定资源或执行请求的操作。
API 操作
列出网络
| 动词 | URI |
| GET | /networks |
此操作返回租户有权访问的所有网络的列表。这包括租户拥有的网络和共享网络。默认情况下，网络对象将返回其所有属性。用户可以使用field 查询参数控制应返回哪些属性。可以通过在查询字符串上指定搜索条件来过滤响应。目前仅支持完全匹配。
正常响应代码：200
错误响应代码：未授权 (401)，错误请求 (400)
JSON 请求和响应示例:
请求
GET /v2.0/networks Accept: application/json
响应
{
"networks": [
{
"status": "ACTIVE",
"subnets": [],
"name": "network_1",
"admin_state_up": true,
"tenant_id": "c1210485b2424d48804aad5d39c61b8f",
"id": "3a06dfc7-d239-4aad-9a57-21cd171c72e5",
"shared": false
},
{
"status": "ACTIVE",
"subnets": [],
"name": "network-2",
"admin_state_up": true,
"tenant_id": "c1210485b2424d48804aad5d39c61b8f",
"id": "7db8c5a4-6eb0-478d-856b-7cfda2b25e13",
"shared": false
},
{
"status": "ACTIVE",
"subnets": ["e12f0c45-46e3-446a-b207-9474b27687a6"],
"name": "network_3",
"admin_state_up": true,
"tenant_id": "ed680f49ff714162ab3612d7876ffce5",
"id": "afc75773-640e-403c-9fff-62ba98db1f19",
"shared": true
}
]
}
显示网络
| 动词 | URI |
| GET | /networks/<network_id> |
此操作返回请求 URI 中指定的网络的完整属性列表，假设网络存在并且发出请求的用户有权访问它。可以通过 field 查询参数控制 API 实际返回的属性集。
正常响应代码：200
错误响应代码：未授权 (401)，错误请求 (400)，未找到 (404)
JSON 请求和响应示例:
请求
GET /v2.0/networks/afc75773-640e-403c-9fff-62ba98db1f19 Accept: application/json
响应
{
"network":
{
"status": "ACTIVE",
"subnets": ["e12f0c45-46e3-446a-b207-9474b27687a6"],
"name": "network_3",
"admin_state_up": true,
"shared": false,
"tenant_id": "ed680f49ff714162ab3612d7876ffce5",
"id": "afc75773-640e-403c-9fff-62ba98db1f19"
}
}
创建网络
| 动词 | URI |
| POST | /networks |
此操作将创建一个新的 Neutron 网络。新创建网络的标识符在响应中返回。shared 属性可用于创建公共网络，即：与所有其他租户共享的网络。但是，Neutron API 的当前模型仅允许完全私有或完全开放的网络。未来 API 版本将提供更复杂的机制来指定网络上的 ACL。
此外，shared 属性的控制权可以保留给特定的用户，例如管理员。在这种情况下，尝试创建共享网络的普通用户将收到 403 - 禁止 错误。
正常响应代码：200
错误响应代码：未授权 (401)，错误请求 (400)
JSON 请求和响应示例:
请求
POST v2.0/networks.json
Content-Type: application/json
Accept: application/json
{
"network":
{
"name": "sample_network",
"admin_state_up": false
}
}
响应
'status': '201'
'content-length': '194'
'content-type': 'application/json;
{
"network":
{
"status": "ACTIVE",
"subnets": [],
"name": "sample_network",
"admin_state_up": false,
"shared": false,
"tenant_id": "c1210485b2424d48804aad5d39c61b8f",
"id": "fc68ea2c-b60b-4b4f-bd82-94ec81110766"
}
}
批量版本
该操作的批量版本允许使用单个请求创建多个网络。批量创建操作的行为始终是原子性的：请求体中的所有网络都创建成功，或者都不创建。为此，必须在请求体中提供一个网络列表，如下所示
JSON 请求和响应示例:
请求
POST v2.0/networks.json
Content-Type: application/json
Accept: application/json
{
"networks": [
{
"name": "sample_network_1",
"admin_state_up": false
},
{
"name": "sample_network_2",
"admin_state_up": false
}]
}
更新网络
| 动词 | URI |
| PUT | /networks/<network-id> |
更新网络操作允许用户更新网络对象的某些属性，例如名称和 admin_state_up。诸如 tenant_id 之类的属性无法更新。如果尝试更新这些属性，将返回 422 'Unprocesable Entity' 错误。
有权控制 shared 属性的用户也允许更改它。虽然共享以前的私有网络始终是可能的，但反之则并非总是如此。如果用户尝试将具有属于不同于网络所有者的租户的子网和/或端口的共享网络变为私有，将返回 409 冲突 错误。
注意：Neutron 中的更新操作采用补丁语义。这意味着 Neutron API 不需要用户发送要更新的整个资源，而只需发送用户希望更新的属性，如以下示例所示。
正常响应代码：200 确定
错误响应代码：400 错误请求，401 未授权，403 禁止，404 未找到
JSON 请求和响应示例:
请求
PUT /v2.0/networks/fc68ea2c-b60b-4b4f-bd82-94ec81110766.json
Content-Type: application/json
Accept: application/json
{
"network":
{
"name": "updated_name"
}
}
响应
status: 200
content-length: 192
content-type: application/json
{
"network":
{"status": "ACTIVE",
"subnets": [],
"name": "updated_name",
"admin_state_up": false,
"shared": false,
"tenant_id": "c1210485b2424d48804aad5d39c61b8f",
"id": "fc68ea2c-b60b-4b4f-bd82-94ec81110766"}}
删除网络
| 动词 | URI |
| DELETE | /networks/<network_id> |
JSON 请求和响应示例:
此操作将删除 Neutron 网络及其所有关联的子网，前提是网络上当前未配置任何端口。如果端口仍然配置在要删除的网络上，将返回 409 错误。
正常响应代码：204
错误响应代码：400 错误请求，401 未授权，403 禁止，404 未找到，409 网络正在使用。
请求
DELETE /v2.0/networks/fc68ea2c-b60b-4b4f-bd82-94ec81110766 Content-Type: application/json Accept: application/json
响应
status: 204
列出子网
| 动词 | URI |
| GET | /subnets |
此操作将返回租户有权访问的子网对象列表。默认策略设置将仅返回提交请求的租户拥有的子网，除非请求由具有管理权限的用户提交。用户可以使用 fields 查询参数控制应返回哪些属性，如前一章所述。此外，可以使用查询字符串参数过滤结果，如前一章所述。
此操作不需要请求体。
正常响应代码：200 确定
错误响应代码：401 未授权
JSON 请求和响应示例:
请求
GET v2.0/subnets.json Accept: application/json
响应
status: 200
content-length: 607
content-type: application/json
{
"subnets": [
{
"name": "",
"network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
"tenant_id": "c1210485b2424d48804aad5d39c61b8f",
"allocation_pools": [{"start": "10.10.0.2", "end": "10.10.0.254"}],
"gateway_ip": "10.10.0.1",
"ip_version": 4,
"cidr": "10.10.0.0/24",
"id": "4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861",
"enable_dhcp": true
},
{
"name": "",
"network_id": "afc75773-640e-403c-9fff-62ba98db1f19",
"tenant_id": "ed680f49ff714162ab3612d7876ffce5",
"allocation_pools": [{"start": "10.0.0.2", "end": "10.0.0.254"}],
"gateway_ip": "10.0.0.1",
"ip_version": 4,
"cidr": "10.0.0.0/24",
"id": "e12f0c45-46e3-446a-b207-9474b27687a6",
"enable_dhcp": true
}]
}
显示子网
| 动词 | URI |
| GET | /subnets/<subnet-id> |
此操作返回请求 URI 中指定的子网的数据。用户可以使用 fields 查询参数控制应返回哪些属性，如前一章所述。如果提交请求的用户无权访问请求的子网，或者请求的子网不存在，将返回 404 错误。
此操作不需要请求主体。
正常响应代码：200 确定
错误响应代码：400 错误请求，401 未授权，404 未找到
JSON 请求和响应示例:
请求
GET /v2.0/subnets/4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861 Accept: application/json
响应
status: 200
content-length: 309
content-type: application/json
{
"subnet":
{
"name": "",
"network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
"tenant_id": "c1210485b2424d48804aad5d39c61b8f",
"allocation_pools": [{"start": "10.10.0.2", "end": "10.10.0.254"}],
"gateway_ip": "10.10.0.1",
"ip_version": 4,
"cidr": "10.10.0.0/24",
"id": "4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861",
"enable_dhcp": false,
}
}
创建子网
| 动词 | URI |
| POST | /subnets |
此操作在特定网络上创建一个新的子网。网络标识符 network_id 是必需的。用户还必须指定子网的 cidr，格式为 <network_address>/<prefix>。其余参数是可选的。
默认情况下，Neutron 创建 IP v4 子网。为了创建 IP v6 子网，用户必须在请求体中将 ip_version 属性的值指定为 6。请注意，Neutron 不会尝试从提供的 CIDR 推断正确的 IP 版本。如果网关地址的参数 gateway_ip 未指定，则 Neutron 将从子网的 cidr 中为子网的网关分配一个地址。为了指定没有网关的子网，用户应在请求体中将 gateway_ip 属性的值指定为 null。如果未指定分配池（属性 allocation_pools），Neutron 将自动分配覆盖 CIDR 中所有 IP 地址的池，不包括为子网网关保留的地址。否则，用户可以显式指定分配池，如下例所示。
最后，子网默认情况下将利用 DHCP 向 VM 分发地址。如果使用不同的策略，例如文件系统 IP 配置注入，则应在 create_subnet 请求中将 enable_dhcp 属性显式设置为 False。
正常响应代码：201 已创建
错误响应代码：400 错误请求，401 未授权，403 禁止，404 未找到
JSON 请求和响应示例:
请求
POST /v2.0/subnets
Content-Type: application/json
Accept: application/json
{
"subnet": {
"network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
"ip_version": 4,
"cidr": "10.0.3.0/24",
"allocation_pools": [{"start": "10.0.3.20", "end": "10.0.3.150"}]
}
}
}}
Response:
{{{
status: 201,
content-length: 306,
content-type: application/json
{
"subnet": {
"name": "",
"network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
"tenant_id": "c1210485b2424d48804aad5d39c61b8f",
"allocation_pools": [{"start": "10.0.3.20", "end": "10.0.3.150"}],
"gateway_ip": "10.0.3.1",
"ip_version": 4,
"cidr": "10.0.3.0/24",
"id": "9436e561-47bf-436a-b1f1-fe23a926e031",
"enable_dhcp": true}
}
批量版本
此操作允许使用单个请求创建多个子网。为此，必须在请求体中提供一个子网列表。该操作的行为始终是原子性的，这意味着要么创建所有子网，要么不创建任何子网。
请求
POST /v2.0/subnets
Content-Type: application/json
Accept: application/json
{
"subnets": [
{
"network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
"ip_version": 4,
"cidr": "10.0.4.0/24",
}
{
"network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
"ip_version": 4,
"cidr": "10.0.5.0/24",
}
]
}
更新子网
| 动词 | URI |
| PUT | /subnets/<subnet-id> |
此操作更新有关子网的信息。某些属性，例如 IP 版本 (ip_version)、CIDR (cidr) 和 IP 分配池 ('allocation_pools) 无法更新。尝试更新这些属性将导致 400 错误请求错误。
更新 host_routes 和 dns_nameservers 属性后，无法保证这些更改何时会反映在正在运行的 VM 实例上。Neutron API 的唯一职责是将数据模型与新信息更新。这些信息然后传播到正在运行的 VM 取决于用于向其提供 IP 配置的机制。在 DHCP 的情况下，这将在 VM 发送新的 DHCP 请求时发生，因此很可能在 DHCP 租约到期或 VM 重新启动时发生。
注意：Neutron 中的更新操作采用补丁语义。这意味着 Neutron API 不需要用户发送要更新的整个资源，而只需发送用户希望更新的属性，如以下示例所示
正常响应代码：200 确定
错误响应代码：400 错误请求，401 未授权，403 禁止，404 未找到，400 错误请求
JSON 请求和响应示例:
请求
PUT /v2.0/subnets/9436e561-47bf-436a-b1f1-fe23a926e031
Content-Type: application/json
Accept: application/json
{
"subnet":
{
"gateway_ip": "10.0.3.254",
"name": "new_name"
}
}
响应
status: 200
content-length: 316
content-type: application/json
{
"subnet":
{
"name": "new_name",
"network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
"tenant_id": "c1210485b2424d48804aad5d39c61b8f",
"allocation_pools": [{"start": "10.0.3.20", "end": "10.0.3.150"}],
"gateway_ip": "10.0.3.254",
"ip_version": 4,
"cidr": "10.0.3.0/24",
"enable_dhcp": true,
"id": "9436e561-47bf-436a-b1f1-fe23a926e031"
}
}
删除子网
| 动词 | URI |
| DELETE | /subnets/<subnetid> |
此操作从 Neutron 网络中删除一个子网。如果来自要删除的子网的 IP 仍然分配，则该操作将失败。
正常响应代码：204
错误响应代码：400 错误请求，401 未授权，403 禁止，404 未找到，409 冲突
JSON 请求和响应示例:
请求
DELETE /v2.0/subnets/9436e561-47bf-436a-b1f1-fe23a926e031 Accept: application/json
响应
Status: 204
列出端口
| 动词 | URI |
| GET | /ports |
此操作将返回租户有权访问的端口对象列表。默认策略设置将仅返回提交请求的租户拥有的子网，除非请求由具有管理权限的用户提交。用户可以使用 fields 查询参数控制应返回哪些属性，如前一章所述。此外，可以使用查询字符串参数过滤结果，如前一章所述。
此操作不需要请求体。
正常响应代码：200
错误响应代码：401 未授权
JSON 请求和响应示例:
请求
GET /v2.0/ports.json HTTP/1.1 accept: application/json
响应
Status: 200
Content-Type: application/json
Content-Length: 805
{
"ports": [
{
"admin_state_up": true,
"device_id": "257614cc-e178-4c92-9c61-3b28d40eca44",
"device_owner": "",
"fixed_ips": [
{
"ip_address": "192.168.111.3",
"subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
}
],
"id": "24e6637e-c521-45fc-8b8b-d7331aa3c99f",
"mac_address": "fa:16:3e:0f:3f:b5",
"name": "",
"network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
"status": "ACTIVE",
"tenant_id": "cf1a5775e766426cb1968766d0191908"
},
{
"admin_state_up": true,
"device_id": "d266f9de-fe2c-4705-93b3-9da71168c93b",
"device_owner": "",
"fixed_ips": [
{
"ip_address": "192.168.111.2",
"subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
}
],
"id": "e54dfd9b-ce6e-47f7-af47-1609cfd1cdb0",
"mac_address": "fa:16:3e:f5:41:7f",
"name": "",
"network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
"status": "ACTIVE",
"tenant_id": "cf1a5775e766426cb1968766d0191908"
}
]
}
显示端口
| 动词 | URI |
| GET | /ports/port-id |
此操作将返回请求 URI 中指定的端口的信息。如果端口不存在或者提交请求的用户无权访问它，将返回 404 错误。
正常响应代码：200
错误响应代码：400 错误请求，401 未授权，404 未找到
JSON 请求和响应示例:
请求
GET /v2.0/ports/ebe69f1e-bc26-4db5-bed0-c0afb4afe3db.json accept: application/json
响应
Status: 200
Content-Type: application/json
Content-Length: 410
{
"port": {
"admin_state_up": true,
"device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
"device_owner": "",
"fixed_ips": [
{
"ip_address": "192.168.111.4",
"subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
}
],
"id": "ebe69f1e-bc26-4db5-bed0-c0afb4afe3db",
"mac_address": "fa:16:3e:a6:50:c1",
"name": "port1",
"network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
"status": "ACTIVE",
"tenant_id": "cf1a5775e766426cb1968766d0191908"
}
}
创建端口
| 动词 | URI |
| POST | /ports |
此操作创建一个新的 Neutron 端口。请求体中必须指定端口将创建的网络 (network_id 参数)。可选地，用户还可以指定以下参数
- 端口的符号名称
- MAC 地址
- 管理状态（True：Up，False：Down）
- 固定 IP
- 仅指定子网 ID，Neutron 会从该子网分配第一个可用 IP 到端口
- 同时指定子网 ID 和 IP 地址，Neutron 将尝试将指定的地址分配给端口
- 连接到端口的设备的标识符（例如：VM 标识符）
- 连接到端口的设备的拥有者的标识符（例如：DHCP 代理标识符）
正常响应代码：201
错误响应代码：400 错误请求，401 未授权，403 禁止，404 未找到，409 冲突
JSON 请求和响应示例:
请求
POST /v2.0/ports.json HTTP/1.1
Content-Length: 158
content-type: application/json
accept: application/json
{
"port": {
"admin_state_up": true,
"device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
"name": "port1",
"network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12"
}
}
响应
Status: 201
Content-Type: application/json; charset=UTF-8
Content-Length: 410
{
"port": {
"admin_state_up": true,
"device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
"device_owner": "",
"fixed_ips": [
{
"ip_address": "192.168.111.4",
"subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
}
],
"id": "ebe69f1e-bc26-4db5-bed0-c0afb4afe3db",
"mac_address": "fa:16:3e:a6:50:c1",
"name": "port1",
"network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
"status": "ACTIVE",
"tenant_id": "cf1a5775e766426cb1968766d0191908"
}
}
批量版本
此操作允许使用单个请求创建多个端口。为此，必须在请求体中提供一个端口列表。Neutron API 始终保证批量操作的原子完成。
批量请求示例
{
"ports": [
{
"admin_state_up": true,
"device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
"name": "port1",
"network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12"
},
{
"admin_state_up": true,
"device_id": "d6b4d3a5-c700-476f-b609-1493dd9dadc0",
"name": "port2",
"network_id": "2cd34a97-e087-75fb-9904-dd12937009ea"
}
]
}
更新端口
| 动词 | URI |
| 更新 | /ports/<port-id> |
此操作可用于更新端口的信息，例如符号名称和关联的 IP。当更新端口的 IP 时，先前关联的 IP 将被删除，返回到各自子网的分配池，并替换为请求体中 Update 请求中指定的 IP。换句话说，此操作的行为是当请求体中指定时替换 fixed_ip 属性。如果新的 IP 地址无效（例如：已在使用中），则操作失败并且现有的 IP 地址不会与端口分离。
请注意，API 的唯一职责是将新的 IP 关联信息更新到数据模型。IP 地址实际更新到正在运行的 VM 的方式取决于用于传播 IP 配置的特定机制。在 DHCP 的情况下，这将在 VM 发送新的 DHCP 请求时发生，因此很可能在 DHCP 租约到期或 VM 重新启动时发生。
正常响应代码：200
错误响应代码：400 错误请求，401 未授权，403 禁止，404 未找到，409 冲突
JSON 请求和响应示例:
请求
PUT /v2.0/ports/1d8591f4-7b62-428e-857d-e82a15e5a7f1.json HTTP/1.1
Content-Length: 63
content-type: application/json
accept: application/json
{
"port": {
"device_id": "37b4f622-5e17-4dca-bf67-7338c5b7dd63"
}
}
响应
Status: 200
Content-Type: application/json;
Content-Length: 410
{
"port": {
"admin_state_up": true,
"device_id": "37b4f622-5e17-4dca-bf67-7338c5b7dd63",
"fixed_ips": [
{
"ip_address": "192.168.111.4",
"subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
}
],
"id": "1d8591f4-7b62-428e-857d-e82a15e5a7f1",
"mac_address": "fa:16:3e:70:d2:8c",
"name": "port2",
"network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
"status": "ACTIVE",
"tenant_id": "cf1a5775e766426cb1968766d0191908"
}
}
删除端口
| 动词 | URI |
| DELETE | /ports/<port-id> |
此操作从 Neutron 网络中删除一个端口。如果端口关联了 IP 地址，则这些地址将返回到各自子网的分配池。
正常响应代码：204
错误响应代码：401 未授权，403 禁止，404 未找到
JSON 请求和响应示例:
请求
DELETE /v2.0/ports/ebe69f1e-bc26-4db5-bed0-c0afb4afe3db.json accept: application/json
响应
status: 204
