Bandeiras de recursos aprimoradas

Flags de recursos aprimorados não estão disponíveis nesta versão da API.

Uma flag de característica aprimorada é um recurso identificado pela combinação única de name + label. label é opcional. Para referenciar explicitamente uma feature flag sem um rótulo, use \0 (URL codificada como %00). Para operações de lista, omitir label correspondências apresenta flags com qualquer etiqueta. Confira os detalhes de cada operação.

Importante

Endpoints de feature flag aprimorados estão disponíveis apenas na 2026-05-01-preview versão da API.

Para representações históricas, veja Revisões aprimoradas de flags de funcionalidades. Para listar rótulos associados a flags de recursos aprimorados, veja Rótulos.

Operations

  • Obter
  • Listar várias
  • Definir
  • Excluir

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

Sinalizador de recurso

{
  "etag": [string, optional, read-only],
  "name": [string, read-only],
  "enabled": [boolean],
  "label": [string, optional, read-only],
  "description": [string, optional],
  "conditions": [Conditions, optional],
  "variants": [array<Variant>, optional],
  "allocation": [Allocation, optional],
  "telemetry": [Telemetry, optional],
  "tags": [object<string, string>, optional],
  "last_modified": [datetime ISO 8601, optional, read-only]
}

Conditions

{
  "requirement_type": [string, enum("Any", "All"), optional],
  "filters": [array<FeatureFilter>, optional]
}

FeatureFilter

{
  "name": [string],
  "parameters": [object<string, string>, optional]
}

Variant

{
  "name": [string],
  "value": [string, optional],
  "content_type": [string, optional],
  "status_override": [string, enum("None", "Enabled", "Disabled"), optional]
}

Alocação

{
  "default_when_disabled": [string, optional],
  "default_when_enabled": [string, optional],
  "percentile": [array<PercentileAllocation>, optional],
  "user": [array<UserAllocation>, optional],
  "group": [array<GroupAllocation>, optional],
  "seed": [string, optional]
}

PercentileAllocation

{
  "variant": [string],
  "from": [number, range(0, 100)],
  "to": [number, range(0, 100)]
}

UserAllocation

{
  "variant": [string],
  "users": [array<string>]
}

GroupAllocation

{
  "variant": [string],
  "groups": [array<string>]
}

Telemetry

{
  "enabled": [boolean],
  "metadata": [object<string, string>, optional]
}

Obter a flag de característica

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

Opcional: label (Se omitido, implica uma flag de característica sem rótulo.)

Opcional: tags (Se não for especificado, implica em qualquer tag.)

Os name e label devem coincidir exatamente antes tags de serem aplicados para filtragem adicional. Para obter mais opções, consulte a seção "Filtragem" mais adiante neste artigo.

GET /ff/{name}?label={label}&tags={tagFilter1}&tags={tagFilter2}&api-version={api-version}

Respostas:

HTTP/1.1 200 OK
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ff"; charset=utf-8
Last-Modified: Fri, 01 May 2026 16:52:32 GMT
ETag: "7XpB48ET4VAlB9068ft6fKMyA3m"
Sync-Token: zAJw6V16=NjotMSM3ODk3NjM=;sn=789763

{
  "etag": "7XpB48ET4VAlB9068ft6fKMyA3m",
  "name": "{name}",
  "enabled": true,
  "label": "{label}",
  "description": "{description}",
  "tags": {
    "t1": "value1"
  },
  "last_modified": "2026-05-01T16:52:32Z"
}

Se a feature flag não existir, a seguinte resposta é 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 etag argumento faz parte da representação da feature flag. Se ambos os cabeçalhos forem omitidos, a operação é incondicional.

A solicitação a seguir recupera a flag de característica somente se a representação atual não corresponder ao especificado etag:

GET /ff/{name}?label={label}&api-version={api-version} HTTP/1.1
Accept: application/json; profile="https://azconfig.io/mime-profiles/ff"
If-None-Match: "{etag}"

Respostas:

HTTP/1.1 304 Not Modified

ou

HTTP/1.1 200 OK

Lista de flags de recursos

Opcional: name (Se não especificado, implica qualquer nome de flag de funcionalidade.)

Opcional: label (se não especificado, implica qualquer rótulo.)

Opcional: tags (Se não for especificado, implica em qualquer tag.)

GET /ff?name=Test*&label=*&tags=tag1=value1&tags=tag2=value2&api-version={api-version} HTTP/1.1

Resposta:

HTTP/1.1 200 OK
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ffset"; charset=utf-8
ETag: "1PlB48ET4VAlB9068ft6fKMyA3m"
Sync-Token: zAJw6V16=NjotMSM3ODk3NjM=;sn=789763

{
  "items": [
    {
      "etag": "7XpB48ET4VAlB9068ft6fKMyA3m",
      "name": "{name}",
      "enabled": true,
      "label": "{label}",
      "tags": {
        "t1": "value1"
      },
      "last_modified": "2026-05-01T16:52:32Z"
    }
  ],
  "etag": "1PlB48ET4VAlB9068ft6fKMyA3m",
  "@nextLink": "{relative uri}"
}

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

