Partilhar via


Instantâneo

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

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

Operações

  • Obtenção
  • Listar vários
  • Criar
  • Arquivar/Recuperar
  • Listar valores-chave

Pré-requisitos

  • Todas as solicitações HTTP devem ser autenticadas. Consulte a seção de autenticação .
  • Todas as solicitações HTTP devem fornecer arquivos .api-version Consulte a seção de 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 If-Match ou If-None-Match solicite cabeçalhos. O etag argumento faz parte da representação do instantâneo. Para mais informações, ver secções 14.24 e 14.26.

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

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 um próximo link na forma da @nextLink propriedade. O URI vinculado inclui o api-version argumento.

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

Uma combinação de name e status filtragem é suportada. Use os parâmetros opcionais name e status de seqüência de caracteres de consulta.

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

Filtros suportados

Filtro de nome Efeito
name for omitida ou name=* Corresponde instantâneos com qualquer nome
name=abc Corresponde a um instantâneo chamado abc
name=abc* Corresponde instantâneos com nomes que começam com abc
name=abc,xyz Corresponde instantâneos com nomes abc ou xyz (limitado a 5 CSV)
Filtro de status Efeito
status for omitida ou status=* Corresponde instantâneos com qualquer status
status=ready Corresponde instantâneos com um status pronto
status=ready,archived Corresponde instantâneos com status pronto ou arquivado (limitado a 5 CSV)

Caracteres reservados

*, \, ,

Se um caractere reservado fizer parte do valor, ele deverá ser escapado usando \{Reserved Character}. Caracteres não reservados também podem ser escapados.

Validação do 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

  • Todos

    GET /snapshots?api-version={api-version}
    
  • O nome do instantâneo 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}
    

Solicitar campos específicos

Use o parâmetro opcional $select de seqüência de caracteres de consulta e forneça uma lista separada por vírgulas de campos solicitados. Se o $select parâmetro for omitido, a resposta conterá o conjunto padrão.

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

Criar instantâneo

parameters

Nome de Propriedade Necessário Default value Validação
nome sim n/d Comprimento
     Máximo: 256
filtros sim n/d Contagem
     Mínimo: 1
     Máximo: 3
filtros[<índice>].key sim n/d
filtros[<índice>].label não nulo Os filtros de etiquetas multicorrespondência (por exemplo: "*", "vírgula, separado") não são suportados com o tipo de composição 'chave'.
etiquetas não {}
composition_type não key
retention_period não Nível padrão
     2592000 (30 dias)
Nível gratuito
     604800 (sete dias)
Nível padrão
     Mínimo: 3600 (uma hora)
     Máximo: 7776000 (90 dias)
Nível gratuito
     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 de Propriedade Necessário Default value Validação
nome sim n/d Comprimento
     Máximo: 256
filtros sim n/d Contagem
     Mínimo: 1
     Máximo: 3
filtros[<índice>].key sim n/d
filtros[<índice>].label não nulo Os filtros de etiquetas multicorrespondência (por exemplo: "*", "vírgula, separado") não são suportados com o tipo de composição 'chave'.
filtros[<índice>].tags não nulo Contagem
     Mínimo: 0
     Máximo: 5
etiquetas não {}
composition_type não key
retention_period não Nível padrão
     2592000 (30 dias)
Nível gratuito
     604800 (7 dias)
Nível padrão
     Mínimo: 3600 (1 hora)
     Máximo: 7776000 (90 dias)
Nível gratuito
     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. Quando o snapshot é totalmente provisionado, o status é atualizado para ready. Os clientes podem sondar o snapshot para aguardar que ele esteja pronto antes de listar seus valores-chave associados. Para consultar informações adicionais sobre a operação, consulte a seção de criação de instantâneo de sondagem.

Se o instantâneo 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âneos de sondagem

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

Respostas:

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

O status da operação de provisionamento de snapshot 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 de 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 (Patch)

Um instantâneo no ready estado pode ser arquivado. Um instantâneo arquivado recebe uma data de validade, com base no período de retenção estabelecido no momento de sua criação. Depois que a data de expiração passar, 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 snapshot que já archived está não afeta o snapshot.

  • 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 provisioning estado 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)

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

A recuperação de um snapshot que já ready está não afeta o snapshot.

  • 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 snapshot recuperado

HTTP/1.1 200 OK
Content-Type: application/vnd.microsoft.appconfig.snapshot+json; charset=utf-8
...
{
  "etag": "90dd86e2885440f3af9398ca392095b9",
  "name": "{name}",
  "status": "ready",
  ...
}

A recuperação de um instantâneo que está atualmente no provisioning estado 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 snapshot (condicionalmente)

Para evitar condições de corrida, use If-Match ou If-None-Match solicite cabeçalhos. O etag argumento faz parte da representação do 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 à especificada etag:

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 à especificada etag:

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 valores-chave de instantâneo

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

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

Nota

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

Solicitar campos específicos

Use o parâmetro opcional $select de seqüência de caracteres de consulta e forneça uma lista separada por vírgulas de campos solicitados. Se o $select parâmetro for omitido, a resposta conterá o conjunto padrão.

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