Banderas de características mejoradas

Las banderas de funcionalidad mejorada no están disponibles en esta versión de la API.

Una bandera de característica mejorada es un recurso identificado por la combinación única de name + label. label es opcional. Para referenciar explícitamente una bandera de característica sin etiqueta, use \0 (URL codificada como %00). Para operaciones de lista, omitir label coincidencias presenta banderas con cualquier etiqueta. Revise los detalles para cada operación.

Importante

Los endpoints de bandera de funcionalidad mejorada solo están disponibles en la 2026-05-01-preview versión de la API.

Para representaciones históricas, véase Revisiones mejoradas de las banderas de características. Para listar etiquetas asociadas a las banderas de características mejoradas, consulte Etiquetas.

Operations

Obtener
Enumerar varios
Establecer
Eliminar

Prerequisites

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.

Syntax

Marca de características

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

Asignación

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

Obtener la bandera de características

Obligatorio: {name}, {api-version}

Opcional: label (Si se omite, implica una bandera de característica sin etiqueta.)

Opcional: tags (Si no se especifica, implica cualquier etiqueta).

Los name y label deben coincidir exactamente antes tags de aplicarse para filtrar adicionalmente. Para obtener más opciones, consulte la sección "Filtrado" más adelante en este artículo.

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

Respuestas:

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

Si la bandera de característica no existe, 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 etag argumento forma parte de la representación de la bandera de características. Si se omiten ambos encabezados, la operación es incondicional.

La siguiente solicitud recupera la bandera de característica solo si la representación actual no coincide con la 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}"

Respuestas:

HTTP/1.1 304 Not Modified

HTTP/1.1 200 OK

Banderas de características de lista

Opcional: name (Si no se especifica, implica cualquier nombre de bandera de característica.)

Opcional: label (si no se especifica, sugiere cualquier etiqueta).

Opcional: tags (Si no se especifica, implica cualquier etiqueta).

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

Respuesta:

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 obtener más opciones, consulte la sección "Filtrado" más adelante en este artículo.

Listar banderas de características (condicionalmente)

Para mejorar el almacenamiento en caché del cliente, use los encabezados de solicitud If-Match o If-None-Match. El etag argumento forma parte del cuerpo de la respuesta de la lista y del encabezado. Si se omiten ambos encabezados, la operación es incondicional.

La siguiente solicitud recupera las banderas de característica solo si la representación actual coincide con la especificada etag:

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

Respuestas:

HTTP/1.1 412 Precondition Failed

HTTP/1.1 200 OK

La siguiente solicitud solo recibe las banderas de característica si la representación actual no coincide con la especificada etag:

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

Respuestas:

HTTP/1.1 304 Not Modified

HTTP/1.1 200 OK

Pagination

El resultado se pagina si el número de elementos devueltos supera el límite de respuesta. Sigue el encabezado de respuesta opcional Link y úsalo rel="next" para navegar. Alternativamente, el contenido proporciona un siguiente enlace en forma de la @nextLink propiedad. El URI vinculado incluye el argumento api-version.

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

Respuesta:

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

Filtros

Se admite una combinación de name, labely tags el filtrado. Use los parámetros opcionales namede cadena de consulta , labely tags . Se pueden proporcionar varios filtros de etiqueta como parámetros de cadena de consulta en el tagName=tagValue formato . Los filtros de etiqueta deben ser una coincidencia exacta.

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

Filtros admitidos

Filtro de nombres	Effect
se omite `name` o `name=*`	Coincide con cualquier nombre de bandera característica
`name=abc`	Coincide con una bandera principal llamada abc
`name=abc*`	Los combates incluyen nombres de banderas que empiezan por abc
`name=abc,xyz`	Los partidos incluyen nombres de banderas abc o xyz (limitado a 5 CSV)

Filtro de etiqueta	Effect
se omite `label` o `label=*`	Coincide con cualquier etiqueta
`label=%00`	Los combates presentan banderas sin etiqueta
`label=prod`	Coincide con la etiqueta prod
`label=prod*`	Coincide con las etiquetas que empiezan por prod
`label=prod,test`	Coincide con las etiquetas prod o test (limitado a 5 archivos CSV)

