使用图像 API v2 共享镜像¶
OpenStack 镜像服务 API v2 允许用户以以下方式相互共享镜像
镜像可以与云中的特定其他用户共享。这种共享模式自 API 的 2.1 版本以来就可用。因此，当我们在此文档中谈论“共享”镜像时，我们指的是这种类型的共享。它在下面的 与特定用户共享镜像 部分中描述。
镜像可以与云中的所有用户共享。这种共享模式自 API 的 2.5 版本以来可用。以这种方式共享的镜像被称为“社区”镜像，因为它们可供云中的所有用户社区使用（并且因为我们想不出更好的名称）。社区镜像在下面的 与所有用户共享镜像 部分中讨论。
为了使后续讨论清晰，以下是一些将要使用的术语。
- 生产者
拥有要与其它用户共享的镜像的用户。
- 消费者
想要使用镜像的用户。
- 共享镜像
已向特定其他用户公开的镜像，如 与特定用户共享镜像 中所述。自 API 的 2.5 版本以来，此类镜像的
visibility属性为shared。（如果您使用的是 API 的早期版本，则visibility为private。）- 社区镜像
已向云中的所有用户公开的镜像，如 与所有用户共享镜像 中所述。自 API 的 2.5 版本以来，此类镜像的
visibility属性为community。（此类型的镜像在 2.5 版本之前不可用。）
与特定用户共享镜像¶
让“生产者”是镜像 71c675ab-d94f-49cd-a114-e12490b328d9 的所有者，让“消费者”是想要从该镜像启动实例的用户。
生产者可以通过将消费者设为该镜像的成员来共享镜像。
为了防止垃圾邮件，消费者必须接受镜像，然后它才会包含在消费者的镜像列表中。
但是，如果消费者知道镜像 ID，仍然可以从镜像启动。
总而言之
镜像生产者可以添加或删除镜像成员，但不能修改镜像成员的状态。
镜像消费者可以更改其成员状态，但不能添加或删除自己作为镜像成员。
消费者可以从共享镜像启动实例，无论他/她是否“接受”了该镜像。
如何识别生产者或消费者？¶
作为镜像生产者，您知道您是谁，但是您如何识别您的镜像的潜在消费者？作为镜像消费者，您如何引用自己，如果您想使用社区镜像，您使用什么来识别镜像的生产者？这些实际上是复杂的问题，因为 Glance 允许操作员决定镜像将由项目拥有还是由用户拥有。默认情况下，镜像由项目拥有，因此您通常会看到这种情况。
注意
有时您会看到项目被称为租户。 “租户”是 OpenStack 最初的项目术语。它已被逐步淘汰，因为在英语中，“租户”一词通常用于指人，这很容易将租户与所有者混淆。但是，当文档或 OpenStack 社区成员提到“租户”或“租户 ID”时，他们实际上指的是“项目”或“项目 ID”。
在镜像所有者为项目的云中，识别镜像生产者或消费者的唯一方法是使用他们的项目 ID。
在这样的云中，镜像在项目之间共享。因此，所有消费项目的用户都可以访问该镜像。在这样的云中，无法仅与单个用户共享镜像。
在镜像所有者为用户的云中，镜像生产者或消费者由他们的用户 ID 标识。
在这样的云中，镜像在用户之间共享。因此，只有作为镜像成员的用户才能访问该镜像。这扩展到与拥有镜像的用户相同的项目中的其他用户。即使他们位于同一个项目，也必须显式设置为成员才能访问该镜像。
请注意，镜像生产者或消费者不能决定使用哪个标识符。这由云管理员为整个云决定。请查阅您云的本地文档，以确定适用于您使用的特定云的配置。（如前所述，默认情况下，镜像由项目拥有，因此如果本地文档没有说明任何内容，那么很有可能正在使用默认配置。）
生产者-消费者通信¶
此 API 中未提供生产者-消费者通信的规定。所有此类通信必须独立于 API 进行。
共享镜像的示例工作流程是
生产者在公共网站上发布特定镜像的可用性。
潜在消费者向生产者提供其适当的标识符和电子邮件地址。（如果您不确定适当的标识符是什么，请参阅 如何识别生产者或消费者？）
生产者使用 Images v2 API 与消费者共享镜像。
生产者通过电子邮件通知消费者镜像已共享及其 UUID。
如果消费者希望共享镜像出现在其镜像列表中，则使用 Images v2 API 将镜像状态更改为
accepted。如果消费者随后希望隐藏镜像，可以使用 Images v2 API 将成员状态更改为
rejected。如果消费者希望隐藏镜像，但愿意接受生产者提醒镜像可用，可以使用 Images v2 API 将成员状态更改为pending。
请注意，就此 API 而言，成员状态只有两种效果
如果成员状态不是
accepted，则镜像不会出现在消费者的默认镜像列表中。可以通过状态过滤消费者的镜像列表，以查看处于各种成员状态的共享镜像。例如，消费者可以通过过滤
visibility=shared&member_status=pending来发现与他/她共享的镜像。
镜像共享模式¶
JSON 模式文档在以下 URI 中提供。
请记住，本文档中包含的模式只是示例，不应用于验证您的请求。
获取镜像成员模式¶
GET /v2/schemas/member
没有请求体。
响应体包含一个 json-schema 文档，该文档表示一个镜像 member 实体。
API 的响应应被视为权威。此处重现模式仅供您参考
{
"name": "member",
"properties": {
"created_at": {
"description": "Date and time of image member creation",
"type": "string"
},
"image_id": {
"description": "An identifier for the image",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"member_id": {
"description": "An identifier for the image member",
"type": "string"
},
"status": {
"description": "The status of this image member",
"enum": [
"pending",
"accepted",
"rejected"
],
"type": "string"
},
"updated_at": {
"description": "Date and time of last modification of image member",
"type": "string"
},
"schema": {
"type": "string"
}
}
}
获取镜像成员模式¶
GET /v2/schemas/members
没有请求体。
响应体包含一个 json-schema 文档，该文档表示一个镜像 members 实体（一个 member 实体的容器）。
API 的响应应被视为权威。此处重现模式仅供您参考
{
"name": "members",
"properties": {
"members": {
"items": {
"name": "member",
"properties": {
"created_at": {
"description": "Date and time of image member creation",
"type": "string"
},
"image_id": {
"description": "An identifier for the image",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"member_id": {
"description": "An identifier for the image member",
"type": "string"
},
"status": {
"description": "The status of this image member",
"enum": [
"pending",
"accepted",
"rejected"
],
"type": "string"
},
"updated_at": {
"description": "Date and time of last modification of image member",
"type": "string"
},
"schema": {
"type": "string"
}
}
},
"type": "array"
},
"schema": {
"type": "string"
}
},
"links": [
{
"href": "{schema}",
"rel": "describedby"
}
]
}
镜像生产者调用¶
以下调用与希望充当共享镜像生产者用户相关。
注意
镜像 visiblity 属性的 shared 值是在 Image API 的 2.5 版本中引入的。从 2.5 版本开始，镜像成员调用成功的一个必要条件是，调用中引用的镜像的 visibility 字段的值为 shared。
创建镜像成员¶
POST /v2/images/<IMAGE_ID>/members
请求体必须是以下格式的 JSON
{
"member": "<MEMBER_ID>"
}
其中 MEMBER_ID 是与要共享镜像的消费者的 ID。
新创建的镜像成员的成员状态为 pending。
如果发出调用的用户不是镜像所有者，则响应的 HTTP 状态码为 404。
响应符合可在 /v2/schemas/member 处获得的 JSON 模式，例如，
{
"created_at": "2013-09-19T20:36:53Z",
"image_id": "71c675ab-d94f-49cd-a114-e12490b328d9",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2013-09-19T20:36:53Z"
}
删除镜像成员¶
DELETE /v2/images/<IMAGE_ID>/members/<MEMBER_ID>
没有请求体。
成功的响应是 204（无内容）。
如果 MEMBER_ID 不是指定镜像的镜像成员，则该调用返回 HTTP 状态码 404。
如果发出调用的用户不是镜像所有者，则该调用返回 HTTP 状态码 404。
镜像消费者调用¶
以下调用适用于希望充当共享镜像消费者的用户。
注意
镜像 visiblity 属性的 shared 值是在 Image API 的 2.5 版本中引入的。从 2.5 版本开始，镜像成员调用成功的一个必要条件是，调用中引用的镜像的 visibility 字段的值为 shared。
更新镜像成员¶
PUT /v2/images/<IMAGE_ID>/members/<MEMBER_ID>
请求体是 JSON 对象，指定应更新镜像成员的成员状态
{
"status": "<STATUS_VALUE>"
}
其中 STATUS_VALUE 是 { pending、accepted 或 rejected } 中的一个。
响应符合可在 /v2/schemas/member 处获得的 JSON 模式，例如，
{
"created_at": "2013-09-20T19:22:19Z",
"image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member",
"status": "accepted",
"updated_at": "2013-09-20T20:15:31Z"
}
如果调用者是镜像所有者，则响应的 HTTP 状态码为 403（禁止）。
如果调用者不是镜像所有者，并且其标识符与 MEMBER_ID 不匹配，则响应的 HTTP 状态码为 404。
镜像成员状态值¶
有三种镜像成员状态值
pending：创建成员时，其状态设置为pending。镜像在成员的镜像列表中不可见，但成员仍然可以从镜像启动实例。accepted：当成员的状态为accepted时，镜像在成员的镜像列表中可见。成员可以从镜像启动实例。rejected：当成员的状态为rejected时，成员决定他/她不想查看镜像。镜像在成员的镜像列表中不可见，但成员仍然可以从镜像启动实例。
适用于生产者和消费者的调用¶
这些调用适用于充当共享镜像生产者或消费者的用户。
注意
镜像 visiblity 属性的 shared 值是在 Image API 的 2.5 版本中引入的。从 2.5 版本开始，镜像成员调用成功的一个必要条件是，调用中引用的镜像的 visibility 字段的值为 shared。
显示镜像成员¶
GET /v2/images/<IMAGE_ID>/members/<MEMBER_ID>
响应符合可在 /v2/schemas/member 处获得的 JSON 模式，例如，
{
"created_at": "2014-02-20T04:15:17Z",
"image_id": "634985e5-0f2e-488e-bd7c-928d9a8ea82a",
"member_id": "46a12bfd09c8459483c03e1b0d71bda8",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2014-02-20T04:15:17Z"
}
镜像所有者（生产者）可以为每个镜像成员成功发出此调用。镜像成员（消费者）只有在 MEMBER_ID 是该消费者的正确标识符时才能成功发出此调用。对于任何其他 MEMBER_ID，消费者会收到 404 响应。
列出镜像成员¶
GET /v2/images/<IMAGE_ID>/members
响应符合可在 /v2/schemas/members 处获得的 JSON 模式，例如，
{
"members": [
{
"created_at": "2013-09-20T19:16:53Z",
"image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
"member_id": "818baf9e073fd04fa78989447062e04a",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2013-09-20T19:16:53Z"
},
{
"created_at": "2013-09-20T19:22:19Z",
"image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2013-09-20T19:22:19Z"
}
],
"schema": "/v2/schemas/members"
}
如果调用者与镜像共享，则成员列表将仅包含该用户的信息。例如，如果调用者是消费者 8989447062e04a818baf9e073fd04fa7，则响应是
{
"members": [
{
"created_at": "2013-09-20T19:22:19Z",
"image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2013-09-20T19:22:19Z"
}
],
"schema": "/v2/schemas/members"
}
如果调用者与镜像未共享，则响应为 404。
列出共享镜像¶
共享镜像作为正常的镜像列表调用的一部分进行列出。在本节中，我们强调一些有用的筛选选项。
visibility=shared：显示与我共享的镜像，我的成员状态为“accepted”visibility=shared&member_status=accepted：与上述相同visibility=shared&member_status=pending：显示与我共享的镜像，我的成员状态为“pending”visibility=shared&member_status=rejected：显示与我共享的镜像，我的成员状态为“rejected”visibility=shared&member_status=all：显示与我共享的所有镜像，无论我的成员状态如何owner=<OWNER_ID>：显示与我共享的镜像，生产者标识符为 OWNER_ID
与所有用户共享镜像¶
从 2.5 版本开始，Image Service API v2 提供了另一种图像共享方式，社区镜像。社区镜像对云中的所有用户可用，无需在镜像上创建成员。
社区镜像是一个 visibility 值设置为 community 的镜像。云运营商可以自行决定是否禁止或限制将镜像社区化。要使镜像成为社区镜像，请使用镜像更新调用来相应地更改镜像的可见性。（有关更多信息，请参阅 更新镜像。）
社区镜像不会出现在任何用户（除了镜像所有者）的默认镜像列表中。为了发现社区镜像，请使用 ‘visibility’ 过滤器进行镜像列表调用
GET v2/images?visibility=community
与标准的镜像列表调用一样，可以对请求应用其他过滤器。例如，要查看由标识符为 931efe8a-0ad7-4610-9116-c199f8807cda 的镜像生产者提供的社区镜像，将进行以下调用
GET v2/images?visibility=community&owner=931efe8a-0ad7-4610-9116-c199f8807cda
注意
有关如何确定镜像生产者标识符的信息，请参阅 如何识别生产者或消费者？
请记住，镜像的 name 属性不要求唯一，因此按名称过滤可能会导致多个匹配项。例如，可能有多个镜像生产者推广名为“Fred’s Excellent OS”的内容，因此以下调用（记住要 URL 编码撇号和空格）
GET v2/images?visibility=community&name=Fred%27s%20Excellent%20OS
可能会返回来自不同镜像生产者的多个镜像记录。如果您只想查找由特定生产者提供的镜像，则按 owner 过滤会给出更准确的结果。此外，如果 Fred 删除了他信任的“Fred’s Excellent OS”镜像，那么另一个您甚至不认识的生产者 George 可能会创建一个“Fred’s Excellent OS”镜像。如果您仅按名称搜索，您会找到 George 的镜像——在您确定 George 的身份、他的可信度以及他放在镜像上的内容之前，您可能不想使用它。
此 API 中未提供生产者-消费者通信的规定。所有此类通信必须独立于 API 进行。
社区镜像的一个示例工作流程是
生产者在公共网站上发布有关社区镜像的信息。这些信息将是对镜像的描述，包括镜像的 UUID。
消费者在 Images v2 API 调用中使用 UUID 来访问镜像。
另一种工作流程是
生产者在公共网站上发布有关社区镜像的信息。该帖子将包括生产者的标识符。
潜在的消费者在镜像列表调用中使用生产者的标识符，如上面的示例所示，以发现可用的镜像并确定要使用的镜像的 UUID。
消费者在 Images v2 API 调用中使用 UUID 来访问镜像。
