Partilhar via

Chaves-valor

  • Artigo

Um valor-chave é um recurso identificado pela combinação exclusiva de key + label. label é opcional. Para fazer referência explícita a um valor-chave sem um rótulo, use "\0" (URL codificado como %00). Veja os detalhes de cada operação.

Operações

  • Obtenção
  • Listar vários
  • Definição
  • Delete

Pré-requisitos

  • Todas as solicitações HTTP devem ser autenticadas. Consulte a seção de autenticação .
  • Todas as solicitações HTTP devem fornecer arquivos .api-version Consulte a seção de controle de versão.

Sintaxe

{
  "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 um rótulo.)

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, a seguinte resposta será retornada:

HTTP/1.1 404 Not Found

Obter (condicionalmente)

Para melhorar o cache do cliente, use If-Match ou If-None-Match solicite cabeçalhos. O etag argumento faz parte da representação-chave. Para mais informações, ver secções 14.24 e 14.26.

A solicitação a seguir recupera o valor-chave somente se a representação atual não corresponder à especificada 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

ou

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 rótulo.)

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

Opcional: tags (Se não for especificado, implica quaisquer tags.)

GET /kv?key=Test*&label=*&tags=tag1=value1&tags=tag2=value2&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 mais opções, consulte a seção "Filtragem" mais adiante neste artigo.

Listar valores-chave (condicionalmente)

Para melhorar o cache do cliente, use If-Match ou If-None-Match solicite cabeçalhos. O etag argumento faz parte da lista, dos valores-chave, do corpo da resposta e do cabeçalho. Se If-Match ou If-None-Match forem omitidos, a operação é incondicional.

A resposta a seguir obtém o valor-chave somente se a representação atual corresponder à especificada etag:

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

Respostas:

HTTP/1.1 412 PreconditionFailed

ou

HTTP/1.1 200 OK

A resposta a seguir obtém os valores-chave somente se a representação atual não corresponder à especificada etag:

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

Respostas:

HTTP/1.1 304 NotModified

ou

HTTP/1.1 200 OK

Paginação

O resultado será paginado se o número de itens retornados exceder o limite de resposta. Siga os cabeçalhos de resposta opcionais Link e use rel="next" para navegação. Como alternativa, o conteúdo fornece um próximo link na forma da @nextLink propriedade. O URI vinculado 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

Uma combinação de key e label filtragem é suportada. Use os parâmetros opcionais key e label de seqüência de caracteres de consulta.

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

Há suporte para uma combinação de key, labele tags filtragem. Use os parâmetros opcionais key, labele query tags string parâmetros. Vários filtros de tag podem ser fornecidos como parâmetros de cadeia de caracteres de tagName=tagValue consulta no formato. Os filtros de tags devem ser uma correspondência exata.

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

Filtros suportados

Filtro de chave Efeito
key for omitida ou key=* Corresponde a qualquer tecla
key=abc Corresponde a uma chave chamada abc
key=abc* Corresponde a nomes de chaves que começam com abc
key=abc,xyz Corresponde a nomes de chaves abc ou xyz (limitado a 5 CSV)
Filtro de etiquetas Efeito
label for omitida ou label=* Corresponde a qualquer rótulo
label=%00 Corresponde a valores-chave sem rótulo
label=prod Corresponde ao rótulo prod
label=prod* Corresponde a rótulos que começam com prod
label=prod,test Corresponde a rótulos prod ou teste (limitado a 5 CSV)
Filtro de tags Efeito
tags for omitida ou tags= Corresponde a qualquer tag
tags=group=app1 Corresponde a valores-chave que têm uma tag nomeada group com valor app1
tags=group=app1&tags=env=prod Corresponde a valores-chave que têm uma tag nomeada group com value app1 e uma tag named env with value prod(limitada a 5 filtros de tag)
tags=tag1=%00 Corresponde a valores-chave que têm uma tag nomeada tag1 com valor null
tags=tag1= Corresponde a valores-chave que têm uma tag nomeada tag1 com valor vazio

Caracteres reservados

*, \, ,

Se um caractere reservado fizer parte do valor, ele deverá ser escapado usando \{Reserved Character}. Caracteres não reservados também podem ser escapados.

Validação do filtro

Se a validação do filtro falhar, a resposta será HTTP 400 com detalhes do 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 todos os rótulos

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

  • O nome da chave começa com abc e o rótulo é igual a v1 ou v2

    GET /kv?key=abc*&label=v1,v2&api-version={api-version}

Solicitar campos específicos

Use o parâmetro opcional $select de seqüência de caracteres de consulta e forneça uma lista separada por vírgulas de campos solicitados. Se o $select parâmetro for omitido, a resposta conterá o conjunto padrão.

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

Acesso baseado no tempo

Obter uma representação do resultado como era em um momento passado. Para mais informações, ver 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

  • Necessário: {key}
  • Opcional: label (Se não for especificado, ou label=%00, implica chave-valor sem um rótulo.)
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, a seguinte resposta será retornada:

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 evitar condições de corrida, use If-Match ou If-None-Match solicite cabeçalhos. O etag argumento faz parte da representação-chave. Se If-Match ou If-None-Match forem omitidos, a operação é incondicional.

A resposta a seguir atualiza o valor somente se a representação atual corresponder à especificada 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 a seguir atualiza o valor somente se a representação atual não corresponder à especificada 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"

A solicitação a seguir adiciona o valor somente 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: "*"

A solicitação a seguir adiciona o valor somente se uma representação ainda não existir:

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
...

ou

HTTP/1.1 412 PreconditionFailed

Delete

  • Obrigatório: {key}, {api-version}
  • Opcional: {label} (Se não for especificado, ou label=%00, implica chave-valor sem um rótulo.)
DELETE /kv/{key}?label={label}&api-version={api-version} HTTP/1.1

Resposta: Retorne o valor-chave excluído, ou nenhum se o valor-chave não existisse.

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

ou

HTTP/1.1 204 No Content

Excluir chave (condicionalmente)

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