1. 從 Oracle Mobile Hub 應用程式存取 REST 資料
  2. 導入 Façade REST 服務的自訂 API

導入 Façade REST 服務的自訂 API

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

在外部後端服務與使用者介面之間開始建置 façade API 層，以盡可能減少後端服務的呼叫次數，這是最佳做法。例如，您的行動應用程式可以對處理其他 REST 服務呼叫的 façade 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/，則您可以新增 /mobile/custom/audits/findings 的資源 findings。
  4. 提供顯示名稱，這是資源的名稱，讓您可以在 API 文件中輕鬆識別。
    資源會依其在「API 測試」頁面左側的顯示名稱列出。
  5. 提供資源的簡短描述。

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

  6. (選擇性) 提供 RAML 資源類型，即資源類型 (resourcesType:)。您不需要指定資源類型。如果您要使用資源類型，但未定義資源類型，請按一下類型連結並加以定義。

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

您可以切換至精簡模式 (位於新資源的右側)，清除雜亂以更快速地找到資源。精簡顯示器會隱藏資源描述、資源類型和路徑。

新增方法至資源

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

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

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

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

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

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

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

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

定義方法的要求

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

  1. 按一下要求以定義要求。
  2. 按一下新增參數，然後選取參數類型：查詢或標頭。如果方法需要參數，請選取必要。
    1. 提供參數的名稱和顯示名稱。
    2. 選取有效值類型： String 、 Number 、 Integer 、 Date 或 Boolean 。
    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. (選擇性) 按一下其他特性，將巢狀特性新增至參數。按一下重複 (Repeat) 以新增目前參數的倍數。
    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 來瞭解您正在設定之 API 中潛在錯誤的原因，請使用 HTTP 狀態代碼來傳回最符合錯誤情況的程式碼。

  3. 提供程式碼指定內容的描述。
  4. 按一下新增標頭，選取回應標頭或查詢，提供標頭或查詢的名稱和標頭的顯示名稱，以及標頭的有效值類型。
  5. 按一下新增媒體類型，然後選取回應的格式。視您選取的媒體類型而定，您可以新增參數、綱要或範例，就像對「要求」主體執行的一樣。
    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 連線器 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 所使用的時間 (毫秒)。值為 0 毫米表示允許無限逾時。

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

      附註：

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

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

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

    附註：

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

  7. 按一下儲存。

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

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

  • (如果您已在「描述區」頁面提供描述區，請移至資源頁面，然後選取公開之資源的方法。

  • 定義規則。

  • 設定安全原則。

若要確定您的連線器 API 組態有效，您應該先完整測試 (不只是從「連線器 API 測試」頁面)，然後再進行發布。也就是說，您應該測試使用此連線器 API 的自訂 API (及其實行)。基本上，如果您準備好發布連線器 API，您也應該準備好發布呼叫它的自訂 API。

設定規則

您可以設定規則來定義行動 App 與服務之間的互動。規則可讓您為服務上的資源呼叫、對特定代理主機路徑的呼叫，以及對特定類型作業 (動詞) 的呼叫新增預設參數值。這有助於強制實行 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 至 https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle 可從 myMapAPI/directions 取得，請包含 Query: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. 按一下下一步 ( >)，即可移至下一個步驟。