實行 Faade REST 服務的自訂 API

開發行動應用程式時，通常是先以使用者介面層開始，然後再使用 REST Web 服務，將您的應用程式與其他應用程式連線。此方法適用於小型或簡單的應用程式。當應用程式較大，而您想要連線多個後端服務時，可能會不小心導致效能與安全問題。

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

建立完整的自訂 API

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

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

定義端點

您可以建立資源來定義 API 的端點。資源是 API 的導覽路徑。它具有類型、部分與其關聯的資料、與其他資源的關係，以及包含一或多個作用的方法。資源幾乎可以是任何內容：影像、文字檔、其他資源的集合、邏輯交易、程序等。

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

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

注意：
請參閱方法連結下的圖示？每次為資源定義方法時，它的圖示都會顯示在方法連結下。可使用它們作為捷徑，查看已為資源定義哪些方法。按一下圖示即可直接移至「方法」頁面中的定義。
提供 URI (相對於基礎 URI) 的資源路徑。例如，如果基礎 URI 是 /mobile/custom/audits/，您可以新增 /mobile/custom/audits/findings 的資源 findings。
提供顯示名稱 (這是資源的名稱)，以便在 API 文件中輕易識別。
資源會依其在「API 測試」頁面左側的顯示名稱列出。
提供資源的簡短描述。

輸入描述後，URI 會顯示在描述欄位下方。
(選擇性) 提供 RAML 資源類型，此為資源類型 (resourcesType:)。您不需要指定資源類型。如果您想要使用資源類型，但尚未定義資源類型，請按一下類型連結，然後定義一個。

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

您可以清除雜亂，直接切換至精簡模式 (位於新資源的右邊) 來更快找出資源。精簡顯示會隱藏資源描述、資源類型及路徑。

新增方法至您的資源

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

按一下方法，新增資源的某些方法。

如果您為其定義方法的資源含有路徑參數，它們會顯示在新增方法上方。
1. (選擇性) 如果您要使用每個方法來傳遞路徑參數，請按一下必要。
  此時會顯示參數名稱。
2. 提供參數的顯示名稱和範例代碼。
3. 從下拉式清單中，選取參數的有效值類型。
按一下新增方法，然後選取想要的方法。

選取方法之後，它就不會再列在方法清單中，因為您每個資源只使用一次方法 (例如，您無法為單一資源定義兩個 DELETE 方法)。您定義的每個方法的圖示會顯示在頁面頂端。按一下方法圖示即可直接移至其定義。
(選擇性) 在描述欄位中輸入方法的簡短描述。
(選擇性) 輸入方法的顯示名稱。
(選擇性) 提供任何特徵以套用至方法。

如果您未定義任何資源特性，請按一下端點以返回主要「資源」頁面，然後按一下「訓練」連結以定義資源特性。訓練功能可讓您定義類似作業的集合。

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

定義方法的要求

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

按一下要求以定義要求。
按一下新增參數，然後選取參數類型：查詢或標頭。如果方法需要參數，請選取必要。
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"
```
  在此範例中，會使用查詢參數 auditorID 和 auditName 來定義 GET 方法。
4. (選擇性) 按一下其他特性，將巢狀特性新增至參數。按一下重複可新增目前參數的倍數。
5. 按一下新增參數即可新增該方法的其他最上層參數。
視您選取的方法而定，按一下新增媒體類型並定義方法主體。本文包含您要傳送給伺服器的資料。舉例來說，如果您正在定義 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"
      }                               
```
按一下新增媒體類型，即可新增其他媒體類型。如果您決定不要使用該方法，請按一下標幟中的 X 來刪除該方法。

定義方法的回應

視要求而定，您可能會也可能不需要回應。回應會描述從服務傳回結果的程序。您可能會想要定義回應，以驗證您要求的資料是否已退回，或者您可能會想要確認是否已收到要求的回應。定義回應與定義要求類似。主要的差異在於您必須選取狀態代碼，才能讓您知道連線的結果。

