Klucze/wartości

Artykuł
08/10/2024

Klucz-wartość to zasób identyfikowany przez unikatową kombinację .key + label Element label jest opcjonalny. Aby jawnie odwołać się do wartości klucza bez etykiety, użyj ciągu "\0" (zakodowanego jako adres URL).%00 Zobacz szczegóły każdej operacji.

Operacje

Get
Lista wielu
Zestaw
Delete

Wymagania wstępne

Wszystkie żądania HTTP muszą być uwierzytelnione. Zobacz sekcję uwierzytelniania .
Wszystkie żądania HTTP muszą podać jawne api-version. Zobacz sekcję przechowywanie wersji.

Składnia

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

Uzyskiwanie wartości klucza

Wymagane: {key}, {api-version}
Opcjonalnie: label (Jeśli pominięto, oznacza to klucz-wartość bez etykiety).

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

Odpowiedzi:

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

Jeśli klucz nie istnieje, zostanie zwrócona następująca odpowiedź:

HTTP/1.1 404 Not Found

Pobieranie (warunkowo)

Aby ulepszyć buforowanie klienta, użyj If-Match nagłówków lub If-None-Match żądań. Argument etag jest częścią reprezentacji klucza. Aby uzyskać więcej informacji, zobacz sekcje 14.24 i 14.26.

Następujące żądanie pobiera wartość klucza tylko wtedy, gdy bieżąca reprezentacja nie jest zgodna z określoną wartością etag:

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

Odpowiedzi:

HTTP/1.1 304 NotModified

lub

HTTP/1.1 200 OK

Wyświetlanie listy par klucz-wartości

Opcjonalnie: key (Jeśli nie zostanie określony, oznacza to dowolny klucz).

Opcjonalnie: label (Jeśli nie zostanie określony, oznacza to dowolną etykietę).

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

Odpowiedź:

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

Opcjonalnie: tags (Jeśli nie zostanie określony, oznacza to jakiekolwiek tagi).

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

Odpowiedź:

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

Aby uzyskać więcej opcji, zobacz sekcję "Filtrowanie" w dalszej części tego artykułu.

Wyświetlanie listy wartości klucza (warunkowo)

Aby ulepszyć buforowanie klienta, użyj If-Match nagłówków lub If-None-Match żądań. Argument etag jest częścią treści odpowiedzi i nagłówka odpowiedzi klucz-wartości listy. Jeśli If-Match operacja zostanie pominięta, If-None-Match operacja jest bezwarunkowa.

Następująca odpowiedź pobiera wartość klucza tylko wtedy, gdy bieżąca reprezentacja jest zgodna z określoną wartością etag:

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

Odpowiedzi:

HTTP/1.1 412 PreconditionFailed

lub

HTTP/1.1 200 OK

Następująca odpowiedź pobiera wartości klucza tylko wtedy, gdy bieżąca reprezentacja nie jest zgodna z określoną wartością etag:

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

Odpowiedzi:

HTTP/1.1 304 NotModified

lub

HTTP/1.1 200 OK

Podział na strony

Wynik jest podzielony na strony, jeśli liczba zwracanych elementów przekracza limit odpowiedzi. Postępuj zgodnie z opcjonalnymi Link nagłówkami odpowiedzi i użyj ich rel="next" do nawigacji. Alternatywnie zawartość udostępnia następny link w postaci @nextLink właściwości. Połączony identyfikator URI zawiera api-version argument .

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

Odpowiedź:

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

Filtrowanie

Obsługiwana jest kombinacja key i label filtrowanie. Użyj opcjonalnych key parametrów ciągu zapytania i label .

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

Obsługiwana jest kombinacja funkcji key, labeli tags filtrowania. Użyj opcjonalnych keyparametrów ciągu , labeli tags ciągu zapytania. W formacie można podać wiele filtrów tagów jako parametry tagName=tagValue ciągu zapytania. Filtry tagów muszą być dokładnie zgodne.

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

Obsługiwane filtry

Filtr klucza	Efekt
Element `key` jest pomijany lub `key=*`	Pasuje do dowolnego klucza
`key=abc`	Pasuje do klucza o nazwie abc
`key=abc*`	Pasuje do nazw kluczy rozpoczynających się od abc
`key=abc,xyz`	Pasuje do nazw kluczy abc lub xyz (ograniczony do 5 CSV)

Filtr etykiet	Efekt
Element `label` jest pomijany lub `label=*`	Pasuje do dowolnej etykiety
`label=%00`	Dopasuje wartości klucz-wartość bez etykiety
`label=prod`	Pasuje do etykiety prod
`label=prod*`	Dopasuj etykiety rozpoczynające się od prod
`label=prod,test`	Dopasuj etykiety prod lub test (ograniczone do 5 CSV)

