Chaves-valor

Artigo
06/01/2023

Um valor-chave é um recurso identificado pela combinação exclusiva de key + label. label é opcional. Para referenciar explicitamente um valor-chave sem uma etiqueta, utilize "\0" (URL codificado como %00). Veja os detalhes de cada operação.

Este artigo aplica-se à versão 1.0 da API.

Operações

Get
Listar múltiplos
Definir
Eliminar

Pré-requisitos

Todos os pedidos HTTP têm de ser autenticados. Veja a secção de autenticação .
Todos os pedidos HTTP têm de fornecer explicitamente api-version. Veja a secção controlo de versões .

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

Obter chave-valor

Obrigatório: {key}, {api-version}
Opcional: label (Se omitido, implica um valor-chave sem uma etiqueta.)

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

Respostas:

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

Se a chave não existir, é devolvida a seguinte resposta:

HTTP/1.1 404 Not Found

Obter (condicionalmente)

Para melhorar a colocação em cache do cliente, utilize If-Match ou If-None-Match solicite cabeçalhos. O etag argumento faz parte da representação da chave. Para obter mais informações, consulte as secções 14.24 e 14.26.

O pedido seguinte obtém o valor-chave apenas se a representação atual não corresponder ao especificado etag:

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

Respostas:

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

Listar valores-chave

Opcional: key (Se não for especificado, implica qualquer chave.) Opcional: label (Se não for especificado, implica qualquer etiqueta.)

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

Resposta:

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

Para obter opções adicionais, consulte a secção "Filtragem" mais à frente neste artigo.

Paginação

O resultado será paginado se o número de itens devolvidos exceder o limite de resposta. Siga os cabeçalhos de resposta opcionais Link e utilize rel="next" para a navegação. Em alternativa, o conteúdo fornece uma ligação seguinte sob a forma da @nextLink propriedade . O URI ligado inclui o api-version argumento .

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

Resposta:

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

Filtragem

É suportada uma combinação de key e label filtragem. Utilize os parâmetros de cadeia de consulta e label opcionaiskey.

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

Filtros suportados

Filtro de chave	Efeito
`key` é omitido ou `key=*`	Corresponde a qualquer chave
`key=abc`	Corresponde a uma chave chamada abc
`key=abc*`	Corresponde a nomes de chaves que começam com abc
`key=abc,xyz`	Corresponde aos nomes das chaves abc ou xyz (limitado a 5 CSV)

Filtro de etiqueta	Efeito
`label` é omitido ou `label=*`	Corresponde a qualquer etiqueta
`label=%00`	Corresponde a KV sem etiqueta
`label=prod`	Corresponde à etiqueta prod
`label=prod*`	Corresponde a etiquetas que começam com prod
`label=prod,test`	Corresponde a etiquetas prod ou teste (limitado a 5 CSV)

Carateres reservados

*, \, ,

Se um caráter reservado fizer parte do valor, tem de ser escapado com \{Reserved Character}. Os carateres não reservados também podem ser escapados.

Validação de filtros

No caso de um erro de validação de filtro, a resposta é HTTP 400 com detalhes de erro:

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
}

Exemplos

Todos
```
GET /kv?api-version={api-version}
```
O nome da chave começa com abc e inclui todas as etiquetas
```
GET /kv?key=abc*&label=*&api-version={api-version}
```
O nome da chave começa com abc e a etiqueta é igual a v1 ou v2
```
GET /kv?key=abc*&label=v1,v2&api-version={api-version}
```

Pedir campos específicos

Utilize o parâmetro de cadeia de consulta opcional $select e forneça uma lista separada por vírgulas dos campos pedidos. Se o $select parâmetro for omitido, a resposta contém o conjunto predefinido.

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

Acesso baseado no tempo

Obtenha uma representação do resultado tal como era num momento anterior. Para obter mais informações, consulte a secção 2.1.1. A paginação ainda é suportada conforme definido anteriormente neste artigo.

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

Resposta:

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

Definir chave

Obrigatório: {key}
Opcional: label (Se não for especificado ou label=%00, implica um valor-chave sem uma etiqueta.)

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

Respostas:

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

Se o item estiver bloqueado, receberá a seguinte resposta:

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
}

Definir chave (condicionalmente)

Para impedir condições de corrida, utilize If-Match ou If-None-Match solicite cabeçalhos. O etag argumento faz parte da representação da chave. Se If-Match for ou If-None-Match for omitido, a operação é incondicional.

A resposta seguinte só atualiza o valor se a representação atual corresponder ao especificado etag:

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

A resposta seguinte só atualiza o valor se a representação atual não corresponder ao especificado 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"

O pedido seguinte só adiciona o valor se já existir uma representação:

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

O pedido seguinte só adiciona o valor se ainda não existir uma representação:

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

Respostas

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

HTTP/1.1 412 PreconditionFailed

Eliminar

Obrigatório: {key}, {api-version}
Opcional: {label} (Se não for especificado ou label=%00, implica um valor-chave sem uma etiqueta.)

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

Resposta: Devolver o valor-chave eliminado ou nenhum se o valor-chave não existir.

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

HTTP/1.1 204 No Content

Eliminar chave (condicionalmente)

Isto é semelhante à secção "Definir chave (condicionalmente)" anteriormente neste artigo.

Partilhar via

Chaves-valor

Operações

Pré-requisitos

Syntax

Obter chave-valor

Obter (condicionalmente)

Listar valores-chave

Filtragem

Filtros suportados

Pedir campos específicos

Acesso baseado no tempo

Definir chave

Definir chave (condicionalmente)

Eliminar

Eliminar chave (condicionalmente)

Recursos adicionais