Flag di funzionalità migliorate

I flag di funzionalità migliorate non sono disponibili in questa versione API.

Un feature flag migliorato è una risorsa identificata dalla combinazione unica di name + label. label è facoltativo. Per fare riferimento esplicito a un flag di caratteristica senza etichetta, si usa \0 (URL codificato come %00). Per le operazioni di lista, omettere label le corrispondenze presenta flag con qualsiasi etichetta. Vedere i dettagli per ogni operazione.

Importante

Gli endpoint con feature flag avanzati sono disponibili solo nella 2026-05-01-preview versione API.

Per rappresentazioni storiche, vedi Revisioni delle bandiere delle caratteristiche migliorate. Per elencare le etichette associate ai feature flag migliorati, vedi Etichette.

Operations

  • Recupero
  • Elencare più
  • Set
  • Elimina

Prerequisiti

  • Tutte le richieste HTTP devono essere autenticate. Vedere la sezione relativa all'autenticazione.
  • Tutte le richieste HTTP devono fornire esplicitamente api-version. Vedere la sezione relativa al controllo delle versioni.

Syntax

Indicatore di funzionalità

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

Allocazione

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

Ottieni il flag delle caratteristiche

Obbligatorio: {name}, {api-version}

Opzionale: label (Se omesso, implica un flag di caratteristica senza etichetta.)

Facoltativo: tags se non specificato, implica eventuali tag.

I name e label devono corrispondere esattamente prima tags che vengano applicati per un filtraggio aggiuntivo. Per altre opzioni, vedere la sezione "Filtro" più avanti in questo articolo.

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

Risposte:

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 il flag feature non esiste, viene restituita la seguente risposta:

HTTP/1.1 404 Not Found

Get (in modo condizionale)

Per migliorare la memorizzazione nella cache del client, usare If-Match o If-None-Match richiedere intestazioni. L'argomento etag fa parte della rappresentazione del feature flag. Se entrambe le intestazioni vengono omesse, l'operazione è incondizionata.

La seguente richiesta recupera il flag di caratteristica solo se la rappresentazione corrente non corrisponde a quella specificata 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}"

Risposte:

HTTP/1.1 304 Not Modified

o

HTTP/1.1 200 OK

Elenco delle bandiere delle caratteristiche

Opzionale: name (Se non specificato, implica qualsiasi nome di flag di caratteristica.)

Facoltativo: label se non specificato, implica qualsiasi etichetta.

Facoltativo: tags se non specificato, implica eventuali tag.

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

Risposta:

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

Per altre opzioni, vedere la sezione "Filtro" più avanti in questo articolo.

Elenco delle flag delle caratteristiche (condizionatamente)

Per migliorare la memorizzazione nella cache del client, usare If-Match o If-None-Match richiedere intestazioni. L'argomento etag fa parte del corpo della risposta della lista e dell'intestazione della lista. Se entrambe le intestazioni vengono omesse, l'operazione è incondizionata.

La seguente richiesta recupera i feature flag solo se la rappresentazione attuale corrisponde a quella specificata etag:

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

Risposte:

HTTP/1.1 412 Precondition Failed

o

HTTP/1.1 200 OK

La seguente richiesta riceve i feature flag solo se la rappresentazione corrente non corrisponde a quella specificata etag:

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

Risposte:

HTTP/1.1 304 Not Modified

o

HTTP/1.1 200 OK

Pagination

Il risultato viene impaginato se il numero di elementi restituiti supera il limite di risposta. Segui l'intestazione opzionale Link della risposta e usalo rel="next" per la navigazione. In alternativa, il contenuto fornisce un link successivo sotto forma della @nextLink proprietà. L'URI collegato include l'argomento api-version .

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

Risposta:

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

Filtro

È supportata una combinazione di namefiltri , labele tags . Usare i parametri facoltativi namedella stringa di query , labele tags . È possibile specificare più filtri di tag come parametri della stringa di query nel tagName=tagValue formato . I filtri tag devono essere una corrispondenza esatta.

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

Filtri supportati

