Snapshot

Artikel
08/10/2024

Snapshot-Ressource ist in API Version 1.0 nicht verfügbar.

Eine Momentaufnahme ist eine Ressource, die eindeutig durch ihren Namen identifiziert wird. Mehr dazu erfahren Sie in den Informationen zum jeweiligen Vorgang.

Operations

Herunterladen
Auflisten mehrerer Werte
Erstellen
Archivieren/Wiederherstellen
Auflisten von Schlüssel-Wert-Paaren

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

Snapshot

{
    "etag": [string],
    "name": [string],
    "status": [string, enum("provisioning", "ready", "archived", "failed")],
    "filters": [array<SnapshotFilter>],
    "composition_type": [string, enum("key", "key_label")],
    "created": [datetime ISO 8601],
    "size": [number, bytes],
    "items_count": [number],
    "tags": [object with string properties],
    "retention_period": [number, timespan in seconds],
    "expires": [datetime ISO 8601]
}

SnapshotFilter

{
  "key": [string],
  "label": [string]
}

{
  "key": [string],
  "label": [string],
  "tags": [array<string>]
}

Abrufen einer Momentaufnahme

Erforderlich: {name}, {api-version}

GET /snapshots/{name}?api-version={api-version}

Antworten:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
Last-Modified: Mon, 03 Mar 2023 9:00:03 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
Link: </kv?snapshot=prod-2023-03-20&api-version={api-version}>; rel="items"

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "name": "prod-2023-03-20",
  "status": "ready",
  "filters": [
      {
          "key": "*",
          "label": null
      }
  ],
  "composition_type": "key",
  "created": "2023-03-20T21:00:03+00:00",
  "size": 2000,
  "items_count": 4,
  "tags": {
    "t1": "value1",
    "t2": "value2"
  },
  "retention_period": 7776000
}

Wenn keine Momentaufnahme mit dem angegebenen Namen vorhanden ist, wird die 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 Darstellung der Momentaufnahme. Weitere Informationen finden Sie in den Abschnitten 14.24 und 14.26.

Die folgende Anforderung ruft die Momentaufnahme nur dann ab, wenn die aktuelle Darstellung nicht dem angegebenen etag entspricht:

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

Antworten:

HTTP/1.1 304 NotModified

Oder

HTTP/1.1 200 OK

Auflisten von Momentaufnahmen

Optional: name (Ohne Angabe wird ein beliebiger Name angenommen.) Optional: status (Ohne Angabe wird ein beliebiger Status angenommen.)

GET /snapshots?name=prod-*&api-version={api-version} HTTP/1.1

Antwort:

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

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

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 /snapshots?api-version={api-version} HTTP/1.1

Antwort:

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshotset+json; charset=utf-8
Link: <{relative uri}>; rel="next"

{
    "items": [
        ...
    ],
    "@nextLink": "{relative uri}"
}

Filtern

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

GET /snapshots?name={name}&status={status}&api-version={api-version}

Unterstützte Filter

Namensfilter	Wirkung
`name` wird weggelassen oder lautet `name=*`	Übereinstimmung mit Momentaufnahmen mit einem beliebigen Namen
`name=abc`	Übereinstimmung mit einer Momentaufnahme namens abc
`name=abc*`	Übereinstimmung mit Momentaufnahmen, deren Name mit abc beginnt
`name=abc,xyz`	Übereinstimmung mit Momentaufnahmen, deren Namen abc oder xyz lauten (auf fünf durch Komma getrennte Werte begrenzt)

Statusfilter	Wirkung
`status` wird weggelassen oder lautet `status=*`	Übereinstimmung mit Momentaufnahmen mit einem beliebigen Status
`status=ready`	Übereinstimmung mit Momentaufnahmen mit dem Status bereit
`status=ready,archived`	Übereinstimmung mit Momentaufnahmen mit dem Status bereit oder archiviert (auf fünf durch Komma getrennte Werte beschränkt)

Reservierte Zeichen

*, \,

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

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 /snapshots?api-version={api-version}

Name der Momentaufnahme beginnt mit abc

GET /snapshot?name=abc*&api-version={api-version}