Filtro de etiquetas	Effect
se omite `tags` o `tags=`	Coincide con cualquier etiqueta
`tags=group=app1`	Las partidas incluyen banderas que llevan una etiqueta con valor `groupapp1`
`tags=group=app1&tags=env=prod`	Las coincidencias incluyen banderas que tienen una etiqueta con `group` valor `app1` y otra etiqueta con `env` valor `prod` (limitada a 5 filtros de etiquetas)
`tags=tag1=%00`	Las partidas incluyen banderas que llevan una etiqueta con valor `tag1null`
`tags=tag1=`	Las partidas presentan banderas que tienen una etiqueta con `tag1` un valor vacío

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

Si se produce un error en la validación del filtro, la respuesta es HTTP 400 con detalles de 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
}

Examples

All
```
GET /ff?api-version={api-version}
```
El nombre de la bandera de la característica comienza por abc e incluye todas las etiquetas
```
GET /ff?name=abc*&label=*&api-version={api-version}
```
El nombre de la bandera de la característica comienza por abc y la etiqueta es igual a v1 o v2
```
GET /ff?name=abc*&label=v1,v2&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. Los cuerpos soportados son name, enabled, label, conditionsdescription, variants, allocation, telemetry, last_modifiedtagsy etag.

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

El $select parámetro se soporta mediante GET solicitudes para una única bandera de característica y colecciones de flags de características.

Acceso basado en el tiempo

Obtenga una representación del resultado tal como era en un momento anterior. Para obtener más información, consulte la sección 2.1.1. Todavía se admite la paginación tal y como se definió anteriormente en este artículo.

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

Establecer la bandera de característica

Obligatorio: {name}, {api-version}
Opcional: label (Si no se especifica, o label=%00, implica una bandera de característica sin etiqueta.)

La enabled propiedad es obligatoria en el cuerpo de la solicitud. Las descriptionpropiedades , conditions, variants, allocation, telemetry, y tags son opcionales. No incluyas name, label, etag, ni last_modified en el cuerpo de la solicitud.

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

Respuestas:

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

Establecer la bandera de característica (condicionalmente)

Para evitar condiciones de carrera, use los encabezados de solicitud If-Match o If-None-Match. El etag argumento forma parte de la representación de la bandera de características. Si se omiten ambos encabezados, la operación es incondicional.

La siguiente solicitud establece la bandera de característica solo si la representación actual coincide con la 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}"

La siguiente solicitud establece la bandera de característica solo si la representación actual no coincide con la 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}"

La siguiente solicitud establece la bandera de característica solo si ya existe una representación:

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

La siguiente solicitud establece la bandera de característica solo si una representación no existe ya:

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

Respuestas

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
...

HTTP/1.1 412 Precondition Failed

Eliminar

Obligatorio: {name}, {api-version}
Opcional: label (Si no se especifica, o label=%00, implica una bandera de característica sin etiqueta.)

DELETE /ff/{name}?label={label}&api-version={api-version} HTTP/1.1

Respuesta: Devuelve la bandera de función eliminada, o ninguna si la bandera de función no existía.

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
...

HTTP/1.1 204 No Content

Eliminar la bandera de función (condicionalmente)

Esto es similar a la sección "Establecer bandera de característica (condicionalmente)" anterior en este artículo. La operación de eliminación soporta la cabecera de If-Match la solicitud.

Para información sobre cabeceras de solicitud y respuesta compartidas por las operaciones del plano de datos de App Configuration, véase Cabeceras comunes.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-08-27

Banderas de características mejoradas

Operations

Prerequisites

Syntax

Marca de características

Conditions

Variant

Asignación

Telemetry

Obtener la bandera de características

Obtención (de manera condicional)

Banderas de características de lista

Listar banderas de características (condicionalmente)

Pagination

Filtros

Filtros admitidos

Solicitud de campos específicos

Acceso basado en el tiempo

Establecer la bandera de característica

Establecer la bandera de característica (condicionalmente)

Eliminar

Eliminar la bandera de función (condicionalmente)

Comentarios

Recursos adicionales