使用无服务器开发人员门户对您的 API Gateway API 编目 - Amazon API Gateway
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

使用无服务器开发人员门户对您的 API Gateway API 编目

开发人员门户 是一款应用程序,借助该应用程序,您可以向客户提供这些 API。您可以使用无服务器开发人员门户直接从 API Gateway 发布 API Gateway 托管 API。您也可以使用该门户,通过上传非 API Gateway 托管 API 的 OpenAPI 定义来发布这些 API。当您在开发人员门户中发布 API 时,您的客户可以轻松地:

  • 发现可用的 API。

  • 浏览您的 API 文档。

  • 注册(并立即接收)他们自己的可用于构建应用程序的 API 密钥。

  • 在开发人员门户 UI 中试用您的 API。

  • 监控他们自己的 API 使用情况。

Amazon API Gateway 定期在 Amazon Serverless Application Repository 中和 GitHub 上发布更新后的无服务器开发人员门户应用程序。它依据 Apache 2.0 许可证发布,允许您对其进行定制并将其合并到您的构建和部署工具中。该前端采用 React 编写,可完全自定义。请参阅 https://github.com/awslabs/aws-api-gateway-developer-portal/wiki/Customization

有关 Amazon Serverless Application Repository 的更多信息,请参阅 Amazon Serverless Application Repository 开发人员指南

提示

如果您想试用开发人员门户示例,请参阅 https://developer.exampleapigateway.com/

创建开发人员门户

您可以按原样部署 API Gateway 无服务器开发人员门户,也可以对其进行自定义以符合您的品牌形象。有以下两种方法可部署您的开发人员门户:

  • 通过使用 Amazon Serverless Application Repository。选择 Deploy (部署) 按钮来启动 API Gateway 无服务器开发人员门户 ‭{1428}‬ 堆栈,并在 Lambda 控制台中输入一小部分堆栈参数。

  • 通过从Amazon GitHub 存储库下载 API Gateway 无服务器开发人员门户,并从 Amazon SAM CLI 启动 API Gateway 无服务器开发人员门户 Amazon CloudFormation 堆栈。

要使用 部署无服务器开发人员门户Amazon Serverless Application Repository

  1. 前往 Amazon Serverless Application Repository 中的 API Gateway 无服务器开发人员门户页面。

  2. 选择 Deploy (部署)

    注意

    系统可能会提示您登录 Amazon Lambda 控制台。

  3. 在 Lambda 控制台中,在应用程序设置下输入必需的开发人员门户堆栈参数

    注意

    S3 存储桶名称和 Amazon Cognito 域前缀为必填项;其他设置为可选项。

  4. 如果希望启用 Got an opinion? (有意见?) 客户反馈按钮,您将需要:

    • DevPortalAdminEmail 框中输入电子邮件地址。当客户提交反馈时,相关电子邮件将会发送到此地址。

      注意

      如果您未提供电子邮件地址,Got an opinion? (有意见?) 将不会显示在开发人员门户中。

    • 您可以选择在 DevPortalFeedbackTableName 框中输入表名称。默认名称为 DevPortalFeedback。当客户提交反馈时,它将存储在具有此名称的 DynamoDB 表中。

  5. 选中 I acknowledge that this app creates custom IAM roles and resource policies (我确认此应用程序创建自定义 IAM 角色和资源策略) 旁边的复选框。

  6. 选择 Deploy (部署)

  7. 如果您在 AdminEmail 堆栈参数中输入了一个电子邮件地址,则系统会向该电子邮件地址发送 Amazon SNS 订阅电子邮件。此电子邮件确认您已订阅在 MarketplaceSubscriptionTopicProductCode 设置中指定的 Amazon SNS 主题。

