實行 FaG4ade REST 服務的自訂 API

當您開發行動應用程式時，通常會先以使用者介面層啟動，然後使用 REST Web 服務，以另一個應用程式連線您的應用程式。這種方法適用於小型或簡單的應用程式。當應用程式較大，而您想要與多個後端服務連線時，可能會意外導入效能與安全問題。

最佳作法是在外部後端服務和使用者介面之間開始建置 faG4ade API 層，以減少每次可能的後端服務呼叫數目。例如，您的行動應用程式可以針對處理其他 REST 服務呼叫的 famwade API 層執行單一呼叫，然後以單一回應將所有內送資料合併至您的行動應用程式。

建立完整的自訂 API

使用 Oracle Mobile Hub 建立完整的自訂 API。

按一下 並選取開發，然後從側邊功能表中選取 api。若已建立 API (不論是處於「草稿」或「已發布」狀態)，您將會見到 API 清單。如果沒有自訂 API，您將會見到含有新 API 按鈕的頁面。按一下您已經建立的 API，或按一下新 API 開始使用。

定義端點

您可以建立資源來定義 API 的端點。資源是 API 的路徑。它有一個類型、一些與其關聯的資料、與其他資源的關係，以及包含一或多個對其採取動作的方法。資源幾乎可以是：影像、文字檔、其他資源的集合、邏輯交易、程序等。

1. 按一下端點導覽連結即可開始。
2. 按一下新建資源，然後新增一些基本資訊。

   每次按一下「新建資源」時，您都會建立最上層 (根) 資源。如果您要新增子項 (巢狀) 資源，請按一下最上層資源旁的新增 (+)。按一下 X 即可刪除資源。

   注意事項：

   查看「方法」連結下方的圖示？每次定義資源的方法時，它的圖示就會顯示在方法連結下方。您可以使用它們作為捷徑來查看已為資源定義哪些方法。按一下圖示，即可直接前往方法頁面上的定義。
3. 請提供資源路徑，此為 URI (相對於基礎 URI)。例如，如果基礎 URI 是/mobile/custom/audits/，則您可以新增資源 findings，亦即/mobile/custom/audits/findings。
4. 請提供顯示名稱，此名稱是讓 API 文件中易於識別的資源名稱。
   資源會依其在「API 測試」頁面左側顯示名稱列出。
5. 提供資源的簡短描述。

   輸入描述之後，URI 會顯示在描述欄位下方。

