键-值

键值是由 key + label 的唯一组合标识的资源。 label 是可选项。 若要显式引用不带标签的键值,请使用“\0”(编码为 %00 的 URL)。 请查看每个操作的详细信息。

Operations

  • 获取
  • 列出多个
  • 设置
  • 删除

必备条件

  • 所有 HTTP 请求都必须经过身份验证。 请参阅身份验证部分。
  • 所有 HTTP 请求都必须提供显式的 api-version。 请参阅版本控制部分。

语法

{
  "etag": [string],
  "key": [string],
  "label": [string, optional],
  "content_type": [string, optional],
  "value": [string],
  "last_modified": [datetime ISO 8601],
  "locked": [boolean],
  "tags": [object with string properties, optional]
}

获取键值

必需:{key}{api-version}
可选:label(如果省略,则表示不带标签的键值。)

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

响应:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8;
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "key": "{key}",
  "label": "{label}",
  "content_type": null,
  "value": "example value",
  "last_modified": "2017-12-05T02:41:26+00:00",
  "locked": "false",
  "tags": {
    "t1": "value1",
    "t2": "value2"
  }
}

如果键不存在,将返回以下响应:

HTTP/1.1 404 Not Found

获取(有条件)

若要改善客户端缓存,请使用 If-MatchIf-None-Match 请求标头。 etag 参数是键表示形式的一部分。 有关详细信息,请参阅第 14.24 和 14.26节

仅在当前表示形式与指定的 etag 不匹配时,以下请求才检索键值:

GET /kv/{key}?api-version={api-version} HTTP/1.1
Accept: application/vnd.microsoft.appconfig.kv+json;
If-None-Match: "{etag}"

响应:

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

列出键值

可选:key(如果未指定,则表示键可以是任何键。)

可选:label(如果未指定,则表示标签可以是任何标签。)

:::zone-end

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

响应:

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

可选:tags(如果未指定,则表示任意标记。)

GET /kv?key=Test*&label=*&tags=tag1=value1&tags=tag2=value2&api-version={api-version} HTTP/1.1

响应:

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

有关更多选项,请参阅本文后面的“筛选”部分。

列表键值(在某些条件下)

若要改善客户端缓存,请使用 If-MatchIf-None-Match 请求标头。 etag 参数是列表键值响应正文和标头的一部分。 如果省略 If-MatchIf-None-Match,则该操作是无条件的。

仅在当前表示与指定的 etag 匹配时,以下响应才会获取键值:

GET /kv?key={key}label={label}&api-version={api-version} HTTP/1.1
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

响应:

HTTP/1.1 412 PreconditionFailed

HTTP/1.1 200 OK

仅在当前表示与指定的 etag 不匹配时,以下响应才会获取键值:

GET /kv?key={key}label={label}&api-version={api-version} HTTP/1.1
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

响应:

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

分页

如果返回的项数超过响应限制,则会对结果进行分页。 遵循可选的 Link 响应标头的要求,并使用 rel="next" 进行导航。 也可让内容以 @nextLink 属性的形式提供下一个链接。 链接的 URI 包含 api-version 参数。

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

响应:

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

筛选

支持组合使用 keylabel 筛选。 使用可选的 keylabel 查询字符串参数。

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

支持将 keylabeltags 组合起来用于筛选。 使用可选的 keylabeltags 查询字符串参数。 可以以 tagName=tagValue 格式提供多个标记筛选器作为查询字符串参数。 标记筛选器必须完全匹配。

GET /kv?key={key}&label={label}&tags={tagFilter1}&tags={tagFilter2}&api-version={api-version}

支持的筛选器

键筛选器 效果
省略 keykey=* 匹配任何键
key=abc 匹配名为“abc”的键
key=abc* 匹配以“abc”开头的键名称
key=abc,xyz 匹配键名称“abc”或“xyz”(限制为 5 个 CSV)
标签筛选器 效果
省略 labellabel=* 匹配任何标签
label=%00 匹配没有标签的键值
label=prod 匹配标签“prod”
label=prod* 匹配以“prod”开头的标签
label=prod,test 匹配标签“prod”或“test”(限制为 5 个 CSV)
标记筛选器 效果
省略 tagstags= 匹配任意标记
tags=group=app1 匹配包含名为 group 且值为 app1 的标记的键值
tags=group=app1&tags=env=prod 匹配包含名为 group 且值为 app1 的标记,以及名为 env 且值为 prod 的标记的键值(限制为 5 个标记筛选器)
tags=tag1=%00 匹配包含名为 tag1 且值为 null 的标记的键值
tags=tag1= 匹配包含名为 tag1 且值为空的标记的键值

保留字符

*, \, ,

如果保留字符是值的一部分,则必须使用 \{Reserved Character} 对其进行转义。 非保留字符也可以进行转义。

筛选器验证

如果筛选器验证失败,则响应为“HTTP 400”,其中包含以下错误详细信息:

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
}

示例

  • 全部

    GET /kv?api-version={api-version}
    
  • 键名称以“abc”开头,并且包括所有标签

    GET /kv?key=abc*&label=*&api-version={api-version}
    
  • 键名称以“abc”开头,并且标签等于“v1”或“v2”

    GET /kv?key=abc*&label=v1,v2&api-version={api-version}
    

请求特定的字段

使用可选的 $select 查询字符串参数,并提供逗号分隔的所请求字段列表。 如果省略 $select 参数,则响应会包含默认集。

GET /kv?$select=key,value&api-version={api-version} HTTP/1.1

基于时间的访问

获得结果在过去的表现形式。 有关详细信息,请参阅第 2.1.1 节。 如本文前面所述,仍支持分页。

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

响应:

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

设置键

  • 必需:{key}
  • 可选:label(如果未指定,或者 label=%00,则表示不带标签的键值。)
PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json
{
  "value": "example value",         // optional
  "content_type": "user defined",   // optional
  "tags": {                         // optional
    "tag1": "value1",
    "tag2": "value2",
  }
}

响应:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "key": "{key}",
  "label": "{label}",
  "content_type": "user defined",
  "value": "example value",
  "last_modified": "2017-12-05T02:41:26.4874615+00:00",
  "tags": {
    "tag1": "value1",
    "tag2": "value2",
  }
}

如果项目已锁定,则返回以下响应:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset="utf-8"
{
    "type": "https://azconfig.io/errors/key-locked",
    "title": "Modifing key '{key}' is not allowed",
    "name": "{key}",
    "detail": "The key is read-only. To allow modification unlock it first.",
    "status": 409
}

设置键(有条件)

若要防止出现争用情况,请使用 If-MatchIf-None-Match 请求标头。 etag 参数是键表示形式的一部分。 如果省略 If-MatchIf-None-Match,则该操作是无条件的。

仅在当前表示形式与指定的 etag 匹配时,才会更新以下响应:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

仅在当前表示形式与指定的 etag 不匹配时,才会更新以下响应:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json;
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

仅当表示形式已存在时,以下请求才会添加值:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json;
If-Match: "*"

仅当表示形式不存在时,以下请求才会添加值:

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json
If-None-Match: "*"

响应

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
...

HTTP/1.1 412 PreconditionFailed

删除

  • 必需:{key}{api-version}
  • 可选:{label}(如果未指定,或者 label=%00,则表示不带标签的键值。)
DELETE /kv/{key}?label={label}&api-version={api-version} HTTP/1.1

响应: 返回已删除的键值;如果键值不存在,则不返回任何内容。

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
...

HTTP/1.1 204 No Content

删除键(有条件)

这与本文前面的“设置密钥(有条件)”一节类似。