发布您的 API

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

如下文所述，将 API 发布到您的门户，以供应用开发者使用。

API 发布概览

向门户发布 API 的过程分为两个步骤：

1. 选择要发布到门户的 API 产品。
2. 根据 OpenAPI 文档或 GraphQL 架构呈现 API 参考文档，以便应用开发者了解您的 API。（如需了解详情，请参阅 API 文档简介）

发布到门户的内容有哪些？

发布 API 时，系统会自动对您的门户进行以下更新：

• API 参考文档。显示的界面取决于您是使用 OpenAPI 文档还是 GraphQL 架构发布 API。请参阅：
  • SmartDocs (OpenAPI)
  • GraphQL 资源管理器
• 将 API 参考页面的链接添加到 API 页面

  API 页面（包含在示例门户中）列出了发布到您的门户的所有 API 的列表（按字母顺序列出），并随附了指向相应 API 参考文档的链接。（可选）您可以自定义以下内容：

  • 为每个 API 卡片显示的图片
  • 用于标记 API 的类别，使开发者可以在 API 页面上发现相关的 API
  注意：您无法直接修改本页面的内容；它不会显示在您门户中的页面列表中。您可以在自定义主题时修改页面的样式。
  

SmartDocs (OpenAPI)

使用 OpenAPI 文档发布 API 时，SmartDocs API 参考文档会添加到您的门户。

注意：当您在门户上使用 SmartDocs 生成交互式 API 参考文档（如下所述）时，Google Cloud 控制台支持 OpenAPI 规范 3.0 和 2.0，但部分功能尚不受支持。SmartDocs 不支持 OpenAPI 文档中的远程引用。

开发者可以查看您的 SmartDocs API 参考文档，并使用试用此 API 面板发出 API 请求并查看输出。根据您的 OpenAPI 文档中定义的安全方法，试用此 API 功能可用于不安全的端点或使用基本身份验证、API 密钥身份验证或 OAuth 身份验证的安全端点。对于 OAuth，支持以下流程：授权代码、密码和客户端凭据。

注意：请按照配置 API 代理以支持试用此 API 面板中所述，确保 API 代理已配置为支持从试用此 API面板发出请求。

点击 全屏以展开“试用此 API”面板。在展开的面板中，您可以查看各种格式（如 HTTP、Python、Node.js 等）的 curl 调用和代码示例，如下所示。

注意：代码示例不适合在生产环境中使用。

GraphQL 资源管理器

使用 GraphQL 架构发布 API 时，系统会将 GraphQL 资源管理器添加到您的门户中。GraphQL 资源管理器是一个交互式平台，用于对 API 运行查询。该资源管理器基于 GraphiQL，后者是由 GraphQL Foundation 开发的 GraphQL IDE 的一个参考实现。

开发者可以使用 GraphQL 资源管理器来浏览基于架构的交互式文档、构建和运行查询、查看查询结果以及下载架构。如果要保护对 API 的访问，开发者可以在请求标头窗格中传递授权标头。如需详细了解 GraphQL，请参阅 graphql.org。

关于 API 文档

每个 OpenAPI 或 GraphQL 文档都用作 API 整个生命周期内的可靠来源。API 生命周期的各个阶段（从开发、发布到监控）都使用相同的文档。修改文档时，您需要了解所做的更改在 API 的其他生命周期阶段对 API 产生的影响，如修改文档时会发生什么情况？中所述

将 API 发布到门户时，您可以保存 OpenAPI 或 GraphQL 文档版本以呈现 API 参考文档。如果修改了文档，可能需要更新发布到门户的 API 参考文档，以反映最新更改。

回调网址简介

如果您的应用需要回调网址，例如，在使用 OAuth 2.0 授权代码授权类型（通常称为“三足式 OAuth”）时，您可以要求开发者在注册应用时指定回调网址。回调网址通常指定要代表客户端应用接收授权代码的应用的网址。如需了解详情，请参阅实现授权代码授权类型。

注意：回调网址以自定义属性的形式存储在相应的 Google Cloud 控制台应用实体中。如果您使用的是第三方身份提供商，则您将负责同步回调网址元数据。

在向门户添加 API 时，您可以配置在应用注册期间是否需要回调网址。您可以随时修改此设置，如管理 API 的回调网址中所述。

注册应用时，开发者必须为所有需要回调网址的 API 输入回调网址，如注册应用中所述。

配置 API 代理以支持“试用此 API”面板

注意：本部分仅适用于使用 OpenAPI 文档生成的 SmartDocs API 参考文档。

在使用 OpenAPI 文档发布 API 之前，您需要配置 API 代理，以支持在 SmartDocs API 参考文档中的“试用此 API”面板上发出请求，如下所示：

