除了查看 SmartDocs API 参考文档,开发者还可以使用试用此 API 面板与您的 API 进行交互,而无需退出 API 文档。在您的门户中,开发者可以向您的 API 发送请求并查看响应。用户在您的门户中试用您的 API,有助于了解他们需要怎么做才能将自己的代码与您的 API 结合使用。
如果您的 API 要求提供 API 密钥或进行身份验证,您必须配置门户,以便您的用户可以与 API 互动。本页介绍了要让开发者可以试用此 API,您需要满足的要求和完成的配置。对于每项任务,本文都指出了完成该任务所需最低权限对应的 Identity and Access Management 角色。如需详细了解 IAM 权限,请参阅以下内容:
前提条件
- 您必须已部署 API 后端。
- 如果您的 API 需要 API 密钥,您必须按照使用 API 密钥限制 API 访问权限中的说明,对服务配置文件进行配置。
- 如果您的 API 需要身份验证,您必须按照对用户进行身份验证中的说明,对服务配置文件进行配置。
- 您的 API 必须可通过 DNS 进行访问。如果 API 未配置为使用自定义域名(例如
example-api.example.com
),则必须将 API 配置为使用 cloud.goog 域名。 - 由于试用此 API 仅支持 REST,因此您必须为 gRPC 服务配置 HTTP/JSON 转码。
配置 API Explorer 设置
如果您的 API 需要 API 密钥和/或 Firebase 或 Auth0 身份验证,则您需要先配置这些设置,然后用户才能试用您的 API。本部分介绍如何配置 API 密钥和身份验证设置。
配置 API 密钥
如需在您的门户中配置 API 密钥,请执行以下操作:
在 Google Cloud Console 中,转到 API 和服务 > 凭据。
在 Google Cloud 控制台顶部的项目下拉列表中,选择您在其中创建 API 的 Google Cloud 项目。
如果您要使用现有的 API 密钥:
- 点击您要使用的 API 密钥旁边的修改 API 密钥 。
- 点击该 API 密钥右侧的复制 将此 API 密钥复制到剪贴板。
- 点击取消。
如果您需要创建 API 密钥:
- 点击创建凭据,然后选择 API 密钥。
- 将密钥复制到剪贴板。
- 点击关闭。
返回您的门户。
点击设置
。点击 API 标签页,然后从下拉列表中选择您的 API。
在 APIs Explorer 设置部分,将 API 密钥粘贴到 Google API 密钥字段中。
点击保存。
配置 Firebase
要配置 Firebase,请执行以下操作:
打开 Firebase 控制台。
如果您当前没有 Firebase 项目:
- 点击添加项目,然后选择 API 所在的 Google Cloud 项目的名称。
- 在身份验证卡片上,点击开始。
- 点击登录方法标签页。
- 在登录提供方部分,启用您要使用的提供商。
- 在已获授权的网域部分,点击添加网域,然后添加您的门户域名(例如
endpointsportal.example-api.example.com
)。 - 点击 Web 设置。此时,系统会显示自定义代码段。使 Firebase 控制台保持打开状态,因为在以下步骤中您需要使用该代码段中的信息。
如果您已有 Firebase 项目:
- 转到开发 > 身份验证。
- 点击登录方法标签页。
- 在已获授权的网域部分,点击添加网域,然后添加您的门户域名(例如
endpointsportal.example-api.example.com
)。 - 点击 Web 设置。此时,系统会显示自定义代码段。使 Firebase 控制台保持打开状态,因为在以下步骤中您需要使用该代码段中的信息。
在浏览器中打开另一个标签页,然后转到您的门户。
点击设置
。在设置页面上,点击 API 标签页,然后从下拉列表中选择您的 API。
在 APIs Explorer 设置部分中:
- 从 Firebase 代码段中复制
apiKey
字段的值,并将其粘贴到 Google API 密钥字段中。 - 从 Firebase 代码段中复制
authDomain
字段的值,并将其粘贴到 Firebase 身份验证网域字段中。
- 从 Firebase 代码段中复制
点击保存。
如需了解详情,请参阅 Firebase 文档。
配置 Auth0
请按照以下概要任务列表配置 Auth0 和您的门户:
任务 1. 确保您有适用于 Cloud Endpoints 服务的 Auth0 API。
任务 2. 配置 Auth0 应用设置。
任务 3. 在您的门户中配置 Auth0 设置。
任务 1:确保您有适用于 Endpoints 服务的 Auth0 API
- 登录 Auth0 信息中心。
在左侧导航栏中,点击 API。如果存在
https://SERVICE_NAME
形式的 API 目标对象(其中SERVICE_NAME
是 Endpoints 服务的名称),则表示您已经创建了一个 API。继续执行下一个任务以配置 Auth0 应用设置。如果尚无 API,则需要创建一个:
- 点击 + 创建 API。
- 输入名称。
在标识符字段中,输入以下格式的网址:
https://SERVICE_NAME
将
SERVICE_NAME
替换为 Endpoints 服务的名称。如果您不确定该服务的名称,请参阅获取服务名称和配置 ID,详细了解如何查找 Endpoints 服务的名称。点击创建。
任务 2:配置 Auth0 应用设置
- 在 Auth0 信息中心中,点击左侧导航栏中的应用。
- 选择您的 Auth0 应用或点击 + 创建应用,创建一个新应用。
在您的应用的 Settings 标签页中,向下滚动并将您的门户的 OAuth 重定向网址添加到 Allowed Callback URLs 字段。门户的 OAuth 重定向网址是您的门户网址加上
/oauth/redirect
(例如https://endpointsportal.example-api.example.com/oauth/redirect
)。“Allowed Callback URLs”字段接受多个以英文逗号分隔的网址。请确保您输入的网址不以
/
结尾。点击保存更改。
让 Auth0 设置浏览器标签页保持打开状态,因为在以下步骤中您需要使用该标签页中的信息。
任务 3:在您的门户中配置 Auth0 设置
- 在浏览器中打开另一个标签页,然后转到您的门户。
- 点击设置 。
- 在设置页面上,点击 API 标签页,然后从下拉列表中选择您的 API。
在 APIs Explorer 设置部分中:
- 在 Auth0 信息中心复制客户端 ID 字段的值,然后将其粘贴到 Auth0 客户端 ID 字段。
- 在 Auth0 信息中心复制网域字段的值,然后将其粘贴到 Auth0 网域字段。
点击保存。
如需详细了解如何配置 Auth0,请参阅 Auth0 文档中的 Auth0 信息中心概览。