建立 RESTful Web 服務

使用模組、範本及處理程式頁面建立 RESTful Web 服務。

若要建立 RESTful Web 服務,您必須:

  • 定義資源模組

  • 定義資源樣板

  • 定義一或多個資源處理程式,例如 GET、PUT、POST 或 DELETE。您可以選擇性地定義需要傳送至資源處理程式的參數。

下列各節提供如何建立資源模組、資源樣板以及資源處理程式的資訊。

另請參閱:

管理資源模組

您可以在「模組」頁面中定義、編輯及刪除資源模組。

若要瀏覽至「模組」頁面,請在「REST 總覽」頁面中,按一下「物件」中的模組,或從標頭的功能表中選取模組

卡片檢視中預設顯示的模組屬性如下圖所示。

可以發佈或取消發佈模組狀態。如果狀態為未發布,圖示會以紅色顯示。

按一下卡片檢視中的模組名稱,即可移至該模組的「範本」頁面。您也可以透過相關內容功能表瀏覽至「範本」頁面。

相關內容功能表中可用的動作如下:

建立資源模組

本節說明如何建立資源模組。

  1. 在「模組」頁面中,按一下建立模組
  2. 在下列欄位中輸入值。帶有星號 (*) 的欄位為必填欄位:

    「模組定義」頁籤

    • 模組名稱:輸入模組的名稱。此欄位區分大小寫。

    • 基礎路徑:輸入 URI 的基礎以存取 RESTful 服務。例如:hr/ 表示所有以 hr/ 開頭的 URI 都將由這個資源模組提供服務 。在您輸入基本路徑時,請注意預覽 URL 中的變更。

    • 已發布:啟用後即可使用 RESTful 服務。

    • 分頁大小:根據資料庫查詢,輸入或選取要在每個頁面傳回的結果數目。預設值為 25。

    • 受權限保護:選取保護模組的權限,使其免於下拉式清單。
    • 註解:輸入描述性註解。

    • 建立後移至模組:選取此選項即可在模組建立後移至「樣板」頁面。

    允許來源頁標

    • 輸入允許存取資源樣板的來源。按一下新增 (+) 來新增每個來源。舉例而言:

      http://example1.org

      https://*.example2.com

    顯示程式碼:選取此選項即可檢視等同於「建立模組」滑動軸的 PL/SQL 程式碼。您可以在工作表中複製並執行此 PL/SQL 程式碼,以執行按一下「建立模組」滑動軸中的建立時所發生的相同動作。

  3. 按一下建立

    新模組會顯示在「模組」頁面上。如果看不到模組,請使用「搜尋」欄位找到模組。

匯入資源模組

本節說明如何匯入資源模組。

附註:

您只能以 JSON 格式匯入 OpenAPI 版本 2.0 或 3.0 文件。
  1. 在「模組」頁面的右上角,按一下匯入模組
  2. 瀏覽並選擇要匯入的 JSON 檔案。按一下開啟

    就會顯示「匯入模組」滑動軸,並預先填入基礎路徑預覽 URL 欄位。視需要編輯基本路徑。若編輯基本路徑欄位,將會一併更新滑動軸中顯示之 JSON 格式的基本路徑。

  3. 按一下匯入

    匯入模組時,會建立權限組態並設定以保護模組。權限的名稱是使用基本路徑並在基本路徑字串的結尾加上 "_priv",同時將基本路徑中的每個斜線 "/" 取代為底線 "_"。

  4. 您的模組已可供編輯。

    匯入模組後,會建立範本與處理程式,但不會發佈模組。您需要為每個處理程式提供 SQL 和 PL/SQL 區塊,並在模組準備好進行測試或生產時發布。

編輯資源模組

本節說明如何編輯資源模組。

  1. 在「模組」頁面的特定模組中,按一下 環境定義功能表圖示,然後選取編輯
  2. 編輯必要欄位,然後按一下儲存。如需欄位的描述,請參閱建立資源模組

刪除資源模組

本節說明如何刪除資源模組。

  1. 在「模組」頁面的特定模組中,按一下 特性功能表,然後選取刪除

    隨即出現提示要求您確認。

  2. 按一下確定以刪除。

發布 / 取消發布資源模組

本節描述如何讓資源模組可供使用。

  1. 在「模組」頁面的特定模組中,按一下 特性功能表,然後選取發佈取消發佈

    您會看到確認的提示。

  2. 按一下確定

匯出資源模組