Listar flags de características (condicionalmente)

Para melhorar o cache do cliente, use os cabeçalhos de solicitação If-Match ou If-None-Match. O etag argumento faz parte do corpo da lista de resposta e do cabeçalho. Se ambos os cabeçalhos forem omitidos, a operação é incondicional.

A requisição a seguir recupera flags de característica apenas se a representação atual corresponder à especificada etag:

GET /ff?name={name}&label={label}&api-version={api-version} HTTP/1.1
If-Match: "{etag}"

Respostas:

HTTP/1.1 412 Precondition Failed

ou

HTTP/1.1 200 OK

A solicitação a seguir recebe as flags de característica apenas se a representação atual não corresponder ao especificado etag:

GET /ff?name={name}&label={label}&api-version={api-version} HTTP/1.1
If-None-Match: "{etag}"

Respostas:

HTTP/1.1 304 Not Modified

ou

HTTP/1.1 200 OK

Pagination

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

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

Resposta:

HTTP/1.1 200 OK
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ffset"; charset=utf-8
Link: <{relative uri}>; rel="next"

{
  "items": [
    ...
  ],
  "@nextLink": "{relative uri}"
}

Filtragem

Há suporte para uma combinação de name, labele filtragem tags e filtragem. Use os parâmetros opcionais name, labele string tags de consulta. Vários filtros de tag podem ser fornecidos como parâmetros de string de consulta no tagName=tagValue formato. Os filtros de tags precisam ser uma correspondência exata.

GET /ff?name={name}&label={label}&tags={tagFilter1}&tags={tagFilter2}&api-version={api-version}

Filtros suportados

Filtro de nome Effect
name é omitido ou name=* Combina com qualquer nome de bandeira de destaque
name=abc Combina com uma bandeira principal chamada abc
name=abc* As partidas apresentam nomes de bandeiras que começam com abc
name=abc,xyz As partidas apresentam nomes de bandeiras abc ou xyz (limitado a 5 CSV)
Filtro de rótulo Effect
label é omitido ou label=* Corresponde a outra etiqueta
label=%00 As partidas apresentam bandeiras sem etiqueta
label=prod Corresponde ao rótulo prod
label=prod* Corresponde aos rótulos que começam com prod
label=prod,test Corresponde aos rótulos prod ou test (limitado a 5 CSVs)
Filtro de tags Effect
tags é omitido ou tags= Corresponde a qualquer tag
tags=group=app1 As partidas apresentam bandeiras que têm uma tag nomeada group com valor app1
tags=group=app1&tags=env=prod As partidas apresentam flags que têm uma tag nomeada group com valor app1 e uma tag nomeada env com valor prod (limitada a 5 filtros de tags)
tags=tag1=%00 As partidas apresentam bandeiras que têm uma tag nomeada tag1 com valor null
tags=tag1= As partidas apresentam flags que têm uma tag nomeada tag1 com um valor vazio

Caracteres reservados

*, \, ,

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

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
}

Examples

  • All

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

  • O nome da bandeira de destaque começa com abc e inclui todos os rótulos

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

  • O nome da flag de feature começa com abc e o rótulo é igual a v1 ou v2

    GET /ff?name=abc*&label=v1,v2&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. Corpos suportados são name, enabled, label, description, conditionsvariants, allocation, telemetry, tags, , last_modified, e etag.

GET /ff?$select=name,enabled,label&api-version={api-version} HTTP/1.1

O $select parâmetro é suportado por GET solicitações para uma única flag de característica e coleções de flags de características.

Acesso baseado em tempo

Obtenha uma representação do resultado como ele era anteriormente. Para saber mais, consulte a seção2.1.1. Ainda há suporte para paginação conforme definido anteriormente neste artigo.

GET /ff/{name}?label={label}&api-version={api-version} HTTP/1.1
Accept-Datetime: Sat, 01 Aug 2026 02:10:00 GMT

GET /ff?api-version={api-version} HTTP/1.1
Accept-Datetime: Sat, 01 Aug 2026 02:10:00 GMT

Definir flag de característica

  • Obrigatório: {name}, {api-version}
  • Opcional: label (Se não especificado, ou label=%00, implica uma flag de característica sem rótulo.)

A enabled propriedade é exigida no órgão do pedido. As descriptionpropriedades , conditions, variants, allocation, telemetry, e tags são opcionais. Não inclua name, label, etag, ou last_modified no corpo do pedido.

PUT /ff/{name}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ff"