• 向您的 API 代理添加 CORS 支持以强制执行客户端跨源请求。
  CORS 是一种标准机制，允许在网页中执行的 JavaScript XMLHttpRequest (XHR) 调用与来自非源网域的资源进行交互。CORS 是通常针对所有浏览器强制执行的同源政策实现的解决方案。
• 如果您使用的是基本身份验证或 OAuth 2.0，请更新 API 代理配置。

下表汇总了 API 代理配置要求，以根据身份验证访问权限支持 SmartDocs API 参考文档中的“试用此 API”面板。

身份验证访问权限	政策配置要求
无或 API 密钥	按照向 API 代理添加 CORS 支持中的步骤向 API 代理添加 CORS 支持。
基本身份验证	请执行以下步骤： 按照向 API 代理添加 CORS 支持中的步骤向 API 代理添加 CORS 支持。 在 Add CORS 政策中，确保 Access-Control-Allow-Headers 标头包含 authorization 属性。例如： <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header>
OAuth 2.0	按照向 API 代理添加 CORS 支持中的步骤向 API 代理添加 CORS 支持。 在 Add CORS 政策中，确保 Access-Control-Allow-Headers 标头包含 authorization 属性。例如： <Header name="Access-Control-Allow-Headers"> origin, x-requested-with, accept, content-type, authorization </Header> 更正 OAuth 2.0 政策中的不符合 RFC 规范的行为。为方便起见，请使用 GitHub 中提供的示例 OAuth 2.0 解决方案或执行以下步骤： 确保将 OAuth 2.0 政策中的 <GrantType> 元素设置为 request.formparam.grant_type（表单参数）。有关详情，请参阅 <GrantType>。 确保将 OAuth 2.0 政策中的 token_type 设置为 Bearer，而不是默认值 BearerToken。

管理 API

按照以下部分中的说明管理您的 API。

探索 API

使用控制台或 curl 命令查看门户中的 API。

控制台

如需查看 API 目录，请执行以下操作：

1. 选择发布 > 门户，然后选择您的门户。

2. 在门户着陆页上点击 API 目录。
   或者，您可以在顶部导航菜单的门户下拉菜单中选择 API 目录。
   API 目录中的 API 标签页显示了已添加到您的门户的 API 列表。

   

   

   如上图所示，您可以通过 API 标签页执行以下操作：

   • 查看门户上可用的 API 的详细信息
   • 向您的门户添加 API
   • 通过执行以下一项或多项任务，在您的门户上修改 API：
     • 管理 API 文档
     • 发布或取消发布 API
     • 管理 API 的公开范围
     • 管理 API 的回调网址
     • 管理 API 卡片的图片
     • 使用类别标记 API
     • 修改 API 标题和说明
   • 从门户中移除 API
   • 管理类别
   • 快速识别其关联 API 产品已从 Google Cloud 控制台中移除的“孤立”API，然后重新创建 API 产品或者从您的门户中删除此 API

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

如需使用 organizations.sites.apidocs/list 列出 API，请执行以下操作：

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。

如需了解如何在响应载荷中使用分页，请参阅分页说明。

响应载荷：

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

其中：

• modified: 从纪元算起到上次修改目录项的时间（以毫秒为单位）。例如 1698165480000。
• id:：目录项的 ID。例如 399668。

分页说明：

• 页面大小：使用 pageSize 指定要在一个页面中返回的列表项数量。默认值为 25，最大值为 100。如果存在其他页面，系统会使用令牌填充 nextPageToken：

  curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"
  

  您需要将其中的：

  • PAGE_SIZE 替换为要在一个页面中返回的列表项的数量。例如 10。

  响应载荷：

  {
    "status": "success",
    "message": "one page of apidocs returned",
    "requestId": "918815495",
    "data": [
      {
        "siteId": "my-org-myportal",
        "title": "Hello New World",
        "description": "Simple hello new world example",
        "specId": "apigee",
        "modified": "1699146887000",
        "anonAllowed": true,
        "imageUrl": "/files/camper1.jpg?v=1695841491415",
        "id": "381054",
        "categoryIds": [
          "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
          "61c1014c-89c9-40e6-be3c-69cca3505620"
        ],
        "published": true,
        "apiProductName": "Hello New World"
      }
    ],
    "nextPageToken": "7zcqrin9l6xhi4nbrb9"
  }
  

• 页面令牌：

  如果有多个页面，请使用 pageToken 检索后续页面：

  curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
  

  您需要将其中的：

  • PAGE_SIZE 替换为要在一个页面中返回的列表项的数量。例如 10。
  • PAGE_TOKEN 替换为 nextPageToken 值。例如 7zcqrin9l6xhi4nbrb9。

添加 API

注意：如需了解当前限制，请参阅门户限制。

如需向您的门户添加 API，请执行以下操作：

控制台

1. 访问 API 目录。
2. 点击 API 标签页（如果尚未选择）。

