Web API：数字化转型的支柱

Oracle API 云服务 — 第二部分

作者：Rolando Carrasco 

2017 年 12 月

在本系列的第一部分中，您已经学习了如何：

• 使用 Oracle Apiary 完成首个 API 建模和设计
• 使用 Oracle API 平台云服务的 API Manager 创建 API
• 将 API 部署到 API Gateway
• 修改 API 以包含简单的标头验证

在本文中，您将学习如何：

• 将 API 发布到 API Portal
• 以开发人员身份进入 API Portal，注册应用并订阅 API
• 生成使用 API 所需的 API 密钥
• 使用 API

开始动手吧！

如何将 API 发布到 API Portal

无论是出于内部目的还是外部目的，都有必要建立一个 API Portal，让第三方或内部开发人员能够注册应用和订阅 API。只有开发人员实际使用我们的 API，API 管理策略才算成功。如果发生这种情况，我们需要：

• 确定这些开发人员
• 管理开发人员
• API 有任何变化时及时与开发人员沟通
• 了解他们使用 API 的方式
• 接收来自开发人员的反馈

API Portal 是实现这种沟通的关键。Oracle API 平台云服务提供了一个现成的门户，可以用来满足上述要求。在本文的下一节中，我们将把 Tickets API 发布到 API Portal。

在 API Manager Portal 中执行以下步骤：

(https://<主机名>:<端口>/apiplatform)

以 API 管理员用户身份登录：

图 1

登录之后，查找 Tickets API（在上一篇文章中创建的）：

图 2

点击它，您将被重定向到 API 配置：

图 3

我们准备好了！

首先是转到 API 的 Publish 部分：

图 4

图 5

在这里，我们可以：

1. 配置将发布 API 的 API Portal URL
2. 创建 API 说明
3. 用多种方式生成 API 文档：
   • HTML / Markdown。在此我们将编写任何有关 API 的说明
   • 将其与 Apiary 连接。如上一篇文章中所了解的，这种办法非常简单、直接。由于它是 API 平台云服务的一部分，我们可以利用它并可重用 Apiary 为我们的 API 创建的所有文档。

我们来配置 API Portal URL。点击黄色突出显示的 URL 部分（图 6）：

图 6

键入“tickets”，然后点击右侧的选中标记。

图 7

绿色的 Publish to Portal 按钮将显示在 URL 右侧：

图 8

Publish to Portal 将处于禁用状态。要启用该按钮，只需点击屏幕右上方的 Save Changes 按钮。

图 9

点击现在启用的 Publish to Portal 按钮，将 API 发布到门户。然后，您将看到：

图 10

API 已发布，并已创建一个指向该 API Portal 的 URL，末尾包含 /tickets 资源。如果您想取消发布，请点击右侧的绿色按钮。

现在我们在 Developer Portal API Overview 中撰写一份简短的 API 说明（图 11）。

图 11

我们编写/记录的所有内容都将作为 API 说明显示在 Developer Portal 中。您必须写一些吸引力的东西来吸引可能的用户。只需点击 HTML/Markdown 按钮（图 12）。

图 12

图 13

在 Overview 部分，您可以执行以下操作：

• File：上载一个包含 API 概述的文件
• Text：编写一些 HTML（Text 选项卡）来描述 API
• Link：包含一个指向描述该 API 的外部 URL 的链接

我们来使用 Text 选项卡为概述编写一个非常简单的 HTML。只需将以下 html 复制粘贴到 Text 选项卡中（图 14）。

         <p>Currently this Tickets API is designed to return the list of open tickets
that your store has with us. It is designed to return the tickets that
your customers have opened regarding malfunctions of our toys.</p>
 <p>In the future this API will offer:</p>
 <p>1. Tickets creation</p>
 <p>2.Tickets by toys</p>
   <p>3.Tickets by customer</p>
 <p>4. Tickets about to expire</p> 

图 14

点击 OK 按钮，您将看到：

图 15

现在我们来进行最后的配置，完成 API 文档。切记，这都是为了方便使用 API 的开发人员。这最后一步是将其与 Apiary 连接。我们来关注页面的这一部分：

图 16

点击 Apiary 按钮。您将看到以下屏幕：

图 17

点击 Continue to Sign in 按钮，输入凭证：

图 18

点击绿色的 Sign In 按钮。然后，将提示您选择想要连接的 Apiary 协作（团队）项目。在本例中，我们选择 ServceTickets 项目：

图 19

在屏幕底部，点击绿色的 Connect 按钮。

图 20

将显示以下屏幕：

图 21

最后：

图 22

我们已经完成了将 API 发布到 API Portal 的配置。只需点击屏幕右上方的 Save Changes 按钮：

图 23

现在我们采用对我们的 API 感兴趣的开发人员的角色。

以开发人员身份进入 API Portal，注册应用并订阅 API

前往以下位置：

https://<yourAPIPCSURL>/developers/login

图 24

以 Developer 身份登录，您将看到以下屏幕：

图 25

作为开发人员，您可以：

• 搜索 API
• 按字母顺序对 API 排序
• 管理应用和 API

我们首先要创建一个将订阅我们的 Tickets API 的应用。在假设的场景中，这是一家第三方零售公司，希望创建一个使用 Tickets API 的应用。假设这个第三方零售商打算为其服务组织打造一个全新的应用，目的是整合不同品牌的票据管理和创建。

为此，点击窗口右上方的 My Applications 按钮。将打开 My Applications 窗口（图 26）。

图 26

图 27

现在我们查找 Tickets API。点击屏幕右上方的 APIs 按钮：

图 28

使用搜索文本框找到 Tickets API（图 29）：

图 29

点击 Tickets。将显示 API 信息（图 30）。

图 30

请注意，现在显示我们先前输入的说明。

点击 Documentation 按钮，如图 31 所示：

图 31

将在 Oracle Apiary 中，打开在上一篇文章中创建的 API 文档（图 32）。

图 32

现在只需点击右上方的蓝色 Subscribe 按钮（如图 31 所示）。

您将看到以下内容：

图 33

选择我们之前创建的应用 (TysForUsTicketsApp)。选中该复选框之后，您将在屏幕右侧看到以下内容：

图 34

点击 Subscribe API 按钮。您将返回文档屏幕，但现在将看到以下屏幕：

图 35

点击 TysForUsTicketsApp 链接（图 35 中以黄色突出显示）。

图 36

将显示应用使用 Tickets API 所需的 API 密钥。您还可以管理用户授权（图 37）：

图 37

您还可以看到应用的统计信息：

图 38

现在来使用 API。

使用 API

如果您尝试在未提供 API 密钥的情况下使用 API，将会收到错误代码 http 401 Unauthorized（图 39）。

图 39

但是，如果我们添加 x-api-key 标头并包含我们的 API 密钥，将能够使用该 API（图 40）。

图 40

现在可以看到调用的结果。

关于作者

Oracle ACE Rolando Carrasco 是墨西哥和拉美 S&P Solutions 团队的 SOA 架构师和联合创始人。他从 2003/2004 年起就在使用 Oracle SOA，其职业生涯主要关注集成领域。Rolando 是墨西哥 Oracle 用户组 (ORAMEX) 的联席董事之一，他还是 SOA MythBusters 博客的联合创始人。

本文已经过相关 Oracle 产品团队审查，符合 Oracle 产品使用标准和实践。