Teilen über

Snapshot

  • Artikel

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

Dieser Artikel bezieht sich auf die API-Version 2022-11-01-preview.

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

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 weiter unten im Abschnitt „Filtern“ dieses Artikels.

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 reservierten Zeichen können ebenfalls mit Escapezeichen versehen werden.

Filterüberprüfung

Im Fall eines Fehlers bei der Filterüberprüfung ist die Antwort ein HTTP-Fehler 400 mit Details:

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
     Höchstwert: 256
Filter ja – Anzahl
     Mindestwert: 1
     Höchstwert: 3
filters[<index>].key ja –
tags Nein {}
filters[<index>].label nein NULL Bezeichnungsfilter mit mehreren Übereinstimmungen (z. B. „*“, „komma,getrennt“) werden beim Kompositionstyp „key“ nicht unterstützt.
composition_type nein Schlüssel
retention_period Nein Standard-Tarif
     2592000 (30 Tage)
Free-Tarif
     604800 (7 Tage)		 Standard-Tarif
     Mindestwert: 3600 (1 Stunde)
     Höchstwert: 7776000 (90 Tage)
Free-Tarif
     Mindestwert: 3600 (1 Stunde)
     Höchstwert: 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": {                           // 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
}

Der Status der neu erstellten Momentaufnahme lautet „Bereitstellung“. Sobald die Momentaufnahme vollständig bereitgestellt wurde, wird der Status auf „bereit“ aktualisiert. 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, erhalten Sie die folgende Antwort:

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, die den Fehler beschreiben.

{
    "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, das auf dem Aufbewahrungszeitraum basiert, der zum Zeitpunkt der Erstellung festgelegt 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. Sobald 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

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?snapshot={name}&$select=key,value&api-version={api-version} HTTP/1.1