3. 点击 添加。

   系统会显示将 API 产品添加到目录对话框。

4. 选择要添加到门户的 API 产品。

5. 点击下一步。此时将显示 API 详细信息页面。

6. 配置 API 参考文档内容及其在门户中的公开范围：

   字段	说明
   已发布	选择发布，以将 API 发布到您的门户。 如果您还没准备好发布 API，请清除该复选框。 您可以稍后更改此设置，如发布或取消发布 API 中所述。
   显示标题	更新目录中显示的 API 的标题。默认情况下，系统会使用 API 产品名称。您可以稍后更改显示标题，如修改显示标题和说明中所述。
   显示说明	更新目录中显示的 API 的说明。默认情况下，系统会使用 API 产品说明。您可以稍后更改显示说明，如修改显示标题和说明中所述。
   要求开发者指定回调网址	如果您希望要求应用开发者指定回调网址，请启用此 API。您可以稍后添加或更新回调网址，如管理 API 的回调网址中所述。
   API 文档	如需使用 OpenAPI 文档，请执行以下操作： 选择 OpenAPI 文档。 点击选择文档。 执行以下步骤之一： 点击上传文件标签页，然后上传文件。 点击从网址导入标签页，然后通过提供要从中导入的名称和网址来导入规范。 点击选择。 如需使用 GraphQL 架构，请执行以下操作： 选择 GraphQL 架构。 点击选择文档。 导航到 GraphQL 架构，并选择它。 点击选择。 或者，您也可以按照管理 API 文档中的说明，选择无文档，然后在添加 API 后再添加文档。 注意：使用网址导入 OpenAPI 文档时，不遵循重定向。
   公开范围	如果您尚未注册受众群体管理功能的 Beta 版，请选择以下选项之一： 匿名用户：允许所有用户查看 API。 注册用户：仅允许注册用户查看 API。 如果您已注册受众群体管理功能的 Beta 版，请选择以下选项之一： 公开（对所有人可见）：允许所有用户查看 API。 经过身份验证的用户：仅允许注册用户查看 API。 选定受众群体：选择您希望能够查看 API 的特定受众群体。 您可以稍后管理受众群体公开范围，如管理 API 的公开范围中所述。
   封面图片	如需在 API 页面上显示 API 卡片的图片，请点击选择图片。在选择图片对话框中，选择一个现有图片、上传新图片或提供外来图片的网址，然后点击选择。预览 API 缩略图，然后点击选择。您可以稍后添加映像，如管理 API 卡片的映像中所述。 指定外来图片的网址时，图片不会上传到您的资产；此外，在集成式门户中加载图片会受到其可用性的约束，而这可能会受内容安全政策的阻止或限制。
   类别	添加 API 将要标记的类别，使应用开发者可在 API 页面上发现相关的 API。如需识别某个类别，请执行以下操作： 从下拉列表中选择类别。 输入新类别的名称，然后按 Enter 键即可添加新类别。 新类别便会添加到“类别”页面，并且在添加或修改其他 API 时可用。

7. 点击保存。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

如需使用 organizations.sites.apidocs.create 向您的门户添加 API，请执行以下操作：

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。
• 将 TITLE 替换为显示标题。例如 Hello World 2。
• 将 DESCRIPTION 替换为显示说明。例如 Simple hello world example。
• 将 ANON_TRUE_OR_FALSE 替换为 true 或 false（默认），其中 true 启用匿名用户访问权限。如果您已注册受众群体管理功能的 Beta 版，则系统会忽略此设置。
• 将 IMAGE_URL 替换为目录项所用外来图片的网址，或门户中存储的图片文件的文件路径，例如 /files/book-tree.jpg。指定外来图片的网址时，图片不会上传到您的资产；此外，在集成式门户中加载图片会受到其可用性的约束，而这可能会受内容安全政策的阻止或限制。
• 将 CALLBACK_TRUE_OR_FALSE 替换为 true 或 false（默认），其中 true 要求门户用户在管理应用时输入网址。

• 将 CATEGORY_ID 替换为类别的 ID。例如 bf6505eb-2a0f-47af-a00a-ded40ac72960。以英文逗号分隔多个类别 ID。使用 list API categories 命令获取类别 ID。

  注意：您必须已定义类别才能在此处添加类别。如需了解相关说明，请参阅添加类别和探索类别。

• 将 PUBLISHED_TRUE_OR_FALSE 替换为 true 或 false（默认），其中 true 表示 API 可公开访问。

• 将 API_PRODUCT 替换为 API 产品的名称。例如 Hello World 2。

响应载荷：