您可以匯出資源模組或 RESTful 服務的 API 或 Open API (Swagger) JSON 程式碼的 PL/SQL 原始碼。如果模組具有範本、處理程式、參數、角色等等,這些物件也會一併顯示和匯出。

  1. 在「模組」頁面的特定模組中,按一下 特性功能表,然後選取匯出模組
  2. 選取 PL/SQL 以複製或匯出 API 的 PL/SQL 來源。選取 OpenAPI 以複製或匯出模組的開放 API (Swagger) JSON 程式碼。

    附註:

    使用 Open API 匯出的模組一律會以未發布的狀態匯入。
  3. 按一下複製到剪貼簿以複製程式碼,或按一下下載以下載至您的本機電腦。

在 OpenAPI 檢視中檢視模組

本節描述如何在 Open API 檢視中開啟模組。

「開放式 API」檢視選項適用於已發佈且未受保護的模組。
  1. 在「模組」頁面的特定模組中,按一下 特性功能表,然後選取 OpenAPI 檢視
  2. 此模組會顯示為 Swagger UI 實作。
    您可以檢視與執行處理常式、將參數傳送給處理常式,以及複製或下載回應。

    若要深入瞭解 Swagger UI 導入,請參閱官方 Swagger UI 網站。

管理資源樣板

您可以在「樣板」頁面中定義、編輯及刪除模組的資源樣板。

若要瀏覽至此頁面,請在「模組」頁面中,按一下模組的 特性功能表 並選取範本,或在卡片檢視中按一下模組的名稱。

在頁面頂端,模組卡可使用內容功能表選項,例如編輯、刪除、發布及匯出。

在卡片檢視中預設顯示的範本屬性如下圖所示。

按一下卡片檢視中的範本名稱,即可移至「處理程式」頁面。您也可以透過相關內容功能表瀏覽至「處理程式」頁面。

相關內容功能表中可用的動作如下:

建立資源樣板

本節說明如何建立資源範本。

  1. 在模組的「樣板」頁面中,按一下建立樣板
  2. 在下列欄位中輸入值。星號 (*) 的欄位表示這些欄位為必填項目:
    • URI 樣板:輸入資源樣板的 URI 樣式。

      例如,/objects/:object/:id?樣式會比對 /objects/emp/101 (符合 ID 為 101 之 emp 資源中的項目要求),同時也會比對 /objects/emp/ (符合 emp 資源的要求,因為 :id 參數會以 ?修飾條件加註,這表示 ID 參數是選擇性的)。

      請注意,輸入 URI 樣板時,預覽 URL 會隨之變更。

    • 優先順序:輸入或選擇應如何評估資源樣板的優先順序 (1 代表低優先順序,9 代表高優先順序)。

    • HTTP 實體標記類型:選取要由資源範本使用的實體標記類型。實體標記是一種 HTTP 標頭,可作為資源的版本 ID。

      選項包括:

      • 安全 HASH (預設值) :傳回之資源表示法的內容會使用安全摘要函數進行雜湊,以提供指定資源版本的唯一指紋。

      • 查詢:手動定義可唯一識別資源版本的查詢。手動定義的查詢通常會比雜湊整個資源表示法更有效率地產生實體標記。

      • :不產生實體標記。

    • 註解:輸入描述性註解 (如果有的話)。

    • 建立後移至處理程式:選取此選項即可在建立樣板之後移至「處理程式」頁面。

    顯示程式碼:選取此選項即可檢視等同於「建立樣板」滑動軸的 PL/SQL 程式碼。您可以在工作表中複製並執行此 PL/SQL 程式碼,以執行按一下「建立樣板」滑動軸中的建立時所發生的相同動作。

  3. 按一下建立

    模組的新範本會新增至「範本」頁面。

    如果選取「建立後移至處理程式」,您可以使用頁面頂端來源路徑中的模組名稱來查看模組的樣板清單。

編輯資源樣板

本節說明如何編輯資源範本。

  1. 在「範本」頁面的特定範本中,按一下 特性功能表,然後選取編輯
  2. 編輯必要欄位,然後按一下儲存

    如需欄位的描述,請參閱建立資源樣板

刪除資源範本

本節說明如何刪除資源樣板。

  1. 在「樣板」頁面的指定樣板中,按一下 特性功能表,然後選取刪除

    系統會提示您將其進行確認。

  2. 按一下確定以刪除。

管理資源處理程式

您可以在「處理程式」頁面中建立、編輯及刪除樣板的資源處理程式。