Filtro dei nomi Effect
name è omesso oppure name=* Corrisponde a qualsiasi nome di bandiera caratteristica
name=abc Corrisponde a una bandiera principale chiamata abc
name=abc* Le partite presentano i nomi delle bandiere che iniziano con abc
name=abc,xyz Le partite presentano i nomi delle bandiere abc o xyz (limitato a 5 CSV)
Filtro per etichette Effect
label è omesso oppure label=* Corrisponde a qualsiasi etichetta
label=%00 Le partite presentano bandiere senza etichetta
label=prod Corrisponde all'etichetta prod
label=prod* Corrisponde alle etichette che iniziano con prod
label=prod,test Corrisponde all'elemento prod o al test delle etichette (limitato a 5 CSV)
Filtro tag Effect
tags è omesso oppure tags= Corrisponde a qualsiasi tag
tags=group=app1 Le partite presentano bandiere con un tag con group valore app1
tags=group=app1&tags=env=prod Le corrispondenze presentano flag che hanno un tag con group valore app1 e un tag con env valore prod (limitato a 5 filtri di tag)
tags=tag1=%00 Le partite presentano bandiere con un tag con tag1 valore null
tags=tag1= Le corrispondenze presentano bandiere con un tag denominato tag1 con un valore vuoto

Caratteri riservati

*, \, ,

Se un carattere riservato fa parte del valore , deve essere preceduto da un carattere di escape tramite \{Reserved Character}. I caratteri non riservati possono anche essere preceduti da caratteri di escape.

Convalida dei filtri

Se la convalida del filtro non riesce, la risposta è HTTP 400 con i dettagli dell'errore:

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

  • Tutti

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

  • Il nome della bandiera principale inizia con abc e include tutte le etichette

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

  • Il nome della bandiera della caratteristica inizia con abc e l'etichetta è uguale a v1 o v2

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

Richiedi campi specifici

Usare il parametro facoltativo $select della stringa di query e specificare un elenco delimitato da virgole di campi richiesti. Se il $select parametro viene omesso, la risposta contiene il set predefinito. I campi supportati sono name, enabled, label, conditionsdescription, variantsallocation, , telemetry, tags, last_modified, e etag.

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

Il parametro $select è supportato da GET richieste per una singola feature flag e collezioni di feature flag.

Accesso basato sul tempo

Ottenere una rappresentazione del risultato come in passato. Per altre informazioni, vedere la sezione 2.1.1. La paginazione è ancora supportata come definito in precedenza in questo articolo.

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

Imposta flag feature

  • Obbligatorio: {name}, {api-version}
  • Opzionale: label (Se non specificato, o label=%00, implica un flag di caratteristica senza etichetta.)

La enabled proprietà è richiesta nel corpo della richiesta. Le descriptionproprietà , conditions, variants, allocation, telemetry, e tags sono opzionali. Non includere name, label, etag, né last_modified nel corpo della richiesta.

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

Risposte:

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

Imposta il flag di caratteristica (condizionatamente)

Per evitare race condition, usare If-Match o If-None-Match richiedere intestazioni. L'argomento etag fa parte della rappresentazione del feature flag. Se entrambe le intestazioni vengono omesse, l'operazione è incondizionata.

La seguente richiesta imposta il feature flag solo se la rappresentazione corrente corrisponde a quella specificata 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 seguente richiesta imposta il feature flag solo se la rappresentazione corrente non corrisponde a quella specificata 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 seguente richiesta imposta il flag di caratteristica solo se una rappresentazione esiste già:

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 seguente richiesta imposta il feature flag solo se una rappresentazione non esiste già:

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

Risposte

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

o

HTTP/1.1 412 Precondition Failed

Elimina

  • Obbligatorio: {name}, {api-version}
  • Opzionale: label (Se non specificato, o label=%00, implica un flag di caratteristica senza etichetta.)
DELETE /ff/{name}?label={label}&api-version={api-version} HTTP/1.1

Risposta: Restituisci il flag di funzionalità eliminato, o nessuno se il flag feature non esisteva.

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

o

HTTP/1.1 204 No Content

Cancella caratteristica (condizionatamente)

Questo è simile alla sezione "Imposta il flag di caratteristica (condizionalmente)" precedente in questo articolo. L'operazione di cancellazione supporta l'intestazione della If-Match richiesta.

Per informazioni sulle intestazioni di richiesta e risposta condivise dalle operazioni del piano dati App Configuration, vedi Intestazioni comuni.

  • Last updated on