键/值修订版Key-value revisions

“键/值修订版”定义了键/值资源的历史表示形式。A key-value revision defines the historical representation of a key-value resource. 对于免费层存储，修订版会在 7 天后过期；对于标准层存储，则在 30 天后过期。Revisions expire after 7 days for Free tier stores, or 30 days for Standard tier stores. 修订版支持 List 操作。Revisions support the List operation.

对于所有操作，key 为可选参数。For all operations, key is an optional parameter. 如果省略，则暗指任何键。If omitted, it implies any key.

对于所有操作，label 为可选参数。For all operations, label is an optional parameter. 如果省略，则暗指任何标签。If omitted, it implies any label.

本文适用于 API 版本 1.0。This article applies to API version 1.0.

先决条件Prerequisites

  • 所有 HTTP 请求都必须经过身份验证。All HTTP requests must be authenticated. 请参阅身份验证部分。See the authentication section.
  • 所有 HTTP 请求都必须提供显式的 api-version。All HTTP requests must provide explicit api-version. 请参阅版本控制部分。See the versioning section.

列出修订版List revisions

GET /revisions?label=*&api-version={api-version} HTTP/1.1

响应：Responses:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvset+json; charset=utf-8"
Accept-Ranges: items

{
    "items": [
        {
          "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
          "key": "{key}",
          "label": "{label}",
          "content_type": null,
          "value": "example value",
          "last_modified": "2017-12-05T02:41:26.4874615+00:00",
          "tags": []
        },
        ...
    ],
    "@nextLink": "{relative uri}"
}

分页Pagination

如果返回的项数超过响应限制，则会对结果进行分页。The result is paginated if the number of items returned exceeds the response limit. 按照可选 Link 响应标头进行操作并使用 rel="next" 进行导航。Follow the optional Link response header and use rel="next" for navigation. 或者，内容以 @nextLink 属性的形式提供下一个链接。Alternatively, the content provides a next link in the form of the @nextLink property.

GET /revisions?api-version={api-version} HTTP/1.1

响应：Response:

HTTP/1.1 OK
Content-Type: application/vnd.microsoft.appconfig.kvs+json; charset=utf-8
Accept-Ranges: items
Link: <{relative uri}>; rel="next"

{
    "items": [
        ...
    ],
    "@nextLink": "{relative uri}"
}

列出修订版的子集List subset of revisions

使用 Range 请求标头。Use the Range request header. 响应包含一个 Content-Range 标头。The response contains a Content-Range header. 如果服务器不能满足所请求的范围，则会以“HTTP 416 (RangeNotSatisfiable)”进行响应。If the server can't satisfy the requested range, it responds with HTTP 416 (RangeNotSatisfiable).

GET /revisions?api-version={api-version} HTTP/1.1
Range: items=0-2

响应Response

HTTP/1.1 206 Partial Content
Content-Type: application/vnd.microsoft.appconfig.revs+json; charset=utf-8
Content-Range: items 0-2/80

筛选Filtering

支持组合使用 key 和 label 筛选。A combination of key and label filtering is supported. 使用可选的 key 和 label 查询字符串参数。Use the optional key and label query string parameters.

GET /revisions?key={key}&label={label}&api-version={api-version}

支持的筛选器Supported filters

键筛选器Key filter 效果Effect
省略 key 或 key=*key is omitted or key=* 匹配任何键Matches any key
key=abc 匹配名为“abc”的键Matches a key named abc
key=abc* 匹配以“abc”开头的键名称Matches keys names that start with abc
key=*abc 匹配以“abc”结尾的键名称Matches keys names that end with abc
key=*abc* 匹配包含“abc”的键名称Matches keys names that contain abc
key=abc,xyz 匹配键名称“abc”或“xyz”（限制为 5 个 CSV） Matches keys names abc or xyz (limited to 5 CSV)
标签筛选器Label filter 效果Effect
省略 label 或 label=label is omitted or label= 匹配不带标签的条目Matches entry without label
label=* 匹配任何标签Matches any label
label=prod 匹配标签“prod”Matches the label prod
label=prod* 匹配以“prod”开头的标签Matches labels that start with prod
label=*prod 匹配以“prod”结尾的标签Matches labels that end with prod
label=*prod* 匹配包含“prod”的标签Matches labels that contain prod
label=prod,test 匹配标签“prod”或“test”（限制为 5 个 CSV）Matches labels prod or test (limited to 5 CSV)

保留字符Reserved characters

保留字符为：The reserved characters are:

*, \, ,*, \, ,

如果保留字符是值的一部分，则必须使用 \{Reserved Character} 对其进行转义。If a reserved character is part of the value, then it must be escaped by using \{Reserved Character}. 非保留字符也可以进行转义。Non-reserved characters can also be escaped.

筛选器验证Filter validation

如果出现筛选器验证错误，则响应为“HTTP 400”，其中包含以下错误详细信息：If a filter validation error occurs, the response is HTTP 400 with error details:

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8

{
  "type": "https://azconfig.io/errors/invalid-argument",
  "title": "Invalid request parameter '{filter}'",
  "name": "{filter}",
  "detail": "{filter}(2): Invalid character",
  "status": 400
}

示例Examples

  • 所有：All:

    GET /revisions

  • 其中的键名称以“abc”开头的项：Items where the key name starts with abc:

    GET /revisions?key=abc*&api-version={api-version}

  • 其中的键名称为“abc”或“xyz”且标签包含“prod”的项：Items where the key name is either abc or xyz, and labels contain prod:

    GET /revisions?key=abc,xyz&label=*prod*&api-version={api-version}

请求特定字段Request specific fields

使用可选的 $select 查询字符串参数，并提供逗号分隔的所请求字段列表。Use the optional $select query string parameter and provide a comma-separated list of requested fields. 如果省略 $select 参数，则响应会包含默认集。If the $select parameter is omitted, the response contains the default set.

GET /revisions?$select=value,label,last_modified&api-version={api-version} HTTP/1.1

基于时间的访问Time-based access

获得结果在过去的表现形式。Obtain a representation of the result as it was at a past time. 有关详细信息，请参阅用于对资源状态进行基于时间的访问的 HTTP 框架 - Memento 的 2.1.1 部分。For more information, see HTTP Framework for Time-Based Access to Resource States -- Memento, section 2.1.1.

GET /revisions?api-version={api-version} HTTP/1.1
Accept-Datetime: Sat, 12 May 2018 02:10:00 GMT

响应：Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.revs+json"
Memento-Datetime: Sat, 12 May 2018 02:10:00 GMT
Link: <{relative uri}>; rel="original"

{
    "items": [
        ....
    ]
}