快照
快照资源在 API 版本 1.0 中不可用。
快照是由其名称唯一标识的资源。 请查看每个操作的详细信息。
Operations
- 获取
- 列出多个
- 创建
- 存档/恢复
- 列出键值
必备条件
语法
Snapshot
{
"etag": [string],
"name": [string],
"status": [string, enum("provisioning", "ready", "archived", "failed")],
"filters": [array<SnapshotFilter>],
"composition_type": [string, enum("key", "key_label")],
"created": [datetime ISO 8601],
"size": [number, bytes],
"items_count": [number],
"tags": [object with string properties],
"retention_period": [number, timespan in seconds],
"expires": [datetime ISO 8601]
}
SnapshotFilter
{
"key": [string],
"label": [string]
}
{
"key": [string],
"label": [string],
"tags": [array<string>]
}
获取快照
必需:{name}
、{api-version}
GET /snapshots/{name}?api-version={api-version}
响应:
HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
Last-Modified: Mon, 03 Mar 2023 9:00:03 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
Link: </kv?snapshot=prod-2023-03-20&api-version={api-version}>; rel="items"
{
"etag": "4f6dd610dd5e4deebc7fbaef685fb903",
"name": "prod-2023-03-20",
"status": "ready",
"filters": [
{
"key": "*",
"label": null
}
],
"composition_type": "key",
"created": "2023-03-20T21:00:03+00:00",
"size": 2000,
"items_count": 4,
"tags": {
"t1": "value1",
"t2": "value2"
},
"retention_period": 7776000
}
如果不存在具有所提供名称的快照,则将返回以下响应:
HTTP/1.1 404 Not Found
获取(有条件)
若要改善客户端缓存,请使用 If-Match
或 If-None-Match
请求标头。 etag
参数是快照表示形式的一部分。 有关详细信息,请参阅第 14.24 和 14.26节。
仅在当前表示形式与指定的 etag
不匹配时,以下请求才会检索快照:
GET /snapshot/{name}?api-version={api-version} HTTP/1.1
Accept: application/vnd.microsoft.appconfig.snapshot+json;
If-None-Match: "{etag}"
响应:
HTTP/1.1 304 NotModified
或
HTTP/1.1 200 OK
列出快照
可选:name
(如果未指定,则表示任意名称。)可选:status
(如果未指定,则表示任意状态。)
GET /snapshots?name=prod-*&api-version={api-version} HTTP/1.1
响应:
HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshotset+json; charset=utf-8
有关更多选项,请参阅本文后面的“筛选”一节。
分页
如果返回的项数超过响应限制,则会对结果进行分页。 遵循可选的 Link
响应标头的要求,并使用 rel="next"
进行导航。
也可让内容以 @nextLink
属性的形式提供下一个链接。 链接的 URI 包含 api-version
参数。
GET /snapshots?api-version={api-version} HTTP/1.1
响应:
HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshotset+json; charset=utf-8
Link: <{relative uri}>; rel="next"
{
"items": [
...
],
"@nextLink": "{relative uri}"
}
筛选
支持组合使用 name
和 status
筛选。
使用可选的 name
和 status
查询字符串参数。
GET /snapshots?name={name}&status={status}&api-version={api-version}
支持的筛选器
名称筛选器 | 效果 |
---|---|
省略 name 或 name=* |
匹配任何名称的快照 |
name=abc |
匹配名称为 abc 的快照 |
name=abc* |
匹配名称以 abc 开头的快照 |
name=abc,xyz |
匹配名称为 abc 或 xyz 的快照(仅限 5 个 CSV) |
状态筛选器 | 效果 |
---|---|
省略 status 或 status=* |
匹配任何状态的快照 |
status=ready |
匹配就绪状态的快照 |
status=ready,archived |
匹配就绪或已存档状态的快照(仅限 5 个 CSV) |
保留字符
*
, \
, ,
如果保留字符是值的一部分,则必须使用 \{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 /snapshots?api-version={api-version}
快照名称以 abc 开头
GET /snapshot?name=abc*&api-version={api-version}
快照名称以 abc 开头,状态等效于就绪或已存档
GET /snapshot?name=abc*&status=ready,archived&api-version={api-version}
请求特定的字段
使用可选的 $select
查询字符串参数,并提供逗号分隔的所请求字段列表。 如果省略 $select
参数,则响应会包含默认集。
GET /snapshot?$select=name,status&api-version={api-version} HTTP/1.1
创建快照
parameters
属性名称 | 必选 | 默认值 | 验证 |
---|---|---|---|
name | 是 | 不适用 | Length 最大值:256 |
筛选器 | 是 | 不适用 | 计数 最小值:1 最大值:3 |
filters[<index>].key | 是 | 不适用 | |
filters[<index>].label | 否 | Null | “键”组合类型不支持多匹配标签筛选器(例如:“*”、“逗号分隔”)。 |
标记 | 否 | {} | |
composition_type | 否 | key | |
retention_period | 否 | 标准层 2592000(30 天) 免费层 604800(七天) |
标准层 最小值:3600(一小时) 最大值:7776000(90 天) 免费层 最小值:3600(一小时) 最大值:604800(七天) |
PUT /snapshot/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
{
"filters": [ // required
{
"key": "app1/*", // required
"label": "prod" // optional
}
],
"tags": { // optional
"tag1": "value1",
"tag2": "value2",
},
"composition_type": "key", // optional
"retention_period": 2592000 // optional
}
响应:
HTTP/1.1 201 Created
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}
{
"etag": "4f6dd610dd5e4deebc7fbaef685fb903",
"name": "{name}",
"status": "provisioning",
"filters": [
{
"key": "app1/*",
"label": "prod"
}
],
"composition_type": "key",
"created": "2023-03-20T21:00:03+00:00",
"size": 2000,
"items_count": 4,
"tags": {
"t1": "value1",
"t2": "value2"
},
"retention_period": 2592000
}
属性名称 | 必选 | 默认值 | 验证 |
---|---|---|---|
name | 是 | 不适用 | Length 最大值:256 |
筛选器 | 是 | 不适用 | 计数 最小值:1 最大值:3 |
filters[<index>].key | 是 | 不适用 | |
filters[<index>].label | 否 | Null | “键”组合类型不支持多匹配标签筛选器(例如:“*”、“逗号分隔”)。 |
filters[<index>].tags | 否 | Null | 计数 最小值:0 最大值:5 |
标记 | 否 | {} | |
composition_type | 否 | key | |
retention_period | 否 | 标准层 2592000(30 天) 免费层 604800(7 天) |
标准层 最小值:3600(1 小时) 最大值:7776000(90 天) 免费层 最小值:3600(1 小时) 最大值:604800(7 天) |
PUT /snapshot/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
{
"filters": [ // required
{
"key": "app1/*", // required
"label": "prod", // optional
"tags": ["group=g1", "default=true"] // optional
}
],
"tags": { // optional
"tag1": "value1",
"tag2": "value2",
},
"composition_type": "key", // optional
"retention_period": 2592000 // optional
}
响应:
HTTP/1.1 201 Created
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}
{
"etag": "4f6dd610dd5e4deebc7fbaef685fb903",
"name": "{name}",
"status": "provisioning",
"filters": [
{
"key": "app1/*",
"label": "prod",
"tags": ["group=g1", "default=true"]
}
],
"composition_type": "key",
"created": "2023-03-20T21:00:03+00:00",
"size": 2000,
"items_count": 4,
"tags": {
"t1": "value1",
"t2": "value2"
},
"retention_period": 2592000
}
新创建的快照的状态为 provisioning
。
完全预配快照后,该状态更新为 ready
。
客户端可以轮询快照,等待快照准备就绪,然后列出其关联的键值。
若要查询有关操作的其他信息,请参阅轮询快照创建部分。
如果快照已存在,则返回以下响应:
HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset=utf-8
{
"type": "https://azconfig.io/errors/already-exists",
"title": "The resource already exists.",
"status": 409,
"detail": ""
}
轮询快照创建
快照创建请求的响应将返回 Operation-Location
标头。
响应:
HTTP/1.1 201 Created
...
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}
可以在 Operation-Location
中包含的 URI 中找到快照配置操作的状态。
客户端可以轮询此状态对象,以确保在列出其关联的键值之前预配快照。
GET {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}
响应:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"id": "{id}",
"status": "Succeeded",
"error": null
}
如果在预配快照期间发生任何错误,则 error
属性包含描述该错误的详细信息。
{
"id": "{name}",
"status": "Failed",
"error": {
"code": "QuotaExceeded",
"message": "The allotted quota for snapshot creation has been surpassed."
}
}
存档(修补程序)
可以存档处于 ready
状态的快照。
根据创建存档快照时确定的保持期,为其分配一个到期日期。
到期日期过后,快照将被永久删除。
在到期日期之前,仍可随时列出快照的项目。
存档已 archived
的快照不会对其产生影响。
- 要求:
{name}
、{status}
、{api-version}
PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
{
"status": "archived"
}
响应:返回存档快照
HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
...
{
"etag": "33a0c9cdb43a4c2cb5fc4c1feede1c68",
"name": "{name}",
"status": "archived",
...
"expires": "2023-08-11T21:00:03+00:00"
}
存档当前处于 provisioning
或 failed
状态的快照是无效操作。
响应:
HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset="utf-8"
{
"type": "https://azconfig.io/errors/invalid-state",
"title": "Target resource state invalid.",
"detail": "The target resource is not in a valid state to perform the requested operation.",
"status": 409
}
恢复(修补程序)
可以恢复处于 archived
状态的快照。
恢复快照后,快照的到期日期将被删除。
存档已 ready
的快照不会对其产生影响。
- 要求:
{name}
、{status}
、{api-version}
PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
{
"status": "ready"
}
响应:返回恢复的快照
HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
...
{
"etag": "90dd86e2885440f3af9398ca392095b9",
"name": "{name}",
"status": "ready",
...
}
恢复当前处于 provisioning
或 failed
状态的快照是无效操作。
响应:
HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset="utf-8"
{
"type": "https://azconfig.io/errors/invalid-state",
"title": "Target resource state invalid.",
"detail": "The target resource is not in a valid state to perform the requested operation.",
"status": 409
}
存档/恢复快照(有条件)
若要防止出现争用情况,请使用 If-Match
或 If-None-Match
请求标头。 etag
参数是快照表示形式的一部分。
如果省略 If-Match
或 If-None-Match
,则该操作是无条件的。
仅在当前表示形式与指定的 etag
匹配时,以下响应才会更新资源:
PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"
仅在当前表示形式与指定的 etag
不匹配时,以下响应才会更新资源:
PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json;
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"
响应
HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
...
或
HTTP/1.1 412 PreconditionFailed
列出快照键值
必需:{name}
、{api-version}
GET /kv?snapshot={name}&api-version={api-version}
注意
尝试列出不处于 ready
或 archived
状态的快照项目将导致空列表响应。
请求特定的字段
使用可选的 $select
查询字符串参数,并提供逗号分隔的所请求字段列表。 如果省略 $select
参数,则响应会包含默认集。
GET /kv?snapshot={name}&$select=key,value&api-version={api-version} HTTP/1.1