若要瀏覽至此頁面,請在「範本」頁面中,按一下範本的 特性功能表 並選取處理程式,或在卡片檢視中按一下範本的名稱。

在頁面頂端,範本卡可使用內容功能表選項,例如「編輯」與「刪除」。

卡片檢視中預設顯示的處理程式屬性如下圖所示。

HTTP 方法可以是下列其中一種方法:GET、PUT、POST 以及 DELETE。

您可以使用相關內容功能表瀏覽至 HTTP 方法頁面。「HTTP 方法」頁面中會顯示三個頁籤:「來源」、「參數」以及「預先認證的要求」。

若要建立資源處理程式,請參閱建立資源處理程式

附註:

如果範本已建立四個處理常式 (GET、POST、PUT、DELETE),則無法使用此選項。

相關內容功能表中可用的動作如下:

建立資源處理程式

本節說明如何建立資源處理程式。

  1. 在「處理程式」頁面中,按一下建立處理程式
  2. 指定資源處理程式的特性。特定選項取決於方法類型。

    處理程式定義頁籤

    • 方法:輸入此處理程式的 HTTP 要求方法:GET (擷取資源的表示法)、POST (建立新資源或新增資源至集合)、PUT (更新現有資源) 或 DELETE (刪除現有資源)。每個 HTTP 方法只能有一個處理程式。

    • 每頁項目數:輸入或選擇資料庫查詢的預設分頁大小或要傳回的資料列數目。此選項僅適用於 GET 處理程式。若未定義此值,則每頁的項目數即為模組中定義的項目數。

    • 來源類型:選取所選 HTTP 方法的來源實行。預設為催收查詢。

      • 收集查詢:執行 SQL 查詢並將結果集轉換成 JSON 表示法。HTTP 方法為 GET 時可用。

      • 收集項目:執行 SQL 查詢,將一列資料傳回 JSON 表示法。HTTP 方法為 GET 時可用。

      • 媒體:執行符合特定格式的「SQL 查詢」,然後將結果集變成二進位表示法,並搭配識別表示法網際網路媒體類型的「HTTP 內容類型」標頭。

      • PL/SQL :執行匿名 PL/SQL 區塊,並將任何 OUT 或 IN/OUT 參數轉換成 JSON 表示法。

    • 來源:輸入 HTTP 方法的 SQL 查詢或 PL/SQL 區塊。在處理程式詳細資訊頁面中,您可以在處理程式編輯器中測試 SQL 或 PL/SQL 處理程式程式碼。

    • 建立後移至處理程式:選取此選項即可在建立處理程式之後移至詳細資訊頁面。

    允許的 MIME 頁籤

    識別「HTTP 要求主體」中包含的資訊類型。例如,如果 POST 處理程式在要求中預期應為 JSON,請新增 "Application/JSON" 作為 MIME 類型。

    顯示程式碼:選取此選項即可檢視等同於「建立處理程式」滑動軸的 PL/SQL 程式碼。您可以在工作表中複製並執行此 PL/SQL 程式碼,以執行按一下「建立處理程式」滑動軸中的建立時所發生的相同動作。

  3. 按一下建立

    處理常式會顯示在特定範本的「處理常式」頁面上。

    您可以使用 REST 從屬端或命令行工具 (例如 cURL) 來測試 REST 服務端點。

編輯資源處理程式

本節說明如何編輯資源處理程式。

  1. 在「處理程式」頁面的特定處理程式中,按一下 特性功能表,然後按一下詳細資訊
  2. 編輯必要欄位,然後按一下儲存

    如需欄位的說明,請參閱建立資源處理程式

刪除資源處理程式

本節說明如何刪除資源處理程式。

  1. 在「處理程式」頁面的特定處理程式中,按一下 特性功能表,然後按一下刪除

    系統會要求您進行確認。

  2. 按一下確定以刪除。

檢視資源處理程式詳細資訊及管理參數

您可以在 HTTP 方法頁面中檢視資源處理程式詳細資訊及管理參數。

若要導覽至此頁面,請針對特定處理程式,按一下 特性功能表,然後選取詳細資訊,或在卡片檢視中按一下處理程式的名稱。

在頁面頂端,處理常式卡可使用相關內容功能表選項,例如「編輯」與「刪除」。