{
  "status": "success",
  "message": "API created",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

其中：

• modified: 从纪元算起到上次修改目录项的时间（以毫秒为单位）。例如 1698165480000。
• id:：目录项的 ID。例如 399668。

修改 API

添加 API 后，请使用控制台或 API 调用进行修改。

本部分举例详细介绍了在门户中修改现有 API 所采取的步骤。

请参阅后续部分，了解具体的修改设置。

控制台

1. 访问 API 目录。
2. 点击 API 标签页（如果尚未选择）。
3. 点击要修改的 API 对应的行。
4. 点击 修改。
5. 在 API 详细信息下，进行任何修改。请参阅添加 API 中的选项说明。
6. 点击保存。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

添加 API 后，请使用 organizations.sites.apidocs.update 调用进行修改。

注意：organizations.sites.apidocs.update API 调用会将任何可变字段重置为默认值（如果未指定可变字段）。

本示例逐步引导您将门户中 API 的已发布状态从 true 更改为 false。如有必要，您可以在一个 API 调用中更改多个设置。

1. 使用 organizations.sites.apidocs/list 命令获取门户中的 API 列表，以查找唯一标识每个 API 的生成 id：

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

   替换以下内容：

   • 将 ORG_NAME 替换为组织的名称。例如 my-org。
   • 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。

   响应载荷：

   {
     "status": "success",
     "message": "one page of apidocs returned",
     "requestId": "1167960478",
     "data": [
       {
         "siteId": "my-org-myportal",
         "title": "Hello New World",
         "description": "Simple hello new world example",
         "specId": "hellowworld",
         "modified": "1695841621000",
         "anonAllowed": true,
         "imageUrl": "/files/camper1.jpg?v=1695841491415",
         "id": "381054",
         "categoryIds": [
           "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
           "61c1014c-89c9-40e6-be3c-69cca3505620"
         ],
         "published": true,
         "apiProductName": "Hello New World"
       },
       {
         "siteId": "my-org-myportal",
         "title": "mock-product",
         "description": "Mock product",
         "specId": "apigee spec",
         "modified": "1698956849000",
         "anonAllowed": true,
         "id": "399638",
         "categoryIds": [
           "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
         ],
         "published": true,
         "apiProductName": "mock-product"
       },
       {
         "siteId": "my-org-myportal",
         "title": "Hello World 2",
         "description": "Simple hello world example",
         "specId": "hello-new-world",
         "modified": "1698950207000",
         "anonAllowed": true,
         "imageUrl": "/files/book-tree.jpg?v=1698165437881",
         "id": "399668",
         "categoryIds": [
           "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
           "61c1014c-89c9-40e6-be3c-69cca3505620"
         ],
         "published": true,
         "apiProductName": "Hello World 2"
       }
     ]
   }

   其中：

   • modified: 从纪元算起到上次修改目录项的时间（以毫秒为单位）。例如 1698165480000。
   • id:：目录项的 ID。例如 399668。

2. 使用 organizations.sites.apidocs.get 调用返回特定 API 的当前值：

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
       -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

   替换以下内容：

   • 将 ORG_NAME 替换为组织的名称。例如 my-org。
   • 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。
   • 将 API_DOC 替换为文档的生成 id。例如 399668。使用 list API docs 命令查找此值。

   响应载荷：

   {
     "status": "success",
     "message": "apidoc returned",
     "requestId": "2072952505",
     "data": {
       "siteId": "my-org-myportal",
       "title": "Hello World 2",
       "description": "Simple hello world example",
       "specId": "hello-new-world",
       "modified": "1698950207000",
       "anonAllowed": true,
       "imageUrl": "/files/book-tree.jpg?v=1698165437881",
       "id": "399668",
       "categoryIds": [
         "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
         "61c1014c-89c9-40e6-be3c-69cca3505620"
       ],
       "published": true,
       "apiProductName": "Hello World 2"
     }
   }

3. 将要保留的可变值包含在 organizations.sites.apidocs.update 调用中，并修改要更改的值。如果您省略了一行，则系统会使用默认设置。在此示例中，将 published 设置从 true 更改为 false：

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": "IMAGE_URL",
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": false,
           "apiProductName": "API_PRODUCT",
        }'
   

   替换以下内容：

   • 将 TITLE 替换为显示标题。例如 Hello World 2。
   • 将 DESCRIPTION 替换为显示说明。例如 Simple hello world example。
   • 将 ANON_TRUE_OR_FALSE 替换为 true 或 false（默认），其中 true 启用匿名用户访问权限。如果您已注册受众群体管理功能的 Beta 版，则系统会忽略此设置。
   • 将 IMAGE_URL 替换为目录项所用外来图片的网址，或门户中存储的图片文件的文件路径，例如 /files/book-tree.jpg。指定外来图片的网址时，图片不会上传到您的资产；此外，在集成式门户中加载图片会受到其可用性的约束，而这可能会受内容安全政策的阻止或限制。
   • 将 CALLBACK_TRUE_OR_FALSE 替换为 true 或 false（默认），其中 true 要求门户用户在管理应用时输入网址。
   • 将 CATEGORY_ID 替换为类别的 ID。例如 bf6505eb-2a0f-47af-a00a-ded40ac72960。以英文逗号分隔多个类别 ID。使用 list API categories 命令获取类别 ID。
   • 将 API_PRODUCT 替换为 API 产品的名称。例如 Hello World 2。

   响应载荷：

   {
     "status": "success",
     "message": "ApiDoc updated",
     "requestId": "197181831",
     "data": {
       "siteId": "my-org-myportal",
       "title": "Hello World 2",
       "description": "Simple hello world example.",
       "modified": "1698884328000",
       "anonAllowed": true,
       "imageUrl": "/files/book-tree.jpg",
       "id": "408567",
       "requireCallbackUrl": true,
       "categoryIds": [
         "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
         "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
       ],
       "published": PUBLISHED_TRUE_OR_FALSE,
       "apiProductName": "Hello World 2"
     }
   }
   

