Partager via

Instantané

  • Article

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

Cet article s’applique à la version 2022-11-01-préversion de l’API.

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

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

ou

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 obtenir des options supplémentaires, 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 une erreur de validation de filtre se produit, la réponse est HTTP 400 avec les détails de l’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
tags non {}
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 ».
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": {                           // 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
}

Le statut de l’instantané nouvellement créé sera « provisionnement ». Une fois l’instantané entièrement approvisionné, le statut passe à « prêt ». 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à, vous recevrez la réponse suivante :

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é contiendra 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é. Une date d’expiration est affectée à un instantané archivé, 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
...

ou

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

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