「處理程式 HTTP 方法」頁面有兩個主要區段:

  • 用於執行在資源處理程式中定義之 SQL 或 PL/SQL 原始程式碼的程式碼編輯器。您可以執行程式碼、儲存、還原、重做、下載和清除輸出。如需有關編輯器的詳細資訊,請參閱在程式碼編輯器中執行 SQL 敘述句

    REST 服務處理程式中使用的隱含參數會顯示在編輯器右側的捲動清單中。請參閱隱含參數

  • 此區段用於管理執行 HTTP 方法所需的參數。

依預設,參數會顯示在方格檢視中。顯示在卡片檢視中參數的屬性如下圖所示。

相關內容功能表中可用的動作如下:

建立參數

本節描述如何建立資源處理程式的參數。

  1. 在處理程式 HTTP 方法頁面中,按一下建立參數
  2. 在下列欄位中輸入值。帶有星號 (*) 的欄位為必填欄位:
    • 參數名稱:輸入參數的名稱,如「URI 樣板」或「HTTP 標頭」中所命名。此名稱定義在內送要求中識別參數的方式,或在「回應」中指定參數的方式。

    • 連結變數名稱:輸入參數的名稱,如 SQL 中所參照的名稱。如果指定 NULL,則參數不會繫結。

    • 來源類型:選取參數源自「URI 樣板」或「HTTP 標頭」時所識別的類型。

    • 參數類型:選取參數的原生類型。

    • 存取方法:選取參數存取方法。指出參數是否為輸入值、輸出值,或兩者皆含。

    顯示程式碼:選取此選項即可檢視等同於「建立參數」滑動軸的 PL/SQL 程式碼。您可以在工作表中複製並執行此 PL/SQL 程式碼,以執行按一下「建立參數」滑動軸中的建立時所發生的相同動作。

  3. 按一下建立

    參數會新增至「參數」區段。

編輯 參數

本節說明如何編輯參數。

  1. 在「參數」區段中,針對特定參數,按一下 特性功能表,然後選取編輯
  2. 編輯必要欄位,然後按一下儲存

    如需欄位的說明,請參閱建立參數

刪除 參數

本節說明如何刪除參數。

  1. 在「參數」區段中,針對特定參數,按一下 特性功能表,然後選取刪除

    系統會要求您進行確認。

  2. 按一下以刪除。
隱含參數

本節描述「資源處理程式詳細資訊」頁面中的隱含參數。這些參數會自動新增至資源處理程式。

表格 4-1 隱含參數

名稱 Type 存取模式 HTTP 標頭 描述

:body

BLOB

IN

將要求的主體指定為暫時 BLOB。

:body_text

CLOB

IN

將要求的主體指定為暫時 CLOB。

:content_type

VARCHAR

IN

Content-Type

指定要求主體的 MIME 類型,如 Content-Type 要求標頭所指示。

:current_user

VARCHAR

IN

指定要求的已認證使用者。若未認證使用者,則會將值設為空值。

:forward_location

VARCHAR

OUT

X-ORDS-FORWARD-LOCATION

指定 Oracle REST Data Services 必須轉寄 GET 要求以產生此要求回應的位置。

:fetch_offset

NUMBER

IN

指定要在頁面上顯示之第一個資料列的零基偏移量。

:fetch_size

NUMBER

IN

指定要在頁面上擷取的資料列數目上限。

:page_offset

NUMBER

IN

指定分頁要求中的零基頁偏移量。

注意:The :page_offset 參數已不再使用。請改用 :row_offset 參數。

:page_size

NUMBER

IN

指定要在頁面上擷取的資料列數目上限。

:page_size 參數已不再使用。請改用 :fetch_size parameter

:row_offset

NUMBER

IN

指定要在分頁要求中顯示之第一個資料列的一個式索引。

:row_count

NUMBER

IN

指定要在分頁要求中顯示之最後一個資料列的一個式索引。

:status_code

NUMBER

OUT

X-ORDS-STATUS-CODE

指定要求的 HTTP 狀態代碼。

如需有關隱含參數的詳細資訊,請參閱 Oracle REST Data Services Developer's Guide

使用預先認證的要求來存取 ORDS RESTful 服務

若要存取受保護的 RESTful 服務,您可以建立及撤銷預先認證的要求。

預先認證的要求可讓您無需使用者證明資料,即可存取受保護的 ORDS RESTful 服務。當您建立預先認證要求時,會產生唯一的 URL。您可以將此 URL 提供給外部使用者,以使用標準 HTTP 工具與特定 RESTful 實體互動。

如需有關預先認證要求的詳細資訊,請參閱 Oracle REST Data Services Developer's Guide 中的 Oracle REST Data Services Pre-Authenticated Requests

