> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJlOTdkODU4MS00MTVkLTQzYzEtODVjYi1kN2Q1NDcyNDQxMjMiLCJleHAiOjE3Nzg0OTMwNDUsImlhdCI6MTc3ODQ5Mjc0NX0.c11vcbX-Qlh9q3dkXJzjgwp8bHC1VlwXJje1AhJu1-g
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 使用受众筛选您的 API

<Warning title="团队版、专业版和企业版功能">
  此功能仅适用于[团队版（文档）、专业版（SDK）和企业版计划](https://buildwithfern.com/pricing)。要开始使用，请联系 [support@buildwithfern.com](mailto:support@buildwithfern.com)。
</Warning>

Fern 提供两种方式来筛选哪些 API 元素会出现在您的 SDK 和 API 参考文档中：

* **`audiences`（基于标签的筛选）：** 为特定端点、模式或属性标记受众标签，然后将 SDK 和文档筛选到这些标签。最适合基于用户类型（公共 vs beta、免费 vs 企业版）或功能成熟度创建变体，无论 URL 结构如何。

* **`settings.filter`（基于路径的筛选）：** 筛选整个 URL 路径或模式。最适合您的 API 组织自然按 URL 划分的情况（如 `/v1/*` vs `/v2/*`，或 `/admin/*` vs `/user/*`）。配置详细信息请参见 [`settings.filter` 参考](/learn/sdks/reference/generators-yml#openapi)。

许多团队同时使用这两种方法：基于路径的筛选用于主要划分，受众标签用于这些划分内的精细控制。

## 基于路径的筛选

在您的 `generators.yml` 中使用 [`settings.filter`](/learn/api-definitions/openapi/generators-yml-reference#settingsfilter) 来限制哪些端点会根据其路径包含在生成的 SDK 或 API 参考中：

```yaml title="generators.yml"
api:
  specs:
    - openapi: "./openapi.yml"
      settings:
        filter:
          endpoints: ["POST /users", "GET /users/{id}"]
```

## 基于标签的筛选（受众）

在您的 OpenAPI 规范中应用受众标签，然后配置您的 SDK 或 API 参考来筛选到这些受众。

<Steps>
  <Step title="在您的规范中标记元素">
    <AccordionGroup>
      <Accordion title="标记服务器">
        将 `x-fern-server-name` 和 `x-fern-audiences` 扩展添加到相关服务器。

        在下面的示例中，`Production` 服务器仅对公共消费者可用：

        ```yaml title="openapi.yml" {3-5}
        servers:
          - url: https://api.com
            x-fern-server-name: Production
            x-fern-audiences:
              - public
        ```
      </Accordion>

      <Accordion title="标记端点">
        将 `x-fern-audiences` 扩展添加到相关端点。

        在下面的示例中，`POST /users/sendEmail` 端点仅对公共消费者可用：

        ```yaml title="openapi.yml" {4-5}
        paths:
          /users/sendEmail:
            post:
              x-fern-audiences:
                - public
              operationId: send_email
        ```
      </Accordion>

      <Accordion title="标记模式">
        将 `x-fern-audiences` 扩展添加到相关模式。

        在此示例中，`Email` 类型对公共和 beta 客户都可用。

        ```yaml title="openapi.yml" {13-15}
        components:
          schemas:
            Email:
              title: Email
              type: object
              properties:
                subject:
                  type: string
                body:
                  type: string
                to:
                  type: string
              x-fern-audiences:
                - public
                - beta
        ```
      </Accordion>

      <Accordion title="标记属性">
        将 `x-fern-audiences` 扩展添加到相关属性。

        在此示例中，`to` 属性仅对 beta 客户可用。

        ```yaml title="openapi.yml" {13-17}
        components:
          schemas:
            Email:
              title: Email
              type: object
              properties:
                subject:
                  type: string
                body:
                  type: string
                to:
                  type: string
                  x-fern-audiences:
                    - beta
        ```
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="筛选 SDK 或文档">
    指定要包含在您的 SDK 或 API 参考文档中的受众。如果**没有指定受众**，所有标记的元素都将包含在您的 SDK 中，无论其受众标签如何。

    <Tabs>
      <Tab title="SDK">
        以下示例配置 SDK 筛选到 `public` 受众：

        ```yaml title="generators.yml" {3-4}
        groups:
          sdks:
            audiences:
              - public
            generators:
              - name: fernapi/fern-typescript-sdk
                version: 0.8.8
        ```
      </Tab>

      <Tab title="文档">
        以下示例配置文档筛选到 `public` 受众：

        ```yaml title="docs.yml" {3-4}
        navigation:
          - api: API Reference
            audiences:
              - public
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>