6. (選擇性) 提供 RAML 資源類型(此為資源類型 (resourcesType：)。您不需要指定資源類型。如果您想要使用資源類型，但沒有定義的資源類型，請按一下類型連結並定義資源類型。

為資源建立方法後，該方法的符號會顯示在方法連結下方。如果您需要檢查資源定義，您可以立即看到為資源定義的方法。按一下圖示可直接前往該方法定義。

只要切換至「壓縮模式」(會到「新資源」的右邊)，即可清除讓資源更快速地找到資源。精簡顯示會隱藏資源描述、資源類型以及路徑。

新增方法至資源

方法是可在資源上執行的動作。「方法」頁面會一次顯示一個方法。至少定義了兩種方法之後，您可以按一下頁面頂端方法的圖示，查看其詳細資訊。

1. 按一下方法，將部分方法新增至資源。

   如果您正在定義的資源具有路徑參數，這些資源會顯示在新增方法的上方。

   1. (選擇性) 如果您想要讓路徑參數與每個方法一起傳送，請按一下必要。
      就會顯示參數名稱。
   2. 提供參數的顯示名稱和範例代碼。
   3. 從下拉式清單中，選取參數的有效值類型。
2. 按一下新增方法，然後選取您要的方法。

   選取方法之後，它就不會再列在方法清單中，因為每個資源只能使用一次方法 (例如，您不能為單一資源定義兩個 DELETE 方法)。頁面頂端會顯示您定義之每個方法的圖示。按一下方法圖示可直接前往其定義。

3. (選擇性) 在描述欄位中輸入方法的簡短描述。
4. (選擇性) 輸入方法的顯示名稱。
5. (選擇性) 提供任何要套用至方法的特徵。

   如果您未定義任何資源特性，請按一下端點回到主要「資源」頁面，然後按一下特徵連結來定義資源。您可以利用特性來定義類似作業的集合。

定義資源的方法後，您可以為這些方法定義要求和回應。

定義方法的要求

選取方法之後，請定義您要連線的服務要求。例如，如果您選取 POST 方法，現在就可以定義要建立的項目。您可以藉由新增參數和要求主體 (包含要傳送給服務之資料的描述) 來達到此目的。

1. 按一下要求以定義要求。
2. 按一下新增參數，然後選取參數類型：查詢或標頭。如果方法需要參數，請選取必要。
   1. 提供參數的名稱和顯示名稱。
   2. 選取有效的值類型：字串、數字、整數、日期或布林值。
   3. (選擇性) 提供參數的描述，以及可供您測試端點有效性時使用的範例。例如，您可以有資源 audits，並新增查詢參數 auditorID，它接受數字值，而另一個參數 auditName 接受字串值：

      /audits: 
        get: 
          description: | 
            Gets list of audits, organizations etc.     
          queryParameters: 
            auditorID:  
              id: Auditor ID
              description: | 
                display auditor identifier 
              type: integer 
              example: |
                1234
              required: false      
            auditName:
              displayName: auditName
              description: |
                Audit name
              example: "Payroll Process Audit"

      在此範例中，GET 方法使用查詢參數 auditorID 和 auditName 來定義。

   4. (選擇性) 按一下其他特性，將巢狀特性新增至參數。按一下重複，即可新增目前參數的倍數。
   5. 按一下新增參數，為方法新增另一個最上層參數。
3. 視您選取的方法而定，按一下新增媒體類型並定義方法主體。主體包含您要傳送給伺服器的資料。例如，如果您是定義 POST 方法，則必須定義您正在建立的項目，例如新的客戶清單或服務要求。如果您是定義 GET 方法，就不需要傳送方法主體，因此您就不需要指定媒體類型。
   1. 選取方法主體的媒體類型，亦即您所傳送之訊息的格式，例如文字、影像或 Web 表單。
      根據類型的不同 (例如，您不應輸入影像類型的綱要)，您可以選擇新增綱要或範例，或新增二者。

      定義綱要時，請只新增資源用途所需的資料。也就是說，不要新增不必要的資料，只會減緩傳輸速度，而且可能增加發生錯誤的潛在資料。

   2. (選擇性) 按一下綱要，然後在編輯器窗格中輸入綱要 (JSON 格式)。綱要就像主體的樣板。您是定義訊息內容的用途。
   3. (選擇性) 按一下範例，然後在編輯器窗格中輸入範例 (以 JSON 格式)，此編輯器窗格會將模擬實行當作方法的模擬回應使用。使用模擬資料可協助您驗證方法的行為。此範例顯示 audits 資源的 POST 方法中所定義，正在傳送於訊息本文中的資料模擬值：

      body: 
        application/json: 
          example: | 
            { 
              "Title": "Leaking Water Heater",
              "Username": "joh1017",  
              "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014", 
              "Notes": "my water heater is broken"
            }                               
      

4. 按一下新增媒體類型，即可新增其他媒體類型。如果您決定不要使用該方法，請按一下標幟中的 X 來將它刪除。

定義方法的回應

根據要求的不同，您可能需要或不需要回應。回應描述從服務傳回結果的處理作業。您可能想定義回應來驗證要求的資料已退回，或者想要回應認可是否收到要求。定義回應與定義要求類似。主要的差異在於您將需要選取狀態碼以讓您知道連線的結果。

1. 按一下「回應」以定義一或多個回應。
2. 按一下新增回應，然後選取您要傳回的狀態代碼。

   預設會提供狀態代碼 200，但如果不是您要的代碼，請從下拉式清單中選取一個代碼。

   • 2 xx 代表成功連線。

   • 3 xx 表示發生重導。

   • 4 xx 指示發生使用者錯誤。

   • 5 xx 指示發生伺服器錯誤。

   為了協助其他使用者瞭解您設定之 API 中可能的錯誤原因，請使用 HTTP 狀態代碼來傳回最符合錯誤狀況的代碼。

3. 提供程式碼指定的描述。
4. 按一下新增標頭、選取回應標頭或查詢、提供標頭或查詢的名稱以及標頭的有效值類型和有效值類型。
5. 按一下新增媒體類型，然後選取回應的格式。視您選取的媒體類型而定，您可以新增參數、綱要或範例，就像在「要求」主體中一樣。
   1. 對於以文字為基礎的媒體類型 (例如 application/json 或 text/xml)，請按一下綱要以 JSON 格式輸入主體的綱要 (使用 JSON 格式)。
      和要求主體一樣，只能將相關資料加到回應主體。請勿包含比作業實際所需的資料更多。
   2. 按一下範例即可為您的回應主體新增模擬資料 (使用 JSON 格式)。使用模擬資料來驗證方法的行為，再使用真實資料進行測試。
   3. 對於表單式媒體類型 (例如 multipart/form-data)，按一下新增參數，然後在必要時選取必要。然後提供名稱並選取值類型。您也可以選擇提供參數的名稱。
   4. 對於以影像為基礎的媒體類型 (例如 image/png)，您不需要提供任何綱要或屬性。

以下範例顯示 audits 資源的 POST 方法的回應已建立，狀態代碼為 201，表示已順利建立新資源。此範例也顯示 application/json 的傳回回回應格式、新增的 Location 標頭，以及包含模擬資料的訊息正文：

responses: 
  201: 
    description: | 
      The request has been fulfilled and resulted in a new resource 
      being created. The newly created resource can be referenced  
      by the URI(s)returned in the entity of the response, with the 
      most specific URI for the resource given by a Location header
      field.  

    headers:
      Location:
        displayName: Location
        description: |
          Identifies the location of the newly created resource.

        type: string
        example: |
          /20934

        required: true

    body: 
      application/json: 
        example: | 
          {
            "id": 20934,
            "title": "Lynn's Leaking Water Heater",
            "contact": {
               "name": "Lynn Adams",                 
               "street": "45 O'Connor Street",
               "city": "Ottawa", 
               "postalcode": "a1a1a1",
               "username": "johnbeta"
              },
           "status": "New",
           "driveTime": 30,
           "priority": "high",
           "notes": "My notes",
           "createdon": "2014-01-20 23:15:03 EDT",
           "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d74331d77/objects/6cdaa3a8-097e-49f7--9bd2-88966c45668f?user=lynn1014"
          }

定義回應時，您可以決定測試端點，或按一下導覽列中的端點返回主「資源」頁面。您可以從此處移至「API 設計工具」的其他頁面，以建立根目錄、資源類型或特性，或新增 API 文件。

如果您決定不要使用方法，請按一下標幟中的 X 來將它刪除。

建立 REST 連線器 API

您可以使用「REST 連線器 API」精靈來建立、設定及測試連線器 API。

若要取得基本工作連線器 API，您可以只輸入連線器 API 的名稱和外部服務的 URL。

您可以在此處執行下列作業：

• 定義規則以構成您要存取之資料的特定要求或回應。

• 設定您存取之服務的從屬端安全原則。

• 測試連線並測試對連線進行呼叫的結果。

您必須建立自訂 API 和實行，讓您的應用程式可以呼叫連線器 API，並自動產生 API 及實行。若要手動執行此作業，您必須以適當資源建立自訂 API，然後實行自訂程式碼。

設定基本連線器

您可以在「REST 連線器 API」精靈中完成前兩個頁面以建立運作連線器。

1. 按一下 並選取開發，然後從側邊功能表中選取 api。

2. 按一下 REST (如果這是要建立的第一個連線器 API) 或新連線器，然後從下拉式清單中選取 REST。

3. 提供下列項目來識別您的新 REST 連線器 API：

   1. API 顯示名稱： 連線器 API 清單中顯示的名稱。

   2. API 名稱： 連線器 API 的唯一名稱。

      依照預設，這個名稱會附加至相對基礎 URI，作為連線器 API 的資源名稱。您可以在「API 名稱」欄位下方查看基礎 URI。

      除了此連線器 API 的新版本以外，其他連線器 API 不能有相同的資源名稱。

   3. 簡短描述： 選取此 API 時，「連線器」頁面上會顯示此描述。

4. 按一下建立。

5. 在「REST 連線器 API」對話方塊的「一般」頁面中，設定逾時值：

   • HTTP 讀取逾時： 等待讀取資料的時間上限 (毫秒)。如果未提供值，則會套用預設值 20 秒。

   • HTTP 連線逾時： 連線遠端 URL 所花費的時間 (毫秒)。0mms 值表示允許無逾時。

     HTTP 逾時值必須小於 Network_HttpRequestTimeout 原則，預設值為 40,000 毫秒。

     注意事項：

     如果除了服務開發人員角色之外，您還具有行動雲端管理員角色，您可以從「管理員」檢視，開啟 policies.properties 檔案，查看目前環境的網路原則值。否則，請洽詢您的行動雲端管理員瞭解值。

6. 按一下描述區，然後輸入服務的連線資訊。

   如果您提供 Swagger 描述區 URL，就會識別並顯示可用的資源，您可以選取需要的資源。

   注意事項：

   僅支援標準網際網路存取連接埠 80 和 443。無法使用自訂連接埠建立服務的連線。

7. 按一下儲存。

8. (選擇性) 按一下測試、選取認證證明資料，然後對服務進行測試呼叫。

您可以使用下列方式進一步設定連線器：

• (如果您已經在「描述區」頁面中提供描述區) 移至「資源」頁面，然後選取顯示之資源的方法。

• 定義規則。

• 設定安全原則。

若要確定連線器 API 組態有效，您應在發布前先從「連線器 API 測試」頁面進行完整測試 (不只是從「連線器 API 測試」頁面)。亦即，您也應該測試使用此連線器 API 的自訂 API (與其實行)。基本上，如果您已準備好發佈連線器 API，您也應該準備好發佈呼叫連線器 API 的自訂 API。

設定規則

您可以設定規則來定義行動應用程式與服務之間的互動。規則提供您新增服務上資源之所有呼叫的預設參數值、呼叫特定代理主機路徑，以及特定作業類型 (動詞) 的呼叫方式。這有助於強制 URL 字串的一致語法，儲存自訂程式碼開發人員不必插入這些值，並可透過分析追蹤不同的呼叫。

您可以建立一或多個規則。每個規則都可以有一或多個類型為 Query 和 Header 的參數。

如果未套用任何規則，則會透過代理主機將所有呼叫傳遞至現有服務。

1. 如果尚未開啟連線器，請按一下 並從側邊功能表中選取開發，然後選取 api。
2. 選取要編輯的連線器 API，然後按一下開啟。
3. 選取角色。
4. 按一下新建規則。
5. 按一下新增參數，然後選取查詢或標頭參數類型，接著輸入查詢或標頭名稱及其值。

   注意事項：

   雖然您可以定義規則來預設設定某些標頭，但如果透過自訂程式碼或間接 (例如從 Web 瀏覽器或行動應用程式) 直接呼叫連線器的從屬端已經設定相同的標頭，就不會套用規則。

   特別是，設定要求主體的格式通常是以 Content-Type 標頭 (而非 REST Connector 規則) 的自訂程式碼執行。同樣地，設定回應主體的格式也是以 Accept 標頭 (而非 REST Connector 規則) 的自訂程式碼來完成。

   您可以視需要將多個參數新增至規則，但這較適合使用太多作業來超載規則。較簡單的規則建構是為了疑難排解。

6. 展開資源，然後編輯遠端 URL 以提供要套用之規則的資源。基本 URL 值是您在設定基本資訊步驟中輸入的值，因此無法編輯。
7. 如果您要將規則僅套用至「遠端 URL」中指定的資源層級，請選取不要套用至較低層級的資源。
8. (選擇性) 取消選取您不想套用至您剛才定義之規則的 HTTP 方法。預設會選取所有方法。
9. (選擇性) 按一下新建規則以建立其他規則。

   注意事項：

   如果您定義與另一個規則衝突的規則，則會優先套用第一個規則，並忽略衝突的規則。

   完成之後，請按一下儲存，然後按一下下一步 (>)，即可移至下一個步驟來設定您的連線器 API。

您剛才定義之規則的描述，會顯示在「預設參數」段落上方的規則標幟中。舉例來說，假設提供下列值：

• 遠端 URL = https://maps.googleapis.com/maps/api/directions/json？origin=los+angeles&destination=seattle

• 本機 URI = myMapAPI

• 具有下列參數的規則：Query:key:A3FAEAJ903022

• GET 和 PUT HTTP 方法

規則描述會如下所示：

對於GET 至httpsTypeI/maps.googleapis.com/maps/api/directions/json?from in=los+angeles&destination=Seattle (位於myMapAPI/directions) ，包括查詢： key = A3FAEAJ903022。

如果未建立任何規則，將會讀取說明：

對於 myMapAPI 可用的https://maps.googleapis.com/maps/api/directions，不會套用任何預設參數。

現在，您有一個對應至現有服務的基礎 URI。使用我們的範例：

mobile/connector/myMapAPI/directions/json？origin=los+angeles&destination=seattle 對映至https://maps.googleapis.com/maps/api/directions/json？origin=los+angeles&destination=seattle

設定安全原則和覆寫特性

在您完成連線器 API 之前，應考慮如何處理其安全性。您可以使用安全原則或授權標頭。選取一個安全原則，說明您要連線的服務之認證配置為建議的方法。

每個安全原則都具有可設定的特性 (稱為覆寫)。覆寫原則組態特性的理由之一是限制您必須維護的原則數目：不需以稍微不同的組態建立多個原則，您可以使用相同的一般原則並覆寫特定值來符合您的需求。

若要選取安全原則並設定原則覆寫：

1. 如果尚未開啟連線器，請按一下 並從側邊功能表中選取開發，然後選取 api。
2. 選取要編輯的連線器 API，然後按一下開啟。
3. 選取安全性。
4. 從可用的原則清單中選取安全原則，然後按一下向右箭號將其移至選取的原則清單。
   只能為連線器 API 選取單一原則。所選原則的描述會顯示在清單下方。
5. 如果不想使用預設值，請指定所選原則的覆寫值 (如果適用)。
   若要覆寫特性，請輸入或選取預設值以外的值。
6. 按一下儲存來儲存您的工作，或按一下儲存並關閉，儲存您的工作並結束 REST 連線器 API 精靈。
7. 按一下下一步 (>)，即可移至下一個步驟。