发布或取消发布 API

发布是将 API 提供给应用开发者使用的过程。

如需在您的门户上发布或取消发布 API，请执行以下操作：

控制台

1. 访问 API 目录。
2. 点击 API 标签页（如果尚未选择）。
3. 点击要修改的 API 对应的行。
4. 点击 修改。
5. 在 API 详细信息下，选择或取消选择已发布（在目录中列出），以分别在您的门户上发布或取消发布 API。
6. 点击保存。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

注意：organizations.sites.apidocs.update API 调用会将任何可变字段重置为默认值（如果未指定可变字段）。

在 update 调用中添加以下其中一项：

  "published": true,    # API is published to your portal
  "published": false,   # API is not published in your portal

如需修改 API，请执行以下操作：

1. 使用 organizations.sites.apidocs.get 调用返回当前值：

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. 使用 organizations.sites.apidocs.update 调用修改 API。添加要保留的可变值并修改要更改的值。如果您省略可变设置，则使用默认值。

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

如需查看步骤、变量和返回载荷的详细示例，请参阅修改 API。

管理 API 的公开范围

通过为以下各项授予访问权限，管理门户中 API 的公开范围：

• 公开（对所有人可见）
• 经过身份验证的用户

• 选定的受众群体（如果您已注册受众群体管理功能的 Beta 版）

  注意：如果您将公开范围设置为经过身份验证的用户或选定的受众群体，则搜索引擎不会将 API 编入索引。

如需管理门户中 API 的公开范围，请执行以下操作：

控制台

1. 访问 API 目录。
2. 点击 API 标签页（如果尚未选择）。
3. 点击要修改的 API 对应的行。
4. 点击 修改。

5. 选择公开范围设置。如果您已注册受众群体功能的 Beta 版，请在 API 公开范围下选择以下选项之一：

   • 公开（对所有人可见）：允许所有用户查看页面。
   • 经过身份验证的用户：只允许注册用户查看页面。
   • 选定的受众群体：选择您希望能够查看相应网页的特定受众群体。请参阅管理门户的受众群体。

   否则，请在受众群体下选择以下选项之一：

   • 匿名用户：允许所有用户查看页面。
   • 已注册的用户：只允许注册用户查看页面。

6. 点击提交。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

注意：organizations.sites.apidocs.update API 调用会将任何可变字段重置为默认值（如果未指定可变字段）。

如果您已注册受众群体管理功能的 Beta 版，请使用控制台管理受众群体。

如果您尚未注册受众群体管理功能，请使用 anonAllowed 管理公开范围。

在 update 调用中添加以下其中一项：

  # When not enrolled in the beta release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

如需修改 API，请执行以下操作：

1. 使用 organizations.sites.apidocs.get 调用返回当前值：

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. 使用 organizations.sites.apidocs.update 调用修改 API。添加要保留的可变值并修改要更改的值。如果您省略可变设置，则使用默认值。

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

如需查看步骤、变量和返回载荷的详细示例，请参阅修改 API。

管理 API 的回调网址

管理 API 的回调网址。请参阅回调网址简介。

如需管理 API 的回调网址，请执行以下操作：

控制台

1. 访问 API 目录。
2. 点击 API 标签页（如果尚未选择）。
3. 点击要修改的 API 对应的行。
4. 点击 修改。
5. 在 API 详细信息下，选择或清除要求开发者指定回调网址，以分别指定是否需要回调网址。
6. 点击保存。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

注意：organizations.sites.apidocs.update API 调用会将任何可变字段重置为默认值（如果未指定可变字段）。

在 update 调用中添加以下其中一项：

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

如需修改 API，请执行以下操作：

1. 使用 organizations.sites.apidocs.get 调用返回当前值：

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. 使用 organizations.sites.apidocs.update 调用修改 API。添加要保留的可变值并修改要更改的值。如果您省略可变设置，则使用默认值。

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