{
  "enabled": true,
  "description": "{description}",
  "conditions": {
    "requirement_type": "All",
    "filters": [
      {
        "name": "Microsoft.Targeting",
        "parameters": {
          "Audience": "{\"Users\":[\"User1\",\"User2\"],\"Groups\":[{\"Name\":\"Ring0\",\"RolloutPercentage\":100}],\"DefaultRolloutPercentage\":20,\"Exclusion\":{\"Users\":[\"ExcludedUser\"],\"Groups\":[\"Ring1\"]}}"
        }
      }
    ]
  },
  "variants": [
    {
      "name": "On",
      "value": "true",
      "content_type": "application/json",
      "status_override": "None"
    },
    {
      "name": "Off",
      "value": "false",
      "content_type": "application/json",
      "status_override": "Disabled"
    }
  ],
  "allocation": {
    "default_when_disabled": "Off",
    "default_when_enabled": "On",
    "percentile": [
      {
        "variant": "On",
        "from": 0,
        "to": 80
      },
      {
        "variant": "Off",
        "from": 80,
        "to": 100
      }
    ],
    "seed": "{name}"
  },
  "telemetry": {
    "enabled": true,
    "metadata": {
      "Tags.Environment": "production"
    }
  },
  "tags": {
    "t1": "value1"
  }
}

Respostas:

HTTP/1.1 200 OK
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ff"; charset=utf-8
Last-Modified: Fri, 01 May 2026 16:52:32 GMT
ETag: "7XpB48ET4VAlB9068ft6fKMyA3m"
Sync-Token: zAJw6V16=NjotMSM3ODk3NjM=;sn=789763

{
  "etag": "7XpB48ET4VAlB9068ft6fKMyA3m",
  "name": "{name}",
  "enabled": true,
  "label": "{label}",
  "description": "{description}",
  "conditions": {
    "requirement_type": "All",
    "filters": [
      {
        "name": "Microsoft.Targeting",
        "parameters": {
          "Audience": "{\"Users\":[\"User1\",\"User2\"],\"Groups\":[{\"Name\":\"Ring0\",\"RolloutPercentage\":100}],\"DefaultRolloutPercentage\":20,\"Exclusion\":{\"Users\":[\"ExcludedUser\"],\"Groups\":[\"Ring1\"]}}"
        }
      }
    ]
  },
  "variants": [
    {
      "name": "On",
      "value": "true",
      "content_type": "application/json",
      "status_override": "None"
    },
    {
      "name": "Off",
      "value": "false",
      "content_type": "application/json",
      "status_override": "Disabled"
    }
  ],
  "allocation": {
    "default_when_disabled": "Off",
    "default_when_enabled": "On",
    "percentile": [
      {
        "variant": "On",
        "from": 0,
        "to": 80
      },
      {
        "variant": "Off",
        "from": 80,
        "to": 100
      }
    ],
    "seed": "{name}"
  },
  "telemetry": {
    "enabled": true,
    "metadata": {
      "Tags.Environment": "production"
    }
  },
  "tags": {
    "t1": "value1"
  },
  "last_modified": "2026-05-01T16:52:32Z"
}

Definir flag de característica (condicionalmente)

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

A solicitação a seguir define a feature flag somente se a representação atual corresponder à especificada etag:

PUT /ff/{name}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ff"
If-Match: "{etag}"

A solicitação a seguir define a feature flag somente se a representação atual não corresponder à especificada etag:

PUT /ff/{name}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ff"
If-None-Match: "{etag}"

A seguinte solicitação define a feature flag apenas se uma representação já existir:

PUT /ff/{name}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ff"
If-Match: "*"

A solicitação a seguir define a feature flag somente se uma representação ainda não existir:

PUT /ff/{name}?label={label}&api-version={api-version} HTTP/1.1
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ff"
If-None-Match: "*"

Respostas

HTTP/1.1 200 OK
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ff"; charset=utf-8
Last-Modified: Fri, 01 May 2026 16:52:32 GMT
ETag: "7XpB48ET4VAlB9068ft6fKMyA3m"
Sync-Token: zAJw6V16=NjotMSM3ODk3NjM=;sn=789763
...

ou

HTTP/1.1 412 Precondition Failed

Excluir

  • Obrigatório: {name}, {api-version}
  • Opcional: label (Se não especificado, ou label=%00, implica uma flag de característica sem rótulo.)
DELETE /ff/{name}?label={label}&api-version={api-version} HTTP/1.1

Resposta: Devolva a flag de feature deletada, ou nenhuma, se a flag de feature não existir.

HTTP/1.1 200 OK
Content-Type: application/json; profile="https://azconfig.io/mime-profiles/ff"; charset=utf-8
Last-Modified: Fri, 01 May 2026 16:52:32 GMT
ETag: "7XpB48ET4VAlB9068ft6fKMyA3m"
Sync-Token: zAJw6V16=NjotMSM3ODk3NjM=;sn=789763
...

ou

HTTP/1.1 204 No Content

Flag de exclusão de recurso (condicionalmente)

Isso é semelhante à seção "Definir flag de característica (condicionalmente)" anteriormente neste artigo. A operação de exclusão suporta o If-Match cabeçalho de requisição.

Para informações sobre cabeçalhos de requisição e resposta compartilhados pelas operações do plano de dados do App Configuration, veja Cabeçalhos comuns.

  • Last updated on