Nyckelvärden

Artikel
08/10/2024

Ett nyckelvärde är en resurs som identifieras med en unik kombination av key + label. label är valfritt. Om du uttryckligen vill referera till ett nyckelvärde utan etikett använder du "\0" (URL-kodad som %00). Se information för varje åtgärd.

Operations

Hämta
Visa en lista över flera
Ställ in
Delete

Förutsättningar

Alla HTTP-begäranden måste autentiseras. Se avsnittet autentisering.
Alla HTTP-begäranden måste ange explicit api-version. Se avsnittet versionshantering.

Syntax

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

Hämta nyckelvärde

Krävs: {key}, {api-version}
Valfritt: label (Om det utelämnas innebär det ett nyckelvärde utan etikett.)

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

Svaren:

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

Om nyckeln inte finns returneras följande svar:

HTTP/1.1 404 Not Found

Hämta (villkorligt)

För att förbättra klientcachelagring använder If-Match du eller If-None-Match begär rubriker. Argumentet etag är en del av nyckelrepresentationen. Mer information finns i avsnitten 14.24 och 14.26.

Följande begäran hämtar endast nyckelvärdet om den aktuella representationen inte matchar den angivna etag:

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

Svaren:

HTTP/1.1 304 NotModified

eller

HTTP/1.1 200 OK

Lista nyckelvärden

Valfritt: key (Om det inte anges innebär det någon nyckel.)

Valfritt: label (Om det inte anges innebär det någon etikett.)

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

Svar:

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

Valfritt: tags (Om det inte anges innebär det några taggar.)

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

Svar:

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

Fler alternativ finns i avsnittet "Filtrering" senare i den här artikeln.

Lista nyckelvärden (villkorsstyrt)

För att förbättra klientcachelagring använder If-Match du eller If-None-Match begär rubriker. Argumentet etag är en del av svarstexten och huvudet för nyckelvärden i listan. Om If-Match eller If-None-Match utelämnas är åtgärden ovillkorlig.

Följande svar hämtar endast nyckelvärdet om den aktuella representationen matchar den angivna etag:

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

Svaren:

HTTP/1.1 412 PreconditionFailed

eller

HTTP/1.1 200 OK

Följande svar hämtar endast nyckelvärdena om den aktuella representationen inte matchar den angivna etag:

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

Svaren:

HTTP/1.1 304 NotModified

eller

HTTP/1.1 200 OK

Sidnumrering

Resultatet sidnumreras om antalet returnerade objekt överskrider svarsgränsen. Följ de valfria Link svarshuvudena och använd rel="next" för navigering. Alternativt tillhandahåller innehållet en nästa länk i form av @nextLink egenskapen. Den länkade URI:n api-version innehåller argumentet.

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

Svar:

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

Filtrering

En kombination av key och label filtrering stöds. Använd parametrarna för valfria key strängar och label frågesträngar.

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

En kombination av key, labeloch tags filtrering stöds. Använd parametrarna för valfria key, labeloch tags frågesträngar. Flera taggfilter kan anges som frågesträngsparametrar i tagName=tagValue formatet. Taggfilter måste vara en exakt matchning.

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

Filter som stöds

Nyckelfilter	Effekt
`key` utelämnas eller `key=*`	Matchar valfri nyckel
`key=abc`	Matchar en nyckel med namnet abc
`key=abc*`	Matchar nycklar som börjar med abc
`key=abc,xyz`	Matchar nycklarnas namn abc eller xyz (begränsat till 5 CSV)

Etikettfilter	Effekt
`label` utelämnas eller `label=*`	Matchar valfri etikett
`label=%00`	Matchar nyckelvärden utan etikett
`label=prod`	Matchar etikettprod
`label=prod*`	Matchar etiketter som börjar med prod
`label=prod,test`	Matchar etiketter prod eller test (begränsat till 5 CSV)

Filter för taggar	Effekt
`tags` utelämnas eller `tags=`	Matchar valfri tagg
`tags=group=app1`	Matchar nyckelvärden som har en tagg med namnet `group` med värdet `app1`
`tags=group=app1&tags=env=prod`	Matchar nyckelvärden som har en tagg med namnet `group` med värdet `app1` och en tagg med namnet `env` med värdet `prod`(begränsad till 5 taggfilter)
`tags=tag1=%00`	Matchar nyckelvärden som har en tagg med namnet `tag1` med värdet `null`
`tags=tag1=`	Matchar nyckelvärden som har en tagg med namnet `tag1` med ett tomt värde

Reserverade tecken

*, , \,

Om ett reserverat tecken är en del av värdet måste det kringgås med hjälp \{Reserved Character}av . Icke-reserverade tecken kan också undantagas.

Filterverifiering

Om filterverifieringen misslyckas är svaret HTTP 400 med felinformation:

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
}

Exempel

Alla
```
GET /kv?api-version={api-version}
```
Nyckelnamnet börjar med abc och innehåller alla etiketter
```
GET /kv?key=abc*&label=*&api-version={api-version}
```
Nyckelnamnet börjar med abc och etiketten är lika med v1 eller v2
```
GET /kv?key=abc*&label=v1,v2&api-version={api-version}
```

Begär specifika fält

Använd den valfria frågesträngsparametern $select och ange en kommaavgränsad lista över begärda fält. Om parametern $select utelämnas innehåller svaret standarduppsättningen.

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

Tidsbaserad åtkomst

Hämta en representation av resultatet som det var vid en tidigare tidpunkt. Mer information finns i avsnitt 2.1.1. Sidnumrering stöds fortfarande enligt definitionen tidigare i den här artikeln.

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

Svar:

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

Ange nyckel

Krävs: {key}
Valfritt: label (Om det inte anges, eller label=%00, innebär det nyckelvärde utan etikett.)

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

Svaren:

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

Om objektet är låst returneras följande svar:

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
}

Ange nyckel (villkorligt)

För att förhindra tävlingsvillkor använder If-Match du eller If-None-Match begär rubriker. Argumentet etag är en del av nyckelrepresentationen. Om If-Match eller If-None-Match utelämnas är åtgärden ovillkorlig.

Följande svar uppdaterar endast värdet om den aktuella representationen matchar den angivna etag:

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

Följande svar uppdaterar endast värdet om den aktuella representationen inte matchar den angivna 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"

Följande begäran lägger bara till värdet om det redan finns en representation:

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

Följande begäran lägger bara till värdet om det inte redan finns någon representation:

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

Svar

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

eller

HTTP/1.1 412 PreconditionFailed

Delete

Krävs: {key}, {api-version}
Valfritt: {label} (Om det inte anges, eller label=%00, innebär det nyckelvärde utan etikett.)

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

Svar: Returnera det borttagna nyckelvärdet, eller inget om nyckelvärdet inte fanns.

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

eller

HTTP/1.1 204 No Content

Ta bort nyckel (villkorligt)

Detta liknar avsnittet "Ange nyckel (villkorligt)" tidigare i den här artikeln.

Dela via

Nyckelvärden

Operations

Förutsättningar

Syntax

Hämta nyckelvärde

Hämta (villkorligt)

Lista nyckelvärden

Lista nyckelvärden (villkorsstyrt)

Filtrering

Filter som stöds

Begär specifika fält

Tidsbaserad åtkomst

Ange nyckel

Ange nyckel (villkorligt)

Delete

Ta bort nyckel (villkorligt)

Feedback

Ytterligare resurser