增强功能标志

该 API 版本不支持增强功能标志。

增强特征标志是由的唯一 name + label组合识别的资源。 label 是可选的。要显式引用无标签的功能标志，请使用 \0 （URL 编码为 %00）。对于列表操作，省略 label 与任何标签的特征标志匹配。请查看每个操作的详细信息。

重要

增强功能标志端点仅在 2026-05-01-preview API 版本中提供。

有关历史表示，请参见增强功能标志修订。要列出与增强功能标志相关的标签，请参见标签。

Operations

Get
列出多个
设置
删除

先决条件

所有 HTTP 请求都必须经过身份验证。请参阅身份验证部分。
所有 HTTP 请求都必须提供显式的 api-version。请参阅版本控制部分。

Syntax

功能标志

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

分配

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

获取功能标志

必需：{name}、{api-version}

可选： label （如果省略，意味着一个没有标签的功能标志。）

可选：tags（如果未指定，则表示任意标记。）

在进行额外过滤之前，必须namelabel与和完全tags匹配。有关更多选项，请参阅本文后面的“筛选”一节。

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

响应：

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

如果没有该功能标志，将返回以下回复：

HTTP/1.1 404 Not Found

获取（有条件）

若要改善客户端缓存，请使用 If-Match 或 If-None-Match 请求标头。该 etag 论证是特征标志表示的一部分。如果两个头部都省略，则该操作为无条件的。

以下请求仅在当前表示不匹配 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}"

响应：

HTTP/1.1 304 Not Modified

或

HTTP/1.1 200 OK

列表特征标志

可选： name （如果未指定，则意味着任何特征标志名称。）

可选：label（如果未指定，则表示标签可以是任何标签。）

可选：tags（如果未指定，则表示任意标记。）

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

响应：

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

有关更多选项，请参阅本文后面的“筛选”一节。

列表特征标志（有条件）

若要改善客户端缓存，请使用 If-Match 或 If-None-Match 请求标头。该 etag 参数是列表响应主体和头部的一部分。如果两个头部都省略，则该操作为无条件的。

以下请求仅在当前表示与指定 etag内容匹配时检索特征标志：

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

响应：

HTTP/1.1 412 Precondition Failed

或

HTTP/1.1 200 OK

以下请求只有在当前表示与指定 etag内容不匹配时才会触发功能标志：

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

响应：

HTTP/1.1 304 Not Modified

或

HTTP/1.1 200 OK

分页

如果返回的项数超过响应限制，则会对结果进行分页。请使用可选 Link 的响应头，并用于 rel="next" 导航。或者，内容以属性的形式 @nextLink 提供下一个链接。链接的 URI 包含 api-version 参数。

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

响应：

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

筛选

支持将 name、label 和 tags 组合起来用于筛选。使用可选的 name、label 和 tags 查询字符串参数。可以以 tagName=tagValue 格式提供多个标记筛选器作为查询字符串参数。标记筛选器必须完全匹配。

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

支持的筛选器

名称筛选器	Effect
省略 `name` 或 `name=*`	匹配任何特征标志名称
`name=abc`	匹配名为abc的特色旗帜
`name=abc*`	比赛旗名以 abc 开头
`name=abc,xyz`	比赛中旗帜名称为 abc 或 xyz （最多5个CSV）

标签筛选器	Effect
省略 `label` 或 `label=*`	匹配任何标签
`label=%00`	比赛中使用无标签的旗帜
`label=prod`	匹配标签“prod”
`label=prod*`	匹配以“prod”开头的标签
`label=prod,test`	匹配标签“prod”或“test”（限制为 5 个 CSV）

标记筛选器	Effect
省略 `tags` 或 `tags=`	匹配任意标记
`tags=group=app1`	比赛中会有 `group` 带有标签的旗帜，标签名称带有数值 `app1`
`tags=group=app1&tags=env=prod`	匹配的标志是带有值`app1`的标签和一个以值`prod`命名`groupenv`的标签（限制为5个标签过滤器）
`tags=tag1=%00`	比赛中会有 `tag1` 带有标签的旗帜，标签名称带有数值 `null`
`tags=tag1=`	比赛中， `tag1` 标签名称为空值的标志

保留字符

*、\、,

如果保留字符是值的一部分，则必须使用 \{Reserved Character} 对其进行转义。非保留字符也可以进行转义。

筛选器验证

如果筛选器验证失败，则响应为“HTTP 400”，其中包含以下错误详细信息：

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
}

示例

全部
```
GET /ff?api-version={api-version}
```

特征标志名称以 abc 开头，包含所有标签

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

功能标志名称以 abc 开头，标签等于 v1 或 v2

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

请求特定的字段

使用可选的 $select 查询字符串参数，并提供逗号分隔的所请求字段列表。如果省略 $select 参数，则响应会包含默认集。支持场有 name， enabled， variantsconditionsallocationlabeltelemetrydescription， tagslast_modified和。etag

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

$select该参数支持GET单一功能标志和功能标志集合的请求。

基于时间的访问

获得结果在过去的表现形式。有关详细信息，请参阅第 2.1.1 节。如本文前面所述，仍支持分页。

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

设置特征标志

必需：{name}、{api-version}
可选： label （如果未指定，或 label=%00，则意味着一个没有标签的特征标志。）

enabled该财产在请求文本中是必需的。 description这些、 conditions、 variantsallocation、 telemetrytags 和属性都是可选的。请不要在请求文中包含 name、 label、 etag或 last_modified 。

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

响应：

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

设置特征标志（有条件地）

若要防止出现争用情况，请使用 If-Match 或 If-None-Match 请求标头。该 etag 论证是特征标志表示的一部分。如果两个头部都省略，则该操作为无条件的。

以下请求仅在当前表示与指定 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}"

以下请求仅在当前表示不匹配 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}"

以下请求仅在已有表示时设置功能标志：

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

以下请求仅在尚未存在表示时设置功能标志：

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

反应

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

删除

必需：{name}、{api-version}
可选： label （如果未指定，或 label=%00，则意味着一个没有标签的特征标志。）

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

回复： 返回已删除的功能标志，或者如果不存在功能标志，则返回不返回。

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

有条件删除功能标志

这与本文早先提到的“设置特征标志（有条件）”部分类似。删除操作支持请求头。If-Match

有关应用配置数据平面操作共享的请求和响应头信息，请参见通用头部。

上次更新时间为 2026-09-07