如需查看步骤、变量和返回载荷的详细示例，请参阅修改 API。

管理 API 卡片的图片

通过添加图片或更改当前图片，管理 API 页面上的 API 卡片中显示的图片。

如需管理 API 卡片的图片，请执行以下操作：

控制台

1. 访问 API 目录。
2. 点击 API 标签页（如果尚未选择）。
3. 点击要修改的 API 对应的行。
4. 点击 修改。

5. 在 API 详细信息下：

   • 点击选择图片以指定图片（如果您未选择图片）。
   • 点击更改图片以指定其他图片。
   • 点击图片中的 x 可将其移除。

   指定图片时，请指定具有目录项所用外部网址的图片，或存储在门户中的图片文件的文件路径，例如 /files/book-tree.jpg。指定外来图片的网址时，图片不会上传到您的资产；此外，在集成式门户中加载图片会受到其可用性的约束，而这可能会受内容安全政策的阻止或限制。

6. 点击保存。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

注意：organizations.sites.apidocs.update API 调用会将任何可变字段重置为默认值（如果未指定可变字段）。

在 update 调用中添加以下内容：

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

如需修改 API，请执行以下操作：

1. 使用 organizations.sites.apidocs.get 调用返回当前值：

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. 使用 organizations.sites.apidocs.update 调用修改 API。添加要保留的可变值并修改要更改的值。如果您省略可变设置，则使用默认值。

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

如需查看步骤、变量和返回载荷的详细示例，请参阅修改 API。

使用类别标记 API

使用类别可帮助应用开发者发现相关 API。另请参阅管理类别。

如需使用类别标记 API，请执行以下操作：

控制台

1. 访问 API 目录。
2. 点击 API 标签页（如果尚未选择）。
3. 点击要修改的 API 对应的行。
4. 点击 修改。

5. 点击类别字段并执行以下某个步骤：

   • 从下拉列表中选择类别。
   • 输入新类别的名称，然后按 Enter 键即可添加新类别。新类别便会添加到类别页面，并且在添加或修改其他 API 时可用。

6. 重复以上操作即可使用更多类别标记 API。

7. 点击保存。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

注意：organizations.sites.apidocs.update API 调用会将任何可变字段重置为默认值（如果未指定可变字段）。

在 update 调用中添加以下内容：

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

使用 list categories 命令获取类别 ID 编号。

如需修改 API，请执行以下操作：

1. 使用 organizations.sites.apidocs.get 调用返回当前值：

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. 使用 organizations.sites.apidocs.update 调用修改 API。添加要保留的可变值并修改要更改的值。如果您省略可变设置，则使用默认值。

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

如需查看步骤、变量和返回载荷的详细示例，请参阅修改 API。

修改显示标题和说明

要修改显示标题和说明，请执行以下操作：

控制台

1. 访问 API 目录。
2. 点击 API 标签页（如果尚未选择）。
3. 点击要修改的 API 对应的行。
4. 点击 修改。
5. 根据需要修改显示标题和显示说明字段。
6. 点击保存。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

注意：organizations.sites.apidocs.update API 调用会将任何可变字段重置为默认值（如果未指定可变字段）。

在 update 调用中添加以下内容：

  "title": "TITLE",              # Display title
  "description": "DESCRIPTION",  # Display description

如需修改 API，请执行以下操作：

1. 使用 organizations.sites.apidocs.get 调用返回当前值：

   curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)"
   

2. 使用 organizations.sites.apidocs.update 调用修改 API。添加要保留的可变值并修改要更改的值。如果您省略可变设置，则使用默认值。

   curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" \
        -d '{
           "title": "TITLE",
           "description": "DESCRIPTION",
           "anonAllowed": ANON_TRUE_OR_FALSE,
           "imageUrl": IMAGE_URL,
           "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
           "categoryIds": [
             "CATEGORY_ID1",
             "CATEGORY_ID2"
           ],
           "published": PUBLISHED_TRUE_OR_FALSE,
           "apiProductName": "API_PRODUCT",
        }'

如需查看步骤、变量和返回载荷的详细示例，请参阅修改 API。

移除 API

如需从您的门户中移除 API，请执行以下操作：

控制台

1. 访问 API 目录。
2. 选择 API 标签页（如果尚未选择）。
3. 将光标置于列表中的 API 上以显示操作菜单。
4. 点击 删除。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

如需使用 organizations.sites.apidocs.delete 从您的门户中移除 API，请执行以下操作：

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。
• 将 API_DOC 替换为文档的生成 id。例如 399668。使用 list API docs 命令查找此值。

响应载荷：

{
  "status":"success",
  "message":"Apidoc deleted",
  "requestId":"645138256"
}

管理 API 文档

以下部分介绍了如何更新、下载或移除 API 文档。

