试用 API

OpenAPI | gRPC

除了查看 SmartDocs API 参考文档，开发者还可以使用试用此 API 面板与您的 API 进行交互，而无需退出 API 文档。在您的门户中，开发者可以向您的 API 发送请求并查看响应。用户在您的门户中试用您的 API，有助于了解他们需要怎么做才能将自己的代码与您的 API 结合使用。

如果您的 API 要求提供 API 密钥或进行身份验证，您必须配置门户，以便您的用户可以与 API 互动。本页介绍了要让开发者可以试用此 API，您需要满足的要求和完成的配置。对于每项任务，本文都指出了完成该任务所需最低权限对应的 Identity and Access Management 角色。如需详细了解 IAM 权限，请参阅以下内容：

前提条件

您必须已部署 API 后端。
如果您的 API 要求 API 密钥，您必须按照使用 API 密钥限制对 API 的访问中所述配置 OpenAPI 文档。
如果您的 API 要求身份验证，则必须使用所选的身份验证方法配置 OpenAPI 文档。请参阅选择身份验证方法。
您的 API 必须可通过 DNS 访问。
- 如果您的 API 部署到了 App Engine 柔性环境，则会自动创建名称格式为 YOUR_PROJECT_ID.appspot.com 的 DNS 条目。在之前的示例中，YOUR_PROJECT_ID 是您要将 API 部署到的 Google Cloud 项目的 ID。这意味着您可以在门户中测试 API 而无需额外进行任何配置。
- 对于其他后端（例如 Compute Engine 或 GKE），如果您的 API 未配置为使用自定义域名（例如 myapi.mycompany.com），则必须将 API 配置为使用 cloud.goog 网域。

配置 API Explorer 设置

如果您的 API 需要 API 密钥和/或 Firebase 或 Auth0 身份验证，则您需要先配置这些设置，然后用户才能试用您的 API。本部分介绍如何配置 API 密钥和身份验证设置。

执行此任务所需的权限

如需执行此任务，您必须拥有项目的 Project Editor 角色。

配置 API 密钥

如需在您的门户中配置 API 密钥，请执行以下操作：

在 Google Cloud Console 中，转到 API 和服务 > 凭据。
转到“凭据”页面
在 Google Cloud 控制台顶部的项目下拉列表中，选择您在其中创建 API 的 Google Cloud 项目。
- 如果您要使用现有的 API 密钥：
  1. 点击您要使用的 API 密钥旁边的修改 API 密钥 。
  2. 点击该 API 密钥右侧的复制将此 API 密钥复制到剪贴板。
  3. 点击取消。
- 如果您需要创建 API 密钥：
  1. 点击创建凭据，然后选择 API 密钥。
  2. 将密钥复制到剪贴板。
  3. 点击关闭。
返回您的门户。
点击设置。
点击 API 标签页，然后从下拉列表中选择您的 API。
在 APIs Explorer 设置部分，将 API 密钥粘贴到 Google API 密钥字段中。
点击保存。

配置 Firebase

要配置 Firebase，请执行以下操作：

打开 Firebase 控制台。
- 如果您当前没有 Firebase 项目：
  1. 点击添加项目，然后选择 API 所在的 Google Cloud 项目的名称。
  2. 在身份验证卡片上，点击开始。
  3. 点击登录方法标签页。
  4. 在登录提供方部分，启用您要使用的提供商。
  5. 在已获授权的网域部分，点击添加网域，然后添加您的门户域名（例如 endpointsportal.example-api.example.com）。
  6. 点击 Web 设置。此时，系统会显示自定义代码段。使 Firebase 控制台保持打开状态，因为在以下步骤中您需要使用该代码段中的信息。
- 如果您已有 Firebase 项目：
  1. 转到开发 > 身份验证。
  2. 点击登录方法标签页。
  3. 在已获授权的网域部分，点击添加网域，然后添加您的门户域名（例如 endpointsportal.example-api.example.com）。
  4. 点击 Web 设置。此时，系统会显示自定义代码段。使 Firebase 控制台保持打开状态，因为在以下步骤中您需要使用该代码段中的信息。
在浏览器中打开另一个标签页，然后转到您的门户。
点击设置。
在设置页面上，点击 API 标签页，然后从下拉列表中选择您的 API。
在 APIs Explorer 设置部分中：
1. 从 Firebase 代码段中复制 apiKey 字段的值，并将其粘贴到 Google API 密钥字段中。
2. 从 Firebase 代码段中复制 authDomain 字段的值，并将其粘贴到 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，则需要创建一个：
1. 点击 + 创建 API。
2. 输入名称。
3. 在标识符字段中，输入以下格式的网址：https://SERVICE_NAME
  
  将 SERVICE_NAME 替换为 Endpoints 服务的名称。如果您不确定该服务的名称，请参阅获取服务名称和配置 ID，详细了解如何查找 Endpoints 服务的名称。
4. 点击创建。

任务 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 设置部分中：
1. 在 Auth0 信息中心复制客户端 ID 字段的值，然后将其粘贴到 Auth0 客户端 ID 字段。
2. 在 Auth0 信息中心复制网域字段的值，然后将其粘贴到 Auth0 网域字段。
点击保存。

如需详细了解如何配置 Auth0，请参阅 Auth0 文档中的 Auth0 信息中心概览。