APEX开发实践（24）：APEX的REST服务详解

经常有朋友问我APEX的REST怎么用，怎么基于REST API数据做开发的问题。今天开篇跟大家好好掰扯掰扯APEX的REST。我们在APEX中能看到有两个REST：REST和RESTful。一开始接触会比较晕。这里先说一下这两者的区别哈。

 

REST基本概念

REST：是一种基于超链接，即HTTP/HTTPS的标准（或叫统一）Web服务协议和接口。这个标准定义了4个具体原则：

  • 资源的识别： URI (URL) 唯一标识资源。
  • 通过表述操作资源： 客户端通过资源的表述（如 JSON， XML）来操作资源（创建、修改、删除）。
  • 自描述消息： 请求和响应包含了足够的信息，说明如何处理它们（如 HTTP 方法、状态码、媒体类型 Content-Type）。
  • 超媒体作为应用状态引擎 (HATEOAS)： 应用状态应通过客户端接收到的超链接（嵌入在资源表述中）来驱动，而不是由客户端自己构造 URI。理想情况下，客户端只需要知道一个入口点 URI，然后通过返回的链接发现其他资源和操作。

 

RESTful：其实就是遵循REST标准，使用REST API进行数据交互的服务和应用。常见的RESTful的特征有：

  • 使用标准 HTTP 方法 (GET, POST, PUT, PATCH, DELETE) 对应资源的 CRUD 操作。
  • 资源通过结构良好的 URI 定位。
  • 数据传输通常使用 JSON (或 XML) 格式。
  • 利用 HTTP 状态码 表示请求结果 (200 OK, 201 Created, 404 Not Found, 400 Bad Request, 401 Unauthorized, 500 Server Error 等)。
  • 在一定程度上（即使不是完全地）体现了无状态性和可缓存性。

 

简单的说，REST是一个名词，说的是一种API标准，RESTful是个REST的形容词词态，是遵循REST标准的服务和应用。下文统一使用REST来行文。这里要注意：由于REST是基于超链接，即HTTP/HTTPS的API，所以它是无状态连接，不能满足复杂的事务操作，一次数据的交互必须在一次REST请求（即HTTP/HTTPS请求）中完成。

 

接下来，说清楚REST的GET, POST, PUT, PATCH, DELETE(GPD)对应的数据库的操作。

REST

SQL

GET

SELECT

POST

INSERT

PUT

UPDATE（如果记录存在，更新该记录所有字段）/

INSERT（如果记录不存在，插入记录）

PATCH

UPDATE（仅更新提供的字段）

DELETE

DELETE

 

REST返回的状态码：​ 不同的 HTTP 方法成功执行后应返回相应的状态码：

  • GET：200 OK (成功), 404 Not Found (资源不存在)
  • POST：201 Created (创建成功，通常在响应头中包含 Location: /resources/new-id)
  • PUT：200 OK / 204 No Content (替换成功) 或 201 Created (创建成功)
  • PATCH：200 OK / 204 No Content
  • DELETE：200 OK / 204 No Content (删除成功) 或 404 Not Found (资源不存在)

 

APEX中启用REST服务

Oracle APEX是通过ORDS（Oracle Rest Data Service）实现基于REST的数据访问交互。所以这也是我们在安装APEX的时候，也要安装ORDS的原因。关于ORDS的功能和使用，不在本文展开。本文只关注APEX的REST使用。

 

注：源端不一定是Oracle的REST，可以是任意的结构化数据，例如MySQL，SQL Server等关系型数据库；或者非结构化数据，例如现在很火的AI大模型应答。只要提供REST API并相应的GPD操作。就可以接入APEX进行数据和信息的交互。反之亦然。

 

为了便于讲解APEX的REST。我在apex.oracle.com中启用了2个APEX工作区，名字分别是xxu（访问端，黑色界面）和xxutest007（源端，白色界面）。

 

在APEX使用REST前需要启用REST服务（在源端XXUTEST007工作区启用）。

image

 

为了便于本文的讲解和演示，我启用REST的时候同时安装了实例，提供EMP和DEPT两张表的服务。我们可以看到启用REST服务后，在左侧菜单栏可以看到实例的模块和创建好的资源模板。

我们要留意模块和资源模板的完整URL定义，这些定义，我们后面在访问端XXU工作区中会使用到。可以通过点击URL最后面的复制小按钮来复制完整的URL。