使用 Amazon SAM 下载并部署无服务器开发人员门户

  1. 请确保您已经安装并配置最新的Amazon CLIAmazon SAM CLI

  2. 下载或克隆 API Gateway 无服务器开发人员门户存储库。

  3. 确保您有一个私有 Amazon S3 存储桶,您可以在其中上传压缩的 Lambda 函数。如果还没有存储桶,可以使用 Amazon S3 控制台或 CLI 创建一个。

    在 Amazon SAM CLI 中,从项目根中运行以下命令,同时将 {your-lambda-artifacts-bucket-name} 替换为您的 Amazon S3 存储桶的名称:

    sam package --template-file ./cloudformation/template.yaml \ --output-template-file ./cloudformation/packaged.yaml \ --s3-bucket {your-lambda-artifacts-bucket-name}
  4. 在此步骤中,有关遵循 开发人员门户设置 的参数(如 CognitoDomainNameOrPrefix)的更多信息,请参阅--parameter-overrides

    注意

    确保您有一个私有 Amazon S3 存储桶,可在其中上传 Amazon SAM 模板。(Amazon CloudFormation 将读取此存储桶中的模板来部署开发人员门户。) 此存储桶可以与您在上一步中指定的用于上传压缩的 Lambda 函数的存储桶相同。

    从项目根运行以下命令,同时将:

    • {your-template-bucket-name} 替换为您的 Amazon S3 存储桶的名称。

    • {custom-prefix} 替换为全局唯一的前缀。

    • {cognito-domain-or-prefix} 替换为唯一的字符串。

    sam deploy --template-file ./cloudformation/packaged.yaml \ --s3-bucket {your-template-bucket-name} \ --stack-name "{custom-prefix}-dev-portal" \ --capabilities CAPABILITY_NAMED_IAM \ --parameter-overrides CognitoDomainNameOrPrefix= "{cognito-domain-or-prefix}" DevPortalSiteS3BucketName="{custom-prefix}-dev-portal-static-assets" ArtifactsS3BucketName="{custom-prefix}-dev-portal-artifacts"

完全部署开发人员门户后,您可以按如下方式获取其 URL。

获取新创建的开发人员门户的 URL

  1. 打开 Amazon CloudFormation 控制台。

  2. 选择堆栈的名称(aws-serverless-repository-api-gateway-dev-portal 是默认堆栈名称)。

  3. 打开 Outputs 部分。开发人员门户的 URL 在 WebsiteURL 属性中指定。

开发人员门户设置

以下是您在部署开发人员人门户期间及之后将需要设置的设置:

注意

下面的许多设置可在您部署开发人员门户后通过更新 Amazon CloudFormation 堆栈来进行更改。有关更多信息,请参阅 Amazon CloudFormation 堆栈更新

ArtifactsS3BucketName(必填)

部署过程将创建一个可私下访问的 Amazon S3 存储桶,其中将存储目录元数据。指定要分配给存储桶的名称。此名称必须全局唯一。

CognitoDomainNameOrPrefix(必填)

此字符串与 Amazon Cognito 托管的 UI 结合使用以进行用户注册和登录。指定唯一的域名或前缀字符串。

CognitoIdentityPoolName

部署过程将创建一个 Amazon Cognito 身份池。该身份池的默认名称为 DevPortalIdentityPool

CustomDomainNameAcmCertArn

如果您提供了与 ACM 证书关联的域名,则还必须在此处指定 ACM 证书的 ARN。将此项留空可创建一个不带自定义域名的开发人员门户。

DevPortalAdminEmail

指定电子邮件地址以启用 Got an opinion? (获取了意见?) 客户反馈按钮。当客户提交反馈时,相关电子邮件将会发送到此地址。

注意

如果您未提供电子邮件地址,Got an opinion? (获取了意见?) 按钮将不会显示在开发人员门户中。

DevPortalFeedbackTableName

如果您为 DevPortalAdminEmail 指定了电子邮件地址,则部署过程将创建一个 DynamoDB 表来存储客户输入的反馈。默认名称为 DevPortalFeedback。您可以选择指定自己的表名称。

DevPortalCustomersTableName

部署过程将创建存储客户账户的 DynamoDB 表。您可以选择指定要分配给此表的名称。该名称在您的账户区域内必须是唯一的。表的默认名称为 DevPortalCustomers

DevPortalSiteS3BucketName(必填)

部署过程将创建一个可私下访问的 Amazon S3 存储桶,其中将存储 Web 应用程序代码。指定要分配给此存储桶的名称。此名称必须全局唯一。

MarketplaceSubscriptionTopicProductCode

这是订阅/取消订阅事件的 Amazon SNS 主题后缀。输入所需的值。默认值为 DevPortalMarketplaceSubscriptionTopic。只有在您使用 Amazon Web Services Marketplace 集成的情况下,此设置才是相关的。有关更多信息,请参阅 SaaS 客户登记

StaticAssetRebuildMode

默认情况下,静态资产重建不会覆盖自定义内容。指定 overwrite-content 以将自定义内容替换为您的本地版本。

重要

如果指定 overwrite-content,您的 Amazon S3 存储桶中的所有自定义更改都将丢失。不要执行此操作,除非您清楚您正在做什么。

StaticAssetRebuildToken

提供一个与上次部署的令牌不同的令牌,以便重新上传开发人员门户站点的静态资产。您可以在每次部署时提供一个时间戳或 GUID 以始终重新上传这些资产。

UseRoute53Nameservers

