快照式

發行項
08/10/2024

API 1.0 版中無法使用快照集資源。

快照集是依其名稱唯一識別的資源。請參閱每個作業的詳細數據。

Operations

取得 Yammer
列出多個
建立
封存/復原
列出索引鍵/值

必要條件

所有 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}"
}

篩選

支援和 status 篩選的組合name。使用選擇性 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	是	n/a	長度最大值：256
篩選	是	n/a	Count 最小值：1 最大值：3
filters[<index>].key	是	n/a
filters[<index>].label	否	null	多重比對標籤篩選條件（例如：“*”、“逗號、分隔”）不支援 'key' 組合類型。
tags	否	{}
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	是	n/a	長度最大值：256
篩選	是	n/a	Count 最小值：1 最大值：3
filters[<index>].key	是	n/a
filters[<index>].label	否	null	多重比對標籤篩選條件（例如：“*”、“逗號、分隔”）不支援 'key' 組合類型。
filters[<index>].tags	否	null	Count 最小值：0 最大值：5
tags	否	{}
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-LocationURI 中找到。用戶端可以輪詢此狀態物件，以確保快照集已布建，再列出其相關聯的索引鍵/值。

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

封存目前處於或 failed 狀態的provisioning快照集是無效的作業。

回應：

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

復原目前處於或 failed 狀態的provisioning快照集是無效的作業。

回應：

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

必要條件

語法

取得快照集

取得（有條件地）

列出快照集

篩選

支援的篩選器

要求特定欄位

建立快照集

輪詢快照集建立

封存（修補程式）

復原（修補程式）

封存/復原快照集（有條件地）

列出快照集索引鍵/值

要求特定欄位

意見反應

其他資源

共用方式為

快照式

Operations

必要條件

語法

取得快照集

取得 （有條件地）

列出快照集

分頁

篩選

支援的篩選器

要求特定欄位

建立快照集

輪詢快照集建立

封存 （修補程式）

復原 （修補程式）

封存/復原快照集 （有條件地）

列出快照集索引鍵/值

要求特定欄位

意見反應

其他資源

取得（有條件地）

封存（修補程式）

復原（修補程式）

封存/復原快照集（有條件地）