更新 API 文档

发布 API 后，您可以随时上传新版本的 OpenAPI 或 GraphQL 文档。

如需上传其他版本的 API 文档，请执行以下操作：

控制台

1. 访问 API 目录。
2. 点击 API 标签页（如果尚未选择）。
3. 点击要修改的 API 对应的行。
4. 点击 修改。
5. 在 API 文档窗格中，选择以下任一选项：
   • OpenAPI 文档
   • GraphQL 架构
6. 点击选择文档，然后选择文档的最新版本。
7. 对于 GraphQL，请指定端点网址。
8. 点击保存。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

如需使用 organizations.sites.apidocs.updateDocumentation 更新 OpenAPI 或 GraphQL 文档内容，请执行以下操作：

OpenAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。
• 将 API_DOC 替换为文档的生成 id。例如 399668。使用 list API docs 命令查找此值。
• 将 DISPLAY_NAME 替换为 API 文档的显示名称。例如 Hello World 2。
• 将 CONTENTS 替换为 API 文档内容的 base64 编码字符串。大多数开发环境都包含一个 base64 转换实用程序，或有许多在线转换工具。

响应载荷：

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。
• 将 API_DOC 替换为文档的生成 id。例如 399668。使用 list API docs 命令查找此值。
• 将 DISPLAY_NAME 替换为 API 文档的显示名称。例如 Hello World 2。
• 将 ENDPOINT_URI 替换为您的端点 URI 的域名。例如 https://demo.google.com/graphql。
• 将 CONTENTS 替换为 API 文档内容的 base64 编码字符串。大多数开发环境都包含一个 base64 转换实用程序，或有许多在线转换工具。

响应载荷：

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
  "data": {
    "graphqlDocumentation": {
      "schema": {
        "displayName": "Hello World 2"
      },
     "endpointUri": "https://demo.google.com/graphql"
    }
  }
}

注意：响应时不会填充规范或架构的内容。请使用 organizations.sites.apidocs.getDocumentation 调用检索内容。

系统会根据该文档呈现 API 参考文档，并将其添加到实时门户的 API 页面中。

下载 API 文档

发布 API 后，您可以随时下载在您的门户上发布的 OpenAPI 或 GraphQL 参考文档。

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

如需使用 organizations.sites.apidocs.getDocumentation 下载 API 文档，请执行以下操作：

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。

• 将 API_DOC 替换为文档的生成 id。例如 399668。使用 list API docs 命令查找此值。

  响应载荷：

{
  "status":"success",
  "message":"Api documentation downloaded",
  "requestId":"645138256",
  "data": {
      "oasDocumentation":{
          "spec":{
            "displayName":"Hello World 2",
            "contents":"c3dhZ2dlcjogJzIuMCcKaW5mbzoKICBkZXNlI ..."
          },
          "Format": YAML
      }
  }
}

其中：

contents: API 文档内容的 base64 编码字符串。

提示：获得授权的门户用户可以从门户下载 API 文档：

1. 导航到门户。
2. 在顶部导航栏中，点击 API。系统会显示 API 页面。
3. 点击 API 卡片以查看 API 参考文档。系统会显示 API 参考文档。
4. 点击下载规范。

移除 API 文档

如需移除 API 文档，请执行以下操作：

控制台

1. 访问 API 目录。
2. 点击 API 标签页（如果尚未选择）。
3. 点击要修改的 API 对应的行。
4. 点击 修改。
5. 在 API 文档窗格中，选择无文档。
6. 点击保存。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

如需使用 API 移除 API 文档内容，请通过发送空请求正文来清除现有设置。

如需使用 organizations.sites.apidocs.updateDocumentation 发送空请求正文并清除现有内容，请执行以下操作：

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。
• 将 API_DOC 替换为文档的生成 id。例如 399668。使用 list API docs 命令查找此值。

响应载荷：

{
   "status":"success",
   "message":"Api documentation updated",
   "requestId":"645138279"
}

管理类别

使用类别标记 API，使应用开发者可在实时门户的 API 页面上发现相关 API。添加和管理类别，如以下部分所述。

探索类别

使用控制台或 curl 命令查看类别。

控制台

要查看“类别”页面，请执行以下操作：

1. 选择发布 > 门户，然后选择您的门户。
2. 在门户着陆页上点击 API 目录。
   或者，您可以在顶部导航菜单的门户下拉菜单中选择 API 目录。

3. 点击类别标签页。 API 目录中的“类别”标签页会显示已为您的门户定义的类别列表。

   

   

   如上图所示，您可以通过 API 页面执行以下操作：

   • 查看类别以及对它们进行标记所对应的 API
   • 添加类别
   • 修改类别
   • 删除类别
   • 管理发布到门户的 API。请参阅探索 API。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