仅当您正在为开发人员门户创建自定义域名时适用。如果设置为 true,则将为您创建 Route 53 HostedZone 和 RecordSet。否则,将此字段设置为 false 并提供自己的名称服务器托管。

为您的开发人员门户创建一个管理员用户

在部署开发人员门户之后,请创建至少一个管理员用户。您可以通过创建一个新用户,并将该用户添加到 Amazon Cognito 用户池的管理员组(在您部署开发人员门户时由 Amazon CloudFormation 创建)来执行此操作。

创建管理员用户。

  1. 在开发人员门户中,选择 Register (注册)

  2. 输入电子邮件地址和密码,然后选择 Register (注册)

  3. 在单独的浏览器选项卡中,登录到 Amazon Cognito 控制台。

  4. 选择 Manage User Pools (管理用户池)

  5. 为您的开发人员门户选择您在部署开发人员门户时设置的用户池。

  6. 将用户提升为管理员。

  7. 选择 Add to group (添加到组)

  8. 从下拉菜单中,选择 {stackname}-dev-portalAdminsGroup,其中 {stackname} 是您部署开发人员门户时的堆栈名称。

  9. 选择 Add to group (添加到组)

  10. 在开发人员门户中,退出登录,再使用相同的凭证重新登录。现在,您应在右上角的 My Dashboard (我的控制面板) 旁边看到一个 Admin Panel (管理员面板) 链接。

管理开发人员门户的用户

在以管理员用户身份登录后,您可以使用管理员面板账户部分来管理用户。管理员用户可以从开发人员门户邀请新用户、删除用户以及将现有用户提升到管理员状态。

将 API Gateway 托管 API 发布到您的开发人员门户

以下步骤概述了您作为 API 所有者如何将 API 发布到您的开发人员门户以便您的可以订阅它。

步骤 1:使 API Gateway 托管 API 可用于发布

  1. 如果您尚未执行此操作,请将该 API 部署到一个阶段

  2. 如果您尚未执行此操作,请创建一个使用计划并将该计划与已部署 API 的 API 阶段关联。

    注意

    您无需将 API 密钥与使用计划关联。开发人员门户为您完成此操作。

  3. 登录到 Developer Portal (开发人员门户),然后转至 Admin Panel (管理员面板)

  4. 您应在 Admin Panel (管理员面板) API 列表中看到该 API。在 API 列表中,API 将按使用计划进行分组。不可订阅的无使用计划 组列出了与使用计划无关联的 API。

步骤 2:使 API Gateway 托管 API 在开发人员门户中可见

  1. Admin Panel (管理员面板) API 列表中,检查您的 API Displayed (显示的) 值。在您首次上传时,此值设置为 False

  2. 要使 API 在开发人员门户中可见,请选择 False 按钮。其值更改为 True,表明 API 现在可见。

    提示

    要使一个使用计划中的所有 API 均可见,请在该使用计划的标头栏中选择 FalsePartial (部分) 按钮。

  3. 导航到 API 面板以按照您的客户查看开发人员门户的方式查看它。您应看到在左侧导航栏中列出的 API。

    如果该 API 已部署到与使用计划关联的阶段,则您应看到该 API 的 Subscribe (订阅) 按钮。此按钮会导致客户的 API 密钥与该 API 所关联的使用计划关联。

现在已显示 API Gateway 托管 API,您可以启用开发工具包生成,以便您的客户可以为其下载开发工具包。

步骤 3:启用 SDK 生成

  1. Admin Panel (管理员面板) API 列表中,选择 Disabled (已禁用) 按钮。其值更改为 Enabled,表明现在允许生成开发工具包。

  2. 导航到 API 面板,然后在左侧导航栏中选择您的 API。现在,您应看到下载开发工具包导出 API 按钮。

更新或删除 API Gateway 托管 API

如果您在 API Gateway 中发布 API 之后对其进行更改,则需要重新部署它。

更新 API Gateway 托管 API

  1. 在 API Gateway 控制台、Amazon CLI 或开发工具包中对 API 进行所需的更改。

  2. 像之前一样将 API 重新部署到同一阶段。

  3. 在开发人员门户的 Admin Panel (管理员面板) API 列表中,选择 Update (更新)。此操作将更新显示在开发人员门户 UI 中的 API。

    注意

    Download SDK (下载 SDK) 按钮将始终获取您的 API 的最新部署版本,即使您未在开发人员门户中更新它。

  4. 导航到 API 面板,然后在左侧导航栏中选择您的 API。您应看到您的更改。