image

 

 下面这个是比较典型的资源模板的定义，带参数，以及GET（查询）和PUT（更新）处理（操作）。

image

 

 点击PUT处理，我们可以看到具体的更新的操作，在这个处理里还定义了IN/OUT的参数。

image

 

在源端启用了APEX的REST服务之后，接下来我们看在访问端如何访问REST服务（数据）。APEX访问REST服务有三种方式：

  • REST数据源：最简单的访问方式，直接使用源端定义好的资源模板或对象的URL即可；
  • 启用REST的SQL服务：通过REST的模块的URL连接访问源端的数据源，这时候需要输入源端的Schema的名称和密码。通过这种方式可以访问源端指定Schema下的所有数据库对象。前提是：源端要放开Schema的密码（全权限访问），风险大；
  • PL/SQL调用REST API：在APEX中通过PL/SQL代码直接调用REST API访问源端定义好的资源模板和对象。这种方式最灵活，也最安全；

 

下面分别讲解这三种访问方式。

通过REST数据源访问REST数据

在访问端的应用程序-》共享组件-》数据源创建REST数据库。REST数据源类型选择HTTP即可，URL端点必须是在源端定义好的资源模板的完整URL。

image

 

远程服务器可以选择新建，或者选择之前创建的远程服务器定义。这里要留意基本URL和服务URL路径，基本URL是源端定义的REST服务的模块的URL全路径；服务URL路径是资源模板的URI。

image

 

 配置正确的话，验证时候就会把源端的数据成功显示。这样就创建了一个REST数据源。

image

 

 接着我们就可以在应用页面创建交互报表或交互网格访问源端的数据。这里要注意的是，如果需要对数据进行增删改的操作，源端的资源模板要设置对应的POST/PUT/PATCH/DELETE的处理定义。

image

 

 启用REST的SQL服务

在访问端的工作区实用程序中设置启用REST的SQL服务。

image

 

创建一个启用REST的SQL服务。这里要特别注意，端点的URL是不带源端REST模块定义中基础路径的URL。

image

 

下一步，输入源端的Schema（用户）名称和密码。（apex.oracle.com的数据库schema/密码就是工作区的登录账号/密码）。

image

 

如果配置正确的话，就会返回测试启用REST的SQL服务成功的消息。

image

 

接下来，我们就可以在APEX页面里使用配置好大的启用REST的SQL服务。可以看到启用REST的SQL服务与上面第一种，REST数据源最大的区别是，可以使用源端放开访问的Schema的所有数据库对象。源类型可以是这个Schema下面的表或视图，也可以是自己写的SQL查询。这样带来了更大的访问的灵活性，也同时带来一定的数据访问的风险。

image

 

 PL/SQL调用REST API

最后来讲一下第三种方式，在PL/SQL里直接调用REST API。第三种方式其实是第一种方式的灵活扩展。它也是基于源端定义好的REST资源模板进行数据交互。我们在这里做个简单的例子，在访问端创建一个表单，输入员工号，通过REST API从源端返回查询结果（JSON串）。先来看一下源端定义的资源模板：employees/:id。通过id查询emp表获取员工信息并以JSON格式返回结果。

image

 

 接下来，我们创建一个表单，表单包括：

  • 项P8_EMPNO，用于输入工号；
  • 项P8_EMPINFO，用于显示REST服务返回的员工查询信息；
  • 按钮QUERY，用于触发REST API调用；
  • 处理REST_REQUEST，当按钮QUERY被点击的时候，执行调用REST API的PL/SQL。PL/SQL代码如下：

image

 

declare
-- 源端定义的资源模板的完整URL路径 
l_url   varchar2(4000) := 'https://apex.oracle.com/pls/apex/xxutest007/hr/employees/' ||:P8_EMPNO||';
begin
:P8_EMPINFO := apex_web_service.make_rest_request(
    p_url => l_url,
    p_http_method => 'GET'
);
end;

　

image

 

　

执行的结果如下。

 

这里只是为了显示REST API调用的过程，以及返回的JSON格式的结果。对JSON结果的解析和数据的报表展现就不再这里赘述。感兴趣的同学可以翻看我以前写的教程。

posted @ 2025-08-28 11:28  搬砖的徐大爷  阅读(11)  评论(0)    收藏  举报