Значения ключей

Статья
06/01/2023

"Ключ-значение" — это ресурс, определяемый уникальным сочетанием key + label. Аргумент label является необязательным. Чтобы явно ссылаться на пару "ключ-значение" без метки, используйте "\0" (URL-адрес в кодировке %00). См. информацию для каждой операции.

Эта статья относится к API версии 1.0.

Operations

Получить
Вывод списка из нескольких значений
Присвойте параметру
Удалить

Предварительные требования

Все 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`	Совпадает с меткой prod
`label=prod*`	Совпадает с метками, которые начинаются с prod
`label=prod,test`	Совпадает с метками 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
}

Примеры

Все
```
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

Предварительные требования

Синтаксис

Получить "ключ-значение"

Получить (условно)

Вывод списка пар "ключ-значение"

Фильтрация

Поддерживаемые фильтры

Поля со сведениями о запросах

Доступ на основе времени

Задать ключ

Задать ключ (условно)

Удалить

Удалить ключ (условно)

Дополнительные ресурсы