快照

项目
10/15/2024

快照资源在 API 版本 1.0 中不可用。

快照是由其名称唯一标识的资源。请查看每个操作的详细信息。

Operations

获取
列出多个
创建
存档/恢复
列出键值

必备条件

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

语法

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

通过

快照

Operations

必备条件

语法

获取快照

获取（有条件）

列出快照

筛选

支持的筛选器

请求特定的字段

创建快照

轮询快照创建

存档（修补程序）

恢复（修补程序）

存档/恢复快照（有条件）

列出快照键值

请求特定的字段

其他资源