Compartilhar via

Instantâneo

  • Artigo

O recurso de instantâneo não está disponível na versão 1.0 da API.

Um instantâneo é um recurso identificado exclusivamente pelo nome. Confira os detalhes de cada operação.

Operações

  • Obter
  • Listar várias
  • Criar
  • Arquivar/recuperar
  • Listar chave-valores

Pré-requisitos

  • Todas as solicitações HTTP deverão ser autenticadas. Confira a seção autenticação.
  • Todas as solicitações HTTP deverão fornecer uma api-version explícita. Confira a seção controle de versão.

Sintaxe

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

Obter instantâneo

Obrigatório: {name}, {api-version}

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

Respostas:

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
}

Se um instantâneo com o nome fornecido não existir, a seguinte resposta será retornada:

HTTP/1.1 404 Not Found

Obter (condicionalmente)

Para melhorar o cache do cliente, use os cabeçalhos de solicitação If-Match ou If-None-Match. O argumento etag faz parte da representação de instantâneo. Para obter mais informações, confira as seções 14.24 e 14.26.

A solicitação a seguir recupera o instantâneo somente se a representação atual não corresponder ao etag especificado:

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

Respostas:

HTTP/1.1 304 NotModified

Ou

HTTP/1.1 200 OK

Listar instantâneos

Opcional: name (Se não for especificado, implica qualquer nome.) Opcional: status (Se não for especificado, implica qualquer status.)

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

Resposta:

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

Para obter mais opções, consulte a seção "Filtragem" mais adiante neste artigo.

Paginação

O resultado será paginado se o número de itens retornados exceder o limite de resposta. Siga os cabeçalhos de resposta opcionais Link e use rel="next" para navegação. Como alternativa, o conteúdo fornece o próximo link da propriedade @nextLink. O URI vinculado inclui o argumento api-version.

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

Resposta:

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

Filtragem

Há suporte para uma combinação de filtragens name e status. Use os parâmetros de cadeia de caracteres de consulta opcionais name e status.

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

Filtros com suporte

Filtro de nome Efeito
name é omitido ou name=* Corresponde a instantâneos com qualquer nome
name=abc Corresponde a um instantâneo chamado abc
name=abc* Corresponde aos instantâneos com nomes que começam com abc
name=abc,xyz Corresponde aos instantâneos com nomes abc ou xyz (limitado a 5 CSVs)
Filtro de status Efeito
status é omitido ou status=* Corresponde aos instantâneos com qualquer status
status=ready Corresponde aos instantâneos com um status pronto
status=ready,archived Corresponde a instantâneos com status prontos ou arquivados (limitado a 5 CSV)

Caracteres reservados

*, \, ,

Caso um caractere reservado faça parte do valor, ele deverá ser ignorado usando \{Reserved Character}. Caracteres não reservados também podem ser escapados.

Validação de filtro

Se a validação do filtro falhar, a resposta será HTTP 400 com detalhes do erro:

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
}

Exemplos

  • Tudo

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

  • O nome do snapshot começa com abc

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

  • O nome do instantâneo começa com abc e o status é igual a pronto ou arquivado

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

Campos específicos da solicitação

Use o parâmetro opcional de cadeia de caracteres de consulta $select e forneça uma lista separada por vírgulas dos campos solicitados. Caso o parâmetro $select seja omitido, a resposta conterá o conjunto padrão.

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

Create snapshot

parameters

Nome da propriedade Obrigatório Valor padrão Validação
name sim N/D Comprimento
     Máximo: 256
filtros sim N/D Contagem
     Mínimo: 1
     Máximo: 3
filters[<index>].key sim N/D
filters[<index>].label não nulo Os filtros de rótulo de várias correspondências (por exemplo: "*", "vírgula, separado") não são compatíveis com o tipo de composição "chave".
marcas não {}
composition_type não chave
retention_period não Camada padrão
     2592000 (30 dias)
Camada gratuita
     604800 (sete dias)		 Camada padrão
     Mínimo: 3600 (uma hora)
     Máximo: 7776000 (90 dias)