若要瀏覽至「預先認證的要求」頁面,您可以執行下列其中一項作業:

  • 從「總覽」頁面中,按一下預先認證的要求磚塊。

  • 從功能表列展開安全,然後選取預先認證的要求

主題

建立預先認證的要求

建立現有處理程式的預先認證要求:

  1. 從現有處理程式的相關內容功能表中,選取建立新的預先認證要求

    就會顯示「建立預先認證的要求」面板。

  2. 權杖到期欄位中,輸入權杖到期持續時間 (秒)。

    選取顯示程式碼,即可檢視建立預先認證要求的基礎原始程式碼。

    按一下建立

    便會顯示存取資源的記號、別名和相對連結。您必須持續追蹤記號和別名,因為您之後無法取得其值。如果忘記值,您可以撤銷記號並再次建立新的記號。

檢視預先認證要求

從現有處理程式的相關內容功能表中,選取預先認證的要求,然後選取詳細資訊

會顯示特定處理程式的預先驗證要求。

撤銷預先認證的要求

撤銷處理程式的預先認證要求:

  1. 從現有處理程式的相關內容功能表中,選取預先認證的要求,然後選取詳細資訊

    會顯示特定處理程式的預先認證要求。

  2. 從預先認證要求的相關內容功能表中,選取撤銷

    系統會要求您進行確認。

  3. 按一下確認,即可撤銷要求。

範例:使用 POST 處理程式插入記錄

下列範例說明如何在 DEPT 表中插入記錄。

先決條件

  • 使用 SQL 頁面中的工作表,建立 DEPT 表格。

    CREATE TABLE DEPT(  
      DEPTNO     number(2,0),  
      DNAME      varchar2(14),  
      LOC        varchar2(13),  
      CONSTRAINT PK_DEPT PRIMARY KEY (DEPTNO)  
    )
    
  • 建立一個名為 example 的模組。請參閱建立資源模組

  • 為模組建立名為 emp/ 的樣板。請參閱建立資源樣板

插入記錄:
  1. 在「處理程式」頁面中,按一下建立處理程式
  2. 請輸入下列詳細資訊:
    • 方法欄位中,選取 POST

    • 來源類型欄位中,選取 PL/SQL

    • 來源欄位中,輸入下列 PL/SQL 區塊:

      DECLARE  
         id number;
      BEGIN
          INSERT INTO DEPT (DEPTNO, DNAME, LOC) VALUES (:DEPTNO, :DEPTNAME, :DEPTLOC) RETURNING DEPTNO INTO id;
          :status_code := 201;
          :forward_location := id;
      END;
      

      其中

      • RETURNING DEPTNO INTO id 會傳回指派給 DEPTNO 的值至變數 id

      • :status_code 是指定 201 的隱含參數,表示已建立資源。

      • :forward_location 是指定的隱含參數,包含 DEPTNO 值的 id。此參數指定轉寄 GET 要求以產生 POST 要求回應的位置。

    • 請確定已選取建立後移至處理程式頁面

    • 允許的 MIME 頁籤中,從下拉式清單中選取 application/json ,然後按一下新增 +。

    • 按一下建立

    「處理程式 POST」頁面會出現。

    您可以按一下「來源」頁籤下的執行敘述句 執行敘述句 來測試原始程式碼。

  3. 建立 GET 資源處理程式,以產生 POST 要求的回應。

    在「範例」模組中,建立一個名為 emp/:id 的樣板。

    建立來源類型催收項目來源包含下列查詢的 GET 資源處理程式:

    SELECT * FROM DEPT WHERE DEPTNO = :id
    
  4. 在 cURL 中使用下列命令測試 RESTful 服務端點。您可以使用 POST 處理程式卡頂端的「複製到剪貼簿」圖示來複製 URL (http://xyz.us.comp.com:1234/ords/pdbdba/example/emp)。
    curl --location --request POST --header "Content-Type: application/json" 
    --data '{"DEPTNO": 54, "DEPTNAME": "HR", "DEPTLOC": "America" }' 'http://xyz.us.comp.com:1234/ords/pdbdba/example/emp/'

    輸出為:

    {"deptno":54,"dname":"HR","loc":"America","links":[{"rel":"collection",
    "href":"xyz.us.comp.com:1234/ords/pdbdba/example/emp/"}]}
  5. 在「SQL」頁面中,檢查 DEPT 表格以查看是否已使用下列陳述式插入新記錄:
    SELECT * FROM DEPT;