部署包装器 API

Oracle Blockchain Platform Digital Assets Edition 允许为 App Builder 生成的链代码内的所有控制器 API 生成包装器 API。本主题提供了在堆栈资源管理器中部署包装器 API 程序包和使用关联的 Postman 集合测试包装器 API 的详细步骤。

使用 Blockchain App Builder 生成包装器 API 程序包时，它会在所选目录中创建两个具有默认命名约定的文件：

1. <ChaincodeName>WrapperAPI.zip：此文件包含部署 Oracle Cloud Infrastructure Resource Manager 中的包装 API 所需的 Terraform 脚本。
2. <ChaincodeName>_WrapperAPI.postman_collection.json：用于在部署后测试包装器 API 的 Postman 集合。

要部署包装器 API，必须在 OCI 资源管理器中使用 WrapperAPI.zip 文件。

先决条件

部署包装器 API 程序包的先决条件如下：

• 包装器 API 程序包必须使用 App Builder 生成。
• 程序包应包括包装器 API 的所有必需的配置变量值和端点值。

部署 Wrapper API 程序包

1. 登录到 OCI。
   打开 OCI 控制台并登录：https://cloud.oracle.com/ 。
   确保您位于将部署堆栈的区间中。
2. 展开 Navigation（导航）菜单。选择开发人员服务。在资源管理器下，选择堆栈。
   此时将打开堆栈的资源管理器界面。您可以使用 Terraform 配置查看现有堆栈、创建新堆栈以及将基础设施作为代码进行管理。
3. 通过单击创建堆栈创建新堆栈。
4. 配置堆栈信息。
   1. 在 Terraform 配置部分中，选择我的配置。
   2. 在堆栈配置中的 Terraform 配置源中，选择 .Zip 文件。
   3. 单击浏览并导航到包装器 API Zip 文件。
   4. 上载后，请确保堆栈名称正确。
   5. 所有剩余设置可以保留为默认值。单击下一步。
5. 配置堆栈变量。
   1. 验证所有配置变量值是否准确，并与包装器 API 程序包中指定的配置变量保持一致，以满足您的部署要求。
   2. 对于 ocir_user_name ，输入与您的 OCI 账户关联的电子邮件地址。
   3. 对于 ocir_user_password ，输入您的密码，即您的 Oracle Cloud Infrastructure 验证令牌。可以在 OCI 控制台的用户设置下生成此令牌。Auth Token 用作登录 Oracle Cloud Infrastructure Registry (OCIR) 的密码。
      有关生成验证令牌的详细说明，请参阅 Generating an Auth Token 。
   4. 所有剩余设置可以保留为默认值。单击下一步。
6. 查看堆栈信息。如果所有信息都正确，则单击创建。
7. 执行 Terraform 计划。
   1. 在堆栈的详细信息页上，单击计划以启动执行计划的创建。
   2. （可选）配置作业计划。您可以编辑默认名称或选择高级选项以更改调整设置的提供者版本。
   3. 单击计划以创建和运行计划作业。
      这将解析 Terraform 配置、生成执行计划并执行执行以下操作的计划：

      • 验证 Terraform 脚本以确保没有语法或配置错误。
      • 模拟资源创建流程，而无需对实际基础设施进行任何更改。
      • 提供输出摘要，其中列出了脚本要创建、修改或销毁的资源。
   4. 监视堆栈的 "Jobs"（作业）部分中的状态。成功完成计划后，请查看输出以确认将创建的资源数，并验证是否不存在问题。
8. 将 Terraform 计划应用于堆栈。
   1. 在堆栈的详细信息页上，单击应用。
   2. 在“Terraform 应用”面板中，单击应用。
      这将执行以下操作：

      • 提供 Terraform 脚本中定义的所有以下资源：
        • 虚拟云网络 (VCN)
        • 应用程序（OCI 函数）
        • API 网关
        • API 部署
        • IAM 策略
        • OCI 注册表存储库
      • 为包装器 API 创建所有必需的基础结构。
   3. 监视堆栈的 "Jobs"（作业）部分中的状态，以确保作业成功完成，没有错误。
9. 检索 API 网关端点。
   1. 应用作业完成后，请转至“应用作业”页的输出部分以查看生成的输出值。
   2. 输出将返回一个 JSON 对象，其中键表示端点名称，值是其对应的端点值。
      例如：

      api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}

   3. 复制端点 - 更新 API Postman 集合所需。

使用 Postman 测试 Wrapper API

您可以在 Postman 中测试 API。通过分配适当的值来配置包装器 API Postman 集合中的所有变量。必须从 OCI 中的堆栈部署输出中获取 api_gateway_endpoint 值，其中将提供动态生成的网关端点。

更新 Postman 集合中的变量后，可以测试包装器 API。集合中的每个 API 请求都包含特定于相应包装器 API 的必要有效负载。

图 6-1 使用 Postman 测试 API 包装器集合

故障排除

以下是一些常见的问题及其解决方案。

未授权：ocir_user_name 或 ocir_user_password 无效

当用户名或密码凭据不正确时，会发生此错误。要解决此问题，请执行以下步骤：

1. 导航到堆栈详细信息页中的 Variables（变量）部分。
2. 单击编辑变量可修改用户名和口令值。
3. 使用正确的信息更新身份证明。
4. 进行更改后，单击应用以重新部署堆栈。

这将解决验证问题，并允许部署成功继续。

部署失败 - “已拒绝 : 只允许匿名用户在公共资料档案库上进行读取访问”

有时，部署可能会失败，并出现以下错误：

denied: Anonymous users are only allowed read access on public repos

这是与堆栈后端中的 Docker 操作相关的间歇性问题。具体而言，当尝试在没有正确验证的情况下将 Docker 映像推送到 Oracle Cloud Infrastructure Registry (OCIR) 时，会发生此错误。

虽然包装器 API 软件包包括一个在推送映像之前执行 docker login 的脚本，以确保正确验证，但此错误仍可能偶尔发生。通常，当系统在映像推送时无法正确识别 Docker 验证步骤时，会发生这种情况。

如果出现此错误，请按照以下步骤解决问题：

1. 销毁现有资源：

   在 OCI Stack Resource Manager 中单击销毁以销毁在部署过程中创建的所有资源。

2. 重新应用堆栈：

   销毁资源后，再次单击应用以重新部署堆栈。这将触发创建必要的资源，包括正确的 Docker 验证，并应解决此问题。

一般部署失败：间歇性问题

有时，堆栈部署可能会因与 docker 相关的随机问题而失败。在这种情况下，请按照以下步骤解决问题：

1. 单击销毁可删除在失败部署期间创建的所有资源。
2. 资源销毁后，导航回堆栈并单击应用以重新部署堆栈。

此过程通常会解决间歇性问题，从而使部署成功进行。