Schlüsselwerte

Artikel
08/10/2024

Ein Schlüssel-Wert-Paar ist eine Ressource, die über die eindeutige Kombination aus key + label identifiziert wird. label ist optional. Verwenden Sie „\0“ (als %00-codierte URL), um explizit auf ein Schlüssel-Wert-Paar ohne Bezeichnung zu verweisen. Mehr dazu erfahren Sie in den Informationen zum jeweiligen Vorgang.

Operations

Herunterladen
Auflisten mehrerer Werte
Set
Löschen

Voraussetzungen

Alle HTTP-Anforderungen müssen authentifiziert werden. Informationen dazu erhalten Sie im Abschnitt Authentifizierung.
Alle HTTP-Anforderungen müssen explizit die api-version angeben. Informationen dazu erhalten Sie im Abschnitt Versionsverwaltung.

Syntax

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

Abrufen des Schlüssel-Wert-Paars

Erforderlich: {key}, {api-version}
Optional: label (Bei Auslassung wird ein Schlüssel-Wert-Paar ohne Bezeichnung impliziert.)

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

Antworten:

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

Wenn der Schlüssel nicht vorhanden ist, wird folgende Antwort zurückgegeben:

HTTP/1.1 404 Not Found

Abrufen (bedingt)

Verwenden Sie If-Match- oder If-None-Match-Anforderungsheader, um das Zwischenspeichern auf dem Client zu verbessern. Das etag-Argument gehört zur Schlüsseldarstellung. Weitere Informationen finden Sie in den Abschnitten 14.24 und 14.26.

Die folgende Anforderung ruft das Schlüssel-Wert-Paar nur dann ab, wenn die aktuelle Darstellung nicht dem angegebenen etag entspricht:

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

Antworten:

HTTP/1.1 304 NotModified

oder

HTTP/1.1 200 OK

Auflisten von Schlüssel-Wert-Paaren

Optional: key (ohne Angabe ist ein beliebiger Schlüssel gemeint).

Optional: label (ohne Angabe ist eine beliebige Bezeichnung gemeint).

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

Antwort:

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

Optional: tags (Falls nicht angegeben, impliziert es Tags.)

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

Antwort:

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

Weitere Optionen finden Sie im Abschnitt "Filtern" weiter unten in diesem Artikel.

Schlüsselwerte auflisten (bedingt)

Verwenden Sie If-Match- oder If-None-Match-Anforderungsheader, um das Zwischenspeichern auf dem Client zu verbessern. Das etag Argument ist Teil des Antworttexts und der Kopfzeile der Listenschlüsselwerte. Wenn If-Match oder If-None-Match ausgelassen werden, ist der Vorgang nicht bedingt.

Die folgende Antwort ruft den Schlüsselwert nur ab, wenn die aktuelle Darstellung dem angegebenen etagentspricht:

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

Antworten:

HTTP/1.1 412 PreconditionFailed

HTTP/1.1 200 OK

Die folgende Antwort ruft die Schlüsselwerte nur ab, wenn die aktuelle Darstellung nicht mit dem angegebenen etagübereinstimmt:

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

Antworten:

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

Paginierung

Das Ergebnis ist paginiert, wenn die Anzahl der zurückgegebenen Elemente das Antwortlimit überschreitet. Folgen Sie den optionalen Link-Headern, und verwenden Sie rel="next" zur Navigation. Alternativ dazu stellt der Inhalt in Form der Eigenschaft @nextLink einen Link zu weiteren Elementen bereit. Der verknüpfte URI enthält das api-version-Argument.

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

Antwort:

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

Filtern

Eine Kombination aus Filterung nach key und label wird unterstützt. Verwenden Sie die optionalen Abfragezeichenfolgeparameter key und label.

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

Es wird eine Kombination aus key, labelund tags Filtern unterstützt. Verwenden Sie die optionalen key, labelund tags Abfragezeichenfolgenparameter. Mehrere Tagfilter können als Abfragezeichenfolgenparameter im tagName=tagValue Format bereitgestellt werden. Tagfilter müssen eine genaue Übereinstimmung sein.

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

Unterstützte Filter

Schlüsselfilter	Wirkung
`key` wird weggelassen oder lautet `key=*`	Übereinstimmung mit einem beliebigen Schlüssel
`key=abc`	Übereinstimmung mit einem Schlüssel namens abc
`key=abc*`	Übereinstimmung mit Schlüsselnamen, die mit abc beginnen
`key=abc,xyz`	Übereinstimmung mit den Schlüsselnamen abc oder xyz (auf fünf CSVs begrenzt)

Bezeichnungsfilter	Wirkung
`label` wird weggelassen oder lautet `label=*`	Übereinstimmung mit einer beliebigen Bezeichnung
`label=%00`	Gleicht Schlüsselwerte ohne Beschriftung ab.
`label=prod`	Übereinstimmung mit Bezeichnung prod
`label=prod*`	Übereinstimmung mit Bezeichnungen, die mit prod beginnen
`label=prod,test`	Übereinstimmung mit den Bezeichnungen prod oder test (auf fünf CSVs begrenzt)

