Flags de funcionalidades melhoradas

Os flags de funcionalidades melhoradas não estão disponíveis nesta versão da API.

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

Importante

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

Para representações históricas, veja Revisões melhoradas das bandeiras de funcionalidades. Para listar etiquetas associadas a flags de funcionalidades melhoradas, consulte Etiquetas.

Operations

  • Obtenção
  • Listar vários
  • Definir
  • Delete

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.

Syntax

Flag de funcionalidade

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

Repartiçã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 flag de funcionalidade

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

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

Opcional: tags (Se não for especificado, implica quaisquer tags.)

Os name e label devem corresponder 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, é devolvida a seguinte resposta:

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 da feature flag. Se ambos os cabeçalhos forem omitidos, a operação é incondicional.

O pedido seguinte recupera a feature flag apenas se a representação atual não corresponder à especificada 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 bandeiras de características

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

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

Opcional: tags (Se não for especificado, implica quaisquer tags.)

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 If-Match ou If-None-Match solicite cabeçalhos. O etag argumento faz parte do corpo da resposta da lista e do cabeçalho. Se ambos os cabeçalhos forem omitidos, a operação é incondicional.

O pedido seguinte recupera as feature flags 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

O pedido seguinte recebe as bandeiras de funcionalidade 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 sob a forma da @nextLink propriedade. O URI vinculado inclui o api-version argumento.

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 tags filtragem. Use os parâmetros opcionais name, labele query tags string parâmetros. Vários filtros de tag podem ser fornecidos como parâmetros de cadeia de caracteres de tagName=tagValue consulta no formato. Os filtros de tags devem 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 for omitida ou name=* Corresponde a qualquer nome de bandeira de destaque
name=abc Corresponde a uma bandeira principal chamada abc
name=abc* Os jogos apresentam nomes de bandeiras que começam por abc
name=abc,xyz Os jogos apresentam nomes de bandeiras abc ou xyz (limitado a 5 CSV)
Filtro de etiquetas Effect
label for omitida ou label=* Corresponde a qualquer rótulo
label=%00 Os combates apresentam bandeiras sem etiqueta
label=prod Corresponde ao rótulo prod
label=prod* Corresponde a rótulos que começam com prod
label=prod,test Corresponde a rótulos prod ou teste (limitado a 5 CSV)
Filtro de tags Effect
tags for omitida ou tags= Corresponde a qualquer tag
tags=group=app1 As partidas apresentam bandeiras que têm uma etiqueta nomeada group com valor app1
tags=group=app1&tags=env=prod As correspondências apresentam flags que têm uma etiqueta nomeada group com valor app1 e uma etiqueta nomeada env com valor prod (limitada a 5 filtros de etiquetas)
tags=tag1=%00 As partidas apresentam bandeiras que têm uma etiqueta nomeada tag1 com valor null
tags=tag1= As partidas apresentam bandeiras que têm uma etiqueta nomeada tag1 com um valor vazio

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
}

Examples

  • Todos

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

  • O nome da bandeira de destaque começa por abc e inclui todas as etiquetas

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

  • O nome da bandeira de funcionalidades começa por abc e o rótulo é igual a v1 ou v2

    GET /ff?name=abc*&label=v1,v2&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. Os corpos suportados são name, enabled, label, conditionsdescription, variants, 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 pedidos para uma única feature flag e coleções de feature flags.

Acesso baseado no tempo

Obter uma representação do resultado como era em um momento passado. Para mais informações, ver secção 2.1.1. A paginação ainda é suportada, 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 o flag de característica

  • Obrigatório: {name}, {api-version}
  • Opcional: label (Se não for especificado, ou label=%00, implica uma feature flag sem etiqueta.)

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, nem 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 a feature flag (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 da feature flag. Se ambos os cabeçalhos forem omitidos, a operação é incondicional.

O pedido seguinte define a feature flag apenas 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}"

O pedido seguinte define a feature flag apenas 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}"

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

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

O pedido seguinte define a feature flag apenas 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

Delete

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

Resposta: Devolva a flag de feature eliminada, ou nenhuma se a feature flag não existisse.

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

Eliminar flag de funcionalidade (condicionalmente)

Isto é semelhante à secção "Definir feature flag (condicionalmente)" anteriormente neste artigo. A operação de eliminação suporta o If-Match cabeçalho do pedido.

Para informações sobre cabeçalhos de pedido e resposta partilhados pelas operações do plano de dados da App Configuration, veja Cabeçalhos comuns.

  • Last updated on