快照

快照资源在 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-MatchIf-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}"
}

筛选

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

GET /snapshots?name={name}&status={status}&api-version={api-version}

支持的筛选器

名称筛选器 效果
省略 namename=* 匹配任何名称的快照
name=abc 匹配名称为 abc 的快照
name=abc* 匹配名称以 abc 开头的快照
name=abc,xyz 匹配名称为 abcxyz 的快照(仅限 5 个 CSV)
状态筛选器 效果
省略 statusstatus=* 匹配任何状态的快照
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"
}

存档当前处于 provisioningfailed 状态的快照是无效操作。

响应:

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",
  ...
}

恢复当前处于 provisioningfailed 状态的快照是无效操作。

响应:

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-MatchIf-None-Match 请求标头。 etag 参数是快照表示形式的一部分。 如果省略 If-MatchIf-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}

注意

尝试列出不处于 readyarchived 状态的快照项目将导致空列表响应。

请求特定的字段

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

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