按一下回應以定義一或多個回應。
按一下新增回應，然後選取您要傳回的狀態代碼。
預設狀態代碼 200，但如果不是您要的代碼，請從下拉式清單中選取。
- 2 xx 表示連線成功。
- 3 xx 代表發生重新導向。
- 4 xx 表示發生使用者錯誤。
- 5 xx 表示發生伺服器錯誤。
若要協助所有人使用 API 來瞭解您所設定之 API 中可能發生的錯誤原因，請使用 HTTP 狀態代碼傳回最符合錯誤情況的代碼。
提供代碼指定項目的描述。
按一下新增標頭，選取回應標頭或查詢，提供標頭或查詢的名稱以及標頭的顯示名稱，以及標頭的有效值類型。
按一下新增媒體類型，然後選取回應的格式。根據您所選之媒體類型的不同，您可以新增參數、綱要或範例，方法與新增「要求」主體的相同。
1. 若為文字型媒體類型 (例如 application/json 或 text/xml)，請按一下綱要以輸入主體的綱要 (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 Connector API 精靈中完成前兩個頁面，來建立運作連線器。

按一下並選取開發，然後從側邊功能表中選取 api。
按一下 REST (如果是要建立的第一個連線器 API) 或新建連線器，然後從下拉式清單中選取 REST。
提供下列資訊以識別您的新 REST 連線器 API：
1. API 顯示名稱：連線器 API 清單中顯示的名稱。
2. API 名稱：連線器 API 的唯一名稱。
  
  依照預設，此名稱會附加至相對基本 URI，作為連線器 API 的資源名稱。您會在 API 名稱欄位下方看到基礎 URI。
  
  除了此連線器 API 的新版本外，其他連線器 API 不能有相同的資源名稱。
3. 簡要說明：選取此 API 時，連線器頁面會顯示此說明。
按一下建立。
在 REST Connector API 對話方塊的「一般」頁面中，設定逾時值：
- HTTP 讀取逾時：等待讀取資料的時間上限 (毫秒)。如果您未提供值，將會套用預設值 20 秒。
- HTTP 連線逾時：連線遠端 URL 所花的時間 (毫秒)。值為 0mms 表示允許無限的逾時。
  
  HTTP 逾時值必須小於 Network_HttpRequestTimeout 原則，預設值為 40,000 毫秒。
  
  注意：
  如果除了服務開發人員角色之外，您還有行動雲端管理員角色，您可以從「管理員」檢視開啟 policies.properties 檔案，查看目前環境之網路原則的值。否則，請洽詢您的行動雲端管理員取得值。
按一下描述區，然後輸入服務的連線資訊。

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

注意：
僅支援標準的網際網路存取連接埠 80 和 443。無法使用自訂連接埠建立服務連線。
按一下儲存。
(選擇性) 按一下測試，選取認證證明資料，然後對服務進行測試呼叫。

您可以透過下列方式，進一步設定連線器：

(如果您已在「描述區」頁面提供描述區)，移至「資源」頁面，然後選取公開之資源的方法。
定義規則。
設定安全原則。

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

設定規則

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

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

如果不套用任何規則，則所有呼叫都會透過代理主機傳送至現有的服務。

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

注意：

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

特別是，系統通常會在自訂程式碼中以 Content-Type 標頭設定要求主體的格式，而不是以 REST Connector 規則設定。同樣地，也會在自訂程式碼中以 Accept 標頭設定回應主體的格式，而不是 REST Connector 規則。

您可以新增不限數目的規則參數，但是使用太多作業，較好不會造成規則超載。更簡單的規則結構更容易進行疑難排解。
展開資源，然後編輯遠端 URL 以提供要套用規則的資源。基礎 URL 值是您在設定基本資訊步驟中輸入的值，而且無法編輯。
如果您想要將規則僅套用至「遠端 URL」中指定的資源層級，請選取不要套用至較低層級的資源。
(選擇性) 取消選取您不想套用至剛定義之規則的 HTTP 方法。預設會選取所有方法。
(選擇性) 按一下新建規則以建立另一個規則。

注意：

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

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

您剛才定義之規則的描述會顯示在預設參數區段上方的規則標幟中。例如，假設有下列值：

遠端 URL = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle
本機 URI = myMapAPI
具有下列參數的規則：Query:key:A3FAEAJ903022
GET 和 PUT HTTP 方法

規則說明將如下：

若要從myMapAPI/Assignment取得 httpsindirect //maps.googleapis.com/maps/api/directions/json?originXllos+angelesestinationyRseattle ，請在myMapAPI/instructions取得，包括查詢：索引鍵= 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 之前，應考慮如何處理其安全性。您可以使用安全原則或授權標頭。選取一個安全原則，描述您目前連線之服務的認證配置是建議的方法。

每個安全原則都有稱為覆寫的特性，您可以設定它。覆寫原則組態特性的一個原因是限制您必須維護的原則數目：您可以使用相同的一般原則，並覆寫特定值，以符合您的需求。

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

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