Instantané

Article
08/10/2024

La ressource d’instantané n’est pas disponible dans l’API version 1.0.

Un instantané est une ressource identifiée uniquement par son nom. Consultez les détails de chaque opération.

Opérations

Obtenir
Liste multiple
Créer
Archiver/récupérer
Lister les paires clé-valeur

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

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

Obtenir un instantané

Obligatoire : {name}, {api-version}

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

Réponses :

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
}

Si un instantané portant le nom fourni 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 de l’instantané. Pour plus d’informations, consultez les sections 14.24 et 14.26.

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

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

Réponses :

HTTP/1.1 304 NotModified

HTTP/1.1 200 OK

Répertorier des instantanés

Facultatif : name (Si non spécifié, cela implique n’importe quelle nom.) Facultatif : status (Si non spécifié, cela implique n’importe quel statut.)

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

Réponse :

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

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

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

Réponse :

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

Filtrage

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

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

Filtres pris en charge

Filtre de nom	Résultat
`name` est omis ou `name=*`	Correspond aux instantanés avec n’importe quel nom
`name=abc`	Correspond à un instantané au nom de abc
`name=abc*`	Correspond aux instantanés dont le nom commence par abc
`name=abc,xyz`	Correspond aux instantanés dénommés abc ou xyz (limités à 5 CSV)

Filtre d'état	Résultat
`status` est omis ou `status=*`	Correspond aux instantanés avec n’importe quel état
`status=ready`	Correspond aux instantanés avec un statut prêt
`status=ready,archived`	Correspond aux instantanés avec des statuts prêts ou archivés (limité à 5 CSV)

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

Le nom de l’instantané commence par abc

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

Le nom de l’instantané commence par abc et le statut est prêt ou archivé

GET /snapshot?name=abc*&status=ready,archived&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 /snapshot?$select=name,status&api-version={api-version} HTTP/1.1

Créer une capture instantanée

parameters

Nom de la propriété	Obligatoire	Valeur par défaut	Validation
name	Oui	n/a	Longueur Maximum : 256
filtres	Oui	n/a	Count Minimum : 1 Maximum : 3
filters[<index>].key	Oui	n/a
filters[<index>].label	non	null	Les filtres d’étiquettes à correspondance multiple (par exemple : « * », « virgule, séparée ») ne sont pas pris en charge avec le type de composition « key ».
tags	non	{}
composition_type	non	key
retention_period	non	Niveau standard 2592000 (30 jours) Niveau Gratuit 604800 (sept jours)	Niveau standard Minimum : 3600 (une heure) Maximum : 7776000 (90 jours) Niveau Gratuit Minimum : 3600 (une heure) Maximum : 604800 (sept jours)

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
}

Réponses :

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
}

Nom de la propriété	Obligatoire	Valeur par défaut	Validation
name	Oui	n/a	Longueur Maximum : 256
filtres	Oui	n/a	Count Minimum : 1 Maximum : 3
filters[<index>].key	Oui	n/a
filters[<index>].label	non	null	Les filtres d’étiquettes à correspondance multiple (par exemple : « * », « virgule, séparée ») ne sont pas pris en charge avec le type de composition « key ».
filters[<index>].tags	non	null	Count Minimum : 0 Maximum : 5
tags	non	{}
composition_type	non	key
retention_period	non	Niveau standard 2592000 (30 jours) Niveau Gratuit 604800 (7 jours)	Niveau standard Minimum : 3600 (1 heure) Maximum : 7776000 (90 jours) Niveau Gratuit Minimum : 3600 (1 heure) Maximum : 604800 (7 jours)

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
}

Réponses :

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
}

L’état de l’instantané nouvellement créé est provisioning. Une fois que l’instantané est entièrement approvisionné, l’état est mis à jour vers ready. Les clients peuvent interroger l’instantané pour attendre que l’instantané soit prêt avant de répertorier les valeurs de clé associées. Pour interroger des informations supplémentaires sur l’opération, reportez-vous à la section de création d’instantané d’interrogation.

Si l’instantané existe déjà, 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/already-exists",
    "title": "The resource already exists.",
    "status": 409,
    "detail": ""
}

Création d’instantané d’interrogation

La réponse d’une requête de création d’instantané retourne un Operation-Location en-tête.

Réponses :

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

L’état de l’opération d’approvisionnement d’instantané se trouve dans l’URI contenu dans Operation-Location. Les clients peuvent interroger cet objet d’état pour s’assurer qu’un instantané est provisionné avant de répertorier les valeurs de clés associées.

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

Réponse :

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

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

Si une erreur se produit pendant l’approvisionnement de l’instantané, la error propriété contient des détails décrivant l’erreur.

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

Archive (patch)

Une instantané à l’état ready peut être archivé. Un instantané archivé reçoit une date d’expiration, en fonction de la période de rétention établie au moment de sa création. Une fois la date d’expiration passée, l’instantané est définitivement supprimé. À tout moment avant la date d’expiration, les éléments de l’instantané peuvent toujours être répertoriés.

L’archivage d’un instantané qui est déjà archived n’affecte pas l’instantané.

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

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

{
  "status": "archived"
}

Réponse: Retourner l’instantané archivé

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

L’archivage d’un instantané actuellement à l’état provisioning ou failed est une opération incorrecte.

Réponse :

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
}

Récupérer (patch)

Un instantané à l’état archived peut être archivé. Une fois l’instantané récupéré, la date d’expiration de l’instantané est supprimée.

La récupération d’un instantané qui est déjà ready n’affecte pas l’instantané.

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

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

{
  "status": "ready"
}

Réponse: Retourner l’instantané récupéré

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

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

La récupération d’un instantané actuellement à l’état provisioning ou failed est une opération incorrecte.

Réponse :

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
}

Archiver/récupérer un instantané (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 de l’instantané. Si If-Match et If-None-Match sont omis, l’opération est inconditionnelle.

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

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

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

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

Réponses

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

HTTP/1.1 412 PreconditionFailed

Répertorier un instantané clés-valeurs

Obligatoire : {name}, {api-version}

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

Notes

Toute tentative de répertorier des éléments d’un instantané qui n’est pas dans l’état ready ou archived entraîne une réponse de liste vide.

Champs spécifiques de la demande

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

Partager via

Instantané

Opérations

Prérequis

Syntaxe

Obtenir un instantané

Obtenir (de manière conditionnelle)

Répertorier des instantanés

Filtrage

Filtres pris en charge

Champs spécifiques de la demande

Créer une capture instantanée

Création d’instantané d’interrogation

Archive (patch)

Récupérer (patch)

Archiver/récupérer un instantané (de manière conditionnelle)

Répertorier un instantané clés-valeurs

Champs spécifiques de la demande

Commentaires

Ressources supplémentaires