跳到主要内容
版本：3.10.x

管理 API 产品

API 产品是通过开发者门户向开发者公开 API 的主要方式。本指南介绍如何使用 Provider Portal Admin API 创建、配置和发布 API 产品。

前置条件​

按照从控制台获取 Token中的步骤创建 Token，并将其导出为环境变量：

export API_KEY="a7ee-xxxxxxxxxxxxx"

创建网关 API 产品​

网关 API 产品链接到 API7 网关中的服务，根据其 OpenAPI 规范自动生成 API 文档。

使用 Admin API​

发送创建网关 API 产品的请求：

curl -k "https://localhost:7443/api/api_products?portal_id={portal_id}" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments API",
    "desc": "Payment processing APIs for developers",
    "type": "gateway",
    "visibility": "public",
    "subscription_auto_approval": false,
    "auth": {
      "key-auth": {}
    },
    "linked_gateway_services": [
      {
        "gateway_group_id": "<gateway-group-id>",
        "service_id": "<service-id>",
        "linked_hosts": ["payments.example.com"]
      }
    ]
  }'

如果不在本地运行，请将 localhost 替换为控制台主机。如果控制台使用自签名 TLS 证书，则需要 -k 参数。

❶ name 是开发者门户中向开发者显示的名称。

❷ type: "gateway" 创建由网关管理的 API 产品。对于不受 API7 网关管理的 API，请使用 external。

❸ visibility 控制谁可以看到 API 产品。对所有开发者使用 public，或仅对已通过身份认证的开发者使用 logged_in。

❹ subscription_auto_approval: false 要求管理员审批订阅请求。

❺ auth 定义 API 产品启用的身份认证类型，例如 key-auth、basic-auth 和 dcr。

❻ linked_gateway_services 列出了 API 产品中包含的服务。

网关产品的前置条件​

在将服务链接到 API 产品之前：

  1. 该服务必须配置在网关组中。
  2. 服务必须在其网关组中发布 OpenAPI 规范，以提供向开发者展示的文档。否则，创建或更新关联的 API 产品会返回 400，并提示该服务的 OAS 尚未发布到网关组。
  3. 不要直接在服务上启用身份认证插件（例如 key-auth 或 basic-auth）。API 产品的身份认证配置会处理此问题；混用两种方式可能导致身份认证冲突。

创建外部 API 产品​

外部 API 产品代表不受 API7 网关管理的 API。你提供 OpenAPI 规范和服务器 URL。

curl -k "https://localhost:7443/api/api_products?portal_id={portal_id}" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Legacy Billing API",
    "desc": "Documentation for the legacy billing system",
    "type": "external",
    "visibility": "public",
    "raw_openapi": "<openapi-spec-as-string>",
    "server_urls": ["https://billing.internal.example.com"]
  }'

外部产品不支持订阅、凭证或身份认证，因为 API7 网关不代理其流量。

配置身份认证​

网关 API 产品支持以下认证类型：

API Key（API 密钥）身份认证​

{
  "auth": {
    "key-auth": {}
  }
}

开发者在其应用程序中创建 API Key，并将其包含在 API 请求中。

基本身份认证​

{
  "auth": {
    "basic-auth": {}
  }
}

开发者创建用户名和密码凭证，并使用 HTTP 基本身份认证。

DCR（动态客户端注册）​

{
  "auth": {
    "dcr": {
      "dcr_provider_id": "<dcr-provider-id>"
    }
  }
}

开发者通过门户注册 OAuth 2.0 客户端。此方式需要配置 DCR 提供商。

你可以同时启用多种身份认证类型：

{
  "auth": {
    "key-auth": {},
    "basic-auth": {},
    "dcr": {
      "dcr_provider_id": "<dcr-provider-id>"
    }
  }
}
警告

更改已发布产品的身份认证配置时，变更会应用到关联的网关服务。应用变更前，请评估对现有客户端的影响。应用变更后，请通过已发布的 API 验证身份认证。

关联网关服务​

创建或更新网关 API 产品时，可添加关联服务。每个关联服务都会指定网关组、服务，并可选指定特定主机：

curl -k -X PATCH "https://localhost:7443/api/api_products/{product_id}?portal_id={portal_id}" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "op": "replace",
      "path": "/linked_gateway_services",
      "value": [
        {
          "gateway_group_id": "<gateway-group-id>",
          "service_id": "<service-id>",
          "linked_hosts": ["api.example.com"]
        },
        {
          "gateway_group_id": "<gateway-group-id>",
          "service_id": "<another-service-id>"
        }
      ]
    }
  ]'

一项服务只能关联到一个 API 产品。尝试关联已属于其他产品的服务会导致错误。

发布和取消发布​

发布​

发布后，API 产品将在开发者门户中可见，身份认证配置也会被推送到关联的网关服务：

curl -k -X PATCH "https://localhost:7443/api/api_products/{product_id}?portal_id={portal_id}" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "op": "replace",
      "path": "/status",
      "value": "published"
    }
  ]'

取消发布（恢复为草稿）​

恢复为草稿会从开发者门户中移除产品、从网关中移除身份认证规则，并删除所有活动订阅：

curl -k -X PATCH "https://localhost:7443/api/api_products/{product_id}?portal_id={portal_id}" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "op": "replace",
      "path": "/status",
      "value": "draft"
    }
  ]'

配置通知​

API 产品支持针对订阅生命周期事件发送通知。配置联系人和事件：

curl -k -X PATCH "https://localhost:7443/api/api_products/{product_id}?portal_id={portal_id}" \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "op": "replace",
      "path": "/notifications",
      "value": [
        {
          "event": "subscription_approval_created",
          "type": "email",
          "contact_point_ids": ["<contact-point-id>"]
        },
        {
          "event": "subscription_approval_accepted",
          "type": "webhook",
          "contact_point_ids": ["<webhook-contact-point-id>"]
        }
      ]
    }
  ]'

支持的通知事件：

事件触发条件
subscription_approval_created开发者提交订阅请求。
subscription_approval_accepted管理员批准订阅。
subscription_approval_rejected管理员拒绝订阅。
subscription_approval_cancelled订阅被取消。

删除 API 产品​

删除 API 产品还会删除所有关联的订阅和待审批请求，并从关联的网关服务中移除身份认证规则：

curl -k -X DELETE "https://localhost:7443/api/api_products/{product_id}?portal_id={portal_id}" \
  -H "X-API-KEY: ${API_KEY}"

其他资源​