元数据

本文档旨在提供关于如何在 OpenStack REST API 中使用元数据的指导。

元数据有时与标签混淆。虽然它们有一些共同之处，但元数据的主要功能是以键值对的形式附加额外信息到实体。另一方面，标签用于将实体分类到组中。关于标签的单独指南文档已存在。

有关此处引用的 REST 指南的背景信息，请参阅关于 命名约定 和 HTTP 指南 的主题文档。

元数据表示

Python 字典被用作资源元数据的表示形式。该字典作为附加字段添加到父资源的表示形式中，字段名称为metadata.

使用服务器资源作为示例请求

GET /servers/1234567890

响应

{
    'id': '1234567890',

    ... other server resource properties ...

    'metadata': {
        "foo": "Foo Value",
        "bar": "Bar Value",
        "baz": "Baz Value"
    }
}

元数据的更新按照标准的 HTTP 请求方法进行，直接针对父资源发出。例如，要更新资源的元数据字典，应将 PUT 请求发送到该资源，其中包含不仅包含元数据，还包含完整的资源表示形式的主体。在这种情况下，更新不必仅限于元数据，其他属性也可以同时更新。

对于表示形式不是 JSON 的资源，必须创建一个单独的端点来暴露元数据。有关更多信息，请参阅下面的“元数据资源 URL”部分。

元数据键和值的字符编码

根据 RFC 7159，JSON 文档应以 UTF-8、UTF-16 或 UTF-32 编码，其中 UTF-8 是默认编码，也是为了最大程度的互操作性而推荐的编码。

由于整个元数据表示形式都是 JSON 文档，因此键和值的编码必须与父文档的编码匹配。强烈建议使用 UTF-8 编码。

元数据资源 URL

有时使用完整的资源表示形式处理资源的元数据部分可能不方便，因此元数据也可以作为独立资源暴露。元数据管理的根资源 URL 必须是元数据所属资源的 URL，后跟 /metadata（对于使用用户生成 URL 且组件数量不同的 API，/metadata URL 组件可以作为前缀而不是后缀添加）。

例如，由 URL http://example.com:8774/servers/1234567890 标识的资源必须使用根 URL http://example.com:8774/servers/1234567890/metadata 暴露其元数据。

获取元数据

要获取资源的元数据，必须将 GET 请求发送到根元数据 URL。成功后，服务器将以 200 状态码和响应主体中的完整元数据项集进行响应。

示例请求

GET /servers/1234567890/metadata

响应

{
    "metadata": {
        "foo": "Foo Value",
        "bar": "Bar Value",
        "baz": "Baz Value"
    }
}

修改元数据

要添加、删除或更改元数据项，必须将 PUT 请求发送到根元数据 URL，并在请求主体中包含更新后的完整元数据项列表。成功后，服务器将以 200 状态码和响应主体中的完整更新的元数据块进行响应。

注意

PUT 请求应使用 etags 以避免丢失更新问题。

示例请求（更新“foo”，删除“bar”，添加“qux”并保持“baz”不变）

PUT /servers/1234567890/metadata
{
    "metadata": {
        "foo": "Foo Value Updated",
        "baz": "Baz Value",
        "qux": "Qux Value"
    }
}

响应

{
    "metadata": {
        "foo": "Foo Value Updated",
        "baz": "Baz Value",
        "qux": "Qux Value"
    }
}

删除元数据

要删除与资源关联的整个元数据块，必须将 DELETE 请求发送到根元数据 URL。成功后，服务器将以 204 状态码进行响应。

示例请求

DELETE /servers/1234567890/metadata

要删除多个元数据项而不影响其余项，必须将 PUT 请求发送到根元数据 URL，并在请求主体中包含更新后的完整元数据项列表（不包含要删除的项）。成功后，服务器将以 200 状态码进行响应。

示例请求（删除“foo”和“qux”）

PUT /servers/1234567890/metadata
{
    "metadata": {
        "baz": "Baz Value"
    }
}

响应

{
    "metadata": {
        "baz": "Baz Value"
    }
}

要删除单个元数据项，请参见下文。

寻址单个元数据项

作为上述内容的扩展，API 可以选择暴露额外的端点，以便为客户端提供处理单个元数据项的能力。如果项目决定实施此选项，则应单独通过将键名附加到根元数据 URL 的方式访问每个键值对。请注意，此选项不适用于使用用户生成 URL 的 API。

要插入单个元数据项而无需发送整个元数据块，客户端可以向根元数据 URL 发送 POST 请求，并在请求主体中包含单个元数据项的表示形式。成功后，服务器将以 201 状态码进行响应，并在Location响应的头部中包含新元数据项的 URL。

示例请求

POST /servers/1234567890/metadata
{
    "key": "qux",
    "value": "Qux Value"
}

响应

Location: http://example.com:8774/servers/1234567890/metadata/qux
{
    "key": "qux",
    "value": "Qux Value",
}

如上例所示，可以通过将键名附加到根元数据 URL 来单独访问元数据项。该表示形式包括键和值。这种格式使 API 能够包含描述元数据项的附加属性，例如到期日期。

要修改项，将 PUT 请求发送到元数据项的 URL。成功后，服务器将以 200 状态码和响应主体中的更新的元数据项表示形式进行响应。

示例请求

PUT /servers/1234567890/metadata/qux
{
    "key": "qux",
    "value": "Qux Value Updated"
}

响应

{
    "key": "qux",
    "value": "Qux Value Updated"
}

要删除单个元数据项而不影响其余项，将 DELETE 请求发送到元数据项 URL。成功后，服务器将以 204 状态码进行响应。

示例请求

DELETE /servers/1234567890/metadata/qux