Filtr tagów	Efekt
Element `tags` jest pomijany lub `tags=`	Pasuje do dowolnego tagu
`tags=group=app1`	Pasuje do wartości klucz-, które mają tag o nazwie `group` z wartością `app1`
`tags=group=app1&tags=env=prod`	Pasuje do wartości klucz-, które mają tag o nazwie `group` z wartością `app1` i tag o nazwie `env` z wartością `prod`(ograniczone do 5 filtrów tagów)
`tags=tag1=%00`	Pasuje do wartości klucz-, które mają tag o nazwie `tag1` z wartością `null`
`tags=tag1=`	Pasuje do wartości klucz-, które mają tag o nazwie `tag1` z pustą wartością

Zastrzeżone znaki

*, , \,

Jeśli zastrzeżony znak jest częścią wartości, należy go uniknić za pomocą polecenia \{Reserved Character}. Znaki inne niż zastrzeżone mogą być również ucieczki.

Walidacja filtru

Jeśli sprawdzanie poprawności filtru zakończy się niepowodzeniem, odpowiedź to HTTP 400 ze szczegółami błędu:

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
}

Przykłady

wszystkie
```
GET /kv?api-version={api-version}
```
Nazwa klucza zaczyna się od abc i zawiera wszystkie etykiety
```
GET /kv?key=abc*&label=*&api-version={api-version}
```
Nazwa klucza zaczyna się od abc i etykieta jest równa v1 lub v2
```
GET /kv?key=abc*&label=v1,v2&api-version={api-version}
```

Żądanie określonych pól

Użyj opcjonalnego $select parametru ciągu zapytania i podaj rozdzielaną przecinkami listę żądanych pól. $select Jeśli parametr zostanie pominięty, odpowiedź zawiera zestaw domyślny.

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

Dostęp oparty na czasie

Uzyskaj reprezentację wyniku w przeszłości. Aby uzyskać więcej informacji, zobacz sekcję 2.1.1. Stronicowanie jest nadal obsługiwane zgodnie z definicją wcześniej w tym artykule.

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

Odpowiedź:

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": [
        ....
    ]
}

Ustaw klucz

Wymagane: {key}
Opcjonalnie: label (Jeśli nie określono etykiety lub label=%00, oznacza to klucz-wartość bez etykiety).

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

Odpowiedzi:

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

Jeśli element jest zablokowany, zostanie zwrócona następująca odpowiedź:

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
}

Ustawianie klucza (warunkowo)

Aby zapobiec warunkom wyścigu, użyj If-Match nagłówków lub If-None-Match zażądaj. Argument etag jest częścią reprezentacji klucza. Jeśli If-Match operacja zostanie pominięta, If-None-Match operacja jest bezwarunkowa.

Następująca odpowiedź aktualizuje wartość tylko wtedy, gdy bieżąca reprezentacja jest zgodna z określoną wartością etag:

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

Następująca odpowiedź aktualizuje wartość tylko wtedy, gdy bieżąca reprezentacja nie jest zgodna z określoną wartością 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"

Następujące żądanie dodaje wartość tylko wtedy, gdy reprezentacja już istnieje:

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

Następujące żądanie dodaje wartość tylko wtedy, gdy reprezentacja jeszcze nie istnieje:

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

Odpowiedzi

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

lub

HTTP/1.1 412 PreconditionFailed

Delete

Wymagane: {key}, {api-version}
Opcjonalnie: {label} (Jeśli nie określono etykiety lub label=%00, oznacza to klucz-wartość bez etykiety).

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

Odpowiedź: Zwróć usuniętą wartość klucza lub brak, jeśli wartość klucza nie istnieje.

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

lub

HTTP/1.1 204 No Content

Usuwanie klucza (warunkowo)

Jest to podobne do sekcji "Ustaw klucz (warunkowo)" we wcześniejszej części tego artykułu.

Udostępnij za pośrednictwem

Klucze/wartości

Operacje

Wymagania wstępne

Składnia

Uzyskiwanie wartości klucza

Pobieranie (warunkowo)

Wyświetlanie listy par klucz-wartości

Wyświetlanie listy wartości klucza (warunkowo)

Filtrowanie

Obsługiwane filtry

Żądanie określonych pól

Dostęp oparty na czasie

Ustaw klucz

Ustawianie klucza (warunkowo)

Delete

Usuwanie klucza (warunkowo)

Opinia

Dodatkowe zasoby