如需使用 organizations.sites.apicategories.list 列出类别，请执行以下操作：

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。

响应载荷：

{
  "data": [
    {
      "siteId": "my-org-myportal",
      "name": "Get Started",
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
    },
    {
      "siteId": "my-org-myportal",
      "name": "Test",
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620"
    }
  ],
  "status": "success",
  "message": "all ApiCategory items returned",
  "requestId": "602661435"
}

其中：

• id:：类别项的 ID。例如 61c1014c-89c9-40e6-be3c-69cca3505620。

添加类别

要添加类别，请按以下步骤操作：

控制台

1. 访问“类别”页面。
2. 点击 添加。
3. 输入新类别的名称。
4. （可选）选择一个或多个要针对类别进行标记的 API。
5. 点击创建。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

要使用 organizations.sites.apicategories.create 添加类别，请执行以下操作：

curl  -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。
• 将 CATEGORY_NAME 替换为类别名称。例如 demo-backend。

响应载荷：

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "API category created",
  "requestId": "295617049"
}

修改类别

如需修改类别，请执行以下操作：

控制台

1. 访问“类别”页面。
2. 将光标置于您要修改的类别上方以显示操作菜单。
3. 点击 修改。
4. 修改类别的名称。
5. 添加或移除 API 标记。
6. 点击保存。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

要使用 organizations.sites.apicategories.patch 修改类别，请执行以下操作：

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。
• 将 CATEGORY_ID 替换为类别的 ID。例如 bf6505eb-2a0f-47af-a00a-ded40ac72960。使用 list API categories 命令获取类别 ID。
• 将 CATEGORY_NAME 替换为类别名称。例如 demo-backend。

响应载荷：

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend-test",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "ApiCategory updated",
  "requestId": "192211979"
}

删除类别

如果删除类别，则该类别的所有 API 标记也将被删除。

要删除类别，请执行以下操作：

控制台

1. 访问“类别”页面。
2. 将光标置于您要修改的类别上方以显示操作菜单。
3. 点击 删除。
4. 点击删除进行确认。

curl

预览版：
此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。如需了解详情，请参阅发布阶段说明。

要使用 organizations.sites.apicategories.delete 删除类别，请执行以下操作：

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"

替换以下内容：

• 将 ORG_NAME 替换为组织的名称。例如 my-org。
• 将 SITE_ID 替换为门户的名称，格式为 ORG_NAME-PORTAL_NAME，其中 ORG_NAME 是组织的名称，PORTAL_NAME 是门户名称，该名称已全部转换为的小写字母，并移除了空格和短划线。例如 my-org-myportal。
• 将 CATEGORY_ID 替换为类别的 ID。例如 bf6505eb-2a0f-47af-a00a-ded40ac72960。使用 list API categories 命令获取类别 ID。

响应载荷：

{
  "status": "success",
  "message": "ApiCategory deleted",
  "requestId": "1610396471"
}

排查已发布的 API 的问题

注意：本部分仅适用于使用 OpenAPI 文档生成的 SmartDocs API 参考文档。

以下部分提供了相关信息来帮助您排查已发布的 API 中存在的特定错误。

错误：使用“试用此 API”时返回“未能获取”错误

使用试用此 API 时，如果系统返回 TypeError: Failed to fetch 错误，请考虑以下可能的原因和解决方法：

• 对于混合内容错误，错误可能是由已知的 Swagger 界面问题引起。一种可能的解决方法是确保在 OpenAPI 文档的 schemes 定义中在 HTTP 前面指定 HTTPS。例如：

  schemes:
     - https
     - http
  

• 对于跨域资源共享 (CORS) 限制错误，请确保您的 API 代理支持 CORS。 CORS 是一种支持客户端跨源请求的标准机制。 请参阅配置 API 代理以支持“试用此 API”面板。

错误：不允许请求标头字段

使用试用此 API 时，如果您收到 Request header field not allowed 错误（类似于以下示例），则可能需要更新 CORS 政策支持的标头。例如：

field content-type is not allowed by Access-Control-Allow-Headers in preflight
response

在此示例中，您需要将 content-type 标头添加到 CORS AssignMessage 政策中的 Access-Control-Allow-Headers 部分，如将 Add CORS 政策附加到新的 API 代理中所述。

错误：使用 OAuth 2.0 调用 API 代理时访问遭拒

Google Cloud 控制台的 OAuthV2 政策会返回包含某些不符合 RFC 规范的属性的令牌响应。例如，该政策将返回值为 BearerToken 的令牌，而不是预期符合 RFC 规范的值 Bearer。使用“试用此 API”时，无效的 token_type 响应可能会导致 Access denied 错误。

如需更正此问题，您可以创建 JavaScript 或 AssignMessage 政策，以将政策输出转换为符合规范的格式。有关详情，请参阅不符合 RFC 规范的行为。