Compartir a través de

Valores clave

  • Artículo

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

or

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

o

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

o

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

or

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

or

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.