Name der Momentaufnahme beginnt mit abc, und der Status ist bereit oder archiviert
```
GET /snapshot?name=abc*&status=ready,archived&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 /snapshot?$select=name,status&api-version={api-version} HTTP/1.1

Erstellen einer Momentaufnahme

parameters

Eigenschaftenname	Erforderlich	Standardwert	Überprüfen
name	ja	–	Länge Maximal: 256
Filter	ja	–	Anzahl Mindestwert: 1 Maximal: 3
filters[<index>].key	ja	Nicht zutreffend
filters[<index>].label	nein	NULL	Beschriftungsfilter mit mehreren Übereinstimmungen (z. B. "*", "Komma,getrennt") werden mit dem Kompositionstyp "Schlüssel" nicht unterstützt.
tags	Nein	{}
composition_type	nein	Schlüssel
retention_period	Nein	Standard-Tarif 2592000 (30 Tage) Free-Tarif 604800 (sieben Tage)	Standard-Tarif Minimum: 3600 (eine Stunde) Maximal: 7776000 (90 Tage) Free-Tarif Minimum: 3600 (eine Stunde) Maximal: 604800 (sieben Tage)

PUT /snapshot/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json

{
  "filters": [                        // required
    {
      "key": "app1/*",                // required
      "label": "prod"                 // optional
    }
  ],
  "tags": {                           // optional
    "tag1": "value1",
    "tag2": "value2",
  },
  "composition_type": "key",          // optional
  "retention_period": 2592000         // optional
}

Antworten:

HTTP/1.1 201 Created
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "name": "{name}",
  "status": "provisioning",
  "filters": [
      {
          "key": "app1/*",
          "label": "prod"
      }
  ],
  "composition_type": "key",
  "created": "2023-03-20T21:00:03+00:00",
  "size": 2000,
  "items_count": 4,
  "tags": {
    "t1": "value1",
    "t2": "value2"
  },
  "retention_period": 2592000
}

Eigenschaftsname	Erforderlich	Standardwert	Überprüfen
name	ja	–	Länge Maximal: 256
Filter	ja	–	Anzahl Mindestwert: 1 Maximal: 3
filters[<index>].key	ja	Nicht zutreffend
filters[<index>].label	nein	NULL	Beschriftungsfilter mit mehreren Übereinstimmungen (z. B. "*", "Komma,getrennt") werden mit dem Kompositionstyp "Schlüssel" nicht unterstützt.
filters[<index>].tags	Nein	NULL	Anzahl Mindestwert: 0 Maximal: 5
tags	Nein	{}
composition_type	nein	Schlüssel
retention_period	Nein	Standard-Tarif 2592000 (30 Tage) Free-Tarif 604800 (7 Tage)	Standard-Tarif Minimum: 3600 (1 Stunde) Maximal: 7776000 (90 Tage) Free-Tarif Minimum: 3600 (1 Stunde) Maximal: 604800 (7 Tage)

PUT /snapshot/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json

{
  "filters": [                                // required
    {
      "key": "app1/*",                        // required
      "label": "prod",                        // optional
      "tags": ["group=g1", "default=true"]    // optional
    }
  ],
  "tags": {                                   // optional
    "tag1": "value1",
    "tag2": "value2",
  },
  "composition_type": "key",                  // optional
  "retention_period": 2592000                 // optional
}

Antworten:

HTTP/1.1 201 Created
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
Last-Modified: Tue, 05 Dec 2017 02:41:26 GMT
ETag: "4f6dd610dd5e4deebc7fbaef685fb903"
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}

{
  "etag": "4f6dd610dd5e4deebc7fbaef685fb903",
  "name": "{name}",
  "status": "provisioning",
  "filters": [
      {
          "key": "app1/*",
          "label": "prod",
          "tags": ["group=g1", "default=true"]
      }
  ],
  "composition_type": "key",
  "created": "2023-03-20T21:00:03+00:00",
  "size": 2000,
  "items_count": 4,
  "tags": {
    "t1": "value1",
    "t2": "value2"
  },
  "retention_period": 2592000
}

Der Status der neu erstellten Momentaufnahme lautet provisioning. Sobald die Momentaufnahme vollständig bereitgestellt wurde, wird der Status aktualisiert ready. Clients können die Momentaufnahme abfragen, um sicherzustellen, dass sie bereit ist, bevor sie die zugehörigen Schlüssel-Wert-Paare auflisten. Zusätzliche Informationen zum Vorgang erhalten Sie im Abschnitt Abfragen der Momentaufnahmeerstellung.

Wenn die Momentaufnahme bereits vorhanden 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/already-exists",
    "title": "The resource already exists.",
    "status": 409,
    "detail": ""
}

Abfragen der Momentaufnahmeerstellung

Die Antwort einer Anforderung zur Momentaufnahmeerstellung gibt einen Operation-Location-Header zurück.

Antworten:

HTTP/1.1 201 Created
...
Operation-Location: {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}

Den Status des Vorgangs zur Momentaufnahmebereitstellung finden Sie unter dem URI in Operation-Location. Clients können dieses Statusobjekt abfragen, um sicherzustellen, dass eine Momentaufnahme bereitgestellt wird, bevor sie die zugehörigen Schlüssel-Wert-Paare auflisten.

GET {appConfigurationEndpoint}/operations?snapshot={name}&api-version={api-version}

Antwort:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": "{id}",
    "status": "Succeeded",
    "error": null
}

Wenn während der Bereitstellung der Momentaufnahme ein Fehler auftritt, enthält die error Eigenschaft Details zur Beschreibung des Fehlers.

{
    "id": "{name}",
    "status": "Failed",
    "error": {
      "code": "QuotaExceeded",
      "message": "The allotted quota for snapshot creation has been surpassed."
    }
}

Archiv (Patch)

Eine Momentaufnahme im Zustand ready kann archiviert werden. Einer archivierten Momentaufnahme wird ein Ablaufdatum zugewiesen, basierend auf dem Aufbewahrungszeitraum, der zum Zeitpunkt der Erstellung eingerichtet wurde. Nach dem Ablaufdatum wird die Momentaufnahme endgültig gelöscht. Zu jedem Zeitpunkt vor dem Ablaufdatum können die Elemente der Momentaufnahme weiterhin aufgelistet werden.

Das Archivieren einer bereits archivierten Momentaufnahme (archived) wirkt sich nicht auf die Momentaufnahme aus.

Erforderlich: {name}, {status}, {api-version}

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json

{
  "status": "archived"
}

Antwort: Rückgabe der archivierten Momentaufnahme

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

{
  "etag": "33a0c9cdb43a4c2cb5fc4c1feede1c68",
  "name": "{name}",
  "status": "archived",
  ...
  "expires": "2023-08-11T21:00:03+00:00"
}

Das Archivieren einer Momentaufnahme, die sich derzeit im Zustand provisioning oder failed befindet, ist ein ungültiger Vorgang.

Antwort:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset="utf-8"

{
    "type": "https://azconfig.io/errors/invalid-state",
    "title": "Target resource state invalid.",
    "detail": "The target resource is not in a valid state to perform the requested operation.",
    "status": 409
}

Wiederherstellen (Patch)

Eine Momentaufnahme im Zustand archived kann wiederhergestellt werden. Nachdem die Momentaufnahme wiederhergestellt wurde, wird das Ablaufdatum der Momentaufnahme entfernt.

Das Wiederherstellen einer bereiten Momentaufnahme (ready) wirkt sich nicht auf die Momentaufnahme aus.

Erforderlich: {name}, {status}, {api-version}

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json

{
  "status": "ready"
}

Antwort: Rückgabe der wiederhergestellten Momentaufnahme

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

{
  "etag": "90dd86e2885440f3af9398ca392095b9",
  "name": "{name}",
  "status": "ready",
  ...
}

Das Wiederherstellen einer Momentaufnahme, die sich derzeit im Zustand provisioning oder failed befindet, ist ein ungültiger Vorgang.

Antwort:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json; charset="utf-8"

{
    "type": "https://azconfig.io/errors/invalid-state",
    "title": "Target resource state invalid.",
    "detail": "The target resource is not in a valid state to perform the requested operation.",
    "status": 409
}

Archivieren/Wiederherstellen einer Momentaufnahme (bedingt)

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

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

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json
If-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

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

PATCH /snapshots/{name}?api-version={api-version} HTTP/1.1
Content-Type: application/vnd.microsoft.appconfig.snapshot+json;
If-None-Match: "4f6dd610dd5e4deebc7fbaef685fb903"

Antworten

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

Oder

HTTP/1.1 412 PreconditionFailed

Auflisten der Schlüssel-Wert-Paare der Momentaufnahme

Erforderlich: {name}, {api-version}

GET /kv?snapshot={name}&api-version={api-version}

Hinweis

Der Versuch, die Elemente einer Momentaufnahme aufzulisten, die sich nicht im Zustand ready oder archived befindet, führt zu einer Antwort mit einer leeren Liste.

Anfordern bestimmter Felder

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

Freigeben über

Snapshot

Operations

Voraussetzungen

Syntax

Abrufen einer Momentaufnahme

Abrufen (bedingt)

Auflisten von Momentaufnahmen

Filtern

Unterstützte Filter

Anfordern bestimmter Felder

Erstellen einer Momentaufnahme

Abfragen der Momentaufnahmeerstellung

Archiv (Patch)

Wiederherstellen (Patch)

Archivieren/Wiederherstellen einer Momentaufnahme (bedingt)

Auflisten der Schlüssel-Wert-Paare der Momentaufnahme

Anfordern bestimmter Felder

Feedback

Zusätzliche Ressourcen