索引鍵/值

發行項
06/01/2023

索引鍵/值是由唯一 key + label 組合所識別的資源。 label 是選擇性的。若要明確參考沒有標籤的索引鍵/值，請使用 "\0" (編碼為 %00 的 URL)。請參閱每個作業的詳細資料。

本發行項適用於 API 版本 1.0。

Operations

Get
列出多個
設定
刪除

必要條件

必須驗證所有 HTTP 要求。請參閱驗證區段。
所有 HTTP 要求都必須提供明確的 api-version。請參閱版本設定區段。

語法

{
  "etag": [string],
  "key": [string],
  "label": [string, optional],
  "content_type": [string, optional],
  "value": [string],
  "last_modified": [datetime ISO 8601],
  "locked": [boolean],
  "tags": [object with string properties, optional]
}

取得索引鍵/值

必要：{key}、{api-version}
選擇性：label (如果省略，則意指沒有標籤的索引鍵/值。)

GET /kv/{key}?label={label}&api-version={api-version}

回應：

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8;
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "key": "{key}",
  "label": "{label}",
  "content_type": null,
  "value": "example value",
  "last_modified": "2017-12-05T02:41:26+00:00",
  "locked": "false",
  "tags": {
    "t1": "value1",
    "t2": "value2"
  }
}

如果索引鍵不存在，則會傳回下列回應：

HTTP/1.1 404 Not Found

取得 (有條件地)

若要改善用戶端快取，請使用 If-Match 或 If-None-Match 要求標頭。 etag 引數是索引鍵表示法的一部分。如需詳細資訊，請參閱 14.24 和 14.26 章節。

只有當目前的表示法不符合指定的 etag 時，下列要求才會擷取索引鍵/值：

GET /kv/{key}?api-version={api-version} HTTP/1.1
Accept: application/vnd.microsoft.appconfig.kv+json;
If-None-Match: "{etag}"

回應：

HTTP/1.1 304 NotModified

或

HTTP/1.1 200 OK

列出索引鍵/值

選擇性：key (若未指定，則意指任何索引鍵。) 選擇性：label (若未指定，則意指任何標籤。)

GET /kv?label=*&api-version={api-version} HTTP/1.1

回應：

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvset+json; charset=utf-8

如需其他選項，請參閱本文後面的「篩選」一節。

分頁

如果傳回的項目數量超過回應限制，結果則會分頁。遵循選用 Link 回應標頭，並使用 rel="next" 瀏覽。或者，內容會以 @nextLink 屬性表單提供下一個連結。連結的 URI 包含 api-version 引數。

GET /kv?api-version={api-version} HTTP/1.1

回應：

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvs+json; charset=utf-8
Link: <{relative uri}>; rel="next"

{
    "items": [
        ...
    ],
    "@nextLink": "{relative uri}"
}

篩選

支援 key 和 label 篩選的組合。使用選用的 key 和 label 查詢字串參數。

GET /kv?key={key}&label={label}&api-version={api-version}

支援的篩選器

金鑰篩選條件	效果
省略 `key` 或使用 `key=*`	符合任何金鑰
`key=abc`	符合具名 abc 的金鑰
`key=abc*`	符合以 abc 開頭的金鑰名稱
`key=abc,xyz`	符合金鑰名稱 abc 或 xyz (限制為 5 個 CSV)

標籤篩選條件	效果
省略 `label` 或使用 `label=*`	符合任何標籤
`label=%00`	比對不含標籤的 KV
`label=prod`	符合標籤產品
`label=prod*`	符合以產品開頭的標籤
`label=prod,test`	符合標籤產品或測試 (限制為 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
}

範例

All
```
GET /kv?api-version={api-version}
```

索引鍵名稱開頭為 abc並包含所有標籤

GET /kv?key=abc*&label=*&api-version={api-version}

索引鍵名稱開頭為 abc，且標籤等於 v1 或 v2

GET /kv?key=abc*&label=v1,v2&api-version={api-version}

要求特定欄位

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

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

限時型存取

獲取過去時間的結果表示法。如需詳細資訊，請參閱 2.1.1 章節。如本文稍早所定義，仍可支援分頁。

GET /kv?api-version={api-version} HTTP/1.1
Accept-Datetime: Sat, 12 May 2018 02:10:00 GMT

回應：

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kvset+json"
Memento-Datetime: Sat, 12 May 2018 02:10:00 GMT
Link: <{relative uri}>; rel="original"

{
    "items": [
        ....
    ]
}

設定索引鍵

必要：{key}
選擇性：label (若未指定，或 label=%00，則意指沒有標籤的索引鍵/值。)

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json

{
  "value": "example value",         // optional
  "content_type": "user defined",   // optional
  "tags": {                         // optional
    "tag1": "value1",
    "tag2": "value2",
  }
}

回應：

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "key": "{key}",
  "label": "{label}",
  "content_type": "user defined",
  "value": "example value",
  "last_modified": "2017-12-05T02:41:26.4874615+00:00",
  "tags": {
    "tag1": "value1",
    "tag2": "value2",
  }
}

若已鎖定項目，您會收到下列回應：

HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset="utf-8"

{
    "type": "https://azconfig.io/errors/key-locked",
    "title": "Modifing key '{key}' is not allowed",
    "name": "{key}",
    "detail": "The key is read-only. To allow modification unlock it first.",
    "status": 409
}

設定索引鍵 (有條件地)

若要防止競爭條件，請使用 If-Match 或 If-None-Match 要求標頭。 etag 引數是機碼表示法的一部分。如果省略 If-Match 或 If-None-Match，則作業是無條件的。

只有在目前的表示法符合指定的 etag 時，下列回應才會更新值：

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

只有在目前的表示法不符合指定的 etag 時，下列回應才會更新值：

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json;
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

只有在表示法已經存在時，下列要求才會新增值：

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json;
If-Match: "*"

只有在表示法尚未存在時，下列要求才會新增值：

PUT /kv/{key}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.kv+json
If-None-Match: "*"

回應

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
...

或

HTTP/1.1 412 PreconditionFailed

刪除

必要：{key}、{api-version}
選擇性：{label} (若未指定，或 label=%00，則意指沒有標籤的索引鍵/值。)

DELETE /kv/{key}?label={label}&api-version={api-version} HTTP/1.1

回應：傳回已刪除的索引鍵/值，如果索引鍵/值不存在，則不會傳回任何資料。

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.kv+json; charset=utf-8
...

或

HTTP/1.1 204 No Content

刪除索引鍵 (有條件地)

這類似於本文稍早的「設定索引鍵 (有條件地)」一節。

共用方式為

索引鍵/值

Operations

必要條件

語法

取得索引鍵/值

取得 (有條件地)

列出索引鍵/值

篩選

支援的篩選器

要求特定欄位

限時型存取

設定索引鍵

設定索引鍵 (有條件地)

刪除

刪除索引鍵 (有條件地)

意見反應

意見反應

其他資源