Kategorienfilter	Wirkung
`tags` wird weggelassen oder lautet `tags=`	Entspricht einem beliebigen Tag
`tags=group=app1`	Gleicht Schlüsselwerte ab, die ein Tag mit dem Wert haben `group` . `app1`
`tags=group=app1&tags=env=prod`	Gleicht Schlüsselwerte ab, die ein Tag mit Dem `group` Wert `app1` und ein Tag mit Dem Wert `prod`haben `env` (auf 5 Tagfilter beschränkt)
`tags=tag1=%00`	Gleicht Schlüsselwerte ab, die ein Tag mit dem Wert haben `tag1` . `null`
`tags=tag1=`	Gleicht Schlüsselwerte mit einem Tag mit leerem Wert ab `tag1` .

Reservierte Zeichen

*, \,

Wenn ein Wert ein reserviertes Zeichen enthält, muss dieses mit einem Escapezeichen versehen werden: \{Reserved Character}. Nicht reservierten Zeichen können ebenfalls mit Escapezeichen versehen werden.

Filterüberprüfung

Wenn die Filterüberprüfung fehlschlägt, lautet die Antwort HTTP 400 mit Fehlerdetails:

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
}

Beispiele

All
```
GET /kv?api-version={api-version}
```
Schlüsselname beginnt mit abc und schließt alle Bezeichnungen ein
```
GET /kv?key=abc*&label=*&api-version={api-version}
```
Schlüsselname beginnt mit abc, und Bezeichnung ist gleich v1 oder v2
```
GET /kv?key=abc*&label=v1,v2&api-version={api-version}
```

Anfordern bestimmter Felder

Verwenden Sie den optionalen Abfragezeichenfolgenparameter $select, und geben Sie eine durch Trennzeichen getrennte Liste der angeforderten Felder an. Wenn der Parameter $select ausgelassen wird, enthält die Antwort die Standardgruppe von Feldern.

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

Zeitbasierter Zugriff

Rufen Sie eine Darstellung des Ergebnisses ab, so wie es zu einem bestimmten Zeitpunkt in der Vergangenheit war. Weitere Informationen finden Sie im Abschnitt 2.1.1. Die Paginierung wird weiterhin wie oben in diesem Artikel definiert unterstützt.

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

Antwort:

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

Schlüssel festlegen

Erforderlich: {key}
Optional: label (Ohne Angabe oder bei „label=%00“ wird ein Schlüsselwert ohne Bezeichnung impliziert.)

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

Antworten:

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

Wenn das Element gesperrt ist, wird die folgende Antwort zurückgegeben:

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
}

Schlüssel festlegen (bedingt)

Um Racebedingungen zu verhindern, verwenden Sie Anforderungsheader vom Typ If-Match oder If-None-Match. Das etag-Argument gehört zur Schlüsseldarstellung. Wenn If-Match oder If-None-Match ausgelassen werden, ist der Vorgang nicht bedingt.

Die folgende Antwort aktualisiert den Wert nur, wenn die aktuelle Darstellung mit dem angegebenen etag übereinstimmt:

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

Die folgende Antwort aktualisiert den Wert nur, wenn die aktuelle Darstellung nicht mit dem angegebenen etag übereinstimmt:

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

Die folgende Anforderung fügt den Wert nur hinzu, wenn bereits eine Darstellung vorhanden ist:

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

Die folgende Anforderung fügt den Wert nur hinzu, wenn noch keine Darstellung vorhanden ist:

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

Antworten

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

oder

HTTP/1.1 412 PreconditionFailed

Löschen

Erforderlich: {key}, {api-version}
Optional: {label} (Ohne Angabe oder bei „label=%00“ wird ein Schlüsselwert ohne Bezeichnung impliziert.)

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

Antwort: Gibt das gelöschte Schlüssel-Wert-Paar oder nichts zurück, wenn das Schlüssel-Wert-Paar nicht vorhanden war.

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

oder

HTTP/1.1 204 No Content

Schlüssel löschen (bedingt)

Dies ähnelt dem Abschnitt „Schlüssel festlegen (bedingt)“ weiter oben in diesem Artikel.

Freigeben über

Schlüsselwerte

Operations

Voraussetzungen

Syntax

Abrufen des Schlüssel-Wert-Paars

Abrufen (bedingt)

Auflisten von Schlüssel-Wert-Paaren

Schlüsselwerte auflisten (bedingt)

Filtern

Unterstützte Filter

Anfordern bestimmter Felder

Zeitbasierter Zugriff

Schlüssel festlegen

Schlüssel festlegen (bedingt)

Löschen

Schlüssel löschen (bedingt)

Feedback

Zusätzliche Ressourcen