停止在开发人员门户 API 列表中显示 API(无需撤消客户对它的访问权限):

  1. Admin Panel (管理员面板) API 列表中,检查您的 API Displayed (显示的) 值。如果 API 可见,则此值将设置为 True

  2. 要使 API 不可见,请选择 True 按钮。其值更改为 False,表明 API 现在不可见。

  3. 导航到 API 面板。您不再看到左侧导航栏中列出的 API。

要撤消客户对 API 的访问权限而不将其完全删除,您必须在 API Gateway 控制台API Gateway CLI 或 REST API 中执行以下操作之一:

  • 删除使用计划中的 API 密钥。

  • 删除使用计划中的 API 阶段。

删除非 API Gateway 托管 API

要停止显示非 API Gateway 托管 API 并删除客户对它的访问权限,请选择删除。这不会删除 API,但将从开发人员门户中删除其 OpenAPI 规范文件。

将非 API Gateway 托管 API 发布到您的开发人员门户

以下步骤概述了如何将非 API Gateway 托管(或“通用”)API 发布给您的客户。您可以为 JSONYAMLYML 文件中的 API 上传 OpenAPI 2.0 (Swagger) 或 3.x 定义。

在您的开发人员门户中发布非 API Gateway 托管 API

  1. 登录到 Developer Portal (开发人员门户),然后转至 Admin Panel (管理员面板)

  2. Generic APIs (通用 API) 下,选择 Add API (添加 API)

  3. 浏览到您的 API 的 OpenAPI 文件所在的目录并选择要上传的文件。

  4. 选择 Upload

    注意

    如果这些文件中有任一文件无法进行解析或不包含 API 标题,您将收到一条警告,而且这些文件将不会进行上传。所有其他文件将进行上传。您将需要选择 x 图标以关闭对话框。

  5. 您现在应看到在 Generic APIs (通用 API) 下列出的 API。如果您未看到,请离开 Admin Panel (管理员面板) 并再次返回以刷新列表。

您的客户如何使用您的开发人员门户

要构建应用程序并测试 API,您的客户需要通过向开发人员门户注册来创建开发人员账户。

创建开发人员账户并获取 API 密钥

  1. 在开发人员门户中,选择 Register (注册)

  2. 输入电子邮件地址和密码,然后选择 Register (注册)

  3. 要找到 API 密钥,请选择 My Dashboard (我的控制面板)

开发人员账户向您的客户提供 API 密钥,使用和测试您的 API 通常需要此密钥。它可以为您和您的客户提供使用情况跟踪。

在客户初次注册时,他们的新 API 密钥将不会与您的任何 API 绑定。

激活 API 的 API 密钥

  1. 选择 API

  2. 从 API 列表中选择 API,然后选择 Subscribe (订阅)

    这将导致 API 密钥与该 API 密钥所关联的使用计划关联。

客户现已订阅 API,并且可以调用 API 上的所有方法。API 的每日使用情况统计信息将显示在 MyDashboard (我的控制面板) 中。

客户可以在开发人员门户 UI 中试用 API 方法(无需订阅)。

注意

如果任一 API 的方法需要 API 密钥,Authorize (授权) 按钮将显示在方法列表上方。需要 API 密钥的方法将带有一个黑色锁定图标。要试用需要 API 密钥的方法,请选择 Authorize (授权) 按钮并输入与 API 阶段的使用计划关联的有效 API 密钥。

您可以在 Authorize (授权) 按钮显示在您已订阅的 API 上时安全地忽略该按钮。

您的客户可以通过开发人员门户提交客户反馈。

客户的反馈将存储在开发人员门户的 DynamoDB 表中。此表的默认名称为 DevPortalFeedback。此外,电子邮件将发送到在 DevPortalAdminEmail 字段中指定的电子邮件地址。如果部署开发人员门户时未指定任何电子邮件地址,则不会显示有意见? 按钮。

注意

如果您更改此表的名称,则必须使用在您的账户区域内唯一的名称。

如果您在管理员面板中为 API 启用了开发工具包生成,则客户可以为其下载开发工具包并导出 API 定义。要了解更多信息,请参阅在 API Gateway 中为 REST API 生成开发工具包从 API Gateway 导出 REST API

开发人员门户的最佳实践

以下是在部署开发人员门户时要遵循的建议最佳实践。

  • 在大多数情况下,您将只希望为所有 API 部署一个开发人员门户。在某些情况下,您可能会选择使用不同的开发人员门户来分别用于 API 的开发和生产版本。建议不要为生产 API 使用多个开发人员门户。

  • 当您创建使用计划并将其与阶段关联时,您无需将任何 API 密钥与使用计划关联。开发人员门户为您完成此操作。

  • 请注意,如果某给定使用计划中的任何 API 可见,则该使用计划中的所有 API 均可订阅,即使您尚未向您的客户显示它们。