Compartir a través de

Depurador de

  • Artículo

Una instantánea es un recurso identificado de forma única por su nombre. Revise los detalles para cada operación.

Este artículo se aplica a la API versión 2022-11-01 versión preliminar.

Operations

  • Obtener
  • Enumerar varios
  • Crear
  • Archivo y recuperación
  • Enumeración de pares clave-valor

Requisitos previos

  • Se deben autenticar todas las solicitudes HTTP. Consulte la sección Autenticación.
  • Todas las solicitudes HTTP deben proporcionar parámetros api-version explícitos. Consulte la sección Control de versiones.

Sintaxis

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

Obtención de la instantánea

Obligatorio: {name}, {api-version}

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

Respuestas:

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 no existe una instantánea con el nombre proporcionado, se devuelve la siguiente respuesta:

HTTP/1.1 404 Not Found

Obtención (de manera condicional)

Para mejorar el almacenamiento en caché del cliente, use los encabezados de solicitud If-Match o If-None-Match. El argumento etag forma parte de la representación de la instantánea. Para obtener más información, consulte las secciones 14.24 y 14.26.

La siguiente solicitud recupera la instantánea solo si la representación actual no coincide con el argumento etag especificado:

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

Respuestas:

HTTP/1.1 304 NotModified

or

HTTP/1.1 200 OK

Lista de instantáneas

Opcional: name (si no se especifica, sugiere cualquier nombre). Opcional: status (si no se especifica, sugiere cualquier estado).

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

Respuesta:

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

Para obtener más opciones, consulte la sección "Filtrado" más adelante en este artículo.

Paginación

El resultado se pagina si el número de elementos devueltos supera el límite de respuesta. Siga los encabezados de respuesta Link opcionales y use rel="next" para la navegación. Como alternativa, el contenido proporciona un vínculo Siguiente en forma de propiedad @nextLink. El URI vinculado incluye el argumento api-version.

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

Respuesta:

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

Filtrado

Se admite una combinación de filtrado de name y status. Use los parámetros de cadena de consulta opcionales name y status.

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

Filtros admitidos

Filtro de nombres Efecto
se omite name o name=* Coincide con instantáneas con cualquier nombre
name=abc Coincide con una instantánea denominada abc
name=abc* Coincide con instantáneas con nombres que empiezan por abc
name=abc,xyz Coincide con instantáneas con nombres abc o xyz (limitado a 5 archivos CSV)
Filtro de estado Efecto
se omite status o status=* Coincide con instantáneas con cualquier estado
status=ready Coincide con instantáneas con estado listo
status=ready,archived Coincide con instantáneas con estado listo o archivado (limitado a 5 archivos CSV)

Caracteres reservados

*, \, ,

Si un carácter reservado forma parte del valor, se debe escapar mediante \{Reserved Character}. Los caracteres no reservados también se pueden escapar.

Validación del filtro

En el caso de un error de validación del filtro, la respuesta es HTTP 400 con detalles del error:

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
}

Ejemplos

  • All

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

  • El nombre de la clave comienza por abc

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

  • El nombre de la instantánea comienza por abc y el estado es igual a listo o archivado

    GET /snapshot?name=abc*&status=ready,archived&api-version={api-version}

Solicitud de campos específicos

Use el parámetro de cadena de consulta opcional $select y proporcione una lista separada por comas de campos solicitados. Si se omite el parámetro $select, la respuesta contiene el conjunto predeterminado.

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

Create snapshot

parameters

Nombre de propiedad Obligatorio Valor predeterminado Validación
name sí N/D Length
     máximo: 256
filters sí N/D Count
     mínimo: 1
     máximo: 3
filters[<index>].key sí N/D
etiquetas no {}
filters[<index>].label no null Los filtros de etiqueta de varias coincidencias (por ejemplo: "*", "separado por comas") no se admiten con el tipo de composición "key".
composition_type no key
retention_period no Nivel Standard
     2592000 (30 días)
Nivel Gratis
     604800 (7 días)		 Nivel Standard
     mínimo: 3600 (1 hora)
     máximo: 7776000 (90 días)
Nivel Gratis
     mínimo: 3600 (1 hora)
     máximo: 604800 (7 días)		 
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
}

Respuestas:

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
}

El estado de la instantánea recién creada será "aprovisionamiento". Una vez que la instantánea esté completamente aprovisionada, el estado se actualizará a "listo". Los clientes pueden sondear la instantánea para esperar a que esté lista antes de enumerar sus valores de clave asociados. Para consultar información adicional sobre la operación, consulte la sección sondeo de creación de instantáneas.

Si la instantánea ya existe, recibirá la siguiente respuesta:

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

Sondeo de creación de instantáneas

La respuesta de una solicitud de creación de instantáneas devuelve un encabezado Operation-Location.

Respuestas:

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

El estado de la operación de aprovisionamiento de instantáneas se puede encontrar en el URI incluido en Operation-Location. Los clientes pueden sondear este objeto de estado para asegurarse de que se aprovisiona una instantánea antes de enumerar sus valores de clave asociados.

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

Respuesta:

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

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

Si se produce algún error durante el aprovisionamiento de la instantánea, la propiedad error contendrá detalles que describen el error.

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

Archivo (revisión)

Se puede archivar una instantánea en el estado ready. A una instantánea archivada se le asignará una fecha de expiración en función del período de retención establecido en el momento de su creación. Una vez superada la fecha de expiración, la instantánea se eliminará permanentemente. En cualquier momento antes de la fecha de expiración, los elementos de la instantánea todavía se pueden mostrar.

Archivar una instantánea que ya está archived no afecta a la instantánea.

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

{
  "status": "archived"
}

Respuesta: Devolver la instantánea archivada

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

Archivar una instantánea que se encuentra actualmente en el estado provisioning o failed es una operación no válida.

Respuesta:

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
}

Recuperación (revisión)

Se puede recuperar una instantánea en el estado archived. Una vez recuperada la instantánea, se quita la fecha de expiración de la instantánea.

Recuperar una instantánea que ya está ready no afecta a la instantánea.

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

{
  "status": "ready"
}

Respuesta: Devolver la instantánea recuperada

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

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

Recuperar una instantánea que se encuentra actualmente en el estado provisioning o failed es una operación no válida.

Respuesta:

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
}

Archivado o recuperación de una instantánea (condicionalmente)

Para evitar condiciones de carrera, use los encabezados de solicitud If-Match o If-None-Match. El argumento etag forma parte de la representación de la instantánea. Si se omiten If-Match o If-None-Match, la operación es incondicional.

La siguiente respuesta actualiza el recurso solo si la representación actual coincide con el valor de etag especificado:

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

La siguiente respuesta actualiza el recurso solo si la representación actual no coincide con el valor de etag especificado:

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

Respuestas

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

or

HTTP/1.1 412 PreconditionFailed

Enumeración de los valores clave-valor de instantánea

Obligatorio: {name}, {api-version}

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

Nota

Si se intenta enumerar los elementos de una instantánea que no está en el estado ready o archived, se producirá una respuesta de lista vacía.

Solicitud de campos específicos

Use el parámetro de cadena de consulta opcional $select y proporcione una lista separada por comas de campos solicitados. Si se omite el parámetro $select, la respuesta contiene el conjunto predeterminado.

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