Clés-valeurs

Article
08/10/2024

Une paire clé-valeur est une ressource identifiée par une combinaison unique de key + label. label est facultatif. Pour référencer explicitement une paire clé-valeur sans étiquette, utilisez « \0 » (URL encodée sous la forme %00). Consultez les détails de chaque opération.

Opérations

Obtenir
Liste multiple
Définissez
DELETE

Prérequis

Toutes les requêtes HTTP doivent être authentifiées. Consultez la section Authentification.
Toutes les requêtes HTTP doivent fournir des api-version explicites. Consultez la section Contrôle de version.

Syntaxe

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

Obtenir une paire clé-valeur

Obligatoire : {key}, {api-version}
Facultatif : label (Si omis, cela implique une paire clé-valeur sans étiquette.)

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

Réponses :

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 clé n’existe pas, la réponse suivante est retournée :

HTTP/1.1 404 Not Found

Obtenir (de manière conditionnelle)

Pour améliorer la mise en cache du client, utilisez les en-têtes de demande If-Match ou If-None-Match. L’argument etag fait partie de la représentation clé. Pour plus d’informations, consultez les sections 14.24 et 14.26.

La requête suivante récupère la paire clé-valeur uniquement si la représentation actuelle ne correspond pas à l’élément etagspécifié :

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

Réponses :

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

Lister les paires clé-valeur

Facultatif : key(Si non spécifié, cela implique n’importe quelle clé.)

Facultatif : label (Si non spécifié, cela implique n’importe quelle étiquette.)

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

Réponse :

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

Facultatif : tags (S’il n’est pas spécifié, cela implique des balises.)

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

Réponse :

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

Pour plus d’options, consultez la section « Filtrage » plus loin dans cet article.

Répertorier les valeurs clés (conditionnellement)

Pour améliorer la mise en cache du client, utilisez les en-têtes de demande If-Match ou If-None-Match. L’argument etag fait partie du corps et de l’en-tête de la réponse clé-valeurs de liste. Si If-Match et If-None-Match sont omis, l’opération est inconditionnelle.

La réponse suivante obtient la valeur clé uniquement si la représentation actuelle correspond à celle spécifiée etag:

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

Réponses :

HTTP/1.1 412 PreconditionFailed

HTTP/1.1 200 OK

La réponse suivante obtient les valeurs clés uniquement si la représentation actuelle ne correspond pas à la valeur spécifiée etag:

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

Réponses :

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

Pagination

Le résultat est paginé si le nombre d’éléments retournés dépasse le nombre limite de réponses. Suivez les en-têtes de réponse Link facultatifs et utilisez rel="next" pour la navigation. Le contenu fournit également un lien suivant sous forme de la propriété @nextLink. L’URI lié comprend l’argument api-version.

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

Réponse :

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

Filtrage

Une combinaison de filtre key et label est prise en charge. Utilisez les paramètres de chaîne de requête key et label facultatifs.

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

Une combinaison de key, labelet tags de filtrage est prise en charge. Utilisez les paramètres de chaîne de requête facultatifs keylabelet tags facultatifs. Plusieurs filtres d’étiquettes peuvent être fournis en tant que paramètres de chaîne de requête au tagName=tagValue format. Les filtres d’étiquettes doivent correspondre exactement.

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

Filtres pris en charge

Filtre de clé	Résultat
`key` est omis ou `key=*`	Correspond à toute clé
`key=abc`	Correspond à une clé nommée abc
`key=abc*`	Correspond aux noms de clé qui commencent par abc
`key=abc,xyz`	Correspond aux noms de clé abc ou xyz (limité à 5 CSV)

Filtre d’étiquette	Résultat
`label` est omis ou `label=*`	Correspond à toute étiquette
`label=%00`	Correspond aux valeurs de clé sans étiquette
`label=prod`	Correspond à l’étiquette prod
`label=prod*`	Correspond aux étiquettes qui commencent par prod
`label=prod,test`	Correspond aux étiquettes prod ou test (limité à 5 CSV)

