Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

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

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

  • 发现可用的 API。

  • 浏览您的 API 文档。

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

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

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

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

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

提示

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

创建开发人员门户

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

  • 通过使用 AWS Serverless Application Repository。只需选择 Deploy (部署) 按钮即可启动 API Gateway 无服务器开发人员门户 AWS CloudFormation 堆栈并在 Lambda 控制台中输入一小部分堆栈参数。

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

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

  1. 转到 AWS Serverless Application Repository 中的 API Gateway 无服务器开发人员门户

  2. 选择 Deploy (部署)

    注意

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

  3. 在 Lambda 控制台中,您将需要填写 Application settings (应用程序设置) 下必填的开发人员门户堆栈参数

    注意

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

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

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

      注意

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

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

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

  6. 选择 Deploy (部署)

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

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

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

  2. API Gateway 无服务器开发人员门户存储库下载或克隆到本地目录中。

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

    在 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. 在此步骤中,有关遵循 --parameter-overrides 的参数(如 CognitoDomainNameOrPrefix)的更多信息,请参阅开发人员门户设置

    注意

    确保您具有可私下访问的 Amazon S3 存储桶以便将 SAM 模板上传到其中。(AWS 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. 打开 AWS CloudFormation 管理控制台。

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

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

开发人员门户设置

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

注意

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

ArtifactsS3BucketName(必填)

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

CognitoDomainNameOrPrefix(必填)

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

CognitoIdentityPoolName

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

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。只有在您使用 AWS Marketplace 集成的情况下,此设置才是相关的。有关更多信息,请参阅配置您的 SaaS 产品以接受新客户

StaticAssetRebuildMode

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

重要

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

StaticAssetRebuildToken

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

UseRoute53Nameservers

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

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

一旦您部署了您的开发人员门户,您将需要创建至少一个管理员用户。您可以通过创建一个新用户,并将该用户添加到 Amazon Cognito 用户池的管理员组(在您部署开发人员门户时由 AWS 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 (显示的) 值。当您的 API 首次上传时,此值将设置为 False

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

    提示

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

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

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

现在已显示 API Gateway 托管 API,您可以启用 SDK 生成,以便您的客户为该 API 下载 SDK。

步骤 3:启用 SDK 生成

  1. Admin Panel (管理员面板) API 列表中,选择 Disabled (已禁用) 按钮。其值将更改为 Enabled (已启用),表示现在已允许 SDK 生成。

  2. 导航到 API 面板,然后在左侧导航栏中选择您的 API。现在,您应看到该 API 对应的 Download SDK (下载 SDK) 按钮。

    如果选择 Download SDK (下载 SDK) 按钮,您应看到可以下载的 SDK 类型的列表。

更新或删除 API Gateway 托管 API

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

更新 API Gateway 托管 API

  1. 在 API Gateway 控制台、AWS 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 并删除客户对它的访问权限,请选择 Delete (删除)。这不会删除 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. 选择 APIs

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

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

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

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

注意

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

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

试用 API(无需订阅)

  1. 导航到 API 列表中的 API。

  2. 选择一种 API 方法以展开它。

  3. 选择 Try it out (请试用)

  4. 选择 Execute (执行)

您的客户可以向您提交客户反馈,如下所示:

提交 API 的反馈

  1. 选择 Got an opinion? (有意见?)

  2. 在弹出窗口中,输入意见。

  3. 选择 Submit (提交)

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

注意

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

如果您在 Admin Panel (管理员面板) 中为 API 启用了 SDK 生成,则客户可以为其下载 SDK。

为 API 下载 SDK

  1. 为所需的 API 选择 Download SDK (下载 SDK) 按钮。

  2. 选择所需的 SDK 平台或语言,如下所示:

    • 对于 Android

      1. 对于 Group ID (组 ID),键入对应项目的唯一标识符。这将在 pom.xml 文件中使用(例如,com.mycompany)。

      2. 对于 Invoker package (调用程序包),请为生成的客户端类键入命名空间(例如 com.mycompany.clientsdk)。

      3. 对于 Artifact ID (构件 ID),键入已编译的 .jar 文件的名称(不含版本)。这将在 pom.xml 文件中使用(例如,aws-apigateway-api-sdk)。

      4. 对于 Artifact version (构件版本),键入已生成客户端的项目版本号。此标识符将在 pom.xml 文件中使用且应遵循 major.minor.patch 模式(例如,1.0.0)。

    • 对于 JavaScript,将立即下载该 SDK。

    • 对于 iOS (Objective-C)iOS (Swift),在 Prefix (前缀) 框中键入唯一的前缀。

      前缀效果如下所示:举例来说,如果您为 SimpleCalc API 的软件开发工具包分配 SIMPLE_CALC 前缀,并使用 InputOutputResult 模型,则生成的软件开发工具包将包含封装 API 的 SIMPLE_CALCSimpleCalcClient 类,其中包括方法请求/响应。此外,生成的开发工具包将包含分别表示输入、输出和结果的 SIMPLE_CALCInputSIMPLE_CALCOutputSIMPLE_CALCResult,从而表示请求输入和响应输出。有关更多信息,请参阅在 Objective-C 或 Swift 中使用由 API Gateway 为 REST API 生成的 iOS 开发工具包

    • 对于 Java

      1. 对于 Service Name (服务名称),指定您的开发工具包的名称。例如:SimpleCalcSdk。这将成为开发工具包客户端类的名称。该名称 pom.xml 文件(位于开发工具包的项目文件夹内)中 <project> 下的 <name> 标记相对应。请勿包括连字符。

      2. 对于 Java Package Name (Java 包名称),指定您的开发工具包的程序包名称。例如:examples.aws.apig.simpleCalc.sdk。此程序包名称将用作开发工具包库的命名空间。请勿包括连字符。

    • 对于 Ruby,对于 Service Name (服务名称),指定您的开发工具包的名称。例如:SimpleCalc。这用于生成您的 API 的 Ruby Gem 命名空间。该名称必须是全字母形式 (a-zA-Z),不含任何特殊字符或数字。

开发人员门户的最佳实践

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

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

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

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