Coppie chiave-valore

Un valore chiave è una risorsa identificata da una combinazione univoca di key + label. label è facoltativo. Per fare riferimento in modo esplicito a un valore chiave senza un'etichetta, usare "\0" (URL codificato come %00). Vedere i dettagli per ogni operazione.

Operazioni

• Recupero
• Elencare più
• Set
• Elimina

Prerequisiti

• Tutte le richieste HTTP devono essere autenticate. Vedere la sezione relativa all'autenticazione.
• Tutte le richieste HTTP devono fornire esplicitamente api-version. Vedere la sezione relativa al controllo delle versioni.

Sintassi

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

Ottenere chiave-valore

Obbligatorio: {key}, {api-version}
Facoltativo: label se omesso, implica un valore chiave senza etichetta.

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

Risposte:

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 la chiave non esiste, viene restituita la risposta seguente:

HTTP/1.1 404 Not Found

Get (in modo condizionale)

Per migliorare la memorizzazione nella cache del client, usare If-Match o If-None-Match richiedere intestazioni. L'argomento etag fa parte della rappresentazione della chiave. Per altre informazioni, vedere le sezioni 14.24 e 14.26.

La richiesta seguente recupera il valore della chiave solo se la rappresentazione corrente non corrisponde all'oggetto specificato etag:

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

Risposte:

HTTP/1.1 304 NotModified

or

HTTP/1.1 200 OK

Elencare i valori chiave

Facoltativo: key se non specificato, implica qualsiasi chiave.

Facoltativo: label se non specificato, implica qualsiasi etichetta.

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

Risposta:

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

Facoltativo: tags se non specificato, implica eventuali tag.

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

Risposta:

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

Per altre opzioni, vedere la sezione "Filtro" più avanti in questo articolo.

Elencare i valori chiave (in modo condizionale)

Per migliorare la memorizzazione nella cache del client, usare If-Match o If-None-Match richiedere intestazioni. L'argomento etag fa parte del corpo e dell'intestazione della risposta list key-values. Se If-Match o If-None-Match vengono omessi, l'operazione è incondizionato.

La risposta seguente ottiene il valore della chiave solo se la rappresentazione corrente corrisponde all'oggetto specificato etag:

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

Risposte:

HTTP/1.1 412 PreconditionFailed

or

HTTP/1.1 200 OK

La risposta seguente ottiene i valori chiave solo se la rappresentazione corrente non corrisponde all'oggetto specificato etag:

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

Risposte:

HTTP/1.1 304 NotModified

or

HTTP/1.1 200 OK

Impaginazione

Il risultato viene impaginato se il numero di elementi restituiti supera il limite di risposta. Seguire le intestazioni di risposta facoltative Link e usare rel="next" per la navigazione. In alternativa, il contenuto fornisce un collegamento successivo sotto forma di @nextLink proprietà . L'URI collegato include l'argomento api-version .

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

Risposta:

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

Filtri

È supportata una combinazione di key filtri e label . Usare i parametri facoltativi key e label della stringa di query.

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

È supportata una combinazione di keyfiltri , labele tags . Usare i parametri facoltativi keydella stringa di query , labele tags . È possibile specificare più filtri di tag come parametri della stringa di query nel tagName=tagValue formato . I filtri tag devono essere una corrispondenza esatta.

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

Filtri supportati

Caratteri riservati

*, \, ,

Se un carattere riservato fa parte del valore , deve essere preceduto da un carattere di escape tramite \{Reserved Character}. I caratteri non riservati possono anche essere preceduti da caratteri di escape.

Convalida dei filtri

Se la convalida del filtro non riesce, la risposta è HTTP 400 con i dettagli dell'errore:

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
}

Esempi

• Tutte le date

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

• Il nome della chiave inizia con abc e include tutte le etichette

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

• Il nome della chiave inizia con abc e label è uguale a v1 o v2

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

Richiedi campi specifici

Usare il parametro facoltativo $select della stringa di query e specificare un elenco delimitato da virgole di campi richiesti. Se il $select parametro viene omesso, la risposta contiene il set predefinito.

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

Accesso basato sul tempo

Ottenere una rappresentazione del risultato come in passato. Per altre informazioni, vedere la sezione 2.1.1. La paginazione è ancora supportata come definito in precedenza in questo articolo.

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

Risposta:

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

Impostare la chiave

• Obbligatorio: {key}
• Facoltativo: label se non specificato o label=%00, implica un valore chiave senza etichetta.

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

Risposte:

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 l'elemento è bloccato, viene restituita la risposta seguente:

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
}

Impostare la chiave (in modo condizionale)

Per evitare race condition, usare If-Match o If-None-Match richiedere intestazioni. L'argomento etag fa parte della rappresentazione della chiave. Se If-Match o If-None-Match vengono omessi, l'operazione è incondizionato.

La risposta seguente aggiorna il valore solo se la rappresentazione corrente corrisponde all'oggetto specificato etag:

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

La risposta seguente aggiorna il valore solo se la rappresentazione corrente non corrisponde all'oggetto specificato 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"

La richiesta seguente aggiunge il valore solo se esiste già una rappresentazione:

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

La richiesta seguente aggiunge il valore solo se non esiste già una rappresentazione:

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

Risposte

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

or

HTTP/1.1 412 PreconditionFailed

Elimina

• Obbligatorio: {key}, {api-version}
• Facoltativo: {label} se non specificato o label=%00, implica un valore chiave senza etichetta.

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

Risposta: restituisce il valore chiave eliminato o nessuno se il valore chiave non esiste.

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

or

HTTP/1.1 204 No Content

Elimina chiave (in modo condizionale)

Questa operazione è simile alla sezione "Impostare la chiave (in modo condizionale)" più indietro in questo articolo.