Valores clave

Artículo
08/10/2024

Un par clave-valor es un recurso identificado por una combinación única de key + label. label es opcional. Para hacer referencia de manera explícita a un par clave-valor sin etiqueta, use "\0" (se codifica para URL como %00). Revise los detalles para cada operación.

Operations

Obtener
Enumerar varios
Set
Eliminar

Requisitos previos

Se deben autenticar todas las solicitudes HTTP. Consulte la sección Autenticación.
Todas las solicitudes HTTP deben proporcionar parámetros api-version explícitos. Consulte la sección Control de versiones.

Sintaxis

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

Obtención del par clave-valor

Obligatorio: {key}, {api-version}
Opcional: label (si se omite, implica un par clave-valor sin etiqueta).

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

Respuestas:

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

Si la clave no existe, se devuelve la respuesta siguiente:

HTTP/1.1 404 Not Found

Obtención (de manera condicional)

Para mejorar el almacenamiento en caché del cliente, use los encabezados de solicitud If-Match o If-None-Match. El argumento etag forma parte de la representación de la clave. Para obtener más información, consulte las secciones 14.24 y 14.26.

La siguiente solicitud recupera el par clave-valor solo si la representación actual no coincide con el argumento etag especificado:

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

Respuestas:

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

Enumeración de pares clave-valor

Opcional: key (si no se especifica, sugiere cualquier clave).

Opcional: label (si no se especifica, sugiere cualquier etiqueta).

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

Respuesta:

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

Opcional: tags (Si no se especifica, implica cualquier etiqueta).

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

Respuesta:

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

Para obtener más opciones, consulte la sección "Filtrado" más adelante en este artículo.

Enumerar los valores de clave (condicionalmente)

Para mejorar el almacenamiento en caché del cliente, use los encabezados de solicitud If-Match o If-None-Match. El etag argumento forma parte del cuerpo y el encabezado de respuesta clave-valores de lista. Si se omiten If-Match o If-None-Match, la operación es incondicional.

La siguiente respuesta obtiene el valor de clave solo si la representación actual coincide con el especificado etag:

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

Respuestas:

HTTP/1.1 412 PreconditionFailed

HTTP/1.1 200 OK

La siguiente respuesta obtiene los valores de clave solo si la representación actual no coincide con el especificado etag:

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

Respuestas:

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

Paginación

El resultado se pagina si el número de elementos devueltos supera el límite de respuesta. Siga los encabezados de respuesta Link opcionales y use rel="next" para la navegación. Como alternativa, el contenido proporciona un vínculo Siguiente en forma de propiedad @nextLink. El URI vinculado incluye el argumento api-version.

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

Respuesta:

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

Filtrado

Se admite una combinación de filtrado de key y label. Use los parámetros de cadena de consulta opcionales key y label.

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

Se admite una combinación de key, labely tags el filtrado. Use los parámetros opcionales keyde cadena de consulta , labely tags . Se pueden proporcionar varios filtros de etiqueta como parámetros de cadena de consulta en el tagName=tagValue formato . Los filtros de etiqueta deben ser una coincidencia exacta.

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

Filtros admitidos

Filtro de clave	Efecto
se omite `key` o `key=*`	Coincide con cualquier clave
`key=abc`	Coincide con una clave de nombre abc
`key=abc*`	Coincide con los nombres de claves que empiezan por abc
`key=abc,xyz`	Coincide con los nombres de claves abc o xyz (limitado a 5 archivos CSV)

Filtro de etiqueta	Efecto
se omite `label` o `label=*`	Coincide con cualquier etiqueta
`label=%00`	Coincide con los valores clave-valor sin etiqueta
`label=prod`	Coincide con la etiqueta prod
`label=prod*`	Coincide con las etiquetas que empiezan por prod
`label=prod,test`	Coincide con las etiquetas prod o test (limitado a 5 archivos CSV)

Filtro de etiquetas	Efecto
se omite `tags` o `tags=`	Coincide con cualquier etiqueta
`tags=group=app1`	Coincide con los valores clave que tienen una etiqueta denominada `group` con el valor `app1`
`tags=group=app1&tags=env=prod`	Coincide con los valores clave que tienen una etiqueta denominada `group` con valor `app1` y una etiqueta denominada `env` con valor `prod`(limitado a 5 filtros de etiqueta).
`tags=tag1=%00`	Coincide con los valores clave que tienen una etiqueta denominada `tag1` con el valor `null`
`tags=tag1=`	Coincide con los valores de clave que tienen una etiqueta denominada `tag1` con un valor vacío.

Caracteres reservados

*, , \, ,

Si un carácter reservado forma parte del valor, se debe escapar mediante \{Reserved Character}. Los caracteres no reservados también se pueden escapar.

Validación del filtro

Si se produce un error en la validación del filtro, la respuesta es HTTP 400 con detalles de error:

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
}

Ejemplos

All
```
GET /kv?api-version={api-version}
```
El nombre de clave comienza por abc e incluye todas las etiquetas
```
GET /kv?key=abc*&label=*&api-version={api-version}
```
El nombre de clave comienza por abc y la etiqueta es igual a v1 o v2
```
GET /kv?key=abc*&label=v1,v2&api-version={api-version}
```

Solicitud de campos específicos

Use el parámetro de cadena de consulta opcional $select y proporcione una lista separada por comas de campos solicitados. Si se omite el parámetro $select, la respuesta contiene el conjunto predeterminado.

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

Acceso basado en el tiempo

Obtenga una representación del resultado tal como era en un momento anterior. Para obtener más información, consulte la sección 2.1.1. Todavía se admite la paginación tal y como se definió anteriormente en este artículo.

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

Respuesta:

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

Establecimiento de clave

Obligatorio: {key}
Opcional: label (si no se especifica o, el valor es label=%00, implica un par clave-valor sin 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",
  }
}

Respuestas:

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

Si el elemento está bloqueado, se devuelve la siguiente respuesta:

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
}

Establecimiento de clave (de manera condicional)

Para evitar condiciones de carrera, use los encabezados de solicitud If-Match o If-None-Match. El argumento etag forma parte de la representación de la clave. Si se omiten If-Match o If-None-Match, la operación es incondicional.

La siguiente respuesta actualiza el valor solo si la representación actual coincide con el valor de 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"

La siguiente respuesta actualiza el valor solo si la representación actual no coincide con el valor de 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"

La siguiente solicitud agrega el valor solo si ya existe una representación:

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

La siguiente solicitud agrega el valor solo si no existe una representación:

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

Respuestas

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

HTTP/1.1 412 PreconditionFailed

Eliminar

Obligatorio: {key}, {api-version}
Opcional: {label} (si no se especifica o, el valor es label=%00, implica un par clave-valor sin etiqueta).

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

Respuesta: Devuelve el par clave-valor eliminado, o no devuelve ningún valor si el par clave-valor no existía.

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

HTTP/1.1 204 No Content

Eliminación de clave (de manera condicional)

Esto es similar a la sección "Establecimiento de clave (de manera condicional)" anteriormente en este artículo.

Compartir vía

Valores clave

Operations

Requisitos previos

Sintaxis

Obtención del par clave-valor

Obtención (de manera condicional)

Enumeración de pares clave-valor

Enumerar los valores de clave (condicionalmente)

Filtrado

Filtros admitidos

Solicitud de campos específicos

Acceso basado en el tiempo

Establecimiento de clave

Establecimiento de clave (de manera condicional)

Eliminar

Eliminación de clave (de manera condicional)

Comentarios

Recursos adicionales