Image API v2 HTTP PATCH media types

概述

HTTP PATCH 请求必须提供一种媒体类型，以便服务器确定如何将补丁应用于镜像资源。不支持的媒体类型将导致 HTTP 错误响应，状态码为 415。对于镜像资源，支持两种媒体类型

  • application/openstack-images-v2.1-json-patch

  • application/openstack-images-v2.0-json-patch

`application/openstack-images-v2.1-json-patch` 媒体类型旨在提供 JavaScript Object Notation (JSON) Patch RFC6902 中定义的功能的一个有用且兼容的子集，该标准定义了 `application/json-patch+json` 媒体类型。

`application/openstack-images-v2.0-json-patch` 媒体类型基于该标准的 draft 4。 其使用已被弃用。

受限的 JSON 指针

本附录中定义的 ‘application/openstack-images-v2.1-json-patch’ 媒体类型采用 JSON-Pointers 的受限形式。 受限的 JSON 指针是一个 Unicode 字符串，包含一个恰好包含一个引用标记的序列，该标记以前缀 ‘/’ (%x2F) 字符开头。

如果引用标记包含 ‘~’ (%x7E) 或 ‘/’ (%x2F) 字符，则必须将其编码为 ‘~0’ 和 ‘~1’ 分别。

其 ABNF 语法是

restricted-json-pointer = "/" reference-token
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7D / %x7F-10FFFF
escaped = "~" ( "0" / "1" )

受限的 JSON 指针按照 JSON-Pointer 的方式评估为普通的 JSON 指针。

例如，给定 `image` 实体

{
    "id": "da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
    "name": "cirros-0.3.0-x86_64-uec-ramdisk",
    "status": "active",
    "visibility": "public",
    "size": 2254249,
    "checksum": "2cec138d7dae2aa59038ef8c9aec2390",
    "~/.ssh/": "present",
    "tags": ["ping", "pong"],
    "created_at": "2012-08-10T19:23:50Z",
    "updated_at": "2012-08-10T19:23:50Z",
    "self": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea",
    "file": "/v2/images/da3b75d9-3f4a-40e7-8a2c-bfab23927dea/file",
    "schema": "/v2/schemas/image"
}

以下受限的 JSON 指针评估为相应的数值

"/name"        "cirros-0.3.0-x86_64-uec-ramdisk"
"/size"        2254249
"/tags"        ["ping", "pong"]
"/~0~1.ssh~1"  "present"

操作

application/openstack-images-v2.1-json-patch 媒体类型支持 application/json-patch+json 媒体类型中定义的操作的一个子集。在请求对象的 “op” 成员中指定操作。

  • 支持的操作包括 add、remove 和 replace。

  • 如果操作对象不包含任何已识别的操作成员，则会发生错误。

在操作对象的 “path” 成员中指定要在目标镜像中执行请求操作的位置。

  • 成员值是一个字符串，包含一个受限的 JSON 指针值，该值引用目标镜像中要执行操作的位置。

在适当的情况下（即，对于 “add” 和 “replace” 操作），操作对象必须包含 “value” 数据成员。

  • 成员值是以 JSON 符号表示的实际值，用于添加（或用于替换操作）。（例如，字符串必须用引号括起来，数值值不带引号。）

PATCH 请求的有效负载必须是 JSON 对象的列表。每个对象必须符合以下格式之一。

  • 添加

add 操作在目标镜像的指定位置添加一个新值。该位置必须引用要添加到现有镜像的镜像属性。

操作对象指定一个 “value” 成员和关联值。

示例

PATCH /images/{image_id}

[
   {
      "op":"add",
      "path":"/login-name",
      "value":"kvothe"
   }
]

您还可以使用 add 操作将位置添加到与指定镜像 ID 关联的位置集合中，如下所示

示例

PATCH /images/{image_id}

[
   {
      "op":"add",
      "path":"/locations/1",
      "value":"scheme4://path4"
   }
]

  • remove

remove 操作删除目标镜像中指定的镜像属性。如果镜像属性在指定位置不存在，则会发生错误。

示例

PATCH /images/{image_id}

[
   {
      "op":"remove",
      "path":"/login-name"
   }
]

您还可以使用 remove 操作从与指定镜像 ID 关联的位置集合中删除位置，如下所示

示例

PATCH /images/{image_id}

[
   {
     "op":"remove",
     "path":"/locations/2"
   }
]

  • replace

replace 操作将目标镜像中指定镜像属性的值替换为新值。操作对象包含一个 “value” 成员，该成员指定替换值。

示例

[
   {
      "op":"replace",
      "path":"/login-name",
      "value":"kote"
   }
]

此操作在功能上与对镜像属性执行 “remove” 操作完全相同，紧接着在相同位置执行 “add” 操作，并使用替换值。

如果目标镜像中指定的镜像属性不存在，则会发生错误。

您还可以使用 replace 操作替换与指定镜像 ID 关联的位置集合中的位置，如下所示

示例

PATCH /images/{image_id}

[
   {
      "op":"replace",
      "path":"/locations",
      "value":[
         "scheme5://path5",
        "scheme6://path6"
      ]
  }
]