Filtre d’étiquettes	Résultat
`tags` est omis ou `tags=`	Correspond à n’importe quelle balise
`tags=group=app1`	Correspond aux valeurs de clé qui ont une balise nommée `group` avec la valeur `app1`
`tags=group=app1&tags=env=prod`	Correspond aux valeurs clés qui ont une balise nommée `group` avec une valeur `app1` et une balise nommée `env` avec une valeur `prod`(limitée à 5 filtres d’étiquettes)
`tags=tag1=%00`	Correspond aux valeurs de clé qui ont une balise nommée `tag1` avec la valeur `null`
`tags=tag1=`	Correspond aux valeurs de clé qui ont une balise nommée `tag1` avec une valeur vide

Caractères réservés

*, , \,

Si un caractère réservé fait partie de la valeur, il doit être placé dans une séquence d’échappement à l’aide de \{Reserved Character}. Les caractères non réservés peuvent également être placés dans une séquence d’échappement.

Validation de filtre

Si la validation du filtre échoue, la réponse est HTTP 400 avec des détails d’erreur :

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
}

Exemples

Tous
```
GET /kv?api-version={api-version}
```
Le nom de clé commence par abc et inclut toutes les étiquettes
```
GET /kv?key=abc*&label=*&api-version={api-version}
```
Le nom de clé commence par abc et l’étiquette est égale à v1 ou v2
```
GET /kv?key=abc*&label=v1,v2&api-version={api-version}
```

Champs spécifiques de la demande

Utilisez le paramètre de chaîne de requête facultatif $select et fournissez une liste séparée par des virgules des champs demandés. Si le paramètre $select est omis, la réponse contient l’ensemble par défaut.

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

Accès basé sur le temps

Obtenez une représentation du résultat tel qu’il était à un moment passé. Pour plus d’informations, voir la section 2.1.1. La pagination est toujours prise en charge, comme défini précédemment dans cet article.

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

Réponse :

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

Définir la clé

Obligatoire : {key}
Facultatif : label (Si non spécifié ou si étiquette = %00, cela implique une paire clé-valeur sans étiquette.)

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

Réponses :

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 l’élément est verrouillé, la réponse suivante est retournée :

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
}

Définir la clé (de manière conditionnelle)

Pour éviter les conditions de concurrence, utilisez les en-têtes de demande If-Match ou If-None-Match. L’argument etag fait partie de la représentation clé. Si If-Match et If-None-Match sont omis, l’opération est inconditionnelle.

La réponse suivante met à jour la valeur uniquement si la représentation actuelle correspond à l’objet etag spécifié :

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

La réponse suivante met à jour la valeur uniquement si la représentation actuelle ne correspond pas à l’objet etag spécifié :

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 requête suivante ajoute la valeur uniquement si une représentation existe déjà :

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

La requête suivante ajoute la valeur uniquement si une représentation n’existe pas déjà :

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

Réponses

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

HTTP/1.1 412 PreconditionFailed

DELETE

Obligatoire : {key}, {api-version}
Facultatif : {label} (Si non spécifié ou si étiquette = %00, cela implique une paire clé-valeur sans étiquette.)

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

Réponse : Retourne la paire clé-valeur supprimée, ou aucune si la paire clé-valeur n’existe pas.

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

HTTP/1.1 204 No Content

Supprimer la clé (de manière conditionnelle)

Équivaut à la section « Définir la clé (de manière conditionnelle) » plus haut dans cet article.

Partager via

Clés-valeurs

Opérations

Prérequis

Syntaxe

Obtenir une paire clé-valeur

Obtenir (de manière conditionnelle)

Lister les paires clé-valeur

Répertorier les valeurs clés (conditionnellement)

Filtrage

Filtres pris en charge

Champs spécifiques de la demande

Accès basé sur le temps

Définir la clé

Définir la clé (de manière conditionnelle)

DELETE

Supprimer la clé (de manière conditionnelle)

Commentaires

Ressources supplémentaires