共用方式為


快照式

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

本文適用于 API 版本 2022-11-01-preview。

Operations

  • Get
  • 列出多個
  • 建立
  • 封存/復原
  • 列出索引鍵/值

必要條件

語法

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

取得快照集

必要: {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}"
}

篩選

支援 和 status 篩選的組合 name 。 使用選擇性 namestatus 查詢字串參數。

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 計數
     最小值:1
     最大值:3
filters[ < index > ].key n/a
tags {}
filters[ < index > ].label null 'key' 組合類型不支援多重比對標籤篩選準則(例如:「*」、「逗號、分隔」。
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": {                           // 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
}

新建立快照集的狀態將會是「布建」。 完整布建快照集之後,狀態會更新為「就緒」。 用戶端可以輪詢快照集,等待快照集準備好,再列出其相關聯的索引鍵/值。 若要查詢作業的其他資訊,請參考 輪詢快照集建立 區段。

如果快照集已經存在,您將會收到下列回應:

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

封存目前處於 或 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-MatchIf-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}

注意

嘗試列出不在 readyarchived 狀態的快照集專案,將會產生空的清單回應。

要求特定欄位

使用選擇性 $select 的查詢字串參數,並提供以逗號分隔的要求欄位清單。 $select如果省略 參數,回應會包含預設集合。

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