索引鍵/值

發行項
08/10/2024

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

Operations

取得 Yammer
列出多個
設定
刪除

必要條件

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

選擇性： tags （如果未指定，則表示任何標記。

GET /kv?key=Test*&label=*&tags=tag1=value1&tags=tag2=value2&api-version={api-version} HTTP/1.1

回應：

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

如需更多選項，請參閱本文稍後的一節。

列出索引鍵/值（有條件地）

若要改善用戶端快取，請使用 If-Match 或 If-None-Match 要求標頭。自 etag 變數是清單索引鍵/值回應本文和標頭的一部分。如果 If-Match 省略或 If-None-Match ，則作業是無條件的。

只有在目前的表示法符合指定的 etag時，下列回應才會取得索引鍵/值：

GET /kv?key={key}&label={label}&api-version={api-version} HTTP/1.1
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

回應：

HTTP/1.1 412 PreconditionFailed

或

HTTP/1.1 200 OK

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

GET /kv?key={key}&label={label}&api-version={api-version} HTTP/1.1
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

回應：

HTTP/1.1 304 NotModified

或

HTTP/1.1 200 OK

分頁

如果傳回的項目數目超過回應限制，則會分頁結果。請遵循選擇性 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}"
}

篩選

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

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

支援、 label和 tags 篩選的組合key。使用選擇性 key、 label和 tags 查詢字串參數。您可以以格式提供多個標籤篩選作為查詢字串參數 tagName=tagValue 。標籤篩選必須是完全相符的。

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

支援的篩選器

金鑰篩選條件	效果
省略 `key` 或使用 `key=*`	比對任何索引鍵
`key=abc`	比對名為 abc 的金鑰
`key=abc*`	比對開頭為 abc 的索引鍵名稱
`key=abc,xyz`	比對金鑰名稱 abc 或 xyz （限制為 5 CSV）

標籤篩選	效果
省略 `label` 或使用 `label=*`	符合任何標籤
`label=%00`	比對沒有標籤的索引鍵/值
`label=prod`	符合標籤 Prod
`label=prod*`	比對以 prod 開頭的標籤
`label=prod,test`	比對標籤生產或測試（限制為 5 CSV）

標籤篩選	效果
省略 `tags` 或使用 `tags=`	比對任何標籤
`tags=group=app1`	比對索引鍵/值，其具有名為 `group` 且具有值的標籤 `app1`
`tags=group=app1&tags=env=prod`	比對索引鍵/值，其標籤具有值且`group`具有值`app1prod`且名為 `env` 的標籤（限制為 5 個標籤篩選）
`tags=tag1=%00`	比對索引鍵/值，其具有名為 `tag1` 且具有值的標籤 `null`
`tags=tag1=`	比對索引鍵/值，其具有空值的標記`tag1`

保留字元

*、、 \,

如果保留字元是值的一部分，則必須使用 \{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 /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

回應： 傳回已刪除的索引鍵/值，如果機碼值不存在，則傳回 none。

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

或

HTTP/1.1 204 No Content

刪除索引鍵（有條件地）

這類似於本文稍早的「設定索引鍵」一節。

共用方式為

索引鍵/值

Operations

必要條件

語法

取得索引鍵/值

取得（有條件地）

列出索引鍵/值

列出索引鍵/值（有條件地）

篩選

支援的篩選器

要求特定欄位

以時間為基礎的存取

設定索引鍵

設定索引鍵（有條件地）

刪除

刪除索引鍵（有條件地）

意見反應

其他資源

共用方式為

索引鍵/值

Operations

必要條件

語法

取得索引鍵/值

取得 （有條件地）

列出索引鍵/值

列出索引鍵/值（有條件地）

分頁

篩選

支援的篩選器

要求特定欄位

以時間為基礎的存取

設定索引鍵

設定索引鍵 （有條件地）

刪除

刪除索引鍵 （有條件地）

意見反應

其他資源

取得（有條件地）

設定索引鍵（有條件地）

刪除索引鍵（有條件地）