Camada gratuita
     Mínimo: 3600 (uma hora)
     Máximo: 604800 (sete dias)		 
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
}

Respostas:

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
}
Nome da propriedade Obrigatório Valor padrão Validação
name sim N/D Comprimento
     Máximo: 256
filtros sim N/D Contagem
     Mínimo: 1
     Máximo: 3
filters[<index>].key sim N/D
filters[<index>].label não nulo Os filtros de rótulo de várias correspondências (por exemplo: "*", "vírgula, separado") não são compatíveis com o tipo de composição "chave".
filtros[<índice>].tags não nulo Contagem
     Mínimo: 0
     Máximo: 5
marcas não {}
composition_type não chave
retention_period não Camada padrão
     2592000 (30 dias)
Camada gratuita
     604800 (7 dias)		 Camada padrão
     Mínimo: 3600 (1 hora)
     Máximo: 7776000 (90 dias)
Camada gratuita
     Mínimo: 3600 (1 hora)
     Máximo: 604800 (7 dias)		 
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
}

Respostas:

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
}

O status do instantâneo recém-criado é provisioning. Depois que o snapshot é totalmente provisionado, o status é atualizado para ready. Os clientes podem sondar o instantâneo para aguardar o instantâneo estar pronto antes de listar seus valores-chave associados. Para consultar informações adicionais sobre a operação, consulte a seção criação de instantâneo de sondagem.

Se o snapshot já existir, a seguinte resposta será retornada:

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

Criação de instantâneo de sondagem

A resposta de uma solicitação de criação instantâneo retorna um cabeçalho Operation-Location.

Respostas:

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

O status da operação de provisionamento de instantâneo pode ser encontrado no URI contido em Operation-Location. Os clientes podem sondar esse objeto de status para garantir que um instantâneo seja provisionado antes de listar seus valores-chave associados.

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

Resposta:

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

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

Se ocorrer algum erro durante o provisionamento do instantâneo, a error propriedade conterá detalhes que descrevem o erro.

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

Arquivo morto (Patch)

Uma instantâneo no estado ready pode ser arquivado. Um snapshot arquivado recebe uma data de expiração, com base no período de retenção estabelecido no momento de sua criação. Depois que a data de validade for aprovada, o instantâneo será excluído permanentemente. A qualquer momento antes da data de validade, os itens do instantâneo ainda podem ser listados.

Arquivar um instantâneo que já está archived não afeta o instantâneo.

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

{
  "status": "archived"
}

Resposta: retornar o instantâneo arquivado

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

Arquivar um instantâneo que está atualmente no estado provisioning ou failed é uma operação inválida.

Resposta:

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
}

Recuperar (Patch)

Uma instantâneo no estado archived pode ser recuperado. Depois que o snapshot é recuperado, a data de expiração do snapshot é removida.

Arquivar um instantâneo que já está ready não afeta o instantâneo.

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

{
  "status": "ready"
}

Resposta: retornar o instantâneo recuperado

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

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

Recuperar um instantâneo que está atualmente no estado provisioning ou failed é uma operação inválida.

Resposta:

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
}

Arquivar/recuperar instantâneo (condicionalmente)

Para evitar condições de corrida, use os cabeçalhos de solicitação If-Match ou If-None-Match. O argumento etag faz parte da representação de instantâneo. Se If-Match ou If-None-Match forem omitidos, a operação é incondicional.

A resposta a seguir atualiza o recurso somente se a representação atual corresponder ao etag especificado:

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

A resposta a seguir atualiza o recurso somente se a representação atual não corresponder ao etag especificado:

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

Respostas

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

Ou

HTTP/1.1 412 PreconditionFailed

Listar instantâneo valores-chave

Obrigatório: {name}, {api-version}

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

Observação

Tentar listar os itens de um instantâneo que não está no estado ready ou archived resultará em uma resposta de lista vazia.

Campos específicos da solicitação

Use o parâmetro opcional de cadeia de caracteres de consulta $select e forneça uma lista separada por vírgulas dos campos solicitados. Caso o parâmetro $select seja omitido, a resposta conterá o conjunto padrão.

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