Valores de chave

Uma chave-valor é um recurso identificado pela combinação exclusiva de key + label. label é opcional. Para referenciar explicitamente uma chave-valor sem um rótulo, use "\0" (URL codificada como %00). Confira os detalhes de cada operação.

Operações

• Obter
• Listar várias
• Definir
• Excluir

Pré-requisitos

• Todas as solicitações HTTP deverão ser autenticadas. Confira a seção autenticação.
• Todas as solicitações HTTP deverão fornecer uma api-version explícita. Confira a seção 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 uma chave-valor 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 os cabeçalhos de solicitação If-Match ou If-None-Match. O argumento etag faz parte da representação de chave. Para obter mais informações, confira as seções 14.24 e 14.26.

A solicitação a seguir recupera a chave-valor somente se a representação atual não corresponder ao etag especificado:

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 chave-valores

Opcional: key (se não especificado, implica qualquer chave.)

Opcional: label (se não 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 em qualquer tag.)

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 chaves-valor (condicionalmente)

Para melhorar o cache do cliente, use os cabeçalhos de solicitação If-Match ou If-None-Match. O etag argumento faz parte do corpo da resposta de valores-chave da lista 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 ao especificado etag:

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

Respostas:

HTTP/1.1 412 PreconditionFailed

or

HTTP/1.1 200 OK

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

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

Respostas:

HTTP/1.1 304 NotModified

or

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 o próximo link da propriedade @nextLink. O URI vinculado inclui o argumento api-version.

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

Há suporte para uma combinação de filtragens key e label. Use os parâmetros de cadeia de caracteres de consulta opcionais key e label.

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

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

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

Filtros com suporte

Caracteres reservados

*, \, ,

Caso um caractere reservado faça parte do valor, ele deverá ser ignorado usando \{Reserved Character}. Os caracteres não reservados também podem ser ignorados.

Validação de 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

• Tudo

  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}
  

Campos específicos da solicitação

Use o parâmetro opcional de cadeia de caracteres de consulta $select e forneça uma lista separada por vírgulas dos campos solicitados. Caso o parâmetro $select seja omitido, a resposta conterá o conjunto padrão.

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

Acesso baseado em tempo

Obtenha uma representação do resultado como ele era anteriormente. Para saber mais, consulte a seção2.1.1. Ainda há suporte para paginação 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, isso implica chave-valor sem 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 os cabeçalhos de solicitação If-Match ou If-None-Match. O argumento etag faz parte da representação de 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 ao etag especificado:

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 ao etag especificado:

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 uma representação já existir:

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

Excluir

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

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

Resposta: Retornar o valor-chave excluído 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
...

ou

HTTP/1.1 204 No Content

Excluir chave (condicionalmente)

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